AI导哈

代码库浏览器

一个Python基础的MCP服务器，为Claude提供完整的代码库访问权限，支持文件管理、代码编辑、搜索和直接执行shell命令。

  • by Tomobobo710
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 Tomobobo710/MCP-Codebase-Browser

使用说明

MCP代码库浏览器

一个基于Python的模型上下文协议（MCP）服务器，它使Claude可以完全访问您的代码库，用于文件管理、代码编辑、搜索和直接执行shell命令。

该服务器是在Claude的协助下创建的，优先考虑简单性和与Claude自然工作风格的兼容性。

概述

Codebase Browser是一个轻量级的MCP工具，它结合了文件操作、代码编辑、搜索、备份和 CLI命令执行 成为一个统一的界面。它既适用于Claude Desktop（通过stdio），也适用于基于浏览器的Claude（通过SSE/HTTP）。

主要特点：

  • 文件操作（读、写、删除、移动、复制、mkdir、rmdir）
  • 使用查找/替换操作进行代码编辑
  • 在代码库中进行全文搜索
  • 自动备份和恢复
  • 带提交跟踪的Shell命令执行 新
  • 自动操作历史和提交跟踪
  • 两种部署模式：克劳德桌面（stdio）和Web/浏览器（SSE）

需求

核心

  • Python 3.8或更高版本
  • Claude桌面应用程序或基于浏览器的Claude，支持MCP

操作系统支持

  • Windows、macOS、Linux
  • Shell:cmd、PowerShell、bash、zsh（自动检测）

安装

快速安装（克劳德桌面版）

跑 setup.bat （Windows）或等效的shell脚本自动执行以下操作：

  • 创建Python虚拟环境
  • 安装所需的依赖项
  • 设置项目目录
  • 检测您的操作系统和可用shell
  • 生成CLI配置
  • 显示Claude Desktop配置说明

手动安装

创建虚拟环境：

python -m venv mcp_env
source mcp_env/bin/activate  # On Windows: mcp_env\Scripts\activate

安装依赖项：

pip install mcp

创建项目目录：

mkdir Project

配置Claude桌面： 打开 claude_desktop_config.json 并添加：

{
  "mcpServers": {
    "MCP_Codebase_Browser": {
      "command": "/path/to/your/mcp_env/bin/python",
      "args": ["/path/to/your/codebase_server.py"]
    }
  }
}

用法

使用克劳德桌面

  1. 完成上述设置
  2. 将你的代码库放在 Project 目录
  3. 重新启动克劳德桌面
  4. 在聊天输入框中查找锤子图标
  5. Claude现在可以管理你的代码库了

文件操作示例

  • “列出项目中的所有文件”
  • “阅读src/main.py的内容”
  • “创建一个名为utils.js的新文件”
  • “在代码库中搜索‘import’的所有用法”
  • “编辑此函数并添加错误处理”
  • “创建我的项目的备份”
  • “从名为'my_project_backup'的备份还原”

CLI命令示例（新增）

  • “跑 npm install 设置依赖关系”
  • “使用以下命令执行测试套件 pytest"
  • “使用编译代码 gcc"
  • “检查git状态”
  • “构建项目 cargo build"

当你要求Claude运行一个命令时，他会提供一条消息，描述他正在做什么，该命令会在你的操作历史中被跟踪。

部署模式

1.克劳德桌面（stdio）

最适合： 使用Claude Desktop应用程序进行本地开发

  • 通过stdio直接连接
  • 自动外壳检测
  • 无网络暴露
  • 最简单的设置

用途： 按照上述安装步骤进行操作

2.Web/浏览器克劳德（SSE模式）

最适合： 在浏览器中使用claude.ai的代码库浏览器

SSE版本允许您通过安全隧道将网络上的Claude（Claude.ai）连接到互联网上的本地代码库。

它是如何工作的： codebase_server_sse.py 运行本地HTTP服务器。 start_tunnel.bat 通过以下方式公开披露 服务.net --一个免费的SSH隧道服务，不需要帐户或安装，只需要标准的SSH。您的服务器可在以下位置访问 https://yoursubdomain.serveo.net/sse，您可以在Claude中将其添加为自定义连接器。

1.配置.env

复制 .env.example 到 .env 并设置您的子域和端口：

TUNNEL_SUBDOMAIN=yoursubdomainhere
SSE_PORT=9051

