Codebase City MCP Server

使用说明（Markdown 格式）

• 项目简介

  • Codebase City 的 MCP 服务器实现，用来在 LLM 客户端（如 Claude/Cursor 等）与后端代码分析系统之间提供标准化的上下文服务能力。核心通过 MCP 机制暴露工具（Tools）以执行特定任务、以及可能的资源访问能力，便于在对话中查询代码结构、计算影响范围等。服务器与后端 REST API 协同工作，以实现从模型对话到代码分析结果的闭环。

• 主要功能点

  • MCP 核心能力暴露：实现一个 FastMCP 服务实例，暴露两个工具（tools）供 MCP 客户端调用：
    • query_architecture：对给定 Cypher 查询文本在本地 KuzuEngine 图数据库中执行原始查询，并返回结果。
    • get_blast_radius：给定文件标识，计算该文件的爆炸半径（受影响的文件列表及深度信息）。
  • 与后端通知机制集成：在需要时通过 HTTP 请求向后端 /api/mcp/notify 接口推送事件，驱动前端 UI 的实时更新（例如展示 Blast Radius）。
  • 与代码图谱的协同：后端底层使用 KUZU DB 和图模型来管理文件、类、函数等节点及依赖关系，MCP 工具直接对这些数据进行查询与分析，便于在对话中产生解释性反馈。
  • 兼容性与扩展性：设计理念匹配 Claude/Cursor 等 MCP 客户端的“工具驱动对话”模式，后续可扩展更多工具以支持更多维度的云端推理。

• 安装步骤

  • 该 MCP 服务器是独立的服务组件，依赖后端图数据和 API 支撑，请确保后端 API 已就绪且 KUZU 引擎数据可用。
  • 运行方法（命令行，一条命令即可启动 MCP 服务器）：
    • 直接执行：python backend/mcp_server.py
  • 运行后，你将得到一个 MCP 服务实例，支持与 MCP 客户端通过 JSON-RPC 进行交互。

• 服务器配置（JSON 配置示例） 说明：MCP 客户端需要一个配置，用于描述服务器名称、启动命令和参数等，用于与 MCP 服务器建立连接。以下信息为配置示例描述，不含代码实现，仅作为指南，实际使用请按客户端要求提供完整配置。

  • server name（服务器名称）：Codebase City MCP Server
  • command（启动命令）：python
  • args（启动参数）：backend/mcp_server.py 注：该配置用于 MCP 客户端在本地或远程环境中调用启动命令以启动与 MCP 服务对接的进程。具体客户端使用格式可能因实现而异，请以实际 MCP 客户端的配置格式为准。

• 基本使用方法

  • 启动后，MCP 客户端（如 Claude/Cursor）可以通过 MCP 协议向服务器发送以下请求：
    • 调用 query_architecture，传入你要执行的 Cypher 查询文本，服务器返回查询结果集。
    • 调用 get_blast_radius，传入目标文件标识与可选的最大深度，服务器返回爆炸半径的结构化结果。
  • 如需 UI 更新通知，请在需要时通过后端 API 将事件通过 /api/mcp/notify 推送到前端，从而实现可视化的更新。

• 备注与依赖

  • MCP 服务与现有后端 API 的协作依赖 HTTP 调用、KuzuEngine 图数据库，以及后端的资源/城市数据，因此运行环境需要具备相应的依赖和数据准备。