Codebase MCP

以隐私为中心的AI开发助手通过MCP | 将Claude变成您的个人编码助手 | 语义代码搜索 • AI辅助编辑 • 质量检查生成 • 持久记忆 | 免费开源替代Cursor及付费AI编码工具 | Python, React, TypeScript, FastAPI

开源**

Codebase MCP 是一个开源的AI驱动开发助手，它通过模型上下文协议（Model Context Protocol）将Claude Desktop（或任何兼容MCP的大语言模型）连接到您的代码库。停止为单独的编码助手支付费用——如果您已经拥有Claude订阅，那就足够了。

📖 阅读完整文档 | 🏗️ 架构图 | 🤝 贡献指南

---

🌟 为什么选择Codebase MCP？

问题

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

解决方案

Codebase MCP 将您现有的Claude订阅转变为强大的编码助手：

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

---

⚡ 快速开始

前提条件

• Python 3.11+
• Claude Desktop（或任何兼容MCP的客户端）
• 已安装Git
• uv 包管理器（推荐）

安装

1. 克隆仓库：

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

2. 全局安装（推荐）：

# 如果尚未安装，请安装uv
pip install uv

# 创建虚拟环境并安装依赖
uv venv
source .venv/bin/activate  # 在Windows上：.venv\Scripts\activate
uv pip install -r requirements.txt

# 全局安装格式化工具（用于代码格式化）
pip install black ruff

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

# 创建.env文件
cp .env.example .env

# 从以下链接获取免费API密钥：https://aistudio.google.com/app/apikey
# 添加到.env中：
GEMINI_API_KEY=your_api_key_here

4. 配置Claude Desktop：

添加到您的claude_desktop_config.json：

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

5. 启动FastAPI服务器：

# 在另一个终端中，导航到您的项目目录
python main.py /path/to/your/project

# 服务器启动于 http://localhost:6789
# 您可以通过 http://localhost:6789 访问Web仪表板

6. 与Claude Desktop一起使用：

• 重启Claude Desktop
• 开始聊天 - Claude现在可以访问13个以上的MCP工具来管理代码库！

---

🎯 关键特性

🔍 语义代码搜索

• 带有本地嵌入的AI驱动代码理解
• 多语言支持（Python, JavaScript, TypeScript）
• 符号级别索引（函数、类、接口）
• 模糊搜索和精确匹配模式

🧠 持久记忆系统

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

🌿 基于会话的Git工作流

• 每个功能的隔离开发分支
• 自动提交跟踪在.codebase目录中
• 独立于用户的.git - 独立跟踪AI更改
• 支持质量门控的自动合并

✍️ 智能代码编写

• 写工具：创建新文件，带有自动格式化和质量评分
• 编辑工具：带Gemini集成的AI辅助编辑（受Cursor启发）
• 质量门控：仅当代码质量≥80%时自动提交
• 依赖检查：防止代码重复和缺少导入

🎨 自动格式化

• Python：Black + Ruff（符合PEP 8）
• TypeScript/JavaScript：Prettier + ESLint
• 质量评分：自动代码质量评估
• 错误恢复：智能重试并纠正

📊 项目智能

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

---

🏗️ 架构

┌─────────────────┐
│ Claude Desktop  │  用户通过聊天交互
└────────┬────────┘
         │ MCP协议（标准I/O）
         ↓
┌─────────────────┐
│   MCP服务器     │  13个以上工具（代理层）
│  (mcp_server.py)│  轻量级，快速
└────────┬────────┘
         │ HTTP/REST
         ↓
┌─────────────────┐
│ FastAPI服务器   │  端口6789（main.py）
│   核心引擎      │  40多个API端点
└────────┬────────┘
         │
    ┌────┴─────┬─────────┬──────────┐
    ↓          ↓         ↓          ↓
┌────────┐ ┌──────┐ ┌────────┐ ┌───────────┐
│语义    │ │记忆  │ │  Git   │ │代码工具   │
│搜索    │ │系统  │ │管理    │ │流水线     │
└────────┘ └──────┘ └────────┘ └───────────┘
    │          │         │          │
    └──────────┴─────────┴──────────┘
               ↓
    ┌──────────────────────┐
    │   本地存储           │
    │ • FAISS（向量）     │
    │ • SQLite（元数据）  │
    │ • .codebase（git）  │
    └──────────────────────┘

