使用说明

GitHub MCP 服务器

一个模型上下文协议（MCP）服务器，为AI助手和应用程序提供全面的GitHub API集成。该服务器采用TypeScript构建，具备强大的错误处理、日志记录、重试机制和速率限制功能。

✨ 特点/功能

这个MCP服务器提供了以下工具：

仓库管理

获取仓库信息
为用户/组织列出存储库
创建新分支
搜索存储库

问题管理

创建问题
列出过滤时遇到的问题
获取问题详情

拉取请求管理

创建拉取请求
列出并筛选拉取请求
获取拉取请求详情

提交管理（或：提交控制）

列出并过滤提交记录
获取提交详情和统计数据

文件管理

获取文件/目录内容
创建或更新文件

搜索

搜索仓库
搜索问题和拉取请求

🚀 新功能与改进

增强型架构

类型安全全面的 TypeScript 类型和接口
错误处理使用自定义错误类进行集中错误处理
记录日志具有可配置级别的结构化日志记录
重试机制自动重试，采用指数退避策略
速率限制内置速率限制以防止滥用API
配置基于环境的配置管理

性能与可靠性

请求/响应日志记录完整API调用监控
性能追踪所有操作的持续时间测量
输入验证对所有输入进行Zod模式验证
**输入净化（或输入验证）**注重安全的输入清理
重试逻辑对失败的请求进行自动重试
错误恢复优雅的错误处理与恢复

📦 安装

克隆此仓库：

git clone <repository-url>
cd github-mcp-server

安装依赖项：

pnpm install

设置环境变量：

cp env.example .env

编辑 .env 并配置您的设置：

# Required: GitHub Personal Access Token
GITHUB_TOKEN=your_github_token_here

# Optional: Environment Configuration
NODE_ENV=development
LOG_LEVEL=info

# Optional: Rate Limiting Configuration
RATE_LIMIT_MAX_REQUESTS=100
RATE_LIMIT_WINDOW_MS=60000

# Optional: Retry Configuration
MAX_RETRIES=3
RETRY_DELAY_MS=1000

获取GitHub令牌

首选 GitHub 设置 > 个人访问令牌
点击“生成新令牌（经典版）”
选择以下范围：
- repo （对私有仓库的完全控制）
- read:user （读取用户资料数据）
- read:org (阅读组织和团队成员信息)
将生成的令牌复制到您的 .env 文件

🛠️ 使用方法

发展

pnpm dev

构建并运行

pnpm build
pnpm start

类型检查

pnpm type-check

⚙️ 配置

环境变量

变量	描述	默认值	是否必需
（无对应中文）	（无对应中文）	（无对应中文）	（无对应中文）
GitHub 个人访问令牌	-	✅	`NODE_ENV`
环境（开发/生产/测试）	开发	❌	`LOG_LEVEL`
日志级别（错误/警告/信息/调试）	信息	❌	`RATE_LIMIT_MAX_REQUESTS`
每窗口最大请求数	100	❌	`RATE_LIMIT_WINDOW_MS`
速率限制窗口（毫秒）	60000	❌	`MAX_RETRIES`
最大重试次数	3	❌	`RETRY_DELAY_MS`

| 重试延迟（毫秒） | 1000 | ❌ |

记录日志

**服务器提供结构化日志记录，包含以下级别：**错误
致命错误和故障警告
警告信息信息
一般信息调试

详细的调试信息

[2024-01-15T10:30:00.000Z] [INFO] Tool request: get_repo_info {"args": {"owner": "octocat", "repo": "Hello-World"}}
[2024-01-15T10:30:00.500Z] [INFO] Tool completed: get_repo_info {"duration": "500ms"}

示例日志输出：

🔧 可用工具

get_repo_info 服务器提供以下MCP工具：
list_repos - 获取仓库信息
create_branch - 列出存储库
create_issue - 在仓库中创建一个新分支
list_issues - 创建一个新问题
get_issue - 列出仓库中的问题
create_pull_request - 获取问题详情
list_pull_requests - 创建一个拉取请求
get_pull_request - 列出拉取请求
list_commits - 获取拉取请求详情
get_commit - 列出提交记录
get_file_content - 获取提交详情
create_or_update_file - 获取文件/目录内容
search_repos - 创建或更新文件
search_issues - 搜索仓库
compare_branches - 搜索问题和拉取请求
merge_branches - 比较两个分支并显示差异

