• 人工智能
• AI Agent
• 代码智能体
• 自主智能体
• MCP Clients
• CLI

本文以 AtomCode 官方文档 docs/mcp/github.md 为骨架，结合crates/atomcode-capabilities/src/mcp/的源码实现，完整讲解如何在 AtomCode 中接入 GitHub 的远程 MCP 服务（Remote MCP）：从创建 GitHub OAuth App、配置环境变量、写入.mcp.json，到命令行 OAuth 登录、TUI 验证、模型调用以及常见故障排查。读完本文，你将掌握一条可复制的"Bring Your Own OAuth App"接入链路，并理解其背后的 loopback 回调、token 落盘与自动刷新机制。

1. 前置条件

开始之前，请确认以下条件已满足：

• 已构建或安装atomcode（项目仓库根目录执行cargo build或使用官方安装脚本均可）。
• 有一台可访问 GitHub 的浏览器环境——OAuth 授权流程需要浏览器完成。
• GitHub 账号具备访问目标仓库/组织的权限，否则即使登录成功，调用工具时仍会因权限不足失败。

MCP（Model Context Protocol）在 AtomCode 中实现于能力层 crateatomcode-capabilities/src/mcp/，将外部 MCP server 暴露的工具转成与内建工具一致的、可审批、可调用的工具。GitHub Remote MCP 是其中的 HTTP 传输 + OAuth 认证型 server。

2. 创建 GitHub OAuth App

GitHub 官方 Remote MCP 网关是https://api.githubcopilot.com/mcp/，它要求客户端持有自己的 GitHub OAuth App 凭据完成授权。打开 GitHub Developer settings：

https://github.com/settings/developers

创建 OAuth App 的步骤：

1. 进入OAuth Apps。
2. 点击New OAuth App/Register a new application。
3. 填写：
   • Application name：例如AtomCode MCP Local
   • Homepage URL：http://127.0.0.1
   • Authorization callback URL：http://127.0.0.1/callback
4. 创建完成后，复制Client ID。
5. 生成并复制Client secret。

为什么 callback 写http://127.0.0.1/callback即可？源码 oauth.rs#L1067-L1072 中的bind_callback_listener()通过TcpListener::bind(("127.0.0.1", 0))绑定 loopback 地址的随机端口，并构造回调地址http://127.0.0.1:<random-port>/callback。GitHub 对 loopback redirect URL 支持随机端口，因此 OAuth App 中统一填写http://127.0.0.1/callback即可，端口号由 AtomCode 在每次登录时动态决定。

3. 配置环境变量

Client secret属于机密凭据，不要把 secret 写进仓库文件，建议只通过环境变量提供：

export ATOMCODE_GITHUB_MCP_CLIENT_ID="<your-github-oauth-client-id>" export GITHUB_MCP_CLIENT_SECRET="<your-github-oauth-client-secret>"

如果使用 shell profile（如~/.bashrc、~/.zshrc）持久化，同样不要提交包含 secret 的文件。这两个变量分别承担两种角色：

• ATOMCODE_GITHUB_MCP_CLIENT_ID：当命令行未显式传--client-id时，自动回退读取该变量。源码 oauth.rs#L89-L106 的McpOAuthLoginOptions::for_server明确写着：GitHub provider 的 server 没有动态客户端注册（RFC 7591）可依赖，所以 client id 必须来自ATOMCODE_GITHUB_MCP_CLIENT_ID。
• GITHUB_MCP_CLIENT_SECRET：配置里client_secret_env指向的变量名，登录与 token 刷新时从中读取真实 secret。

4. 添加 GitHub MCP 配置

4.1 用命令写入（推荐）

写进项目级配置（当前目录下的.mcp.json）：

atomcode mcp add-github-oauth github

或写进全局配置（~/.atomcode/mcp.json）：

atomcode mcp add-github-oauth github --global

