AI导哈

AI开发助手

Codebase MCP是一个开源的AI开发助手，通过Model Context Protocol将Claude Desktop（或任何MCP兼容的LLM）连接到您的代码库，提供语义代码搜索、AI辅助编辑、质量检查生成和持久记忆等功能。

  • by danyQe
  • Python
  • 本地部署
  • 50 星标
  • 更新于
在 GitHub 查看 danyQe/codebase-mcp

使用说明

代码库 MCP

通过MCP实现的以隐私为先的AI开发助手 | 将Claude变成你的个人编码助手 | 语义代码搜索 • AI辅助编辑 • 质量校验生成 • 持久记忆 | Cursor及付费AI编码工具的免费开源替代品 | 支持Python、React、TypeScript、FastAPI

开源**

代码库 MCP 这是一个开源的AI驱动开发助手，通过模型上下文协议（Model Context Protocol）将Claude桌面版（或任何兼容MCP的大语言模型）与您的代码库连接起来。无需再为单独的编码助手付费——如果您已经订阅了Claude，那么您就拥有了所需的一切。

📖 书籍或阅读的象征 阅读完整文档 🏗️ 建筑 🤝 贡献

🌟 为什么选择Codebase MCP？

问题

像Cursor、Windsurf等现代AI编码助手会收费 每月20-40美元+ 在您现有的大型语言模型（LLM）订阅之上。如果您已经在为Claude付费，为什么还要再次为一个编码助手付费呢？

解决方案

代码库 MCP 将您现有的Claude订阅升级为强大的编码助手：

  • ✅ 一个订阅 - 使用您现有的Claude Pro/团队计划
  • ✅ 隐私优先 - 局部嵌入与处理（编辑操作除外）
  • ✅ 开源 - Apache 2.0 许可证，社区驱动
  • ✅ 可扩展的 - 通过模型上下文协议，与任何MCP兼容的大型语言模型（LLM）协同工作
  • ✅ 轻便的 - 中型项目占用约100MB内存
  • ✅ 快速 - 使用本地FAISS索引进行亚秒级语义搜索

⚡ 快速入门

先决条件

  • Python 3.11及以上版本
  • Claude Desktop（可译为“Claude桌面版”或保持原样，具体取决于语境是否需要更具体的翻译） （或任何兼容MCP的客户端）
  • Git（一种分布式版本控制系统） 安装好的
  • 紫外线 包管理器（推荐）

安装

1. 克隆仓库：

git clone https://github.com/danyQe/codebase-mcp.git
cd codebase-mcp

2. 全局安装（推荐）：

# Install uv if you haven't
pip install uv

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

# Install formatters globally (required for code formatting)
pip install black ruff

3. 配置Gemini API（用于编辑工具）：

# Create .env file
cp .env.example .env

# Get free API key from: https://aistudio.google.com/app/apikey
# Add to .env:
GEMINI_API_KEY=your_api_key_here

4. 配置Claude桌面版：

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "codebase-manager": {
      "command": "/path/to/your/.venv/bin/python",
      "args": [
        "/path/to/codebase-mcp/mcp_server.py"
      ]
    }
  }
}

5. 启动FastAPI服务器：

# In a separate terminal, navigate to your project directory
python main.py /path/to/your/project

# Server starts on http://localhost:6789
# You can access the web dashboard at: http://localhost:6789

6. 与Claude桌面版配合使用：

  • 重启Claude桌面版
  • 开始聊天吧——现在Claude已能使用13+种MCP工具进行代码库管理！

🎯 主要特点

🔍 翻译为中文是：“🔍”（这个符号本身在中文中通常表示“放大镜”或“搜索”的意思，但在这里直接以原样呈现，因为它是特定的符号，没有直接的中文对应词汇需要翻译）。如果要解释其含义，可以说：“🔍 这个符号代表放大镜，常用于表示搜索或查看细节。” 语义代码搜索

  • 利用局部嵌入实现的AI驱动代码理解
  • 多语言支持（Python、JavaScript、TypeScript）
  • 符号级索引（函数、类、接口）
  • 模糊搜索和精确匹配模式

🧠 这个表情符号通常代表“大脑”或“思考”，在中文中可以翻译为“大脑”或根据上下文翻译为“正在思考中”等表达。 持久内存系统

  • 记住跨聊天会话的上下文
  • 分类学习内容：进展、错误、解决方案、架构
  • 带重要性评分的语义记忆搜索
  • 永远不要重复犯同样的错误

