mcp-case-knowledge

v1.0.1

Published

6 months ago

MCP Case Knowledge System - Intelligent debug case management and retrieval

0High
0Medium
0Low

mcp model-context-protocol debug knowledge-management case-based-reasoning developer-tools ai-assistant claude typescript sqlite

🧠 MCP Case Knowledge Server

智能调试案例知识管理系统 - 基于 Model Context Protocol (MCP)

一个强大的 MCP 服务，帮助开发者存储、搜索和分析调试案例，提升团队的问题解决效率。

🚀 核心特性

📚 智能案例管理

自动分类: 基于问题描述自动分类案例（UI/UX、性能、安全等）
智能标签: 自动提取技术标签和关键词
版本化存储: 支持案例更新和历史记录
批量导入: 支持从现有文档批量导入案例

🔍 强大搜索引擎

语义搜索: 基于向量嵌入的语义相似度搜索
关键词搜索: 传统关键词匹配搜索
混合搜索: 结合语义和关键词的最佳搜索体验
智能过滤: 按分类、标签、框架、复杂度等多维度过滤

📊 数据洞察分析

使用统计: 案例查看、应用次数统计
成功率分析: 解决方案有效性跟踪
趋势分析: 问题类型和解决方案趋势
热门标签: 最常见的技术问题分析

⚡ 高性能架构

SQLite + Drizzle ORM: 轻量级但功能完整的数据存储
本地向量搜索: 无需外部依赖的语义搜索
智能缓存: 多层缓存优化查询性能
异步处理: 非阻塞的案例处理流程

🛠️ 安装和配置

系统要求

Node.js >= 18.0.0
TypeScript >= 5.0
SQLite3 支持

快速开始

安装依赖

cd mcp-case-knowledge
npm install

构建项目

npm run build

运行测试

npm test

启动服务器

npm run dev
# 或者运行构建版本
node dist/index.js

MCP 客户端配置

在您的 MCP 客户端配置中添加以下配置：

{
  "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 - 存储调试案例

存储新的调试案例，包含问题描述、分析过程和解决方案。

{
  "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 - 搜索相似案例

使用自然语言搜索相似的调试案例。

{
  "name": "search-cases",
  "arguments": {
    "query": "React 组件不渲染内容",
    "filters": {
      "category": "ui-ux",
      "framework": "react"
    },
    "limit": 5,
    "options": {
      "mode": "hybrid",
      "threshold": 0.5
    }
  }
}

3. get-case-details - 获取案例详情

获取指定案例的完整详细信息。

{
  "name": "get-case-details",
  "arguments": {
    "caseId": "case-uuid-here",
    "includeStatistics": true
  }
}

4. update-case-stats - 更新案例统计

记录案例应用结果和用户反馈。

{
  "name": "update-case-stats",
  "arguments": {
    "caseId": "case-uuid-here",
    "success": true,
    "timeToResolve": 15,
    "feedback": "helpful"
  }
}

5. get-insights - 获取数据洞察

获取案例库的统计洞察和趋势分析。

{
  "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: 统一错误处理和日志记录

数据模型

核心实体

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        # 服务器入口

开发流程

添加新功能
- 更新类型定义 (types/)
- 实现业务逻辑 (services/)
- 创建 MCP 工具 (tools/)
- 添加单元测试 (tests/)
数据库变更
- 修改 schema (db/schema.ts)
- 生成迁移文件 (npm run db:generate)
- 运行迁移 (npm run db:migrate)
测试策略
- 单元测试：服务和工具函数
- 集成测试：MCP 工具端到端测试
- 性能测试：搜索引擎性能基准

代码规范

TypeScript 严格模式: 所有代码必须通过严格类型检查
错误处理: 使用 Result 模式进行统一错误处理
文档注释: 所有公共 API 必须有 JSDoc 注释
性能优化: 搜索响应时间 < 100ms

🧪 测试

运行测试

# 运行所有测试
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% | 语义搜索相关性准确率 |

优化策略

数据库优化
- 智能索引策略
- 查询优化
- 连接池管理
搜索优化
- 向量索引缓存
- 批量搜索处理
- 结果缓存机制
内存管理
- 对象池复用
- 垃圾回收优化
- 内存泄漏检测

🔄 与 SuperClaude 框架集成

自动触发机制

当用户描述遇到的问题时，系统会自动：

检测问题模式: 识别 "效果不工作"、"没有反应" 等关键词
搜索相似案例: 自动搜索相关的解决方案
提供建议策略: 基于历史成功案例提供解决建议
记录解决过程: 成功解决后自动存储新案例

工作流集成

// 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: 企业级特性 (规划中)

⏳ 分布式搜索
⏳ 高可用部署
⏳ 安全加固
⏳ 监控告警

🤝 贡献指南

我们欢迎社区贡献！请遵循以下步骤：

Fork 项目 并创建特性分支
编写代码 并确保通过所有测试
更新文档 包括 API 和使用示例
提交 PR 并描述您的更改

贡献类型

🐛 Bug 修复
✨ 新功能开发
📚 文档改进
⚡ 性能优化
🧪 测试用例

📄 许可证

本项目采用 MIT 许可证。详情请查看 LICENSE 文件。

🙏 致谢

Model Context Protocol - 提供优秀的协议规范
Drizzle ORM - 类型安全的 ORM 框架
SQLite - 可靠的嵌入式数据库
SuperClaude Framework - 智能开发助手框架

📞 支持

如果您遇到问题或有建议，请：

查看 FAQ
搜索已知问题
创建新的 Issue
加入我们的讨论

MCP Case Knowledge System - 让调试经验成为团队的共同财富 🚀

开发者：ahwq
版本：v1.0.0
更新时间：2025-01-22