Code Knowledge RAG MCP

一个基于 Model Context Protocol (MCP) 的代码知识检索增强生成服务器，专门用于存储和检索代码优化案例、提交记录和技术文档。

🚀 功能特性

• 多类型知识存储：支持代码案例、Git提交记录和技术手册的存储
• 向量化检索：基于语义相似度的智能知识检索
• 性能优化专用：针对性能热点优化场景设计的知识管理
• MCP协议支持：完全兼容 Model Context Protocol 标准
• 多种部署方式：支持 stdio 和 HTTP 两种传输模式
• Docker化部署：提供完整的容器化解决方案

📋 系统要求

• Python 3.13+
• Docker (可选，用于容器化部署)
• 嵌入服务API访问权限

🛠️ 安装与配置

1. 环境配置

复制环境变量模板并配置：

cp .env.example .env

编辑 .env 文件，配置以下关键参数：

# 嵌入服务配置
EMBEDDING_SERVICE__PROVIDER=tp-link
EMBEDDING_SERVICE__API_KEY=your_api_key_here
EMBEDDING_SERVICE__API_BASE=https://your-api-endpoint.com/v1/embeddings
EMBEDDING_SERVICE__MODEL=your_embedding_model

# 存储路径
STORAGE__VECTOR_STORE_PATH=./data/vector_store
STORAGE__COMMIT_PARENT_STORAGE_PATH=./data/commit_parent_docstore
STORAGE__CASE_PARENT_STORAGE_PATH=./data/case_parent_docstore

# MCP服务器配置（推荐使用 streamable-http）
MCP_SERVER__TRANSPORT=streamable-http
MCP_SERVER__HOST=localhost
MCP_SERVER__PORT=11462

2. 依赖安装

使用 uv 包管理器：

# 安装 uv
pip install uv

# 安装项目依赖
uv sync

🚀 运行方式

推荐方式：Docker 部署

# 构建镜像
docker-compose build

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f

方式二：直接运行（开发环境）

# 使用 uv 运行
uv run python -m code_knowledge_rag_mcp

# 或者激活虚拟环境后运行
uv shell
python -m code_knowledge_rag_mcp

🧪 测试与验证

使用 MCP Inspector 测试

推荐使用 MCP Inspector 来测试和调试服务器功能。MCP Inspector 提供了直观的 Web UI 界面：

快速启动测试

# 1. 启动服务器（Docker 方式）
docker-compose up -d

# 2. 启动 MCP Inspector UI
npx @modelcontextprotocol/inspector

# 3. 在浏览器中打开 http://localhost:6274

连接配置

在 Inspector UI 中配置连接参数：

• 传输类型: Streamable HTTP
• 服务器 URL: http://localhost:11462/mcp

测试功能

通过 Inspector UI 可以：

• 📋 浏览所有可用的工具和资源
• ⚡ 交互式测试工具调用（如 store_knowledge）
• 🔍 查看资源内容（如 knowledge://statistics）
• 🐛 实时调试参数和响应格式
• 📊 验证知识检索功能

📚 MCP 工具和资源

工具 (Tools)

store_knowledge

向知识库存储代码案例、提交记录或技术文档

参数：

• knowledge_type: 知识类型 (case, commit, manual)
• knowledge_data: 知识数据对象

示例：

{
  "knowledge_type": "case",
  "knowledge_data": {
    "title": "分支预测优化案例",
    "content": "通过重构条件判断逻辑减少分支预测失误...",
    "type": "perf_based_optimization",
    "language": "c",
    "source_type": "manual_input",
    "tags": ["performance", "branch-prediction"],
    "perf_event": "branch-load-misses"
  }
}

search_hot_point_optimization

基于性能热点及其上下文检索相关优化知识

参数：

• context_summary: 性能热点及相关上下文的摘要描述
• perf_event: 性能事件类型

delete_knowledge

根据知识ID删除知识库中的数据

参数：

• knowledge_id: 要删除的知识数据ID

资源 (Resources)

knowledge://statistics

获取知识库统计信息，包括总数量、各类型数量、最后更新时间等

knowledge://knowledge-data-schemas

获取知识数据的结构模式和验证规则

knowledge://perf-events