- 将一个分支合并到另一个分支

📝 工具示例

创建分支工具 create_branch 这个

该工具允许你在GitHub仓库中创建一个新分支：

owner 参数：
repo （必填）：仓库所有者（用户名或组织）
branch （必填）：仓库名称
base_branch （必填）：要创建的新分支的名称

（可选）：用于创建的基分支（默认为“main”）

{
  "name": "create_branch",
  "arguments": {
    "owner": "octocat",
    "repo": "Hello-World",
    "branch": "feature/new-feature",
    "base_branch": "main"
  }
}

示例用法：

{
  "ref": "refs/heads/feature/new-feature",
  "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "url": "https://api.github.com/repos/octocat/Hello-World/git/refs/heads/feature/new-feature",
  "branch_name": "feature/new-feature",
  "base_branch": "main"
}

回答：

Git 操作工具

分支比较工具 compare_branches 该

该工具允许您比较两个分支并分析它们的差异：

owner 参数：
repo （必填）：仓库所有者（用户名或组织）
base （必填）：仓库名称
head （必填）：基础分支名称

（必填）：要与基础分支进行比较的头分支名称

{
  "name": "compare_branches",
  "arguments": {
    "owner": "octocat",
    "repo": "Hello-World",
    "base": "main",
    "head": "feature/new-feature"
  }
}

示例用法：

{
  "status": "ahead",
  "ahead_by": 3,
  "behind_by": 0,
  "total_commits": 3,
  "base_commit": {
    "sha": "abc123...",
    "message": "Latest commit on main",
    "author": "octocat",
    "date": "2024-01-15T10:00:00Z"
  },
  "commits": [
    {
      "sha": "def456...",
      "message": "Add new feature",
      "author": "developer",
      "date": "2024-01-15T11:00:00Z",
      "url": "https://github.com/octocat/Hello-World/commit/def456..."
    }
  ],
  "files": [
    {
      "filename": "src/feature.js",
      "status": "added",
      "additions": 50,
      "deletions": 0,
      "changes": 50
    }
  ]
}

回应：

合并分支工具 merge_branches 这个（或“它”）

该工具允许您以编程方式将一个分支合并到另一个分支中：

owner 参数：
repo （必填）：仓库所有者（用户名或组织）
base （必填）：仓库名称
head （必填）：要合并到的目标分支
commit_message （必填）：要合并的源分支

（可选）：为合并操作自定义提交信息

{
  "name": "merge_branches",
  "arguments": {
    "owner": "octocat",
    "repo": "Hello-World",
    "base": "main",
    "head": "feature/new-feature",
    "commit_message": "feat: Add new feature"
  }
}

示例用法：

{
  "sha": "ghi789...",
  "merged": true,
  "message": "feat: Add new feature",
  "author": "octocat",
  "date": "2024-01-15T12:00:00Z",
  "url": "https://github.com/octocat/Hello-World/commit/ghi789...",
  "parents": [
    {
      "sha": "abc123...",
      "url": "https://github.com/octocat/Hello-World/commit/abc123..."
    },
    {
      "sha": "def456...", 
      "url": "https://github.com/octocat/Hello-World/commit/def456..."
    }
  ]
}

回答：

🏗️ 项目结构 该项目遵循 基于特征的架构