🌿 表示植物或绿叶，可译为“🌿（绿叶/植物）”。 基于会话的Git工作流程

  • 为每个功能设置独立的开发分支
  • 自动提交跟踪在 .codebase 目录
  • 与用户分开的 .git - 独立追踪AI变化
  • 支持带质量门的自动合并

✍️ 智能代码编写

  • 写入工具创建新文件，自动格式化并进行质量评分
  • 编辑工具结合Gemini的AI辅助编辑功能（受Cursor启发）
  • **质量门（或质量控制点）**仅当代码质量≥80%时自动提交
  • 依赖检查防止代码重复和遗漏的导入

🎨 表示“美术”或“绘画”相关的意思。 自动格式化

  • pythonBlack + Ruff（符合PEP 8规范）
  • **TypeScript/JavaScript（注：此处为保持原文格式，未做额外翻译，直接给出了原文的中文对应表述，实际上“TypeScript/JavaScript”在中文中通常也直接使用其英文名称，无需翻译。）**Prettier + ESLint
  • 质量评分自动代码质量评估
  • 错误恢复智能重试并修正

📊（表格） 项目智能

  • 实时代码库分析
  • 文件结构可视化
  • 依赖关系追踪
  • 符号提取和索引

🏗️ 建筑学

┌─────────────────┐
│ Claude Desktop  │  User interacts via chat
└────────┬────────┘
         │ MCP Protocol (stdio)
         ↓
┌─────────────────┐
│   MCP Server    │  13+ Tools (proxy layer)
│  (mcp_server.py)│  Lightweight, fast
└────────┬────────┘
         │ HTTP/REST
         ↓
┌─────────────────┐
│ FastAPI Server  │  Port 6789 (main.py)
│   Core Engine   │  40+ API endpoints
└────────┬────────┘
         │
    ┌────┴─────┬─────────┬──────────┐
    ↓          ↓         ↓          ↓
┌────────┐ ┌──────┐ ┌────────┐ ┌───────────┐
│Semantic│ │Memory│ │  Git   │ │Code Tools │
│ Search │ │System│ │Manager │ │  Pipeline │
└────────┘ └──────┘ └────────┘ └───────────┘
    │          │         │          │
    └──────────┴─────────┴──────────┘
               ↓
    ┌──────────────────────┐
    │   Local Storage      │
    │ • FAISS (vectors)    │
    │ • SQLite (metadata)  │
    │ • .codebase (git)    │
    └──────────────────────┘

隐私说明： 除编辑工具外，所有处理均在本地进行，该工具使用谷歌免费的Gemini API进行AI辅助代码编辑。仅编辑过的文件会被发送至Gemini，不包含项目上下文或历史记录。

🛠️ 可用工具

代码库MCP提供 13种专门的MCP工具 为了实现全面的开发自动化：

工具 用途 关键特性
项目 类别 描述
管理开发会话 创建分支、自动提交、合并 memory_tool
存储/检索知识 持久上下文，语义搜索 git_tool
Git 操作 状态、差异、日志、提交、分支 write_tool
智能文件创建 自动格式化、质量评分、依赖检查 edit_file
AI辅助编辑 由Gemini驱动，支持错误恢复，格式验证 search_tool
语义代码搜索 4种模式：语义、模糊、文本、符号 read_code_tool
智能代码阅读 符号级别、行范围、整个文件 project_context_tool
项目分析 结构、依赖关系、概览 list_directory_tool
目录浏览 树状视图、元数据、支持.gitignore code_analysis_tool
代码质量检查 语法、代码规范检查、导入、依赖项 list_file_symbols_tool
符号提取 函数、类、接口 read_symbol_from_database
数据库符号查找 快速索引检索 project_structure_tool

| 项目可视化 | 带统计数据的增强树形图 |

  • 📈 表现 语义搜索：
  • 典型代码库的亚秒级响应 内存占用：
  • 对于中等规模的项目（<20k行代码），约100MB 索引速度：
  • 初始索引10k行，耗时约30秒 编辑操作：
  • 5-15秒（Gemini API + 格式化） 最佳项目规模：

20,000行（已测试并验证） 注：

编辑工具可能会因为Gemini API的延迟和代码格式化而变慢。Claude Desktop在处理非常大的编辑时可能会超时（建议使用较小且有针对性的编辑）。

🎓 使用示例

User: "Create a FastAPI endpoint for user authentication with JWT tokens"

Claude:
✅ Searching for existing auth patterns...
✅ Creating session: feat/user-auth
✅ Writing authentication.py with JWT implementation
✅ Auto-formatted with Black + Ruff
✅ Quality score: 95% - Auto-committed
✅ Storing solution in memory

创建新功能

User: "Refactor the user service to use dependency injection"