隐私说明：所有处理都在本地进行，除了编辑工具，它使用Google的免费Gemini API进行AI辅助代码编辑。只有被编辑的文件发送给Gemini - 不包括项目上下文或历史记录。

---

🛠️ 可用工具

Codebase MCP提供13个专门的MCP工具，用于全面的开发自动化：

工具	目的	主要特征
session_tool	管理开发会话	创建分支，自动提交，合并
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	代码质量检查	语法，linting，导入，依赖
list_file_symbols_tool	符号提取	函数，类，接口
read_symbol_from_database	数据库符号查找	快速索引检索
project_structure_tool	项目可视化	增强树状图带统计信息

---

📈 性能

• 语义搜索：典型代码库的亚秒响应时间
• 内存占用：中型项目约100MB（<20k行）
• 索引速度：初始索引10k行约30秒
• 编辑操作：5-15秒（Gemini API + 格式化）
• 最佳项目大小：<20,000行（已测试和验证）

注意：编辑工具可能因Gemini API延迟和代码格式化而变慢。对于非常大的编辑，Claude Desktop可能会超时（使用较小、集中的编辑）。

---

🎓 使用示例

创建新功能

用户："创建一个使用JWT令牌的用户认证FastAPI端点"

Claude：
✅ 搜索现有认证模式...
✅ 创建会话：feat/user-auth
✅ 编写authentication.py，实现JWT
✅ 自动格式化，使用Black + Ruff
✅ 质量评分：95%，自动提交
✅ 将解决方案存储在内存中

重构代码

用户："重构用户服务以使用依赖注入"

Claude：
✅ 阅读当前用户服务实现
✅ 在代码库中搜索DI模式
✅ 使用AI辅助编辑（Gemini）
✅ 使用质量门控验证更改
✅ 会话：refactor/user-di，准备审查

内存驱动开发

用户："继续支付集成的工作"

Claude：
✅ 加载内存上下文...
✅ 找到先前进度：Stripe API设置完成
✅ 找到先前错误：不要在异步端点中使用同步请求
✅ 从上次检查点继续...

---

🔐 隐私与安全

隐私优先设计

• 本地嵌入：AllMiniLM-L6-v2完全运行在您的机器上
• 本地处理：FAISS向量存储，SQLite元数据 - 全部本地
• 无云依赖：除了Gemini API（仅编辑工具）

Gemini API使用

• 范围：仅edit_file工具使用Gemini
• 发送的数据：仅编辑的文件（不包括项目上下文）
• 替代方案：贡献者可以添加本地LLM支持（需要GPU）
• 成本：免费层级（15 RPM，250K TPM，1K RPD）

安全最佳实践

• 不要提交包含API密钥的.env
• 使用.gitignore保护敏感文件
• 在生产部署前审核AI生成的代码
• 保持依赖项更新

---

🤝 贡献

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

优先领域：

• 🌐 语言支持：添加Java, Go, Rust, PHP等
• 🧠 本地LLM集成：用本地模型替换Gemini
• 🔍 搜索改进：增强语义算法
• 📊 UI/UX：改进Web仪表板
• ⚡ 性能：优化大型代码库

详情参见 CONTRIBUTING.md。

---

📄 许可证

本项目根据Apache License 2.0许可 - 详情见LICENSE文件。

致谢：

• 编辑工具技术灵感来自 Cursor
• 使用 Claude Sonnet 4 和 4.5 构建
• 由 Model Context Protocol 提供支持

---

🗺️ 发展路线图

当前版本：v1.0.0-beta

即将推出的功能：

• 社区驱动的改进
• 更多语言支持
• 本地LLM替代方案
• 性能优化
• 高级提示工程模板

---

📞 支持

• 📖 文档：https://danyqe.github.io/codebase-mcp/
• 🐛 问题：https://github.com/danyQe/codebase-mcp/issues
• 💬 讨论：https://github.com/danyQe/codebase-mcp/discussions
• 🌟 如果觉得有用，请给这个仓库点赞！

---

🎉 致谢

特别感谢：

• Anthropic 提供Claude和模型上下文协议
• Google 提供免费的Gemini API
• Cursor团队 开创AI辅助编辑技术
• 开源社区 使这一切成为可能

---

由开发者为开发者制作

停止为编码助手付费。开始使用自己的大语言模型构建。