GitHub MCP Server

一个通过安全、结构化的工具，让 AI 助手与 GitHub 对话的项目。

简单说：这个项目不是让 AI 去猜 GitHub 是怎么运作的，而是给 AI 一个清晰的操作菜单——比如“列出我的仓库”“显示未关闭的 issue”或“读取某个文件”。AI 选出正确的操作，这个服务器去调用 GitHub，再把结果以一种干净、AI 能理解的格式返回。

它解决了什么问题？

聊天机器人擅长语言，但它们通常无法自动实时访问你的 GitHub 账户。

这个项目搭起了一座 桥梁：

1. 你用日常语言提出请求（例如“显示 microsoft/vscode 中未关闭的 issue”）。

2. 一个 AI 模型（通过 Groq）决定该调用哪个 GitHub 工具。

3. MCP 服务器 针对真实的 GitHub API 执行该工具。

4. 返回的结果经过清洗，成为（normalize）之后交给 AI。

5. AI 再用通俗的语言把结果解释给你。

MCP 是指 Model Context Protocol（模型上下文协议）。你可以把它理解成一个标准的「插口」：任何兼容的 AI 客户端都能够连上这个服务器并使用它的工具集。

Related MCP server: GitHub MCP Server

整体架构（Big picture)

You
  ↓
AI Agent (client/agent.py)  ← talks to Groq LLM
  ↓
MCP Server (notebooks/server.py)  ← menu of GitHub tools
  ↓
GitHub Client  ← HTTP calls with your token
  ↓
GitHub REST API
  ↓
GitHub

设计原则（重要)

所有工具保持在“薄薄”的一层：

1. 检查输入（仓库名字是否合法？）。

2. 调用 GitHub 客户端。

3. 把结果归一化 成稳定的结构。

4. 把干净的规范数据返回给Agent。

其余复杂的 GitHub 细节都保存在 client 层内部——而不是散落在各工具之间。

项目文件夹（各部分用途）

工具能做什么

服务器提供很多 GitHub 操作。简单的分组如下：

只读（安全探索）

• 列出你的 Repos

• 读取某个 repo 的详情

• 列出 / 获取 issue 和 pull request

• 抓取 PR Diffs

• 列出分支、commits、labels

• 代码库内搜索代码

• 读取文件内容

• 列出 GitHub Actions 工作流的最新 run 列表

写操作（会改变 GitHub）

• 创建 issue、评论、PR、分支、labels

• 更新 issue、添加/移除 labels

• 重新打开 issue

破坏性操作（有风险——受保护）

默认这些需要 extra 二次确认：

• merge_pull_request

• delete_file

• create_repository

• create_or_update_file

• close_issue

对于这几个，Agent 的常规流程是：

1. 先用 dry_run=true 调用 → 只做预览

2. 再用 confirm=true 调用 → 真正操作

你可以通过环境变量把这些操作再收紧或放开（详见后文）。

统一返回结构

GitHub 原始返回很大、且经常变。本项目则返回稳定格式。

列表类工具的结果长得像这样：

{
  "count": 20,
  "items": [ ... ],
  "page": 1,
  "per_page": 20,
  "has_next": true,
  "has_prev": false,
  "next_page": 2,
  "prev_page": null,
  "last_page": 5
}

如果要取下一页，直接重新调用相同工具，并带上 page=2（用 page=next_page 也可）。

单个 issue 的示例：

{
  "number": 42,
  "title": "Bug in login",
  "state": "open",
  "author": "some-user",
  "labels": ["bug"],
  "comments": 3,
  "html_url": "https://github.com/...",
  "is_pull_request": false
}

另外：get_issues 会自动过滤 pull request（因为 GitHub 的 issues API 会把 PR 混在一起返回）。

安全特性

可选的环境变量：

GITHUB_MCP_DESTRUCTIVE_MODE=confirm
GITHUB_MCP_DESTRUCTIVE_ALLOWLIST=merge_pull_request,delete_file

日志与调试

服务器只会把 JSON 日志输出到 stderr。