Claude:
✅ Reading current user service implementation
✅ Searching for DI patterns in codebase
✅ Editing with AI assistance (Gemini)
✅ Validating changes with quality gates
✅ Session: refactor/user-di ready for review

重构代码

User: "Continue working on the payment integration"

Claude:
✅ Loading memory context...
✅ Found previous progress: Stripe API setup complete
✅ Found previous mistake: Don't use synchronous requests in async endpoints
✅ Continuing from last checkpoint...

内存驱动开发

🔐 隐私与安全

  • 隐私优先设计局部嵌入
  • AllMiniLM-L6-v2 完全在您的机器上运行本地处理
  • FAISS 向量存储，SQLite 元数据 - 全部本地无云依赖

除了Gemini API（仅限编辑工具）

  • Gemini API 使用范围 edit_file 仅
  • 该工具使用Gemini数据发送
  • **仅编辑中的文件（无项目上下文）**备选方案；替代品
  • **贡献者可以添加本地大型语言模型（LLM）支持（需要GPU）**成本

免费层级（每分钟15次请求，每小时25万次交易，每天1000次请求）

  • 安全最佳实践 .env 永远不要承诺
  • 使用API密钥 .gitignore 使用
  • 对于敏感文件
  • 在生产部署前审查由AI生成的代码

保持依赖项更新

🤝 贡献（或：参与贡献）

我们欢迎贡献！这个项目旨在由社区驱动并具有可扩展性。

  • 优先领域： **🌐 代表“互联网”或“全球网络”的符号，可翻译为“🌐（互联网/全球网络）”。不过，通常在实际语境中，这个符号会根据上下文被解释为“互联网”或“全球网络”的意思，而无需直接翻译出符号本身。**语言支持
  • 添加Java、Go、Rust、PHP等。 **🧠 代表“大脑”或“思考”的意思。**本地大型语言模型（LLM）集成
  • 用本地模型替换Gemini **🔍（放大镜图标，常用于表示搜索、查看细节等含义）**搜索改进
  • 增强的语义算法 📊 表格/数据图表用户界面/用户体验（UI/UX）
  • 优化网页仪表盘 **⚡（闪电符号，常用于表示快速、能量、电力等概念，在此处可作为表情符号或特定语境下的符号使用，无直接中文对应词汇，根据上下文可灵活翻译为“闪电”或保持符号形式）**演出

针对大型代码库的优化 见 CONTRIBUTING.md（贡献指南文件）

以获取详细指南。

📄 许可证 这个项目遵循以下许可协议： Apache许可证2.0 - 看 许可证

文件中详述。

模型上下文协议

🗺️ 路线图

当前版本：v1.0.0-测试版

  • 即将推出的特性：
  • 社区驱动的改进
  • 更多的语言支持
  • 本地LLM（大型语言模型）替代方案
  • 性能优化

高级提示工程模板

  • 📞 支持 **📖（书本的符号，本身无直接对应文字，可理解为“书”或“书籍”的意思）**文档
  • https://danyqe.github.io/codebase-mcp/ 的中文翻译可以是：“https://danyqe.github.io/codebase-mcp/（或可表述为‘该网址指向 danyqe 在 GitHub 上的 codebase-mcp 项目页面’）”。不过，通常直接保留网址原样即可，因为网址本身在中文语境下也是通用的。所以，如果只是简单地翻译说明，可以说：“这是 danyqe 在 GitHub 上的 codebase-mcp 项目页面的网址。” **🐛 表示“虫子”或“错误（bug）”。**问题
  • https://github.com/danyQe/codebase-mcp/issues 的中文翻译是：“https://github.com/danyQe/codebase-mcp/issues（GitHub上的代码库mcp的议题页面）”。不过，通常我们直接保留URL不变，仅对其中文含义进行说明，即“GitHub上danyQe用户维护的codebase-mcp项目的议题（或问题）页面” **💬**讨论
  • https://github.com/danyQe/codebase-mcp/discussions 翻译为中文是：“https://github.com/danyQe/codebase-mcp/讨论区” 🌟（星星符号，常用于表示亮点、重要性或装饰性元素） 给这个仓库点赞（或关注）

如果你觉得它有用！

🎉 致谢

  • 特别感谢： Anthropic（公司名，不直接翻译，可保持原样或根据上下文意译为“安萨特里普”等，但通常保留原名）
  • 为克劳德和模型上下文协议 谷歌
  • 对于免费的Gemini API Cursor团队
  • 因开创性的人工智能辅助编辑技术 开源社区

使得这一切成为可能

由开发者倾心打造，为开发者而生

相关 MCP