该命令底层调用merge_http_oauth_mcp_server_into_json_file，向目标文件写入一条 HTTP + OAuth 型 server：url固定为https://api.githubcopilot.com/mcp/，auth.type为oauth、auth.provider为github。命令还支持-C <dir>指定项目目录、name参数自定义 server 键名（默认为github，工具会以mcp__<name>__…形式出现）。此命令只写配置，不登录。

4.2 手写.mcp.json

也可以手动创建项目根.mcp.json或~/.atomcode/mcp.json：

{ "mcpServers": { "github": { "url": "https://api.githubcopilot.com/mcp/", "auth": { "type": "oauth", "provider": "github", "client_secret_env": "GITHUB_MCP_CLIENT_SECRET" }, "timeout_ms": 60000 } } }

要点说明：

• client_secret_env是环境变量名，不是 secret 本身——配置文件里永远不出现真实 secret。对应源码 config.rs#L173-L192 的McpAuthEntry，它只记录变量名，登录时通过std::env::var(name)取值。
• timeout_ms建议给 GitHub Remote MCP 设置为60000。源码 transport_http.rs#L21-L22 显示默认超时是30_000毫秒（30 秒），而 GitHub Remote MCP 首次tools/list可能较慢，把超时放宽到 60 秒可避免被 TUI 外层超时取消。
• auth子字段还支持issuer、resource、client_id、scopes等（见 config.rs#L75-L89 的McpOAuthConfig），对 GitHub 场景使用文档中的最小配置即可。
• 配置读取遵循项目级覆盖用户级规则：同名 server 时项目.mcp.json覆盖~/.atomcode/mcp.json（config.rs#L214-L230）。

若 server 配置在项目级.mcp.json中，还要注意信任门：未信任项目里的项目级 server 不会连接（状态显示blocked: untrusted project），用户级~/.atomcode/mcp.json不受此限。详见 docs/mcp.md。

5. OAuth 登录

执行登录命令：

atomcode mcp login github \ --client-id "$ATOMCODE_GITHUB_MCP_CLIENT_ID" \ --client-secret-env GITHUB_MCP_CLIENT_SECRET

如果配置中已经写了client_secret_env，可以省略该参数：

atomcode mcp login github --client-id "$ATOMCODE_GITHUB_MCP_CLIENT_ID"

如果既不传--client-id也不传--client-secret-env，登录命令也会自动从ATOMCODE_GITHUB_MCP_CLIENT_ID读取 client id（见 main.rs#L4209-L4215 与 oauth.rs#L89-L106）；但--client-secret-env缺失时 login_github_oauth_with 会直接报错——GitHub 的 token endpoint 要求携带client_secret。

登录过程（对应源码 oauth.rs#L617-L702 的login_github_oauth_with）：

1. 终端打印 GitHub 授权 URL，并尝试调用系统浏览器打开它（https://github.com/login/oauth/authorize）。
2. 在浏览器中授权 OAuth App。授权 URL 携带client_id、redirect_uri（随机端口的 loopback 地址）、state（防 CSRF）以及 scope。
3. GitHub 回调到本地127.0.0.1:<random-port>/callback，AtomCode 用TcpListener接收回调并校验state与发起时一致（不一致即报OAuth state mismatch）。
4. AtomCode 携带client_id、client_secret、code、redirect_uri向https://github.com/login/oauth/access_token换取 access token，并把 token 保存到本机配置目录下的mcp_auth.toml。

默认 scope 为repo read:org notifications（见 oauth.rs#L649-L653），可通过--scopes参数以逗号分隔自定义。

检查 token 是否已保存：

cat ~/.atomcode/mcp_auth.toml

该文件以0600 权限原子写入（oauth.rs#L275-L279），内容包含access_token、refresh_token、expires_at、scopes、token_endpoint等字段。不要把该文件内容贴到日志、issue 或 PR 中。

6. 在 AtomCode TUI 中验证

启动 AtomCode：

atomcode

在 TUI 中依次执行：

/mcp reload /mcp /mcp tools github

预期结果：

• /mcp reload显示 GitHub MCP server 正在连接，随后连接成功。
• /mcp能看到github状态为connected。
• /mcp tools github能列出mcp__github__...工具，例如 issue、pull request、repository、file 相关工具。

