GitHub MCP 服务器

一个模型上下文协议 (MCP) 服务器，提供与 GitHub API 交互的工具。该服务器允许 LLM 代理通过标准化接口管理 GitHub 仓库、议题、拉取请求、分支、文件和发布。

目录

• 概述
  • 架构 & 组件
• 特性
  • 仓库管理
  • 分支管理
  • 议题管理
  • 拉取请求管理
  • 文件管理
  • 发布管理
• 安装
  • 前提条件
  • 设置
• 配置
• 项目结构
• 工具
  • 仓库管理工具
  • 分支管理工具
  • 议题管理工具
  • 拉取请求管理工具
  • 文件管理工具
  • 发布管理工具
• 开发
  • 项目结构
  • 脚本
• 错误处理
• 贡献
• 许可证

概述

github-mcp-server 实现了模型上下文协议 (MCP)，从而可以通过以下方式实现 LLM 和外部系统之间的标准化通信：

• 客户端: Claude Desktop、IDE 和其他 MCP 兼容的客户端
• 服务器: 用于项目管理和协作的工具和资源
• LLM 代理: 利用以编程方式执行 GitHub 操作的能力的 AI 模型。

它充当 AI 模型和 GitHub API 之间的桥梁，提供一组定义良好的工具，这些工具遵循一致的模式并处理身份验证、验证、错误处理和速率限制。

主要功能：

• GitHub API 集成: 与 GitHub 的 REST API 安全无缝集成
• 全面的 GitHub 功能: 完整管理仓库、分支、议题、PR 等
• 原子特性架构: 组织良好的模块化代码结构，易于维护
• 输入验证: 使用 Zod 模式对所有操作进行强大的验证
• 错误处理: 一致的错误分类和报告
• 速率限制: 内置 GitHub API 速率限制处理
• 性能关注: 优化的操作和响应格式

架构 & 组件

核心系统架构：

<details> <summary>点击展开 Mermaid 图表</summary>

flowchart TB
    subgraph API["API 层"]
        direction LR
        MCP["MCP 协议"]
        Val["验证"]
        Rate["速率限制"]

        MCP --> Val --> Rate
    end

    subgraph Features["特性模块"]
        direction LR
        Repo["仓库管理"]
        Branch["分支管理"]
        Issue["议题管理"]
        PR["拉取请求管理"]
        File["文件管理"]
        Release["发布管理"]

        Repo <--> Branch
        Repo <--> Issue
        Repo <--> PR
        Repo <--> File
        Branch <--> PR
    end

    subgraph Services["服务层"]
        direction LR
        GitHub["GitHub 服务"]
        Mapper["响应映射器"]
        RateLimiter["速率限制器"]

        GitHub <--> RateLimiter
        GitHub <--> Mapper
    end

    Rate --> Repo
    Rate --> Branch
    Rate --> Issue
    Rate --> PR
    Rate --> File
    Rate --> Release

    Repo --> GitHub
    Branch --> GitHub
    Issue --> GitHub
    PR --> GitHub
    File --> GitHub
    Release --> GitHub

    classDef layer fill:#2d3748,stroke:#4299e1,stroke-width:3px,rx:5,color:#fff
    classDef component fill:#1a202c,stroke:#a0aec0,stroke-width:2px,rx:3,color:#fff
    classDef api fill:#3182ce,stroke:#90cdf4,stroke-width:2px,rx:3,color:#fff
    classDef features fill:#319795,stroke:#81e6d9,stroke-width:2px,rx:3,color:#fff
    classDef services fill:#2f855a,stroke:#9ae6b4,stroke-width:2px,rx:3,color:#fff

    class API,Features,Services layer
    class MCP,Val,Rate api
    class Repo,Branch,Issue,PR,File,Release features
    class GitHub,Mapper,RateLimiter services

</details>

核心组件：

• MCP 协议层: 处理与 AI 助手的通信
• 验证层: 通过模式验证确保数据完整性
• GitHub 服务: 与 GitHub REST API 的核心集成
• 速率限制器: 防止 API 速率限制耗尽
• 特性模块: 领域特定的 GitHub 操作
• 错误处理: 全面的错误处理和日志记录系统

特性

仓库管理

• 创建、列表、获取: 创建新仓库、列出用户仓库并获取详细的仓库信息
• 验证 & 配置: 验证仓库设置并管理配置选项

分支管理

• 创建、删除、列表: 通过安全验证完成分支生命周期管理
• 受保护分支支持: 过滤和操作受保护的分支

议题管理

• 创建 & 列表: 创建带有标签的详细议题，并列出带有过滤选项的议题
• 状态跟踪: 按议题状态（打开、关闭、全部）进行过滤

拉取请求管理

• 创建、更新、合并、列表: 完整的拉取请求生命周期管理
• 审查 & 评论集成: 向拉取请求添加审查和评论
• 合并选项: 支持不同的合并策略（合并、压缩、变基）

文件管理

• 创建 & 更新文件: 添加和修改带有提交消息的仓库内容
• Base64 编码支持: 处理文本和二进制文件内容

发布管理

• 创建发布: 创建带有可自定义选项的标记发布
• 草稿 & 预发布支持: 支持草稿和预发布工作流程

安装

前提条件

• Node.js (v16 或更高版本)
• 具有适当权限的 GitHub 个人访问令牌

设置

1. 克隆仓库：

   git clone https://github.com/cyanheads/github-mcp-server.git
   cd github-mcp-server
   

