GitHub MCP 服务器

基于 Node.js 和 TypeScript 的 MCP 服务器，允许兼容的代理通过自然语言对 GitHub 执行操作。

架构

Usuario -> Antigravity (Host) -> MCP Client -> MCP Server -> Octokit -> GitHub API

聊天机器人主要进行对话。AI 助手通过附加能力提供帮助。AI 代理解释目标，决定需要哪些操作，并使用工具来实现目标。

MCP（模型上下文协议）标准化了 AI 主机、MCP 客户端以及暴露工具或数据源的服务器之间的通信。在本项目中，传输方式是 stdio：协议消息使用 stdin/stdout，日志使用 stderr。

Related MCP server: GitHub MCP Server

技术栈

• Node.js 18 或更高版本

• TypeScript，启用 strict: true

• @modelcontextprotocol/sdk

• @octokit/rest

• zod

• dotenv

• Vitest

安装

npm install
npm run build

配置

将 .env.example 复制为 .env 并在本地填写令牌：

GITHUB_TOKEN=tu_token_de_github

.env 已被 .gitignore 排除，绝不应提交。

令牌应仅具有必要的权限。对于私有仓库，细粒度令牌必须根据操作允许访问仓库和内容/问题。经典 PAT 可能需要 repo。user 权限仅用于额外的用户操作，admin:org 对于当前五个工具不是必需的，除非组织强制要求该场景。令牌不会包含在示例、测试、日志或 MCP 响应中。

脚本

npm run dev       # Ejecuta TypeScript directamente
npm run build     # Compila a dist/
npm start         # Ejecuta el JavaScript compilado
npm test          # Ejecuta los tests unitarios

MCP 工具

create_repository

在已认证账户中创建新仓库。

输入：name、description。

返回仓库的全名和 URL。

create_issue

在现有仓库中创建问题。

输入：owner、repo、title、body。

返回问题的编号、标题和 URL。

list_repositories

列出已认证用户的仓库。

可选输入：page、per_page。

返回包含全名和 URL 的摘要列表。

create_commit

创建或更新文件，并通过 Contents API 生成提交。

输入：owner、repo、path、message、content；branch 可选。

该工具首先查询文件。如果存在，则使用其 SHA；如果 GitHub 返回 404，则创建文件而不带 SHA。

list_issues

列出仓库的开放问题，并排除拉取请求。

输入：owner、repo；page 和 per_page 可选。

错误处理

错误分类为 ValidationError、AuthenticationError、GitHubAPIError 或 NetworkError。MCP 响应包含可操作的消息，不会转发可能暴露凭据的技术消息。

操作仅在遇到速率限制、5xx 错误或可恢复的网络错误时重试最多三次。验证错误、认证错误和不存在的资源错误不会重试。

测试

测试不会调用真实的 GitHub。它们使用模拟的 Octokit 客户端，并涵盖：

• 仓库和问题的有效和无效模式。

• 创建仓库和问题。

• 列出仓库和开放问题。

• 创建新文件。

• 使用 SHA 更新现有文件。

• 错误转换。

• 带退避的重试。

运行 npm test 执行完整测试套件。

MCP Inspector

编译项目并通过 Inspector 运行服务器：

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

在启动 Inspector 之前，在环境中配置 GITHUB_TOKEN。验证五个工具、其描述和模式是否出现。对于真实测试，请使用测试仓库，并避免破坏性操作。

Antigravity 和 VS Code

.vscode/mcp.json 文件包含一个 stdio 配置，不包含版本化的凭据。在从主机启动服务器之前，使用 npm run build。该配置执行 dist/index.js，并从本地环境获取 GITHUB_TOKEN。

对于其他兼容 MCP 的主机，注册等效命令：

{
  "type": "stdio",
  "command": "node",
  "args": ["dist/index.js"],
  "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" }
}

检查主机是否检测到 create_repository、create_issue、list_repositories、create_commit 和 list_issues。

结构

src/
  errors/       Errores clasificados y sanitizacion
  github/       Cliente Octokit y operaciones GitHub
  schemas/      Schemas Zod y tipos inferidos
  tools/        Handlers MCP individuales
  utils/        Retry, logging, respuestas y ensamblado del servidor
  index.ts      Entrada y transporte stdio
tests/          Tests unitarios con mocks

安全

• 不要硬编码令牌。

• 不要提交 .env。

• 不要打印令牌或授权头。

• 将日志保持在 stderr，以免污染协议。

• 对 PAT 应用最小权限原则。

• 在执行写入 GitHub 的工具之前，审查更改。