SuperAPI AI 工具集
合作ENAI 行业资讯收藏
全部工具AI编程工具codebase-agent-mcp

codebase-agent-mcp

CodebaseAgent-MCP 是一个面向 AI 编程智能体的令牌高效型 MCP 服务器（同时兼具 MCP 客户端功能）。它将文档与源代码分析、以及与相关上下文提供型 MCP 服务器的交互，委托给本地或低成本的 OpenAI 兼容 LLM 处理，从而大幅降低顶级 LLM 上编程智能体的令牌消耗与上下文体积。它支持本地模型（如 Gemma、Qwen）和低成本云端 OpenAI 兼容服务，可选集成 Qdrant 实现 RAG 缓存，并提供 STDIO 与 HTTP 两种模式、递归子智能体树、防卡死机制、任务完成控制、沙箱化文件系统访问、可插拔外部 stdio MCP 工具以及基于 SQLite 的异步后台任务持久化。

访问官网

工具介绍

用途

CodebaseAgent-MCP 是一个令牌高效型 MCP 服务器，用于 AI 编程智能体。它把大型代码库分析委托给一个专用的 OpenAI 兼容 LLM，从而减少上下文体积、延迟和令牌成本。它不会强迫主编程助手反复扫描大型代码库，而是单独执行该工作，只返回当前任务所需的信息。

它可运行于本地模型（如 Gemma 或 Qwen），也可运行于低成本的 OpenAI 兼容云服务商，在降低延迟和令牌消耗的同时，让主助手专注于推理和代码生成。

根据作者的实际使用情况（分析大量数据，如文档、科学论文集合、从政府网站保存的过滤/搜索功能较差的海量内容等），该项目正在平滑演进为一个独立的通用长时程智能体子框架，可连接到任何 CLI/GUI 智能体。

主要能力

  • 专为管理小型 LLM 而设计：聚焦于解决它们阻碍其他框架有效工作的特定行为特征和弱点。
  • 精确的对话历史压缩。
  • 可配置深度的递归子智能体树。
  • LLM 防卡死机制（防止模型陷入无限自我重复循环）。
  • 任务完成控制（防止小型 LLM 过早终止工作）。
  • 完整的子智能体树。
  • 同时支持 STDIO 和 HTTP 模式。
  • 针对文件大于所连接模型上下文窗口的仓库，进行令牌高效的代码与依赖分析。
  • 通过内置 qdrant_* 插件之一实现可选的 RAG 缓存。
  • 沙箱化文件系统访问，范围限定在配置的库根目录内。
  • 可插拔的外部 stdio MCP 工具。
  • 可与本地 OpenAI 兼容服务器（LM Studio、llama.cpp、vLLM、Sglang 等）或兼容的托管 API 配合使用。
  • 可与云端 OpenAI 兼容服务器（OpenRouter 等）配合使用。
  • 异步后台任务，结果通过 SQLite 持久化。

使用方式

  1. 安装 uv：https://docs.astral.sh/uv/getting-started/installation/
  2. 通过 uvx 初始化并创建 CodebaseAgent-MCP 配置：uvx --from codebase-agent-mcp cb-agent-init。它会返回你的 codebase_agent.config.json 配置文件路径。可随时使用该命令查找配置文件位置。
  3. 更新到最新版本（不会影响你的配置）。
  4. 在启动服务器前编辑 codebase_agent.config.json：
    • 定义 OpenAI 兼容 LLM（本地或云端）。
    • 定义框架可分析的本地仓库、依赖源码或文档树。
    • Qdrant（可选）：CodebaseAgent-MCP 作为 Qdrant 的客户端工作，支持本地或云端。qdrant_fastembed 和 qdrant_cloud 可启用 RAG 缓存。默认安装 qdrant_fastembed 客户端。
  5. 将 CodebaseAgent-MCP 注册为 MCP 服务器：配置你的 MCP 客户端（ClaudeCode/Codex/OpenCode/Hermes/PiAgent 等）通过 uvx 运行 CodebaseAgent-MCP。
  6. 向你的框架（ClaudeCode/Codex 等）安装子智能体和技能：进入项目根目录运行相应命令；也可用 git clone https://github.com/FI-Mihej/codebase-agent-mcp.git 克隆仓库后手动操作：
    • ClaudeCode：复制 ./codebase_agent/data/integration_to/claude/.claude 到项目根目录。
    • Codex：复制 ./codebase_agent/data/integration_to/codex/.agents、./codebase_agent/data/integration_to/codex/.codex 和 ./codebase_agent/data/integration_to/codex/.codex/config.toml 到项目根目录。
    • OpenCode：复制 ./codebase_agent/data/integration_to/opencode/.opencode 到项目根目录。
    • Cursor：复制 ./codebase_agent/data/integration_to/cursor/.cursor 到项目根目录。
    • Antigravity：复制 ./codebase_agent/data/integration_to/antigravity/.agents 到项目根目录。Antigravity 缺少智能体概念，因此令牌效率会低于其他框架。请务必启用隐式缓存以获得显著节省。
    • Hermes Agent：复制 ./codebase_agent/data/integration_to/hermes/skills 到项目根目录。
    • Pi Coding Agent：1. 安装 https://github.com/nicobailon/pi-subagents 或类似方案；2. 复制 ./codebase_agent/data/integration_to/pi_agent/.pi 到项目根目录。
  7. 以短语 "Use skill libraries-analysis-skill ." 开始你的开发提示词，以降低成本。

Qdrant（可选）使用：在首次使用启用了 qdrant_* 插件的 CodebaseAgent-MCP 之前，以及每次更改 qdrant_* 插件配置中的 "configuration"."model_name" 字段之后，必须初始化（下载）模型。对依赖库代码库执行索引，以将各个实体（文件、类、函数）的关键特征添加到 RAG 存储中。

适用场景

现代编程智能体在开始解决实际任务之前，会反复花费数千（有时数百万）令牌重新阅读仓库、依赖源码和文档。当项目正在积极演进、文档不完整或过时、必须直接检查源代码、每个新的智能体会话都从空上下文开始时，成本会更高。CodebaseAgent-MCP 将这种探索委托给专用的分析模型，主编程助手只接收相关发现，而不是反复处理整个代码库。

限制与说明

  • 项目有意聚焦于 OpenAI Chat Completions API，这是历史上第三方推理服务器支持最完整的接口。
  • 不使用 LangChain，因为 LangChain 无法（且“未计划”）在聊天历史中检索或发送非官方但事实上的推理自定义字段。
  • GitHub 仓库是项目的公开镜像。作者通常在私有仓库中进行活跃开发（包括实验代码和私有研究笔记），定期发布选定快照。欢迎 pull request（不来自 LLM）。
  • Qdrant 集合元数据要求 Qdrant 服务器 1.16 或更高版本。兼容的元数据前集合会被无数据丢失地采用；当启用 recreate_incompatible_collections 时，已识别的无向量模式的旧集合会被重建。
  • 每个服务商的缓存实现不同，有些根本不支持缓存。
  • 关于本地 LLM 的技术细节和配置建议见 docs。
  • 需防范依赖库代码中的提示注入。将提示注入嵌入仓库代码正变得越来越普遍，从 Meta 维护的仓库（github.com/facebook/*）到可能导致凭据泄露、社会安全号码暴露、财务损失等真正危险的情况。

同类工具

查看分类