@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: ルートが正確に 1 つだけ必要で、ファイルシステムルートを拒否し、実際の .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 はシェルや任意の Git 引数配列ではなく、操作の列挙型と型付きフィールドを公開します。そのコンテナには実際の .git がありますが、ネットワークも認証情報もありません。

git_remote は fetch、fast-forward のみの pull、push、ls_remote、auth_check、push_dry_run のみを受け付け、リモート/ref フィールドは境界付きです。認証情報なしの GitHub HTTPS または SSH リモートを要求し、設定されたリモートからリポジトリ ID を導出し、SSH 形式を .git/config を変更せずに内部で認証情報なしの HTTPS に正規化し、contents:write と workflows:write を持つそのリポジトリに限定されたインストールトークンを要求します。トークンは一時的なランタイム内で生成され、プライベートな askpass ヘルパーを通じて Git に供給され、出力からは編集され、コンテナとともに破棄されます。pull はまず認証付き fetch を実行し、その後認証情報なしの --ff-only マージを実行します。

Git フック、グローバル/システム設定、ファイルトランスポート、サブモジュールの再帰、対話型エディタ、GPG 署名、ターミナルの認証情報プロンプトは無効化されます。出力は制限され、GitHub トークンパターンと認証情報を含む URL がスクラブされます。

認証の検証

git ls-remote は認証の証明にはなりません。公開リポジトリでは匿名で成功する可能性があります。代わりに auth_check はリポジトリ限定のインストールトークンを生成し、GitHub の認証付きリポジトリエンドポイントを呼び出します。その固定応答は、API 応答や認証情報を返すことなく、App の認証とリポジトリの認可を確認します。

{ "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 トランスポートが push をネゴシエートできることを証明します。ランタイムは常に --dry-run を挿入します。呼び出し側は Git 引数、force フラグ、削除 refspec を指定できません。GitHub は提案された更新を評価しますが、ローカルとリモートの ref はどちらも変更されません。

{ "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."
}

これらのチェックには、要求された contents:write と workflows:write 権限、リポジトリアクセス、ネットワークアクセス、正確に設定された PEM パスを持つインストール済み App が必要です。無関係なリポジトリが認可されていることを証明するものではなく、GitHub の dry-run 応答を超えてブランチ保護の結果を検査するものでもありません。

自動チェックは npm test で実行し、完全なローカルパッケージ検証は npm run validate で実行します。任意のライブ検証では、auth_check と push_dry_run の前後で git ls-remote を使用してリモートブランチのオブジェクト ID を記録し、ID が一致し、返されたすべての credential_exposed フィールドが false であることを確認する必要があります。通常の push を代用してはなりません。

GitHub Issues、プルリクエスト、レビュー、Actions、Projects、検索は再実装されていません。これらは MCP 経由で以下にプロキシされます。

ghcr.io/github/github-mcp-server

公式サーバーは正確に以下を受け取ります。

GITHUB_TOOLSETS=context,issues,pull_requests,actions,projects

無関係なツールセットが暗黙的に有効化されることはありません。

設定と来歴

ランチャーは 3 つの外部設定値すべてを要求し、いずれかが欠落または無効な場合は、認証付きコンテナを起動する前にフェイルクローズします。

• 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 ルートを通じて提供される 1 つのローカル Git ワークスペース

• リモート Git コンテナと公式 GitHub コンテナからのネットワークアクセス

公式 GitHub 子サーバーは、ツールが一覧表示されるか API ツールが呼び出されたときに遅延起動します。Git ランタイムイメージは最初の Git 操作で遅延ビルドされ、パッケージバージョン/コンテンツから導出されたローカルタグによって再利用されます。Git 操作コンテナは一時的です（--rm）。SIGINT/SIGTERM は公式子トランスポートを閉じます。

公式 GitHub コンテナには、ファサードプロセスごとに一意のインフラ生成名があります。MCP の stdin EOF/close、SIGINT、SIGTERM、SIGHUP、致命的なプロセスエラーは冪等なクリーンアップをトリガーします。ファサードは子トランスポートを閉じ、その後フォールバックとして自身の名前付きコンテナを明示的に削除します。コンテナ名とクリーンアップターゲットは MCP ツール入力から受け付けられることはなく、同時実行の VS Code セッションがクリーンアップターゲットを共有することもありません。

ローカルリンク

このパッケージディレクトリの Git Bash から:

npm run link

リンク解除:

npm run unlink

VS Code の設定

ホスト PEM パスを環境設定として提供し、1 つの 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>"
      }
    }
  }
}

3 つの値はすべて必須です。数値識別子は呼び出し元の App とインストールを選択します。パッケージがテナント固有の ID を提供することはありません。

github-token-broker からの移行

旧プライベートブローカーは 0.0.0.0:8080 でリッスンし、GET /credential から Git の credential-helper 形式でインストールトークンを返していました。そのアーキテクチャは廃止されました。このパッケージには HTTP リスナー、認証情報エンドポイント、トークン応答はありません。既存のブローカーソースは監査/移行履歴のために保持されていますが、このパッケージでは配布されません。

agent-env-mcp 0.4.0 以降、その Git サービスと公開 git_command は削除されました。エンジニアリングサービスは実際の .git をマスクし続け、PEM、インストールトークン、GitHub MCP ツールを受け取ることはありません。

ライセンス

MIT。LICENSE を参照してください。