mcp-github-enterprise

mcp-github-enterprise

一个默认安全的 Model Context Protocol 服务，可让 AI agent 管理 GitHub Enterprise（Cloud 和 Server）——组织、成员、团队、仓库、规则集、安全警报和 Actions；内置安全态势基线和治理控制，让 agent 能协助管理企业环境，同时无法造成严重破坏。

属于 dockndevai 治理型基础设施 MCP 服务套件。默认只读 · 限定组织范围 · 全程审计 · 由人工确认。

为什么需要它

向 agent 提供 GitHub 管理员令牌存在风险：一条不够严谨的指令就可能删除仓库、移除成员，或将组织改为公开。此服务为 agent 设置的控制措施，与授予初级管理员的控制措施相同：

• 除非你另行授权，否则只读。 高于当前访问模式的工具绝不会被列出。
• 限定影响范围。 使用组织允许列表和受保护组织（永久只读）。
• 破坏性操作需要通过多重门槛。 管理模式 ＋ 明确的删除标志 ＋ 指定格式的确认 ＋ 人工提示。提示会显示工具、确切参数和指纹；提示和操作会固定目标版本，如果版本发生变化则拒绝操作；无人响应的提示也会导致拒绝。
• 绝不泄露机密。 Webhook 机密和秘密扫描值会在传递给模型前进行脱敏。
• 所有操作均有审计记录。 每项操作都会向 stderr 写入一行 JSON。

此外，它不仅安全，还真正实用：内置一套有主见的安全基线——assess_org_posture 会评估实时组织的安全态势，harden_org_settings 会应用修复措施；另附两个运维技能（安全设置和 Actions 优化）。

快速开始

# Read-only, against GitHub Enterprise Cloud
GHE_TOKEN=your-token GHE_MODE=read-only npx -y @dockndevai/mcp-github-enterprise

添加到 Claude Code：

claude mcp add github-enterprise -e GHE_TOKEN="your-token" -e GHE_MODE="read-only" -- npx -y @dockndevai/mcp-github-enterprise

GitHub Enterprise Server：添加 -e GHE_API_URL="https://HOST/api/v3"。完整的客户端配置（Cursor、Windsurf、Codex、VS Code、Claude Desktop）请参阅 docs/CLIENTS.md。

首次运行的工具：whoami——确认令牌和基础 URL 配置正确。

配置

变量	默认值	用途
GHE_TOKEN	—	必需。 细粒度 PAT、经典 PAT 或 App 安装令牌。遵循最小权限原则。
GHE_API_URL	https://api.github.com	Cloud 默认值。GHES：https://HOST/api/v3。
GHE_ENTERPRISE	—	Enterprise slug，用于企业级审计日志 / 策略。
GHE_MODE	read-only	read-only → read-write → admin。
GHE_ORG_ALLOWLIST	（所有可见组织）	允许操作的组织，以逗号分隔。请固定此设置。
GHE_PROTECTED_ORGS	—	可读取但绝不修改的组织。
GHE_ALLOW_DELETE	false	执行任何破坏性操作时必需（同时需要 admin 模式）。
GHE_REQUIRE_CONFIRMATION	true	破坏性操作需要输入与目标匹配的确认信息。
GHE_DRY_RUN	false	验证并记录写入操作，但不发送请求。
GHE_AUDIT_LOG	true	每项操作都会向 stderr 输出一行 JSON 审计记录（也包含批准回执）。
交互式确认	（自动）	—
GHE_REQUIRE_HUMAN_APPROVAL	false	设为 true 时，如果客户端无法显示批准提示，则拒绝破坏性和高影响操作（而不是仅依赖 GHE_ALLOW_DELETE 门槛）。
GHE_MAX_PAGES	10	自动分页上限（每页 100 条）。
GHE_GUARD_MODE	off	可选的 laya-guard AI 风险门控：monitor | enforce。

完整列表请参阅 .env.example。

工具

仅注册当前模式允许的工具：read-only 模式 23 个，read-write 模式 32 个，admin 模式 38 个。

读取（始终启用）

