mcp-case-knowledge

# 🧠 MCP Case Knowledge Server > 智能调试案例知识管理系统 - 基于 Model Context Protocol (MCP) 一个强大的 MCP 服务，帮助开发者存储、搜索和分析调试案例，提升团队的问题解决效率。 [![npm version](https://badge.fury.io/js/mcp-case-knowledge.svg)](https://www.npmjs.com/package/mcp-case-knowledge) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/) ## 🚀 核心特性 ### 📚 智能案例管理 - **自动分类**: 基于问题描述自动分类案例（UI/UX、性能、安全等） - **智能标签**: 自动提取技术标签和关键词 - **版本化存储**: 支持案例更新和历史记录 - **批量导入**: 支持从现有文档批量导入案例 ### 🔍 强大搜索引擎 - **语义搜索**: 基于向量嵌入的语义相似度搜索 - **关键词搜索**: 传统关键词匹配搜索 - **混合搜索**: 结合语义和关键词的最佳搜索体验 - **智能过滤**: 按分类、标签、框架、复杂度等多维度过滤 ### 📊 数据洞察分析 - **使用统计**: 案例查看、应用次数统计 - **成功率分析**: 解决方案有效性跟踪 - **趋势分析**: 问题类型和解决方案趋势 - **热门标签**: 最常见的技术问题分析 ### ⚡ 高性能架构 - **SQLite + Drizzle ORM**: 轻量级但功能完整的数据存储 - **本地向量搜索**: 无需外部依赖的语义搜索 - **智能缓存**: 多层缓存优化查询性能 - **异步处理**: 非阻塞的案例处理流程 ## 🛠️ 安装和配置 ### 系统要求 - Node.js >= 18.0.0 - TypeScript >= 5.0 - SQLite3 支持 ### 快速开始 1. **安装依赖** ```bash cd mcp-case-knowledge npm install ``` 2. **构建项目** ```bash npm run build ``` 3. **运行测试** ```bash npm test ``` 4. **启动服务器** ```bash npm run dev # 或者运行构建版本 node dist/index.js ``` ### MCP 客户端配置在您的 MCP 客户端配置中添加以下配置： ```json { "mcpServers": { "case-knowledge": { "command": "node", "args": ["mcp-case-knowledge"], "env": { "DATABASE_PATH": "~/.claude/case-knowledge.db", "LOG_LEVEL": "info", "ENABLE_METRICS": "true" } } } } ``` ### 环境变量 | 变量名 | 默认值 | 描述 | |--------|--------|------| | `DATABASE_PATH` | `case-knowledge.db` | 数据库文件路径 | | `LOG_LEVEL` | `info` | 日志级别 (debug, info, warn, error) | | `ENABLE_METRICS` | `false` | 是否启用性能指标收集 | | `MAX_CONNECTIONS` | `10` | 最大并发连接数 | ## 📖 API 文档 ### MCP 工具接口 #### 1. store-case - 存储调试案例存储新的调试案例，包含问题描述、分析过程和解决方案。 ```typescript { "name": "store-case", "arguments": { "title": "React 组件渲染异常", "problem": { "description": "组件在特定条件下不渲染内容", "symptoms": ["页面显示空白", "控制台无错误"], "userFeedback": "用户反馈页面加载后显示空白" }, "analysis": { "rootCause": ["条件渲染逻辑错误", "状态更新时机问题"], "layersAffected": ["logic", "visual"], "toolsUsed": ["React DevTools", "浏览器调试器"] }, "solution": { "summary": "修复条件渲染逻辑并优化状态更新", "steps": [ { "order": 1, "description": "检查组件的条件渲染逻辑", "reasoning": "定位渲染失败的根本原因" } ], "codeChanges": [ { "filePath": "src/components/MyComponent.tsx", "changeType": "modify", "language": "typescript" } ], "verification": ["组件正常渲染", "用户交互正常"] } } } ``` #### 2. search-cases - 搜索相似案例使用自然语言搜索相似的调试案例。 ```typescript { "name": "search-cases", "arguments": { "query": "React 组件不渲染内容", "filters": { "category": "ui-ux", "framework": "react" }, "limit": 5, "options": { "mode": "hybrid", "threshold": 0.5 } } } ``` #### 3. get-case-details - 获取案例详情获取指定案例的完整详细信息。 ```typescript { "name": "get-case-details", "arguments": { "caseId": "case-uuid-here", "includeStatistics": true } } ``` #### 4. update-case-stats - 更新案例统计记录案例应用结果和用户反馈。 ```typescript { "name": "update-case-stats", "arguments": { "caseId": "case-uuid-here", "success": true, "timeToResolve": 15, "feedback": "helpful" } } ``` #### 5. get-insights - 获取数据洞察获取案例库的统计洞察和趋势分析。 ```typescript { "name": "get-insights", "arguments": { "timeRange": "month", "groupBy": "category" } } ``` ## 🏗️ 架构设计 ### 系统架构 ``` ┌─────────────────────────────────────────┐ │ MCP Client (Claude) │ ├─────────────────────────────────────────┤ │ MCP Protocol │ ├─────────────────────────────────────────┤ │ Case Knowledge Server │ │ ┌─────────┐ ┌─────────┐ ┌────────────┐ │ │ │ Storage │ │ Search │ │ Embedding │ │ │ │ Service │ │ Engine │ │ Service │ │ │ └─────────┘ └─────────┘ └────────────┘ │ ├─────────────────────────────────────────┤ │ SQLite + Drizzle ORM │ └─────────────────────────────────────────┘ ``` ### 核心组件 #### 数据层 (Data Layer) - **Database Schema**: 使用 Drizzle ORM 定义的类型安全数据模型 - **Migration System**: 版本化数据库迁移管理 - **Connection Pool**: 智能连接池管理 #### 服务层 (Service Layer) - **CaseStorageService**: 案例存储、更新、删除服务 - **CaseSearchEngine**: 多模式搜索引擎 - **EmbeddingService**: 向量嵌入生成服务 - **TemplateEngine**: 解决方案模板适配引擎 #### 工具层 (Tools Layer) - **MCP Tools**: 标准 MCP 工具接口实现 - **Input Validation**: 严格的输入数据验证 - **Error Handling**: 统一错误处理和日志记录 ### 数据模型 #### 核心实体 ```typescript interface DebugCase { id: string; // UUID title: string; // 案例标题 category: CaseCategory; // 分类 tags: string[]; // 标签数组 problem: ProblemDescription; // 问题描述 analysis: CaseAnalysis; // 分析过程 solution: CaseSolution; // 解决方案 metadata: CaseMetadata; // 元数据 statistics: CaseStatistics; // 使用统计 } ``` #### 关系模型 - **Cases (1) → (N) Tags**: 案例可以有多个标签 - **Cases (1) → (1) Statistics**: 每个案例有对应的统计信息 - **Cases (1) → (1) SearchIndex**: 每个案例有对应的搜索索引 - **Cases (1) → (N) ApplicationHistory**: 案例可以有多次应用记录 ## 🔧 开发指南 ### 项目结构 ``` src/ ├── types/ # TypeScript 类型定义 │ ├── case.ts # 案例相关类型 │ ├── common.ts # 通用类型和错误 │ ├── mcp.ts # MCP 协议类型 │ └── index.ts # 类型导出 ├── db/ # 数据库层 │ ├── schema.ts # Drizzle 数据模型 │ ├── client.ts # 数据库客户端 │ └── index.ts # 数据库导出 ├── services/ # 业务服务层 │ ├── caseStorage.ts # 案例存储服务 │ ├── searchEngine.ts # 搜索引擎 │ ├── embedding.ts # 嵌入向量服务 │ └── index.ts # 服务导出 ├── tools/ # MCP 工具实现 │ ├── store-case.ts # 存储案例工具 │ ├── search-cases.ts # 搜索案例工具 │ ├── insights.ts # 洞察分析工具 │ └── index.ts # 工具导出 ├── utils/ # 工具函数 │ ├── validation.ts # 数据验证 │ ├── nlp.ts # NLP 工具 │ ├── similarity.ts # 相似度计算 │ └── index.ts # 工具导出 └── index.ts # 服务器入口 ``` ### 开发流程 1. **添加新功能** - 更新类型定义 (`types/`) - 实现业务逻辑 (`services/`) - 创建 MCP 工具 (`tools/`) - 添加单元测试 (`tests/`) 2. **数据库变更** - 修改 schema (`db/schema.ts`) - 生成迁移文件 (`npm run db:generate`) - 运行迁移 (`npm run db:migrate`) 3. **测试策略** - 单元测试：服务和工具函数 - 集成测试：MCP 工具端到端测试 - 性能测试：搜索引擎性能基准 ### 代码规范 - **TypeScript 严格模式**: 所有代码必须通过严格类型检查 - **错误处理**: 使用 Result 模式进行统一错误处理 - **文档注释**: 所有公共 API 必须有 JSDoc 注释 - **性能优化**: 搜索响应时间 < 100ms ## 🧪 测试 ### 运行测试 ```bash # 运行所有测试 npm test # 运行测试覆盖率报告 npm run test:coverage # 运行性能基准测试 npm run test:benchmark ``` ### 测试结构 ``` tests/ ├── unit/ # 单元测试 │ ├── services/ # 服务层测试 │ ├── utils/ # 工具函数测试 │ └── tools/ # MCP 工具测试 └── integration/ # 集成测试 ├── database/ # 数据库测试 ├── search/ # 搜索功能测试 └── mcp/ # MCP 协议测试 ``` ## 📊 性能指标 ### 性能目标 | 指标 | 目标值 | 说明 | |------|--------|------| | 搜索响应时间 | < 100ms | 语义搜索平均响应时间 | | 存储响应时间 | < 200ms | 案例存储平均响应时间 | | 数据库大小 | < 100MB | 10,000 个案例的数据库大小 | | 内存使用 | < 256MB | 服务器峰值内存使用 | | 搜索准确率 | > 85% | 语义搜索相关性准确率 | ### 优化策略 1. **数据库优化** - 智能索引策略 - 查询优化 - 连接池管理 2. **搜索优化** - 向量索引缓存 - 批量搜索处理 - 结果缓存机制 3. **内存管理** - 对象池复用 - 垃圾回收优化 - 内存泄漏检测 ## 🔄 与 SuperClaude 框架集成 ### 自动触发机制当用户描述遇到的问题时，系统会自动： 1. **检测问题模式**: 识别 "效果不工作"、"没有反应" 等关键词 2. **搜索相似案例**: 自动搜索相关的解决方案 3. **提供建议策略**: 基于历史成功案例提供解决建议 4. **记录解决过程**: 成功解决后自动存储新案例 ### 工作流集成 ```typescript // SuperClaude 检测引擎集成示例 export const caseKnowledgeIntegration = { detection: { triggers: ["效果不工作", "没有反应", "功能失效"], async onTrigger(userInput: string, context: any) { const similarCases = await searchCases({ query: userInput, filters: { framework: context.project.frameworks }, limit: 3 }); return { suggestedApproach: similarCases[0], confidence: similarCases[0]?.similarity || 0 }; } } }; ``` ## 🛣️ 开发路线图 ### Phase 1: MVP (已完成) - ✅ 基础数据模型和存储 - ✅ 搜索引擎实现 - ✅ MCP 工具接口 - ✅ 基本功能测试 ### Phase 2: 功能完善 (进行中) - 🔄 解决方案模板引擎 - 🔄 高级搜索过滤器 - 🔄 性能优化 - ⏳ 集成测试完善 ### Phase 3: 扩展功能 (计划中) - ⏳ 多语言支持 (中英文) - ⏳ 团队协作功能 - ⏳ Web UI 管理界面 - ⏳ 外部 API 集成 ### Phase 4: 企业级特性 (规划中) - ⏳ 分布式搜索 - ⏳ 高可用部署 - ⏳ 安全加固 - ⏳ 监控告警 ## 🤝 贡献指南我们欢迎社区贡献！请遵循以下步骤： 1. **Fork 项目** 并创建特性分支 2. **编写代码** 并确保通过所有测试 3. **更新文档** 包括 API 和使用示例 4. **提交 PR** 并描述您的更改 ### 贡献类型 - 🐛 Bug 修复 - ✨ 新功能开发 - 📚 文档改进 - ⚡ 性能优化 - 🧪 测试用例 ## 📄 许可证本项目采用 MIT 许可证。详情请查看 [LICENSE](LICENSE) 文件。 ## 🙏 致谢 - [Model Context Protocol](https://modelcontextprotocol.io) - 提供优秀的协议规范 - [Drizzle ORM](https://orm.drizzle.team) - 类型安全的 ORM 框架 - [SQLite](https://sqlite.org) - 可靠的嵌入式数据库 - [SuperClaude Framework](https://github.com) - 智能开发助手框架 ## 📞 支持如果您遇到问题或有建议，请： 1. 查看 [FAQ](docs/FAQ.md) 2. 搜索 [已知问题](issues) 3. 创建新的 [Issue](issues/new) 4. 加入我们的 [讨论](discussions) --- **MCP Case Knowledge System** - 让调试经验成为团队的共同财富 🚀 开发者：ahwq 版本：v1.0.0 更新时间：2025-01-22