@brycepelletier/github-app-mcp

一个面向 GitHub Operator 角色的单一 MCP stdio 门面。它将活动工作区上的受限 Git 操作与委托给 GitHub 官方 MCP 服务器的 GitHub API 工具相结合。它从不返回 GitHub App 私钥或安装令牌。

架构与职责划分

Software Engineer                    GitHub Operator
       |                                    |
agent-env-mcp                         github-app-mcp
       |                         /-----------+-----------\
source/build/edit            ephemeral Git runtime   official GitHub MCP
.git masked                  real .git               GitHub API
no GitHub credentials        local: no network       fixed toolsets
                             remote: App auth

agent-env-mcp 仍然是工程能力面。其工程容器在物理上屏蔽了 .git，并且不接收任何 GitHub 凭据。本包是 github-operator.agent.md 唯一面向模型的 Git/GitHub 表面。

该门面通过 MCP roots/list 发现工作区，要求恰好一个本地 file: 根，拒绝文件系统根，并要求真实的 .git 元数据。任何模型工具参数都不能选择主机路径、PEM、镜像、工具集或 Docker 参数。

Related MCP server: github-mcp-tool

信任边界与 Docker 行为

MCP client
   | stdio
host-side trusted launcher (may control Docker; no Docker socket is mounted)
   |-- git_local  -> ephemeral container, workspace mount, network=none, no PEM
   |-- git_remote -> ephemeral container, workspace + read-only PEM, GitHub HTTPS
   `-- API tools  -> ghcr.io/github/github-mcp-server, read-only PEM

本地 Git 和远程 Git 具有不同的执行模式。git_local 暴露操作枚举和类型化字段，而不是 shell 或任意 Git 参数数组。其容器具有真实的 .git，但没有网络和凭据材料。

git_remote 仅接受 fetch、仅快进 pull、push、ls_remote、auth_check 和 push_dry_run，并带有受限的 remote/ref 字段。它要求一个无凭据的 GitHub HTTPS 或 SSH 远程，从该配置的远程派生仓库身份，在内部将 SSH 形式规范化为无凭据的 HTTPS 而不更改 .git/config，并请求一个仅限于该仓库的安装令牌，具有 contents:write 和 workflows:write 权限。该令牌在临时运行时内铸造，通过私有 askpass 助手提供给 Git，从输出中清除，并随容器一起丢弃。pull 首先执行经过身份验证的 fetch，然后执行无凭据的 --ff-only 合并。

Git 钩子、全局/系统配置、文件传输、子模块递归、交互式编辑器、GPG 签名和终端凭据提示均被禁用。输出是受限的，并会清除 GitHub 令牌模式和包含凭据的 URL。

身份验证验证

git ls-remote 不是身份验证的证明：它可以在公共仓库上匿名成功。auth_check 转而铸造一个仓库受限的安装令牌，并调用 GitHub 的经过身份验证的仓库端点。其固定响应确认 App 身份验证和仓库授权，而不返回 API 响应或任何凭据：

{ "operation": "auth_check", "remote": "origin" }

{
  "authenticated": true,
  "repository_authorized": true,
  "repository": "owner/repository",
  "remote_scheme": "https",
  "permissions": { "contents": "write", "workflows": "write" },
  "credential_exposed": false
}

push_dry_run 另外证明经过身份验证的 Git HTTPS 传输可以协商推送。运行时始终插入 --dry-run；调用者不能提供 Git 参数、强制标志或删除 refspec。GitHub 评估提议的更新，但本地和远程 refs 都不会被更改。

{ "operation": "push_dry_run", "remote": "origin", "branch": "main" }

{
  "authenticated": true,
  "transport": "https",
  "dry_run": true,
  "exit_code": 0,
  "signal": null,
  "stdout": "",
  "stderr": "Everything up-to-date\n",
  "truncated": false,
  "credential_exposed": false,
  "summary": "Authenticated push dry run succeeded; no refs were changed."
}

这些检查需要一个已安装的 App，具有所请求的 contents:write 和 workflows:write 权限、仓库访问权限、网络访问权限以及精确配置的 PEM 路径。它们不证明无关仓库已获授权，也不检查超出 GitHub dry-run 响应的分支保护结果。

使用 npm test 运行自动化检查，或使用 npm run validate 运行完整的本地包验证。可选的实时验证应在 auth_check 和 push_dry_run 前后使用 git ls-remote 记录远程分支对象 ID，然后确认 ID 匹配且所有返回的 credential_exposed 字段均为 false。切勿用普通推送替代。

GitHub Issues、拉取请求、审查、Actions、Projects 和搜索不会被重新实现。它们通过 MCP 代理到：

ghcr.io/github/github-mcp-server

官方服务器恰好接收：

GITHUB_TOOLSETS=context,issues,pull_requests,actions,projects

不会静默启用无关的工具集。

配置与来源

启动器要求所有三个外部配置值，如果任何一个缺失或无效，会在启动经过身份验证的容器之前安全失败：

• GITHUB_APP_ID — 正数 GitHub App 标识符。

• GITHUB_APP_INSTALLATION_ID — 正数安装标识符。

• GITHUB_APP_PRIVATE_KEY_PATH — 必需的绝对或可解析的主机路径。

已知的工作值 GITHUB_APP_ID=4618233 和 GITHUB_APP_INSTALLATION_ID=154276908 来自用户现有的 VS Code GitHub MCP 配置以及之前为 GitHub App bp-agent-github-app 的 compose 设置。它们是此部署的文档化来源，而不是包默认值。每个安装必须提供自己的值。GitHub 安装/设置页面仍然是仓库访问的权威来源。该 App 最初是为 brycepelletier/environment-controller 安装的。

该包故意没有默认的主机 PEM 文件名。早期材料仅确定它位于 C:/Users/bryce/.ssh/ 下的某个位置；这不足以安全猜测。配置的主机文件以只读方式挂载在固定容器路径 /secrets/github-app.pem 上。该密钥永远不会被复制到 npm 包中、打印、作为工具输入接受或通过 MCP 返回。

主机先决条件与 MCP 生命周期

• Node.js 24 LTS 或兼容的 Node 24 版本

• 支持 Linux 容器的 Docker

• 受信任的主机端启动器可读取的 GitHub App PEM

• 通过 MCP roots 提供的一个本地 Git 工作区

• 远程 Git 和官方 GitHub 容器的网络访问

官方 GitHub 子服务器在列出工具或调用 API 工具时惰性启动。Git 运行时镜像在第一次 Git 操作时惰性构建，并通过包版本/内容派生的本地标签重用；Git 操作容器是临时的（--rm）。SIGINT/SIGTERM 关闭官方子传输。

官方 GitHub 容器为每个门面进程具有唯一的基础设施生成的名称。MCP stdin EOF/关闭、SIGINT、SIGTERM、SIGHUP 和致命进程错误触发幂等清理：门面关闭子传输，然后显式移除自己的命名容器作为回退。容器名称和清理目标永远不会从 MCP 工具输入中接受，并发 VS Code 会话不共享清理目标。

本地链接

在此包目录中的 Git Bash 中：

npm run link

使用以下命令取消链接：

npm run unlink

VS Code 配置

将主机 PEM 路径作为环境配置提供，并暴露一个 MCP 条目：

{
  "servers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@brycepelletier/github-app-mcp@0.3.0"],
      "env": {
        "GITHUB_APP_ID": "4618233",
        "GITHUB_APP_INSTALLATION_ID": "154276908",
        "GITHUB_APP_PRIVATE_KEY_PATH": "<exact-host-path-to-existing-pem>"
      }
    }
  }
}

所有三个值都是必需的。数字标识符选择调用者的 App 和安装；该包从不提供租户特定的身份。

从 github-token-broker 迁移

旧的私有代理监听在 0.0.0.0:8080 上，并以 Git credential-helper 格式从 GET /credential 返回安装令牌。该架构已退役：此包没有 HTTP 监听器、凭据端点或令牌响应。现有的代理源代码保留用于审计/迁移历史，但不由此包发布。

自 agent-env-mcp 0.4.0 起，其 Git 服务和公共 git_command 已被移除。工程服务继续屏蔽真实的 .git，并且永远不会接收 PEM、安装令牌或 GitHub MCP 工具。

许可证

MIT。请参阅 LICENSE。