子域名是先到先得的——如果它目前没有被使用，你就可以得到它。选择一些足够独特的东西，没有人会抓住它。如果它被拿走了，你会在隧道窗口中看到一个错误，只需要选择一个不同的名称。

2.跑步 start_tunnel.bat

这将打开两个窗口——一个运行MCP服务器，一个运行到serveo.net的SSH隧道。当隧道打开时，你会看到：

Forwarding HTTP traffic from https://yoursubdomainhere.serveo.net

3.在Claude中添加为连接器

转到Claude.ai→ 设置→ 连接器→ 添加自定义连接器并输入完整的SSE URL：

https://yoursubdomainhere.serveo.net/sse

笔记：

  • Serveo自动处理HTTPS——无需设置SSL证书
  • 您的子域未被保留——如果您的隧道关闭，其他人可以认领它。只需在中选择一个新名称 .env 如果发生这种情况
  • 对于有保证的持久子域，您需要拥有一个域并添加指向serveo.net的DNS记录——请参阅 提供.net文档

配置

CLI配置（自动生成）

当你奔跑时 setup.bat一 cli_config.json 告诉克劳德：

  • 您的操作系统类型
  • 可用的shell（cmd、PowerShell、bash、zsh等）
  • 如何调用命令

SSE配置（.env）

对于SSE版本，请复制 .env.example 到 .env 并配置您的设置。最低设置 TUNNEL_SUBDOMAIN 使用 start_tunnel.bat.

重要提示： 永不承诺 .env 到版本控制（它在 .gitignore)

安全与最佳实践

文件大小限制

  • 读取/返回大文件时会进行行号过滤，以防止上下文溢出
  • 搜索操作期间跳过超过10MB的文件
  • 结果大小限制在~99KB，以保持响应效率

提交跟踪

  • 每个操作（文件写入、编辑、删除、CLI命令）都会记录下来
  • 使用“显示最近的提交”查看操作历史记录
  • 在主要操作之前使用备份

备份

  • 创建备份：“备份名为'v1.0'的代码库”
  • 列出备份：“显示我的备份”
  • 还原：“从名为'v1.0'的备份还原”

⚠️ 警告

此工具允许Claude更改您的文件。他可能会破坏东西。

这是一个强大的工具。 在进行重大更改之前，始终要求Claude创建备份。 作者对数据丢失不承担任何责任。

故障排除

  • 克劳德没有显示锤子图标： 重新启动Claude Desktop并检查 claude_desktop_config.json 具有正确的路径
  • 命令执行失败： 检查您的外壳是否在检测到的外壳中（检查 cli_config.json)
  • 日志： 在以下网址查看克劳德桌面日志 %AppData%\Claude\logs\mcp*.log （Windows）或 ~/.claude/logs/ （macOS/Linux）
  • 路径问题： 确保路径在macOS/Linux上使用正斜杠，在Windows上使用反斜杠
  • SSL错误（SSE）： 验证中的证书路径 .env 是正确的

备注

  • 单一统一工具： 一切都是一个工具，可以最大限度地减少权限提示
  • 无人为限制： Claude直观地使用该工具，而不是违反工程限制
  • 语言不可知： 适用于任何编程语言（JavaScript、Python、Java、Rust、Go等）
  • 上下文效率： 文件操作智能地处理大小，以防止上下文膨胀
  • 操作历史： 跟踪每个更改以进行问责制和调试

设计理念

这个工具包含了克劳德的长处，而不是与他的弱点作斗争。

其他MCP工具试图通过限制性错误消息或谜题“教”克劳德。在实践中，Claude并没有很好地从工具约束中学习——他只是转向了另一种方法。相反，这个工具是有效的 随着 克劳德的实际行为：

  • 代码意识： Claude为你的代码维护了一个优秀的心理模型。该工具通过接受他对更改的描述（“找到X，用Y替换”）而不是强制行号来利用这一点。
  • 意图清晰： 每个操作都需要一条描述意图的消息。这使得更改可审计，并帮助克劳德保持专注。
  • 简单性： 没有人为的障碍，只需要直接访问文件和执行命令。
  • 历史： 完整的提交跟踪，以便您了解发生了什么以及原因。

结果：工具使用失败率最低，生产率最高。

许可证

MIT许可证-有关详细信息，请参阅许可证文件

相关 MCP