投诉mcp
一种MCP（模型上下文协议）服务器，使AI编码代理能够就开发任务中遇到的丢失或混淆信息提交结构化的投诉报告。
状态：积极发展| 建筑：具有类型安全的清洁建筑
______________________________________________________________________
🎯 执行摘要
投诉mcp 是一个复杂的MCP服务器，当AI编码代理在开发任务中遇到信息缺失、规范混乱或文档不充分时，它能够提交结构化的投诉报告。建于 企业级架构 和 类型安全Go，它提供透明的数据管理、高级缓存和全面的可观察性。
______________________________________________________________________
✨ 主要特点
🏗️ 核心功能
- 📝 结构化投诉归档：具有丰富元数据的标准化投诉报告
- 💾 双存储系统：本地项目存储+全球用户范围跟踪
- 📅 智慧型组织：具有会话上下文的基于时间戳的文件名
- 🔄 分辨率跟踪：完整的投诉生命周期管理
- 📄 文件导出：多格式导出（Markdown、HTML、文本）
- 🔍 高级搜索：在投诉内容中进行全文搜索
- 📊 性能分析：实时缓存统计和指标
🛡️ 企业级架构
- 🏛️ 整洁架构：分层设计，明确区分关注点
- 🔒 类型安全：具有验证功能的强类型域模型
- 🧵 线程安全：具有适当同步的并发安全操作
- 📋 BDD测试：行为测试套件（47/52项测试通过）
- 🔍 可观测性：结构化跟踪和全面记录
- ⚡ 高性能：具有O（1）个查找的LRU缓存
🆕 最新增强功能
- 📁 文件路径透明度：完全了解数据存储位置
- 🛠️ 增强的MCP集成：工具响应中包含的文件路径
- 🔧 改进了错误处理：通过详细的日志记录进行优雅的降级
- 📋 存储库接口扩展：GetFilePath（）和GetDocsPath（）方法
______________________________________________________________________
🏗️ 架构概述
┌─────────────────────────────────────────────────────────────────────────┐
│ MCP CLIENTS (AI Agents) │
└─────────────────────┬───────────────────────────────────────────────┘
│ stdio/transport
┌─────────────────────▼───────────────────────────────────────────────┐
│ MCP SERVER LAYER │
│ ┌─────────────────┬─────────────────┬─────────────────┐│
│ │ Tool Handlers │ DTO Layer │ Error Handling ││
│ │ (file_complaint)│ (type-safe) │ (structured) ││
│ └─────────────────┴─────────────────┴─────────────────┘│
└─────────────────────┬───────────────────────────────────────────────┘
│ Service Interface
┌─────────────────────▼───────────────────────────────────────────────┐
│ SERVICE LAYER │
│ ┌─────────────────┬─────────────────┬─────────────────┐│
│ │ Business Logic│ Path Resolution│ Configuration ││
│ │ (Orchestration)│ (NEW!) │ Management ││
│ └─────────────────┴─────────────────┴─────────────────┘│
└─────────────────────┬───────────────────────────────────────────────┘
│ Repository Interface
┌─────────────────────▼───────────────────────────────────────────────┐
│ REPOSITORY LAYER │
│ ┌─────────────────┬─────────────────┬─────────────────┐│
│ │ File Repository│ Cached Repository│ Docs Repository ││
│ │ (JSON Storage) │ (LRU Cache) │ (Multi-format) ││
│ │ GetFilePath() ✨ │ GetFilePath() ✨ │ Export logic) ││
│ │ GetDocsPath() ✨ │ GetDocsPath() ✨ │ ││
│ └─────────────────┴─────────────────┴─────────────────┘│
└─────────────────────┬───────────────────────────────────────────────┘
│ File System
┌─────────────────────▼───────────────────────────────────────────────┐
│ STORAGE LAYER │
│ ┌─────────────────┬─────────────────┬─────────────────┐│
│ │ JSON Files │ Markdown Files │ HTML Files ││
│ │ ({uuid}.json) │ (YYYY-MM-DD...) │ (YYYY-MM-DD...) ││
│ └─────────────────┴─────────────────┴─────────────────┘│
└───────────────────────────────────────────────────────────────────────┘______________________________________________________________________
📊 数据模型
投诉结构
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "AI-Coding-Assistant",
"session_name": "feature-development-session",
"task_description": "Missing API documentation for authentication endpoints",
"severity": "high",
"project_name": "user-management-system",
"timestamp": "2024-11-09T12:18:30Z",
"context_info": "Implementing OAuth2 authentication flow",
"missing_info": "API endpoint specifications, error response formats",
"confused_by": "Confusing token refresh mechanism",
"future_wishes": "Comprehensive API documentation with examples",
"resolved": false,
"resolved_at": null,
"resolved_by": "",
"file_path": "/Users/larsartmann/.local/share/complaints/550e8400-e29b-41d4-a716-446655440000.json",
"docs_path": "docs/complaints/2024-11-09_12-18-feature-development-session.md"
}严重程度级别
low-轻微不便，有解决方法medium-生产率受到重大影响，替代方案不明确high-阻碍者，没有明确的前进道路critical-系统故障，项目完全停滞
决议国
open-投诉已提交，等待解决resolved-问题已解决，时间戳已记录rejected-投诉已审查，视为无效deferred-推迟到以后审议
______________________________________________________________________
🗂️ 文件组织和存储
主存储（JSON）
{storage_base_dir}/{complaint_id}.json
Examples:
/Users/larsartmann/.local/share/complaints/550e8400-e29b-41d4-a716-446655440000.json
/var/lib/complaints/8f94a312-c5f7-4e2b-9ff1-0a3b4c8d7e2f.json文档导出（Markdown/HTML/文本）
{docs_dir}/{YYYY-MM-DD_HH-MM-SESSION_NAME}.{format}
Examples:
docs/complaints/2024-11-09_12-18-feature-development-session.md
docs/complaints/2024-11-09_14-32-api-integration-session.html
docs/complaints/2024-11-09_16-45-bug-fix-session.txt项目名称检测
- Git远程存储库名称 -主要来源
- 当前目录名称 -回退选项
- “未知项目” -最后手段违约
______________________________________________________________________
🛠️ 安装和设置
先决条件
- 使用模块实现1.21+
- Git（用于项目名称检测）
- 10MB可用磁盘空间
从源代码构建
# Clone repository
git clone https://github.com/LarsArtmann/complaints-mcp.git
cd complaints-mcp
# Build binary
go build -o complaints-mcp ./cmd/server
# Verify installation
./complaints-mcp --help配置
环境变量
export COMPLAINTS_MCP_SERVER_NAME="complaints-mcp"
export COMPLAINTS_MCP_SERVER_HOST="localhost"
export COMPLAINTS_MCP_SERVER_PORT=8080
export COMPLAINTS_MCP_STORAGE_BASE_DIR="$HOME/.local/share/complaints"
export COMPLAINTS_MCP_STORAGE_DOCS_DIR="docs/complaints"
export COMPLAINTS_MCP_STORAGE_DOCS_ENABLED=true
export COMPLAINTS_MCP_STORAGE_DOCS_FORMAT="markdown"
export COMPLAINTS_MCP_LOG_LEVEL="info"配置文件（YAML）
server:
name: "complaints-mcp"
host: "localhost"
port: 8080
storage:
base_dir: "$HOME/.local/share/complaints"
docs_dir: "docs/complaints"
docs_enabled: true
docs_format: "markdown"
max_size: 10485760 # 10MB
retention_days: 0 # Infinite retention
auto_backup: true
cache_enabled: true
cache_max_size: 1000
cache_eviction: "lru"
log:
level: "info"
format: "text"
output: "stdout"______________________________________________________________________
🚀 使用和集成
运行服务器
# Standard execution
./complaints-mcp
# With custom configuration
./complaints-mcp --config config/custom.yaml
# With environment variables
COMPLAINTS_MCP_SERVER_PORT=9090 ./complaints-mcpMCP工具接口
服务器公开了以下MCP工具：
文件投诉
{
"name": "file_complaint",
"description": "File a structured complaint about missing or confusing information",
"inputSchema": {
"type": "object",
"properties": {
"agent_name": { "type": "string", "minLength": 1, "maxLength": 100 },
"session_name": { "type": "string", "maxLength": 100 },
"task_description": { "type": "string", "minLength": 1, "maxLength": 1000 },
"context_info": { "type": "string", "maxLength": 500 },
"missing_info": { "type": "string", "maxLength": 500 },
"confused_by": { "type": "string", "maxLength": 500 },
"future_wishes": { "type": "string", "maxLength": 500 },
"severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
"project_name": { "type": "string", "maxLength": 100 }
},
"required": ["agent_name", "task_description", "severity"]
}
}列表_投诉
{
"name": "list_complaints",
"description": "Retrieve paginated list of complaints",
"inputSchema": {
"type": "object",
"properties": {
"limit": { "type": "integer", "minimum": 1, "maximum": 100 },
"severity": { "type": "string", "enum": ["low", "medium", "high", "critical"] },
"resolved": { "type": "boolean" }
}
}
}resolve_投诉
{
"name": "resolve_complaint",
"description": "Mark a complaint as resolved",
"inputSchema": {
"type": "object",
"properties": {
"complaint_id": {
"type": "string",
"pattern": "^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$"
},
"resolved_by": { "type": "string", "minLength": 1, "maxLength": 100 }
},
"required": ["complaint_id", "resolved_by"]
}
}搜索_投诉
{
"name": "search_complaints",
"description": "Search complaints by content",
"inputSchema": {
"type": "object",
"properties": {
"query": { "type": "string", "minLength": 1, "maxLength": 200 },
"limit": { "type": "integer", "minimum": 1, "maximum": 50 }
},
"required": ["query"]
}
}get_ache_stats
{
"name": "get_cache_stats",
"description": "Get cache performance statistics",
"inputSchema": {
"type": "object",
"properties": {}
}
}AI助手集成
粉碎集成
添加到您的Crush配置(.crush.json):
{
"$schema": "https://charm.land/crush.json",
"mcp": {
"complaints": {
"type": "stdio",
"command": "/path/to/complaints-mcp",
"args": ["--config", "/path/to/config.yaml"],
"timeout": 120,
"disabled": false
}
}
}Claude集成
添加到您的Claude桌面配置：
{
"mcpServers": {
"complaints-mcp": {
"command": "/path/to/complaints-mcp",
"args": ["--config", "/path/to/config.yaml"]
}
}
}______________________________________________________________________
📋 示例使用场景
场景1：缺少API文档
{
"agent_name": "AI-Coding-Assistant",
"session_name": "api-auth-implementation",
"task_description": "Implement OAuth2 authentication endpoints",
"context_info": "Working on user management microservice",
"missing_info": "Complete API specification for /auth/refresh endpoint",
"confused_by": "Token rotation logic unclear from requirements",
"future_wishes": "OpenAPI specification with Postman collection",
"severity": "high",
"project_name": "user-management-system"
}场景2：混淆错误消息
{
"agent_name": "Bug-Fix-Assistant",
"session_name": "memory-leak-debugging",
"task_description": "Fix memory leak in data processing pipeline",
"context_info": "Analyzing heap dumps, processing large datasets",
"missing_info": "Clear explanation of error code 'ERR_MEM_CORRUPT'",
"confused_by": "Error message suggests hardware failure but logs show software issue",
"future_wishes": "Comprehensive error code documentation with troubleshooting steps",
"severity": "medium",
"project_name": "data-processor"
}通过文件路径增强响应
{
"success": true,
"message": "Complaint filed successfully",
"complaint": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"agent_name": "AI-Coding-Assistant",
"task_description": "Missing API documentation",
"severity": "high",
"timestamp": "2024-11-09T12:18:30Z",
"resolved": false,
"file_path": "/Users/larsartmann/.local/share/complaints/550e8400-e29b-41d4-a716-446655440000.json",
"docs_path": "docs/complaints/2024-11-09_12-18-api-auth-implementation.md"
}
}______________________________________________________________________
🔧 开发与测试
项目结构
complaints-mcp/
├── cmd/server/ # Application entry point
├── internal/
│ ├── config/ # Configuration management
│ ├── delivery/mcp/ # MCP server implementation
│ ├── domain/ # Business logic & entities
│ ├── repo/ # Data access layer
│ ├── service/ # Business orchestration
│ ├── tracing/ # Observability
│ └── types/ # Type definitions
├── features/bdd/ # Behavioral tests
├── docs/ # Project documentation
└── examples/ # Usage examples运行测试
# Run all tests
just test
# Run specific test suite
go test ./internal/domain -v
# Run BDD tests
go test ./features/bdd -v
# Run with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out建设促进发展
# Build with race detection
go build -race -o complaints-mcp ./cmd/server
# Build for different platforms
GOOS=linux GOARCH=amd64 go build -o complaints-mcp-linux ./cmd/server
GOOS=windows GOARCH=amd64 go build -o complaints-mcp.exe ./cmd/server
# Build with debug symbols
go build -gcflags="all=-N -l" -o complaints-mcp-debug ./cmd/server______________________________________________________________________
📊 性能与监控
高速缓存性能
{
"cache_enabled": true,
"stats": {
"hits": 1247,
"misses": 89,
"evictions": 12,
"current_size": 156,
"max_size": 1000,
"hit_rate": 0.9332
}
}监控指标
- 请求率：每分钟/小时/天的平均投诉数
- 解决时间：从提交到解决的时间
- 存储使用情况：按投诉数据分列的磁盘空间消耗
- 缓存效率：命中率、驱逐模式
- 错误率：每个时间段的失败操作
日志级别
trace-详细的执行跟踪debug-开发调试信息info-一般操作信息warn-非关键问题和弃用error-需要注意的失败操作
______________________________________________________________________
🔐 安全注意事项
数据隐私
- 投诉存储在用户控制的本地位置
- 无外部数据传输或云存储
- 文件权限尊重系统umask设置
- 在适当级别记录敏感信息
访问控制
- 文件系统访问尊重用户权限
- 本地使用无需身份验证
- 默认情况下禁用网络访问（stdio传输）
- 由用户权限控制的配置文件访问
输入验证
- 具有长度限制的严格输入验证
- 清除文件路径以防止目录遍历
- SQL注入防护（不适用于JSON存储）
- 所有字符串操作中的缓冲区溢出保护
______________________________________________________________________
🔄 迁移和升级
版本兼容性
- 向后兼容：支持所有现有的JSON文件
- 配置迁移：自动检测旧配置格式
- API稳定性：跨版本维护MCP工具合同
- 数据迁移：用于传统格式的内置转换实用程序
升级过程
# Backup existing data
cp -r ~/.local/share/complaints ~/.local/share/complaints.backup
# Upgrade binary
go build -o complaints-mcp ./cmd/server
# Run migration (automatic on first run)
./complaints-mcp --migrate
# Verify data integrity
./complaints-mcp --verify______________________________________________________________________
🐛 故障排除
常见问题
服务器无法启动
# Check configuration
./complaints-mcp --validate-config
# Check permissions
ls -la ~/.local/share/complaints/
# Check port availability
lsof -i :8080投诉不保存
# Check disk space
df -h ~/.local/share/
# Check file permissions
touch ~/.local/share/complaints/test.json
# Review logs
./complaints-mcp --log-level debug性能问题
# Check cache statistics
echo '{"tool": "get_cache_stats"}' | ./complaints-mcp
# Monitor memory usage
./complaints-mcp --profile-memory
# Benchmark operations
go test -bench=. ./internal/repo/调试模式
# Enable comprehensive debugging
COMPLAINTS_MCP_LOG_LEVEL=debug ./complaints-mcp --trace
# Generate bug report
./complaints-mcp --bug-report > bug-report.txt
# Validate data integrity
./complaints-mcp --validate-data______________________________________________________________________
📚 文档和资源
项目文档
外部引用
社区与支持
______________________________________________________________________
🤝 贡献
我们欢迎捐款！看 贡献.md 详细指南。
开发工作流程
- Fork存储库
- 创建特征分支(
git checkout -b feature/amazing-feature) - 提交更改(
git commit -m 'Add amazing feature') - 推送到分支(
git push origin feature/amazing-feature) - 打开拉取请求
代码规范
- 遵循围棋惯例
gofmt格式化 - 保持测试覆盖率在80%以上
- 为新功能添加全面的BDD测试
- 更新API变更文档
- 确保向后兼容性
______________________________________________________________________
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
______________________________________________________________________
🎯 路线图和未来发展
计划的功能
- \[ \] 插件架构 -可扩展工具系统
- \[ \] 高级搜索 -过滤、排序、分面搜索
- \[ \] 分析仪表板 -基于Web的监控界面
- \[ \] 导入/导出 -批量数据管理
- \[ \] API服务器 -RESTful HTTP接口选项
长远愿景
- \[ \] 多租户支持 -组织级隔离
- \[ \] 事件溯源 -完成审计跟踪和回放
- \[ \] 机器学习 -自动分类和优先级排序
- \[ \] 集成中心 -与外部问题跟踪器连接
- \[ \] 移动应用程序 -本地移动投诉提交
______________________________________________________________________
🏆 致谢
- 模型上下文协议团队 -卓越的MCP规格
- 魅力手镯 -优秀的Go库和工具
- 围棋界 -持续改进语言
- 开源贡献者 -获得宝贵的反馈和贡献
______________________________________________________________________
制作❤️ 由AI代理，为AI代理