src/
├── features/         # Feature modules (feature-based architecture)
│   ├── index.ts      # Aggregates all handlers and tool definitions
│   ├── commit/       # Commit management feature
│   │   ├── handler.ts    # MCP request handlers
│   │   ├── schema.ts     # Zod validation schemas
│   │   ├── service.ts    # GitHub API services & interfaces
│   │   └── index.ts      # Feature exports
│   ├── file/         # File management feature
│   │   ├── handler.ts
│   │   ├── schema.ts
│   │   ├── service.ts
│   │   └── index.ts
│   ├── git/          # Git operations feature
│   │   ├── handler.ts
│   │   ├── schema.ts
│   │   ├── service.ts
│   │   └── index.ts
│   ├── issue/        # Issue management feature
│   │   ├── handler.ts
│   │   ├── schema.ts
│   │   ├── service.ts
│   │   └── index.ts
│   ├── pullRequest/  # Pull request management feature
│   │   ├── handler.ts
│   │   ├── schema.ts
│   │   ├── service.ts
│   │   └── index.ts
│   ├── repo/         # Repository management feature
│   │   ├── handler.ts
│   │   ├── schema.ts
│   │   ├── service.ts
│   │   └── index.ts
│   └── search/       # Search feature
│       ├── handler.ts
│       ├── schema.ts
│       ├── service.ts
│       └── index.ts
├── shared/           # Shared utilities and components
│   ├── index.ts      # Shared exports
│   ├── schema.ts     # Common schemas (JsonRpc, etc.)
│   └── service.ts    # Common services (Octokit setup)
├── config/           # Configuration management
│   └── index.ts      # Environment configuration
├── types/            # TypeScript type definitions
│   └── index.ts      # Common types and interfaces
├── utils/            # Utility functions
│   ├── index.ts      # Common utilities (error handling, etc.)
│   └── logger.ts     # Logging system
└── index.ts          # MCP server implementation (entry point)

为了提高可维护性和可扩展性：

架构优势

基于特征的组织方式：
每个功能（如提交、文件、问题等）都是独立的，拥有自己的处理器、模式和服务
易于维护、测试和扩展单个功能
职责与责任的清晰划分

轻松添加新功能，且不影响现有代码

共享组件： shared/
常用的工具和配置被集中管理在
所有功能中一致的错误处理和日志记录

可重用的架构和服务

🔒 安全功能输入验证
所有输入均使用Zod模式进行验证输入消毒（或输入清理/输入验证）
HTML标签和特殊字符已进行清理速率限制
内置速率限制以防止滥用API错误处理
安全的错误消息，不泄露敏感信息代币安全性

GitHub token 仅从环境变量中加载

🚀 性能特性重试机制
对于失败的请求，自动进行指数退避重试请求记录
全面的API调用监控和性能追踪缓存
内置请求缓存以减少API调用速率限制
智能限速以尊重GitHub API限制性能监控

所有操作的持续时间追踪

🐛 错误处理

**服务器提供全面的错误处理：**验证错误
清晰的验证错误消息GitHub API 错误
妥善处理GitHub API错误网络错误
网络故障时自动重试速率限制错误
优雅地处理超出速率限制的情况认证错误

清晰的认证错误信息

📊 监控与日志记录结构化日志记录
带有时间戳的JSON格式日志性能指标
请求持续时间和成功率错误追踪
详细的错误日志记录，包括堆栈跟踪API监控
完整的GitHub API调用监控可配置的日志级别

可调节的日志详细程度

🤝 贡献（或“参与贡献”）
为仓库创建分支 git checkout -b feature/amazing-feature
创建一个特性分支： git commit -m 'Add amazing feature'
提交您的更改： git push origin feature/amazing-feature
推送到分支：

提交一个拉取请求

📄 许可证

麻省理工学院（MIT）

🙏 致谢模型上下文协议
对于MCP规范 Octokit（注：Octokit是一个用于与GitHub API交互的库，通常用于开发GitHub相关的应用程序或工具）
用于GitHub API集成佐德
用于运行时类型验证 TypeScript

使用说明

GitHub MCP 服务器

✨ 特点/功能

仓库管理

问题管理

拉取请求管理

提交管理（或：提交控制）

文件管理

搜索

🚀 新功能与改进

增强型架构

性能与可靠性

📦 安装

获取GitHub令牌

🛠️ 使用方法

发展

构建并运行

类型检查

⚙️ 配置

环境变量

| 重试延迟（毫秒） | 1000 | ❌ |

示例日志输出：

- 将一个分支合并到另一个分支

📝 工具示例

回答：

Git 操作工具

回应：

回答：

为了提高可维护性和可扩展性：

可重用的架构和服务

GitHub token 仅从环境变量中加载

所有操作的持续时间追踪

清晰的认证错误信息

可调节的日志详细程度

提交一个拉取请求

麻省理工学院（MIT）

相关 MCP

12306票务搜索服务

Git仓库管理MCP服务器

GitLab项目管理服务器

数学计算协议服务

金融数据服务

Git MCP 服务器