为什么用 stderr？因为 MCP 是通过 stdout 跑协议通讯的。如果把日志打到 stdout，就等于在 AI 通讯线上塞垃圾。

日志会有这些类型字段：

• 请求方法与路径

• HTTP 状态码

• 耗费时长

• 剩余 rate limit

不打印这些：

• 你的 GitHub Token

• Authorization 头

• 形似机密的值（PAT、Bearer token 等

日志例子：

{"ts":"2026-08-23T12:00:00+00:00","level":"INFO","event":"github_request","method":"GET","path":"/repos/microsoft/vscode/issues","status_code":200,"duration_ms":120.5}

Agent 模块（client/agent.py）

agent.py 处理逻辑是：

1. 用子进程启动 MCP Server（跑了 notebooks/server.py）。

2. 问服务器要可用工具清单。

3. 把用户的 prompt + 工具信息发给 Groq。

4. 若 Groq 想调用某个工具，则通过 MCP 让 server 执行对应调用。

5. 最后把工具结果返回给 Groq，形成最终答案。

常用命令（在项目根目录，在虚拟环境内）：

# See all registered tools
python client/agent.py --list-tools

# Only show which tool the AI would pick (no GitHub write)
python client/agent.py --dry-run "list my github repos"

# One real question, then exit
python client/agent.py --once "show open issues for microsoft/vscode"

# Interactive chat
python client/agent.py

# Check tool-picking quality on many sample prompts
python client/test_tool_picking.py

循环/限制（可选）——

python client/agent.py --max-rounds 5 --once "..."

或直接在 .env 中：

AGENT_MAX_TOOL_ROUNDS=8
AGENT_MAX_TOOL_CALLS=16
AGENT_MAX_CONSECUTIVE_ERRORS=3

环境变量

MCP 服务器（必填）

Agent （聊天 / 工具选择，必填）

可选

复制 .env.example → .env 填上真实信息。更完整请看 SETUP.md。

技术栈（相关）

• Python 3.13+（开发于 3.13）

• MCP（mcp Python 包）—— 给 tool 协议的实现

• httpx —— 用来请求 GitHub 的 HTTP Client

• Pydantic —— Schema 定义 / 数据校验

• python-dotenv —— 加载 .env 文件

• OpenAI 兼容 Client → 用于调用 Groq（作为 Agent）

• Jupyter（可选用）—— 学习用的 Notebook

如何安装和启动

阅读友好的引导：

👉 SETUP.md —— 安装 Python、创建密钥、配置 .env，然后运行你的第一条命令。

如果你本身懂 Python，简短版：

cd "path\to\Github-MCP-server"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
# edit .env with your tokens
python client/agent.py --list-tools
python client/agent.py --once "list my github repos"

推荐学习路径

1. 先读完这个 README（你已经看到这里）。

2. 按 SETUP.md 部署环境，直到可以 --list-tools.

3. 看 docs/ARCHITECTURE_HLD_LLD.md：理解 HLD 与 LLD 的流配置。

4. 先尝试 --dry-run 和 --once，配合简单的只读问题。

5. 进入 50 个场景手工测试计划 ： tests/MANUAL_TESTING_50_SCENARIOS.md

   • 自动跑：python client/run_manual_scenarios.py

6. 打开 notebooks/01_github_mcp_server.ipynb 让你看清每一层是怎么搭的。

7. 最后才碰 带 dry_run + confirm 的写入/破坏性工具。

奇奇怪怪问题（速查）

安全提醒

• 永远请不要把 .env 提交上去。

• 不要把 GitHub 或 Groq token 发进 chat、截图、公开 issue。

• 尽量只用需要的最小 scope 的 GitHub token。

• 若没法信任环境，保持 GITHUB_MCP_DESTRUCTIVE_MODE=confirm（或 deny）。

• 不要公开分享 server_1.py 旧实验里的 debug token（会泄漏）——用 server.py。

授权 / 版权

这是一个 GitHub MCP 服务器与 agent 相关的“个人 / 学习用的生成式 AI”项目。如果要公开发布，请根据你的需求调整 owner 和许可证。