基于LlamaIndex的持久化代码 MCP 服务器

一个模型上下文协议 (MCP) 服务器，用于创建和维护由 Claude 生成的代码的语义知识图谱。由 LlamaIndex 驱动，这允许跨会话维护上下文，并具有高级语义搜索功能，而无需将整个代码库都放在上下文窗口中。

问题 & 解决方案

当使用 Claude 开发软件时：

• 上下文窗口有限，使得处理大型代码库变得困难
• 之前的代码上下文在会话之间丢失
• Claude 缺乏对项目结构的持久理解
• 在每个会话中都需要冗余的代码解释
• 维护实现一致性具有挑战性

Persistent-Code 通过以下方式解决这些问题：

• 创建代码组件及其关系的知识图谱
• 跟踪每个组件的实现状态
• 提供导航、查询和理解代码库的工具
• 为特定的编码任务组装最少的必要上下文
• 在聊天会话中保持持久的知识

LlamaIndex 集成

Persistent-Code 利用 LlamaIndex 提供增强的语义理解：

1. 语义搜索：基于含义查找代码组件，而不仅仅是关键字
2. 向量嵌入：代码被嵌入到向量空间中以进行相似性匹配
3. 知识图谱：组件之间的关系以语义方式跟踪
4. 上下文检索：基于语义相关性检索相关代码

这种集成使 Claude 能够更深入地理解您的代码库：

• 根据函数的功能查找函数，而不仅仅是它们的名称
• 在准备上下文时获取更相关的代码组件
• 更好地理解组件之间的关系
• 更准确地检索类似实现的示例

安装

前提条件

• Python 3.10 或更高版本
• UV 包管理器（推荐）或 pip

设置

# 克隆仓库
git clone https://github.com/your-username/persistent-code-mcp.git
cd persistent-code-mcp

# 使用 UV 设置环境
uv venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
uv pip install -r requirements.txt

# 或者使用 pip
python -m venv venv
source venv/bin/activate  # 在 Windows 上：venv\Scripts\activate
pip install -r requirements.txt

用法

初始化项目

python -m persistent_code init --project-name "YourProject"

启动服务器

python -m persistent_code serve --project-name "YourProject"

为桌面版 Claude 配置

1. 编辑您的桌面版 Claude 配置文件：
   • 位置：~/Library/Application Support/Claude/claude_desktop_config.json
   • 添加以下配置：

{
  "mcpServers": {
    "persistent-code": {
      "command": "venv 中 python 的路径",
      "args": [
        "-m",
        "persistent_code",
        "serve",
        "--project-name",
        "default"
      ],
      "cwd": "persistent-code-mcp",
      "env": {
        "PYTHONPATH": "persistent-code-mcp 的绝对路径"
      }
    }
  }
}

2. 重启桌面版 Claude
3. 通过询问 Claude 关于您的代码来连接到您的 MCP 服务器

可用工具

知识图谱管理

• add_component: 向图谱添加新的代码组件
• update_component: 更新现有组件
• add_relationship: 创建组件之间的关系

代码检索和导航

• get_component: 按 ID 或名称检索组件
• find_related_components: 查找与给定组件相关的组件
• search_code: 以语义方式搜索代码库

状态管理

• update_status: 更新组件的实现状态
• get_project_status: 检索整个项目的实现状态
• find_next_tasks: 建议要实现的下一个逻辑组件

上下文组装

• prepare_context: 为特定任务组装最少的上下文
• continue_implementation: 提供上下文以继续实现组件
• get_implementation_plan: 生成实现待处理组件的计划

代码分析

• analyze_code: 分析代码并更新知识图谱

示例工作流程

1. 初始化一个项目：

   python -m persistent_code init --project-name "TodoApp"
   

2. 启动服务器：

   python -m persistent_code serve --project-name "TodoApp"
   

3. 要求 Claude 设计您的项目：

   你能帮我用 Python 和 FastAPI 设计一个 Todo 应用程序吗？ 让我们从核心数据模型开始。
   

4. Claude 将创建组件并在知识图谱中跟踪它们

5. 在以后的会话中继续开发：

   让我们继续开发 Todo 应用程序。 我们的实施状态如何？
   

6. Claude 将检索当前状态并建议后续步骤

7. 实现特定组件：

   让我们为我们的 Todo 应用程序实现任务完成端点
   

8. Claude 将检索相关上下文并提供一致的实现

使用语义搜索

通过 LlamaIndex 集成，您现在可以使用更自然的语言来查找组件：

找到所有与处理任务完成相关的代码

Claude 将使用语义搜索来查找相关组件，即使它们没有明确包含“任务完成”字样。

运行 LlamaIndex 演示

我们包含了一个演示脚本来展示语义功能：

# 激活您的虚拟环境
source .venv/bin/activate  # 或 source venv/bin/activate

# 运行演示
python examples/llama_index_demo.py

这将演示分析日历应用程序并执行语义搜索以查找功能。

贡献

欢迎贡献！ 请随时提交 Pull Request。

许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。