whoami · get_rate_limit · list_organizations · get_organization · list_members · list_teams · list_security_managers · list_repositories · get_repository · get_branch_protection · list_org_rulesets · list_webhooks · get_actions_permissions · list_self_hosted_runners · list_runner_groups · get_actions_cache_usage · list_workflows · list_secret_scanning_alerts · list_code_scanning_alerts · list_dependabot_alerts · get_audit_log · assess_org_posture · recommend_enterprise_setup

写入（read-write 及以上）

harden_org_settings · update_org_settings · set_actions_permissions · create_team · set_member_role · create_org_ruleset · protect_branch · update_repo_security · create_webhook

写入前需经用户批准（客户端能够显示提示时；若 GHE_REQUIRE_HUMAN_APPROVAL=true，没有提示则拒绝执行）：harden_org_settings、update_org_settings、set_actions_permissions、create_org_ruleset、protect_branch、update_repo_security、create_webhook，以及授予 admin 权限时的 set_member_role。提示会显示更改内容（逐字段显示 current → new；对于 create_org_ruleset，会并列显示新规则集和现有规则集），且批准会绑定到提示中展示的状态。设为 GHE_DRY_RUN=true 时，这些工具会在显示任何提示前返回。create_team 不会显示提示。每次写入时，set_actions_permissions 都会发送 GitHub 要求的 enabled_repositories（若只设置 allowed_actions，则会从组织的实时策略中读取并保留当前 enabled_repositories）。protect_branch 接受 requiredStatusChecks（或其别名 requireStatusChecks）。

管理（admin，破坏性操作还需要 GHE_ALLOW_DELETE）

create_repository（创建 private 仓库时不会提示；创建 public 和 internal 仓库时会先征求人工确认；如果客户端无法提示，则在 GHE_REQUIRE_HUMAN_APPROVAL=true 时会拒绝创建） · delete_repository · remove_member · delete_team · delete_org_ruleset · delete_webhook

安全态势基线

assess_org_posture { org } 会依据内置基线评估组织，并返回各项控制措施的发现结果及评级：

{
  "org": "acme",
  "summary": { "score": 60, "grade": "C", "passed": 6, "failed": 4, "high_failures": 2 },
  "findings": [
    { "id": "push-protection", "severity": "high", "status": "fail",
      "current": false, "recommended": true,
      "rationale": "Blocks secrets at push time — the only control that prevents the leak…",
      "remediation": "harden_org_settings, or update_org_settings { secret_scanning_push_protection_enabled_for_new_repositories: true }." }
  ]
}

然后，harden_org_settings { org } 会应用该基线（基础 read 权限、秘密扫描 + 推送保护、Dependabot 默认设置、禁止创建公开仓库、禁止派生私有仓库、提交签署）；可通过 GHE_DRY_RUN=true 预览。recommend_enterprise_setup 会返回完整的企业 → 组织 → 仓库设置模板。

2FA 会由评估器报告，但必须在组织/企业身份验证界面中强制启用——GitHub 不提供可通过 REST 切换的选项。

技能

.claude/skills 中内置了两个 Agent 技能：

• github-enterprise-admin — 操作手册：最低权限令牌设置、安全设置模板、组织策略基线，以及破坏性操作的防护措施。
• github-actions-optimization — 流水线优化策略、缓存策略（依赖项、Docker 层、缓存限制），以及使用 actions-runner-controller（ARC）在 Kubernetes 上运行的 自托管运行器：GitHub App/PAT 连接、自动扩缩、跨临时 Pod 缓存，以及运行器隔离。

第三个技能 mcp-suite-maintenance 介绍了如何安全地扩展此服务。

开发

npm install
npm run typecheck && npm test && npm run build
npm run dev   # watch mode

架构（套件共用）：config.ts（环境变量 → 类型化配置） · security.ts（纯策略引擎，经过单元测试） · github/client.ts（REST 封装） · baseline.ts（纯态势评估器） · tools/{read,write,admin}.ts（带能力标签）。请参阅 SECURITY.md 和 PUBLISHING.md。

许可证

MIT © dockndevai