获取支持的性能事件类型列表

🏗️ 项目结构

code-knowledge-rag-mcp/
├── src/code_knowledge_rag_mcp/
│   ├── __init__.py
│   ├── __main__.py          # 程序入口
│   ├── server.py            # MCP服务器实现
│   ├── config.py            # 配置管理
│   ├── data_models.py       # 数据模型定义
│   ├── knowledge_service.py # 知识存储和检索服务
│   ├── embeddings.py        # 嵌入服务封装
│   ├── resources.py         # MCP资源提供者
│   ├── local_file_store.py  # 本地文件存储
│   └── utils.py             # 工具函数
├── docs/                    # 项目文档
├── .env.example             # 环境变量模板
├── docker-compose.yml       # Docker编排文件
├── Dockerfile               # Docker镜像定义
├── pyproject.toml           # 项目配置
└── README.md                # 项目说明

🔧 配置说明

嵌入服务配置

项目支持多种嵌入服务提供商，通过环境变量配置：

EMBEDDING_SERVICE__PROVIDER=tp-link
EMBEDDING_SERVICE__API_KEY=your_api_key
EMBEDDING_SERVICE__API_BASE=https://api-endpoint.com/v1/embeddings
EMBEDDING_SERVICE__MODEL=embedding_model_name
EMBEDDING_SERVICE__MAX_INPUT_CHARS=2000
EMBEDDING_SERVICE__PERIOD_MAX_CALL=20
EMBEDDING_SERVICE__PERIOD=60

MCP服务器配置

推荐使用 streamable-http 模式，特别是在Docker环境中：

MCP_SERVER__TRANSPORT=streamable-http
MCP_SERVER__HOST=localhost
MCP_SERVER__PORT=11462

存储配置

STORAGE__VECTOR_STORE_PATH=./data/vector_store
STORAGE__COMMIT_PARENT_STORAGE_PATH=./data/commit_parent_docstore
STORAGE__CASE_PARENT_STORAGE_PATH=./data/case_parent_docstore

文档处理配置

DOCUMENT_PROCESSING__CASE_CHILD_CHUNK_SIZE=2000
DOCUMENT_PROCESSING__CASE_CHILD_CHUNK_OVERLAP=200
DOCUMENT_PROCESSING__MAX_DOCUMENT_SIZE=20971520  # 20MB

📊 支持的性能事件类型

• cycles: CPU周期数
• branch-load-misses: 分支预测失误
• L1-icache-load-misses: L1指令缓存失误
• L1-dcache-load-misses: L1数据缓存失误

🔍 使用示例

存储代码优化案例

# 通过MCP客户端调用
await mcp_client.call_tool("store_knowledge", {
    "knowledge_type": "case",
    "knowledge_data": {
        "title": "循环展开优化",
        "content": "通过手动展开循环减少分支跳转...",
        "type": "perf_based_optimization",
        "language": "c",
        "source_type": "manual_input",
        "tags": ["loop-unrolling", "performance"],
        "perf_event": "cycles"
    }
})

检索优化知识

# 基于热点上下文检索
await mcp_client.call_tool("search_hot_point_optimization", {
    "context_summary": "函数foo中的条件分支导致大量分支预测失误",
    "perf_event": "branch-load-misses"
})

🐛 故障排除

常见问题

1. 嵌入服务连接失败

   • 检查API密钥和端点配置
   • 确认网络连接正常

2. 向量存储初始化失败

   • 检查存储路径权限
   • 确保磁盘空间充足

3. Docker部署问题

   • 检查端口占用情况
   • 确认环境变量配置正确

日志查看

# 查看应用日志
tail -f logs/debug_app.log

# Docker环境查看日志
docker-compose logs -f

🤝 贡献指南

欢迎贡献代码和建议！请遵循以下步骤：

1. 创建特性分支进行开发
2. 确保代码符合项目规范
3. 添加必要的测试和文档
4. 提交清晰的提交信息

📄 许可证

本项目采用 MIT 许可证。

📞 支持

如有问题或建议，请联系项目维护者或查看项目文档。

---

注意: 本项目专为代码性能优化场景设计，特别适用于基于性能分析数据的代码优化知识管理。