2. 安装依赖项：

   npm install
   

3. 在项目根目录中创建一个 .env 文件，其中包含您的 GitHub 令牌：

   GITHUB_TOKEN=your_github_personal_access_token
   LOG_LEVEL=info
   SERVER_NAME=github-mcp-server
   

4. 构建项目：

   npm run build
   

5. 启动服务器：

   node build/index.js
   

配置

可以通过环境变量配置服务器：

环境变量	描述	默认值
GITHUB_TOKEN	GitHub 个人访问令牌（必需）	-
LOG_LEVEL	日志记录级别（debug、info、warn、error、fatal）	info
SERVER_NAME	MCP 服务器名称	github-mcp-server
SERVER_VERSION	MCP 服务器版本	0.1.0
API_TIMEOUT_MS	API 调用超时时间（毫秒）	10000
RATE_LIMITING_ENABLED	是否启用速率限制	true
RATE_LIMITING_MIN_REMAINING	限制前剩余的最小请求数	100
RATE_LIMITING_RESET_BUFFER_MS	添加到速率限制重置时间的时间缓冲区（毫秒）	5000

MCP 客户端设置

添加到您的 MCP 客户端设置：

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/path/to/github-mcp-server/build/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_github_personal_access_token",
        "LOG_LEVEL": "info",
        "SERVER_NAME": "github-mcp-server"
      }
    }
  }
}

项目结构

该项目遵循原子特性导向的架构模式：

/src
  /configuration             // 应用程序配置
  /dependencyInjection       // 工具注册表和 DI 容器
  /features                  // 按域组织的特性模块
    /repositoryManagement
      /resources             // 读取操作
      /modifications         // 写入操作
    /branchManagement
    /issueManagement
    /pullRequestManagement
    /fileManagement
    /releaseManagement
  /services                  // 外部服务集成
    /githubAccess            // GitHub API 客户端和实用程序
  /types                     // 核心类型定义
  /utilities                 // 辅助函数和实用程序

每个特性域都分为：

• Resources: 不修改数据的读取操作
• Modifications: 创建、更新或删除数据的写入操作

每个操作都包含在自己的目录中，其中包含：

• 操作实现文件
• 类型定义文件
• 导出索引文件

工具

GitHub MCP Server 提供了一套全面的工具，用于与 GitHub 交互：

仓库管理工具

工具	描述
get_repository	获取有关特定仓库的详细信息<br>参数：owner、repo
list_repositories	列出经过身份验证的用户的仓库<br>参数：type（可选）、sort（可选）
create_repository	创建新的 GitHub 仓库<br>参数：name、description（可选）、private（可选）

分支管理工具

工具	描述
list_branches	列出仓库中的分支<br>参数：owner、repo、protected（可选）、per_page（可选）
create_branch	创建新分支<br>参数：owner、repo、branch、sha
delete_branch	删除分支<br>参数：owner、repo、branch

议题管理工具

工具	描述
create_issue	在仓库中创建新议题<br>参数：owner、repo、title、body（可选）、labels（可选）
list_issues	列出仓库中的议题<br>参数：owner、repo、state（可选）、labels（可选）

拉取请求管理工具

工具	描述
create_pull_request	创建新的拉取请求<br>参数：owner、repo、title、head、base、body（可选）
merge_pull_request	合并拉取请求<br>参数：owner、repo、pull_number、commit_title（可选）、commit_message（可选）、merge_method（可选）
update_pull_request	更新现有拉取请求<br>参数：owner、repo、pull_number、title（可选）、body（可选）、state（可选）、base（可选）、maintainer_can_modify（可选）
list_pull_requests	列出仓库中的拉取请求<br>参数：owner、repo、state（可选）、head（可选）、base（可选）、sort（可选）、direction（可选）

文件管理工具

工具	描述
update_file	在仓库中创建或更新文件<br>参数：owner、repo、path、message、content、sha（可选）、branch（可选）

发布管理工具

工具	描述
create_release	创建新发布<br>参数：owner、repo、tag_name、name（可选）、body（可选）、draft（可选）、prerelease（可选）

开发

项目结构

该项目遵循严格的命名约定和目录结构：

• 文件命名：action.entity.type.ts（例如，create.repository.operation.ts）
• 每个模块都有明确定义的用途
• 类型与其实现位于同一位置
• 所有导出都通过索引文件集中管理

脚本

• npm run build - 构建项目
• npm run watch - 监视更改并重建
• npm run inspector - 运行 MCP 检查器工具
• npm run clean - 清理构建工件
• npm run rebuild - 清理并重建项目
• npm run tree - 生成目录树表示

错误处理

服务器实现了全面的错误处理策略：

• 标准化错误对象: 具有分类的一致错误格式
• 输入验证: 使用 Zod 模式进行预验证
• 速率限制保护: 自动处理 GitHub API 速率限制
• 错误类别:
  • 网络错误（连接问题）
  • 身份验证错误（令牌问题）
  • 验证错误（无效输入）
  • GitHub API 错误（API 特定问题）
  • 系统错误（意外故障）
• 详细日志记录: 所有操作和错误的结构化日志记录

贡献

欢迎贡献！请随时提交拉取请求。

1. Fork 仓库
2. 创建您的特性分支 (git checkout -b feature/amazing-feature)
3. 提交您的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

Apache License 2.0

---

<div align="center"> 使用模型上下文协议构建 </div>