GitHub MCP API客户端
用于通过MCP（模型上下文协议）服务器集成与GitHub API交互的TypeScript包。
特性
- 完全支持TypeScript和类型定义
- 129 MCP工具 涵盖所有主要的GitHub API操作：
- 存储库管理（创建、更新、删除、搜索、设置、管理） - 问题跟踪（创建、更新、关闭、评论、搜索） - 拉取请求管理（创建、合并、审核、评论） - 分支操作（创建、删除、列出、保护） - 提交操作（列表、获取、比较） - 发布管理（创建、更新、删除、资产） - 内容操作（读取、写入、删除文件） - GitHub操作（工作流、运行、工件） - Webhooks（创建、更新、删除、交付、重新交付） - 协作者和团队（添加、删除、权限） - 存储库统计数据和见解 - 安全设置（Dependabot、漏洞警报） - 跨存储库、问题、PR、代码、提交、用户、主题和标签的高级搜索
- 内置日志功能
@onamfc/developer-log - 包装检查
@onamfc/pkg-inspect - 稳健的错误处理
安装
来自NPM
npm install @onamfc/mcp-github-integration来源
git clone https://github.com/onamfc/mcp-github-integration.git
cd mcp-github-integration
npm install
npm run build配置
将您的GitHub个人访问令牌设置为环境变量：
export GITHUB_TOKEN=your_github_token_here用法
使用MCP服务器
import { MCPServer } from '@onamfc/mcp-github-integration';
const server = new MCPServer(process.env.GITHUB_TOKEN);
// Get authenticated user
const response = await server.handleRequest({
method: 'github_get_authenticated_user',
params: {},
});
if (response.success) {
console.log('User:', response.data);
}
// Search repositories
const searchResponse = await server.handleRequest({
method: 'github_search_repositories',
params: {
q: 'typescript',
per_page: 10,
},
});直接使用GitHub客户端
import { GitHubClient } from '@onamfc/mcp-github-integration';
const client = new GitHubClient({
token: process.env.GITHUB_TOKEN,
});
// Create a new repository
const newRepo = await client.createRepository({
name: 'my-awesome-project',
description: 'My awesome project description',
private: false,
auto_init: true,
});
// Get repository information
const repo = await client.getRepository('owner', 'repo-name');
console.log(repo);
// Create an issue
const issue = await client.createIssue({
owner: 'owner',
repo: 'repo-name',
title: 'Bug Report',
body: 'Description of the bug',
labels: ['bug'],
});
// List pull requests
const prs = await client.listPullRequests({
owner: 'owner',
repo: 'repo-name',
state: 'open',
});可用的GitHub API操作
存储库操作（25个端点）
github_get_repository-获取存储库信息github_list_repositories-列出用户的公共存储库github_create_repository-创建新存储库github_delete_repository-删除存储库github_update_repository-更新存储库设置和配置github_get_repository_topics-获取存储库主题/标签github_replace_repository_topics-设置存储库主题以实现可发现性github_get_repository_languages-使用编程语言github_get_code_frequency_stats-获取每周添加/删除统计数据github_get_contributors_stats-获取贡献者活动统计数据github_get_participation_stats-获取每周提交次数统计github_transfer_repository-将存储库转移给新所有者github_list_repository_teams-列出有权访问存储库的团队github_check_team_permission-检查存储库的团队权限github_add_repository_team-添加或更新团队对存储库的访问权限github_remove_repository_team-从存储库中删除团队访问权限github_enable_automated_security_fixes-启用Dependabot自动安全修复程序github_disable_automated_security_fixes-禁用自动安全修复程序github_enable_vulnerability_alerts-启用Dependabot漏洞警报github_disable_vulnerability_alerts-禁用漏洞警报
协作者管理（7个端点）
github_list_collaborators-列出存储库合作者github_check_collaborator-检查用户是否为合作者github_add_collaborator-将合作者添加到存储库github_remove_collaborator-从存储库中删除合作者github_get_collaborator_permission-获取合作者权限级别github_list_repository_invitations-列出待处理的存储库邀请github_delete_repository_invitation-删除/取消存储库邀请
问题操作（9个端点）
github_create_issue-创建新问题github_list_issues-在存储库中列出问题github_get_issue-获取特定问题github_update_issue-更新现有问题github_close_issue-关闭问题github_create_issue_comment-向问题添加评论github_list_issue_comments-列出对某个问题的评论github_update_issue_comment-更新问题评论github_delete_issue_comment-删除问题注释
拉取请求操作（4个端点）
github_create_pull_request-创建新的pull请求github_list_pull_requests-在存储库中列出拉取请求github_get_pull_request-获取特定的拉取请求github_merge_pull_request-合并拉取请求
分支操作（5个端点）
github_list_branches-列出存储库中的所有分支github_get_branch-获取特定分支机构的信息github_create_branch-创建新分支github_delete_branch-删除分支github_get_branch_protection-获取分支保护规则
提交操作（3个端点）
github_list_commits-列出存储库中的提交github_get_commit-获得特定的承诺github_compare_commits-比较两个提交或分支
发布操作（6个端点）
github_list_releases-列出所有版本github_get_latest_release-获取最新版本github_get_release-按ID获取特定版本github_create_release-创建新版本github_update_release-更新版本github_delete_release-删除发布
内容操作（5个端点）
github_get_file_content-获取文件内容github_create_file-创建文件github_update_file-更新文件github_delete_file-删除文件github_get_directory_content-获取目录的内容
GitHub操作（9个端点）
github_list_workflows-列出所有工作流github_get_workflow-获取特定的工作流程github_list_workflow_runs-列表工作流运行github_get_workflow_run-运行特定的工作流github_cancel_workflow_run-取消工作流运行github_rerun_workflow-重新运行工作流github_delete_workflow_run-删除工作流运行github_list_workflow_run_artifacts-列出工作流运行的工件github_download_artifact-下载工作流工件
Webhook操作（11个端点）
github_list_webhooks-列出存储库的所有Webhookgithub_get_webhook-按ID获取特定的webhookgithub_create_webhook-创建新的webhookgithub_update_webhook-更新现有的webhookgithub_delete_webhook-删除webhookgithub_ping_webhook-向webhook触发ping事件github_test_webhook-向webhook触发测试推送事件github_list_webhook_deliveries-列出webhook的交付github_get_webhook_delivery-获取特定的webhook交付github_redeliver_webhook-重新交付webhook交付
搜索操作（8个端点）
github_search_repositories-搜索存储库github_search_issues-搜索问题并提取请求github_search_code-跨存储库搜索代码github_search_commits-搜索提交github_search_users-搜索用户github_search_topics-搜索主题github_search_labels-在存储库中搜索标签
用户操作（1个端点）
github_get_authenticated_user-获取经过身份验证的用户信息
常见用例
存储库自动化
以编程方式创建和配置存储库：
// Create repository with full configuration
await server.handleRequest({
method: 'github_create_repository',
params: {
name: 'my-project',
description: 'My awesome project',
private: false,
auto_init: true,
gitignore_template: 'Node',
license_template: 'mit',
},
});
// Update repository settings
await server.handleRequest({
method: 'github_update_repository',
params: {
owner: 'myorg',
repo: 'my-project',
has_issues: true,
has_wiki: false,
allow_squash_merge: true,
delete_branch_on_merge: true,
},
});
// Add topics for discoverability
await server.handleRequest({
method: 'github_replace_repository_topics',
params: {
owner: 'myorg',
repo: 'my-project',
topics: ['javascript', 'api', 'automation'],
},
});团队和访问管理
管理合作者和权限：
// Add collaborator
await server.handleRequest({
method: 'github_add_collaborator',
params: {
owner: 'myorg',
repo: 'my-project',
username: 'developer123',
permission: 'push',
},
});
// Add team access
await server.handleRequest({
method: 'github_add_repository_team',
params: {
owner: 'myorg',
repo: 'my-project',
team_slug: 'backend-team',
permission: 'admin',
},
});CI/CD集成
自动化工作流程和部署：
// List workflow runs
await server.handleRequest({
method: 'github_list_workflow_runs',
params: {
owner: 'myorg',
repo: 'my-project',
workflow_id: 'deploy.yml',
},
});
// Re-run failed workflow
await server.handleRequest({
method: 'github_rerun_workflow',
params: {
owner: 'myorg',
repo: 'my-project',
run_id: 123456,
},
});
// Download build artifacts
await server.handleRequest({
method: 'github_download_artifact',
params: {
owner: 'myorg',
repo: 'my-project',
artifact_id: 789012,
},
});Webhook管理
设置事件驱动的集成：
// Create webhook
await server.handleRequest({
method: 'github_create_webhook',
params: {
owner: 'myorg',
repo: 'my-project',
config: {
url: 'https://myapp.com/webhooks',
content_type: 'json',
secret: 'my-secret-key',
},
events: ['push', 'pull_request', 'issues'],
active: true,
},
});
// List webhook deliveries
await server.handleRequest({
method: 'github_list_webhook_deliveries',
params: {
owner: 'myorg',
repo: 'my-project',
hook_id: 12345,
},
});
// Redeliver failed webhook
await server.handleRequest({
method: 'github_redeliver_webhook',
params: {
owner: 'myorg',
repo: 'my-project',
hook_id: 12345,
delivery_id: 67890,
},
});发布管理
自动化发布工作流程：
// Create release
await server.handleRequest({
method: 'github_create_release',
params: {
owner: 'myorg',
repo: 'my-project',
tag_name: 'v1.0.0',
name: 'Version 1.0.0',
body: 'Release notes here',
draft: false,
prerelease: false,
},
});
// Get latest release
await server.handleRequest({
method: 'github_get_latest_release',
params: {
owner: 'myorg',
repo: 'my-project',
},
});示例
演示客户能力的工作示例见 examples/basic-usage.ts:
基本用法示例
演示所有核心操作：
- 获取存储库信息
- 列出问题和拉取请求
- 列出分支和提交
- 获取经过身份验证的用户信息
运行示例：
# Using default repository (octocat/Hello-World)
GITHUB_TOKEN=your_token npm run example:basic
# Using your own repository
GITHUB_TOKEN=your_token REPO_OWNER=owner REPO_NAME=repo npm run example:basic注： 这 examples/ 目录包含其他工作示例，包括 setup-new-repo.ts 这演示了存储库设置自动化。看 examples/README.md 了解详情。
MCP请求/响应格式
请求格式
{
method: string, // The tool/method name
params: { // Parameters for the method
[key: string]: any
}
}响应格式
{
success: boolean, // Whether the request succeeded
data?: any, // Response data (if successful)
error?: { // Error information (if failed)
code: string,
message: string,
details?: any
}
}重要说明
GitHub代币要求
- 需要GitHub个人访问令牌
- 在以下位置生成一个：https://github.com/settings/tokens
- 所需范围取决于操作：
- repo -完全存储库访问权限（用于私有存储库） - public_repo -仅限公共存储库访问 - read:user -读取用户配置文件数据 - user:email -读取用户电子邮件地址 - admin:repo_hook -完全控制存储库挂钩（webhooks） - admin:org -完全控制组织设置（用于团队操作） - workflow -更新GitHub操作工作流
速率限制
GitHub API有速率限制：
- 经过身份验证的请求：每小时5000个请求
- 未经身份验证的请求：每小时60个请求
- 检查响应标头中的速率限制状态
- 如果速率受限，客户端将抛出错误
错误处理
所有方法throw GitHubAPIError 失败时：
try {
const repo = await client.getRepository('owner', 'repo');
} catch (error) {
if (error instanceof GitHubAPIError) {
console.error(`Error ${error.code}: ${error.message}`);
console.error('Status:', error.statusCode);
}
}安全最佳实践
- 永远不要将GitHub令牌提交给版本控制
- 为令牌使用环境变量
- 定期旋转令牌
- 为您的令牌使用所需的最小范围
- 考虑将GitHub Apps用于生产应用程序
- 始终使用webhook密钥进行签名验证
- 在存储库上启用Dependabot安全警报
API 文档
有关GitHub API的详细文档，请访问：
许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
贡献
欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。
请确保根据需要更新测试。