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 -列出存储库的所有Webhook
github_get_webhook -按ID获取特定的webhook
github_create_webhook -创建新的webhook
github_update_webhook -更新现有的webhook
github_delete_webhook -删除webhook
github_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的详细文档，请访问：

Octokit.js文档

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

贡献

欢迎投稿！请随时提交拉取请求。对于重大更改，请先打开一个问题来讨论您想要更改的内容。

请确保根据需要更新测试。

MCP GitHub Integration

快速接入

详细介绍