内容
# 代码侦察 MCP 工具
在Claude Desktop中用简单的中文提问任何GitHub仓库的问题。
该工具使用 **MCP（模型上下文协议）** 与Claude Desktop连接。它读取整个GitHub仓库的代码，并允许您向Claude提问关于代码的问题——例如“这个函数的作用是什么？”或“这个项目中如何处理身份验证？”——Claude使用实际代码作为上下文回答问题。
---
## 开始前需要准备
1. **Claude Desktop 应用** 已安装（[在此下载](https://claude.ai/download)）
2. **Python 3.10+** 已安装 → 使用以下命令检查：
```bash
python --version
```
如果未安装，请从 [python.org](https://www.python.org/downloads/) 获取——在Windows上安装时，请勾选“将Python添加到PATH”。
3. **GitHub 个人访问令牌** （仅限私有仓库或避免速率限制时需要——公共仓库无需令牌也可工作）
- 进入GitHub → 设置 → 开发者设置 → 个人访问令牌 → 生成新令牌
- 仅授予 `repo` 读取权限（不要授予不必要的权限）
---
## 步骤 1 — 下载该项目
```bash
git clone https://github.com/YOUR-USERNAME/Code_Scout_MCP.git
cd github-repo-reader
```
（或者，在GitHub上点击“代码 → 下载ZIP”并解压，如果您不使用git。）
## 步骤 2 — 安装所需包
```bash
pip install -r requirements.txt
```
## 步骤 3 — 设置GitHub令牌（可选但推荐）
```bash
GITHUB_TOKEN=您的令牌值
```
> ⚠️ 绝不能分享此文件或将其提交到GitHub。该文件已通过 `.gitignore` 排除。
## 步骤 4 — 连接到Claude Desktop
打开Claude Desktop配置文件：
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
添加以下条目（编辑路径以匹配项目下载位置）：
```json
{
"mcpServers": {
"github-repo-reader": {
"command": "python",
"args": ["完整路径/server.py"],
"env": {
"GITHUB_TOKEN": "您的令牌值"
}
}
}
}
```
**提示：** 如果单独使用 `python` 无法运行，请使用完整路径（在Windows上运行 `where python` 或在Mac/Linux上运行 `which python3` 查找）。
## 步骤 5 — 完全重启Claude Desktop
不要直接关闭窗口 — 从系统托盘/菜单栏中完全退出，然后重新打开。这对于Claude启动新工具是必要的。
## 步骤 6 — 试用
在Claude Desktop中，尝试提问：
> “读取github.com/某用户/某项目仓库并告诉我它的作用。”
如果运行正常，Claude将拉取代码并使用它回答问题。
---
## 故障排除
| 问题 | 可能的解决方法 |
|---|---|
| 工具在Claude中未显示 | 配置文件有JSON语法错误 — 检查每个逗号/括号。同时确认已完全重启Claude。 |
| “命令未找到”错误 | 在配置中使用`python.exe` / `python3`的完整路径，而不是仅使用`python`。 |
| GitHub速率限制错误 | 添加`GITHUB_TOKEN` — 无认证请求限制为每小时60次。 |
| 仍然遇到问题 | 查看Windows上的日志 `%APPDATA%\Claude\logs\mcp-server-github-repo-reader.log` 获取确切的错误信息。 |
---
## 工作原理（简版）
1. Claude Desktop在启动应用时将此Python脚本作为后台进程启动。
2. 当您提出问题时，Claude调用此工具，该工具使用GitHub API从GitHub仓库获取相关文件。
3. 代码内容作为上下文返回给Claude，Claude使用它回答您的提问 — 类似于RAG，但使用的是实时仓库而非静态文档存储。
---
## 贡献
欢迎提交拉取请求！该项目适合初学者，因此请保持更改简单并添加注释。
## 许可证
MIT — 免费使用、修改和分享。
