麦普吉比特集成

Name: 麦普吉比特集成
Author: onamfc

作者：onamfc2 星标更新：2025-11-21

安装使用来源：spider==github.com

项目介绍

技术文档摘要

GitHub MCP API 客户端

这是一个 TypeScript 包，通过 MCP（模型上下文协议）服务器集成与 GitHub API 进行交互。

特性

具有类型定义的完整 TypeScript 支持
129 个 MCP 工具涵盖所有主要的 GitHub API 操作：
- 仓库管理（创建、更新、删除、搜索、设置、管理）
- 问题跟踪（创建、更新、关闭、评论、搜索）
- 拉取请求管理（创建、合并、审查、评论）
- 分支操作（创建、删除、列出、保护）
- 提交操作（列出、获取、比较）
- 发布管理（创建、更新、删除、资产）
- 内容操作（读取、写入、删除文件）
- GitHub Actions（工作流、运行、工件）
- 网络钩子（创建、更新、删除、交付、重新发送）
- 协作者和团队（添加、移除、权限）
- 仓库统计和洞察
- 安全设置（Dependabot、漏洞警报）
- 跨仓库、问题、拉取请求、代码、提交、用户、主题和标签的高级搜索
使用 @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);

// 获取认证用户
const response = await server.handleRequest({
  method: 'github_get_authenticated_user',
  params: {},
});

if (response.success) {
  console.log('用户:', response.data);
}

// 搜索仓库
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,
});

// 创建一个新的仓库
const newRepo = await client.createRepository({
  name: 'my-awesome-project',
  description: '我的优秀项目描述',
  private: false,
  auto_init: true,
});

// 获取仓库信息
const repo = await client.getRepository('owner', 'repo-name');
console.log(repo);

// 创建一个问题
const issue = await client.createIssue({
  owner: 'owner',
  repo: 'repo-name',
  title: 'Bug 报告',
  body: '关于 Bug 的描述',
  labels: ['bug'],
});

// 列出拉取请求
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 - 创建新的拉取请求
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 Actions（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 - 下载工作流工件

网络钩子操作（11 个端点）

github_list_webhooks - 列出仓库的所有网络钩子
github_get_webhook - 根据 ID 获取特定的网络钩子
github_create_webhook - 创建新的网络钩子
github_update_webhook - 更新现有的网络钩子
github_delete_webhook - 删除网络钩子
github_ping_webhook - 触发网络钩子的 ping 事件
github_test_webhook - 触发网络钩子的测试推送事件
github_list_webhook_deliveries - 列出网络钩子的交付
github_get_webhook_delivery - 获取特定的网络钩子交付
github_redeliver_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 - 获取认证用户信息

常见用例

仓库自动化

程序化地创建和配置仓库：

// 创建带有完整配置的仓库
await server.handleRequest({
  method: 'github_create_repository',
  params: {
    name: 'my-project',
    description: '我的优秀项目',
    private: false,
    auto_init: true,
    gitignore_template: 'Node',
    license_template: 'mit',
  },
});

// 更新仓库设置
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,
  },
});

// 添加话题以提高可发现性
await server.handleRequest({
  method: 'github_replace_repository_topics',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    topics: ['javascript', 'api', 'automation'],
  },
});

团队及访问管理

管理协作者和权限：

// 添加协作者
await server.handleRequest({
  method: 'github_add_collaborator',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    username: 'developer123',
    permission: 'push',
  },
});

// 添加团队访问权限
await server.handleRequest({
  method: 'github_add_repository_team',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    team_slug: 'backend-team',
    permission: 'admin',
  },
});

CI/CD 集成

自动化工作流和部署：

// 列出工作流运行
await server.handleRequest({
  method: 'github_list_workflow_runs',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    workflow_id: 'deploy.yml',
  },
});

// 重新运行失败的工作流
await server.handleRequest({
  method: 'github_rerun_workflow',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    run_id: 123456,
  },
});

// 下载构建工件
await server.handleRequest({
  method: 'github_download_artifact',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    artifact_id: 789012,
  },
});

网络钩子管理

设置基于事件驱动的集成：

// 创建网络钩子
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,
  },
});

// 列出网络钩子交付
await server.handleRequest({
  method: 'github_list_webhook_deliveries',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    hook_id: 12345,
  },
});

// 重新发送失败的网络钩子交付
await server.handleRequest({
  method: 'github_redeliver_webhook',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    hook_id: 12345,
    delivery_id: 67890,
  },
});

发布管理

自动化发布工作流：

// 创建发布
await server.handleRequest({
  method: 'github_create_release',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    tag_name: 'v1.0.0',
    name: '版本 1.0.0',
    body: '发布说明在这里',
    draft: false,
    prerelease: false,
  },
});

// 获取最新发布
await server.handleRequest({
  method: 'github_get_latest_release',
  params: {
    owner: 'myorg',
    repo: 'my-project',
  },
});

示例

在 examples/basic-usage.ts 中提供了一个演示客户端功能的工作示例：

基本使用示例

演示所有核心操作：

获取仓库信息
列出问题和拉取请求
列出分支和提交
获取认证用户信息

运行示例：

# 使用默认仓库（octocat/Hello-World）
GITHUB_TOKEN=your_token npm run example:basic

# 使用您自己的仓库
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,        // 工具/方法名称
  params: {              // 方法参数
    [key: string]: any
  }
}

响应格式

{
  success: boolean,      // 请求是否成功
  data?: any,            // 响应数据（如果成功）
  error?: {              // 错误信息（如果失败）
    code: string,
    message: string,
    details?: any
  }
}

重要注意事项

GitHub 令牌要求

需要 GitHub 个人访问令牌
在 https://github.com/settings/tokens 处生成一个
所需范围取决于操作：
- repo - 完整的仓库访问权限（针对私有仓库）
- public_repo - 仅限公共仓库访问
- read:user - 读取用户资料数据
- user:email - 读取用户电子邮件地址
- admin:repo_hook - 对仓库钩子（网络钩子）的完全控制
- admin:org - 对组织设置的完全控制（针对团队操作）
- workflow - 更新 GitHub Actions 工作流

速率限制

GitHub API 有速率限制：

已认证请求：每小时 5,000 次请求
未认证请求：每小时 60 次请求
在响应头中检查速率限制状态
如果达到速率限制，客户端会抛出错误

错误处理

所有方法在失败时都会抛出 GitHubAPIError：

try {
  const repo = await client.getRepository('owner', 'repo');
} catch (error) {
  if (error instanceof GitHubAPIError) {
    console.error(`错误 ${error.code}: ${error.message}`);
    console.error('状态码:', error.statusCode);
  }
}

安全最佳实践

绝不要将 GitHub 令牌提交到版本控制系统
使用环境变量存储令牌
定期轮换令牌
使用最小所需的范围来创建令牌
考虑在生产应用中使用 GitHub 应用
总是使用网络钩子密钥进行签名验证
在仓库上启用 Dependabot 安全警报

API 文档

有关详细的 GitHub API 文档，请访问：

许可证

此项目根据 MIT 许可证授权 - 详情请参阅 LICENSE 文件。

贡献

欢迎贡献！请随时提交 Pull Request。对于重大更改，请先打开一个议题讨论您想要更改的内容。

请确保适当更新测试。