GitHub MCP Server

🚨 此代码仓库已弃用。🚨

请改用官方 GitHub MCP 服务：https://github.com/github/github-mcp-server

🚨 此代码仓库已弃用。🚨

GitHub MCP 服务

一个用于与 GitHub API 交互的 Model Context Protocol（MCP）服务。该服务允许大模型 Agent 通过标准化接口管理 GitHub 仓库、议题、拉取请求、分支、文件和版本发布。

目录

• 概览
  • 架构与组件
• 功能
  • 仓库管理
  • 分支管理
  • 议题管理
  • 拉取请求管理
  • 文件管理
  • 版本发布管理
• 安装
  • 先决条件
  • 设置
• 配置
• 项目结构
• 工具
  • 仓库管理工具
  • 分支管理工具
  • 议题管理工具
  • 拉取请求管理工具
  • 文件管理工具
  • 版本发布管理工具
• 开发
  • 项目结构
  • 脚本
• 错误处理
• 贡献
• 许可证

概览

github-mcp-server 实现了 Model Context Protocol（MCP），通过以下方式实现大模型与外部系统之间的标准化通信：

• 客户端：Claude Desktop、IDE 及其他兼容 MCP 的客户端
• 服务：用于项目管理和协作的工具与资源
• 大模型 Agent：能够以编程方式执行 GitHub 操作的 AI 模型。

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

主要能力：

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

架构与组件

核心系统架构：

flowchart TB
    subgraph API["API Layer"]
        direction LR
        MCP["MCP Protocol"]
        Val["Validation"]
        Rate["Rate Limiting"]

        MCP --> Val --> Rate
    end

    subgraph Features["Feature Modules"]
        direction LR
        Repo["Repository Management"]
        Branch["Branch Management"]
        Issue["Issue Management"]
        PR["Pull Request Management"]
        File["File Management"]
        Release["Release Management"]

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

    subgraph Services["Services Layer"]
        direction LR
        GitHub["GitHub Service"]
        Mapper["Response Mapper"]
        RateLimiter["Rate Limiter"]

        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

核心组件：

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

功能

仓库管理

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

分支管理

• 创建、删除、列出：通过安全验证完整管理分支生命周期
• 受保护分支支持：筛选和操作受保护分支

Issue 管理

• 创建与列出：创建包含标签的详细 Issue，并按筛选选项列出 Issue
• 状态跟踪：按 Issue 状态（open、closed、all）筛选

Pull Request 管理

• 创建、更新、合并、列出：完整管理 Pull Request 生命周期
• 审查与评论集成：为 Pull Request 添加审查和评论
• 合并选项：支持不同的合并策略（merge、squash、rebase）

文件管理

• 创建与更新文件：通过提交消息添加和修改仓库内容
• Base64 编码支持：处理文本和二进制文件内容

Release 管理

• 创建 Release：创建带标签的 Release，并可自定义选项
• 草稿与预发布支持：支持草稿和预发布工作流

安装

前提条件

• 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
   

配置

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

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             // Application configuration
  /dependencyInjection       // Tool registry and DI container
  /features                  // Feature modules organized by domain
    /repositoryManagement
      /resources             // Read operations
      /modifications         // Write operations
    /branchManagement
    /issueManagement
    /pullRequestManagement
    /fileManagement
    /releaseManagement
  /services                  // External service integrations
    /githubAccess            // GitHub API client and utilities
  /types                     // Core type definitions
  /utilities                 // Helper functions and utilities

每个功能领域分为：

• 资源：不会修改数据的读取操作
• 修改操作：创建、更新或删除数据的写入操作

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

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

工具

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

仓库管理工具

分支管理工具

问题管理工具

拉取请求管理工具

文件管理工具

发布管理工具

开发

项目结构

项目遵循严格的命名规范和目录结构：

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

脚本

• 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 的问题）
  • 系统错误（意外故障）
• 详细日志记录：对所有操作和错误进行结构化日志记录

贡献

欢迎贡献！请随时提交 Pull Request。

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. 打开 Pull Request

许可证

Apache License 2.0