github-repo-mcp

github-repo-mcp

一个 MCP（模型上下文协议）服务，让任何 AI Agent（Claude Desktop、Claude Code、Cursor）都能直接分析公开的 GitHub 仓库，无需人工阅读 README、提交记录和问题跟踪器。

为什么要开发这个工具

评估陌生仓库（“这个项目还在积极维护吗？这个问题真的适合新手吗？最近有哪些变化？”）是每位开发者都会反复进行的手动工作。这个服务将其转化为四个可供任何兼容 MCP 的 Agent 调用的工具。

工具

工具	功能
get_repo_health	根据提交近期情况、问题分流率和贡献者数量，确定性地计算 0–100 的健康评分。立即标记已归档的仓库。
summarize_recent_commits	按类型（功能／修复／文档／重构／杂项）对过去 N 天的提交分组，快速了解“有哪些变化”。
find_good_first_issues	查找标记为适合新手的问题，为每个问题评估其描述是否真正清晰，并标记看似标签错误的问题（例如，尽管带有“good first issue”标签，却涉及核心架构）。
ask_repo	基于嵌入的语义搜索（Voyage AI + Qdrant 余弦相似度），在 README、docs/*.md 和热门问题讨论串中进行自由文本问答。

设置

npm install
cp .env.example .env
# Add a GitHub personal access token to .env — raises the rate limit from 60/hr to 5000/hr.
# No special scopes needed for public repo data: https://github.com/settings/tokens
#
# ask_repo also needs, both free tier:
#   VOYAGE_API_KEY  — https://dashboard.voyageai.com/ (API Keys -> Create new key)
#   QDRANT_URL, QDRANT_API_KEY — https://cloud.qdrant.io/ (create a free cluster)
npm run build

使用 Claude Desktop 在本地运行

将以下内容添加到 Claude Desktop MCP 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "github-repo-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/github-repo-mcp/build/index.js"],
      "env": { "GITHUB_TOKEN": "your_token_here" }
    }
  }
}

重启 Claude Desktop，然后试试：“使用 github-repo-mcp 检查 facebook/react 的健康状况，并帮我找一个适合新手的问题。”

架构说明

• 使用 GitHub API，而非抓取网页——接口整洁、文档完善，使用令牌时还有宽裕的速率限制。
• 确定性评分，生成式说明——get_repo_health 的评分采用固定公式（近期情况 + 问题分流 + 贡献者多样性），而非由大模型猜测。这让评分结果可以复现；大模型（位于调用方 Agent 中）可以在此基础上说明原因。
• 在 find_good_first_issues 中检测标签错误——真正适合新手的问题标签往往不准确。该工具会检查正文长度、危险关键词（架构、迁移、安全）和评论数量，以发现标签错误的问题，而非仅仅照单全收。

演示

请参阅 docs/demo.md，了解与 facebook/react 进行的真实（非模拟）协议交互，其中基于嵌入的 ask_repo 会针对一个与源文本毫无共同词语的查询检索出正确答案。

ask_repo 检索的工作原理

ask_repo 最初采用基于 README 的关键词窗口检索（参见 git 历史记录），后来升级为基于嵌入的 RAG，实现在 src/rag.ts 中：

1. 首次查询某个仓库时，对 README、docs/*.md（顶层文件，最多 15 个）以及讨论最热烈的 8 个 issue 讨论串（标题 + 正文，约 500 词的文本块，重叠 50 词）进行分块
2. 使用 Voyage AI（voyage-3.5-lite）为每个文本块生成嵌入
3. 将向量存储在 Qdrant Cloud 中，每个仓库对应一个 collection（repo_<owner>_<name>）
4. 每次查询时：为问题生成嵌入，通过余弦相似度搜索排名前 5 的文本块
5. 后续查询同一仓库时会跳过重新索引（通过 collection 的 points_count 检查）——只有查询本身会生成嵌入

为什么使用嵌入而不是关键词匹配： 关键词重合要求字面上有相同的词——“how do I install React?” 和标题为 “Getting Started” 的 README 章节没有共同词汇，因此永远不会匹配。无论具体措辞如何，嵌入都会将语义相似的文本放在向量空间中彼此靠近的位置，因此即使改写措辞或使用同义词，检索仍能奏效——这正是关键词搜索在实际使用中遇到的失效模式。

已知的简化之处（在 src/rag.ts 中标记为 ponytail:），每项都注明了升级方案：

• Issue 讨论串仅索引标题和正文，不索引完整的评论讨论（避免每个 issue 多调用一次 API）——如果答案需要反映问题解决过程，而不只是原始报告，可获取 /issues/{n}/comments。
• 分块大小使用词数近似估算 token 数，而非使用真正的分词器。
• 没有过时检查——仓库一旦完成索引，即使文档发生变化，也会一直保留该索引。如果内容过时，可添加 TTL，或将 pushed_at 与已存储的索引进行比对。

许可证

MIT