首次连接时 GitHub MCP 的tools/list可能较慢。如果设置了timeout_ms: 60000，AtomCode 的外层 tools/list 超时会按该配置加少量余量等待，避免误判超时（transport_http.rs#L192-L201 展示了按self.timeout_ms计算超时的实现）。

从源码看，HttpClient 的请求链路 会在没有用户钉死Authorization头时，自动从 token store 加载 token 并附加Authorization: Bearer <token>；如果 token 已过期且有 refresh token，会先自动刷新再重试（oauth.rs#L301-L368）。刷新失败或未登录时，请求会明确提示执行atomcode mcp login <server>或/mcp login <server>。

7. 调用 GitHub MCP

登录并 reload 成功后，就可以让模型使用 GitHub MCP 工具。例如只读任务：

用 GitHub MCP 获取当前登录用户信息，只读操作。

或：

用 GitHub MCP 列出我能访问的仓库，先只读，不要做任何修改。

当模型调用 MCP 工具时，AtomCode 会展示工具审批。确认参数无误后批准执行。注意：写操作工具（创建分支、改文件、发评论、创建 PR 等）务必保持审批开启，逐次确认，防止模型误触发破坏性变更。

8. 常见问题

MCP server not found in config

说明还没有写入github这个 MCP server 配置。先执行：

atomcode mcp add-github-oauth github

或写入全局配置：

atomcode mcp add-github-oauth github --global

missing fieldaccess_token

通常是 GitHub token endpoint 返回了错误 JSON。常见原因是没有传client_secret。确认环境变量已设置：

echo "$ATOMCODE_GITHUB_MCP_CLIENT_ID" echo "$GITHUB_MCP_CLIENT_SECRET"

并使用完整登录命令：

atomcode mcp login github \ --client-id "$ATOMCODE_GITHUB_MCP_CLIENT_ID" \ --client-secret-env GITHUB_MCP_CLIENT_SECRET

tools/list timed out

GitHub Remote MCP 首次tools/list可能较慢。建议在 MCP 配置里设置：

"timeout_ms": 60000

然后在 TUI 中执行：

/mcp reload /mcp tools github

已登录但连接失败

可以删除 GitHub 的 MCP token 后重新登录：

atomcode mcp logout github atomcode mcp login github \ --client-id "$ATOMCODE_GITHUB_MCP_CLIENT_ID" \ --client-secret-env GITHUB_MCP_CLIENT_SECRET

logout命令底层调用McpTokenStore::delete_token删除mcp_auth.toml中对应 server 的条目（main.rs#L4248-L4257）。也可以检查配置文件：

cat .mcp.json cat ~/.atomcode/mcp.json

项目级.mcp.json会覆盖同名的全局~/.atomcode/mcp.jsonserver——排查时如果全局和项目各有一份github配置，以项目级为准。

9. 安全注意事项

• 不要提交 GitHub OAuthClient secret；一律通过环境变量注入。
• 不要提交~/.atomcode/mcp_auth.toml（token 文件，0600 权限）。
• 对写操作工具保持审批，例如创建分支、改文件、发评论、创建 PR 等。
• 需要最小权限时，应在 GitHub OAuth App 和组织策略中限制授权范围；也可以在登录时用--scopes收窄申请的权限集。

10. 参考资源

• 官方说明文档：docs/mcp/github.md
• MCP 集成总览（含信任门、配置字段表、嵌入式 DocumentStore 保管凭据）：docs/mcp.md
• OAuth 登录与 token 存储/刷新实现：crates/atomcode-capabilities/src/mcp/oauth.rs
• MCP 配置解析与合并实现：crates/atomcode-capabilities/src/mcp/config.rs
• HTTP 传输与 Bearer 注入实现：crates/atomcode-capabilities/src/mcp/transport_http.rs
• CLI 子命令add-github-oauth/login/logout定义：crates/atomcode-cli/src/main.rs

• 人工智能
• AI Agent
• 代码智能体
• 自主智能体
• MCP Clients
• CLI