cyanheads
服务介绍
GitHub MCP 服务器
一个实现模型上下文协议（MCP）的服务器，提供与GitHub API交互的工具。该服务器允许LLM代理通过标准化接口管理GitHub仓库、问题、拉取请求、分支、文件和发布。
目录
概述
github-mcp-server 实现了模型上下文协议（MCP），通过以下方式实现了LLM与外部系统之间的标准化通信：
- 客户端：Claude Desktop、IDE和其他MCP兼容客户端
- 服务器：用于项目管理和协作的工具和资源
- LLM代理：利用程序化执行GitHub操作能力的人工智能模型
它充当AI模型与GitHub API之间的桥梁，提供了一组定义良好的工具，这些工具遵循一致的模式，并处理身份验证、验证、错误处理和速率限制。
主要功能包括：
- GitHub API集成：安全无缝地与GitHub REST API集成
- 全面的GitHub功能：对仓库、分支、问题、PR等进行全面管理
- 原子化功能架构：为可维护性而设计的模块化代码结构
- 输入验证：所有操作均使用Zod模式进行强大的验证
- 错误处理：一致的错误分类和报告
- 速率限制：内置GitHub API速率限制处理
- 性能优化：优化的操作和响应格式
架构与组件
核心系统架构：
mermaid
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
核心组件：
- MCP 协议层：处理与 AI 助手的通信
- 验证层：通过模式验证确保数据完整性
- GitHub 服务：与 GitHub REST API 的核心集成
- 速率限制器：防止 API 速率限制耗尽
- 功能模块：特定领域的 GitHub 操作
- 错误处理：全面的错误处理和日志系统
功能
仓库管理
- 创建、列出、获取：创建新仓库，列出用户仓库，并获取详细的仓库信息
- 验证与配置：验证仓库设置并管理配置选项
分支管理
- 创建、删除、列出：完整的分支生命周期管理，带有安全验证
- 受保护分支支持：过滤和操作受保护的分支
问题管理
- 创建与列出：创建带有标签的详细问题，并列出具有过滤选项的问题
- 状态跟踪：按问题状态（打开、关闭、全部）进行过滤
拉取请求管理
- 创建、更新、合并、列出：完整的拉取请求生命周期管理
- 审查与评论集成：向拉取请求添加审查和评论
- 合并选项：支持不同的合并策略（合并、压缩、变基）
文件管理
- 创建与更新文件：使用提交消息添加和修改仓库内容
- Base64 编码支持：处理文本和二进制文件内容
发布管理
- 创建发布：创建带有可自定义选项的标记发布
- 草稿与预发布支持：支持草稿和预发布工作流
安装
前提条件
- Node.js (v16 或更高版本)
- 具有适当权限的 GitHub 个人访问令牌
设置
-
克隆仓库：
bash
git clone https://github.com/cyanheads/github-mcp-server.git
cd github-mcp-server -
安装依赖项：
bash
npm install -
在项目根目录下创建一个
.env文件，并在其中添加您的 GitHub 令牌：GITHUB_TOKEN=your_github_personal_access_token
LOG_LEVEL=info
SERVER_NAME=github-mcp-server -
构建项目：
bash
npm run build -
启动服务器：
bash
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 客户端设置中：
json
{
"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 // 辅助函数和工具每个功能域被划分为：
- 资源：不修改数据的读取操作
- 修改：创建、更新或删除数据的写入操作
每个操作都包含在自己的目录中，包括：
- 操作实现文件
- 类型定义文件
- 导出索引文件
工具
GitHub MCP 服务器提供了一整套与 GitHub 交互的工具：
仓库管理工具
| 工具 | 描述 |
|---|---|
get_repository |
获取特定仓库的详细信息参数: owner, repo |
list_repositories |
列出已认证用户的所有仓库参数: type (可选), sort (可选) |
create_repository |
创建一个新的 GitHub 仓库参数: name, description (可选), private (可选) |
分支管理工具
| 工具 | 描述 |
|---|---|
list_branches |
列出仓库中的分支参数: owner, repo, protected (可选), per_page (可选) |
create_branch |
创建一个新分支参数: owner, repo, branch, sha |
delete_branch |
删除一个分支参数: owner, repo, branch |
问题管理工具
| 工具 | 描述 |
|---|---|
create_issue |
在仓库中创建一个新的问题参数: owner, repo, title, body (可选), labels (可选) |
list_issues |
列出仓库中的问题参数: owner, repo, state (可选), labels (可选) |
拉取请求管理工具
| 工具 | 描述 |
|---|---|
create_pull_request |
创建一个新的拉取请求参数: owner, repo, title, head, base, body (可选) |
merge_pull_request |
合并一个拉取请求参数: owner, repo, pull_number, commit_title (可选), commit_message (可选), merge_method (可选) |
update_pull_request |
更新现有的拉取请求参数: owner, repo, pull_number, title (可选), body (可选), state (可选), base (可选), maintainer_can_modify (可选) |
list_pull_requests |
列出仓库中的拉取请求参数: owner, repo, state (可选), head (可选), base (可选), sort (可选), direction (可选) |
文件管理工具
| 工具 | 描述 || ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| update_file | 在仓库中创建或更新文件参数：owner, repo, path, message, content, sha (可选), branch (可选) |
发布管理工具
| 工具 | 描述 |
|---|---|
create_release |
创建新的发布参数：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特定问题）
- 系统错误（意外故障）
- 详细日志记录：对所有操作和错误进行结构化日志记录
贡献
欢迎贡献！请随时提交Pull Request。
- 分叉仓库
- 创建你的功能分支 (
git checkout -b feature/amazing-feature) - 提交你的更改 (
git commit -m 'Add some amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 打开一个Pull Request
