Codebase Context MCP 服务器

关键词

代码上下文向量搜索本地索引LanceDB模型上下文协议

使用说明（Markdown 格式）

  • 项目简介

    • 该仓库实现了一个基于 Model Context Protocol (MCP) 的后端服务，面向 LLM 客户端提供代码库相关的上下文、工具和提示模板等能力。核心职责包括：托管与管理资源和数据、注册并执行工具、定义并渲染提示模板，以及通过 JSON-RPC 与客户端进行通信。

  • 主要功能点

    • MCP 接口实现
      • 提供 ListTools、ListResources、ReadResource、CallTool 等 MCP 请求的处理能力，并返回标准的 JSON-RPC 响应。
    • 工具与资源托管
      • 注册并执行工具（如 search_codebase、get_codebase_metadata、refresh_index 等），以及暴露可读取的资源。
    • 提示模板与上下文
      • 通过内置逻辑渲染 Codebase Intelligence、Prompts/模板等上下文信息，帮助 LLM 在生成代码时遵循团队约定。
    • 会话与能力管理
      • 维护 server 状态、启动/初始化流程、逐步展示索引状态和错误信息，支持自动修复（Auto-Heal）机制，如在遇到向量索引损坏时自动触发再索引。
    • 本地化与传输
      • 使用 StdioServerTransport 作为 MCP 标准传输，支持本地开发与集成场景。具备对 legacy 结构的迁移能力与调试输出。
    • 代码库分析与索引
      • 集成 CodebaseIndexer、CodebaseSearcher、嵌入向量、LanceDB 向量库等，完成对代码库的解析、嵌入、存储与检索。
    • 安全与容错
      • 错误处理、日志输出、并在特定错误情况下进行自愈，确保 MCP 客户端在遇到问题时有清晰的错误信息。

  • 安装步骤（简要）

    • 将代码克隆到本地，并安装依赖（如 npm ci / npm install）。
    • 通过 TypeScript 编译或直接在 Node 环境下运行可执行入口（index.js/CLI 入口）。
    • 按需配置环境变量（如 CODEBASE_ROOT、OPENAI_API_KEY、EMBEDDING_PROVIDER 等），以及本地缓存/向量数据库路径。

  • 服务器配置（给 MCP 客户端使用的 JSON 配置示例说明）

    • 服务器名称：codebase-context
    • 启动命令与参数（MCP 客户端需提供以连接到服务器）
    • 说明性描述（不直接粘贴代码块，而是以说明文本呈现）：
      • server 名称：codebase-context
      • command：npx
      • args：["codebase-context", "/path/to/your/project"]
      • 该配置用于 MCP 客户端在启动时通过指定的命令与参数来拉起服务器实例，或作为容器/脚本调用的参数输入。
    • 说明要点
      • 客户端只需要知道服务器的名称、启动命令与参数即可建立连接，无需理解服务器内部实现细节。
      • 若环境首次运行出现提示，建议使用 npx --yes 或 npx -y 进行自动确认。

  • 基本使用方法

    • 客户端连接
      • 通过 MCP 客户端配置将服务器启动命令与参数传入，即可在初始化阶段建立与 MCP 服务器的 JSON-RPC 通道。
    • 常用操作
      • 调用工具：通过工具名（如 search_codebase、remember 等）执行相应的 JSON-RPC 请求，获得回答或结果。
      • 读取资源：请求内置资源（如 Codebase Intelligence、上下文片段）以便在推理阶段提供背景信息。
      • 获取元数据：获取代码库元数据、索引状态等，辅助判断当前环境与可用能力。
    • 自动修复
      • 在向量索引损坏等错误发生时，服务器会尝试自动重建索引并重试查询。

  • 额外信息

    • 该实现包含本地向量检索、嵌入生成、索引存储、内存记忆系统等模块，适合在本地安全环境中对代码库进行快速、可控的上下文化支持。

服务器信息

访问项目