@brycepelletier/github-app-mcp

Eine einzelne MCP-stdio-Fassade für die GitHub-Operator-Rolle. Sie kombiniert begrenzte Git-Operationen über dem aktiven Workspace mit GitHub-API-Tools, die an den offiziellen MCP-Server von GitHub delegiert werden. Sie gibt niemals einen privaten GitHub-App-Schlüssel oder ein Installationstoken zurück.

Architektur und Verantwortungsverteilung

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 bleibt die technische Fähigkeitsoberfläche. Deren Engineering-Container maskiert physisch .git und erhält keine GitHub-Anmeldedaten. Dieses Paket ist die einzige vorgesehene modellzugewandte Git-/GitHub-Oberfläche für github-operator.agent.md.

Die Fassade ermittelt den Workspace über MCP roots/list, verlangt genau eine lokale file:-Wurzel, lehnt Dateisystemwurzeln ab und verlangt echte .git-Metadaten. Kein Modell-Toolparameter kann einen Host-Pfad, ein PEM, ein Image, ein Toolset oder ein Docker-Argument auswählen.

Related MCP server: github-mcp-tool

Vertrauensgrenzen und Docker-Verhalten

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

Lokales Git und entferntes Git haben unterschiedliche Ausführungsmodi. git_local legt ein Operations-Enum und typisierte Felder offen, statt einer Shell oder einem beliebigen Git-Argumentarray. Dessen Container hat echtes .git, aber kein Netzwerk und kein Anmeldedatenmaterial.

git_remote akzeptiert nur fetch, pull (nur Fast-Forward), push, ls_remote, auth_check und push_dry_run, mit begrenzten Remote-/Ref-Feldern. Es verlangt eine anmeldefreie GitHub-HTTPS- oder SSH-Remote, leitet die Repository-Identität von dieser konfigurierten Remote ab, kanonisiert SSH-Formen intern zu anmeldefreiem HTTPS, ohne .git/config zu ändern, und fordert ein Installationstoken an, das auf dieses Repository mit contents:write und workflows:write beschränkt ist. Das Token wird innerhalb der ephemeren Laufzeit geprägt, Git über einen privaten askpass-Helfer zugeführt, aus der Ausgabe entfernt und mit dem Container verworfen. pull führt zuerst einen authentifizierten Fetch aus, gefolgt von einem anmeldefreien --ff-only-Merge.

Git-Hooks, globale/System-Konfiguration, Dateitransport, Submodul-Rekursion, interaktive Editoren, GPG-Signierung und Terminal-Anmeldeaufforderungen sind deaktiviert. Die Ausgabe ist begrenzt und auf GitHub-Tokenmuster und anmeldedatentragende URLs bereinigt.

Authentifizierungsprüfung

git ls-remote ist kein Beweis für Authentifizierung: Es kann für ein öffentliches Repository anonym erfolgreich sein. auth_check prägt stattdessen ein repository-beschränktes Installationstoken und ruft den authentifizierten Repository-Endpunkt von GitHub auf. Seine feste Antwort bestätigt App-Authentifizierung und Repository-Autorisierung, ohne die API-Antwort oder Anmeldedaten zurückzugeben:

{ "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 beweist zusätzlich, dass authentifizierter Git-HTTPS-Transport einen Push aushandeln kann. Die Laufzeit fügt immer --dry-run ein; Aufrufer können keine Git-Argumente, Force-Flags oder Lösch-Refspecs liefern. GitHub bewertet das vorgeschlagene Update, aber weder lokale noch entfernte Refs werden geändert.

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

Diese Prüfungen erfordern eine installierte App mit den angeforderten contents:write- und workflows:write-Berechtigungen, Repository-Zugriff, Netzwerkzugriff und einem exakten konfigurierten PEM-Pfad. Sie beweisen nicht, dass nicht verwandte Repositorys autorisiert sind, und prüfen keine Branch-Protection-Ergebnisse über die GitHub-Dry-Run-Antwort hinaus.

Führen Sie automatisierte Prüfungen mit npm test oder die vollständige lokale Paketvalidierung mit npm run validate aus. Optionale Live-Verifikation sollte die Remote-Branch-Objekt-ID vor und nach auth_check und push_dry_run mit git ls-remote aufzeichnen, dann bestätigen, dass die IDs übereinstimmen und alle zurückgegebenen credential_exposed-Felder falsch sind. Ersetzen Sie niemals einen normalen Push.

GitHub Issues, Pull Requests, Reviews, Actions, Projects und Suchen werden nicht neu implementiert. Sie werden über MCP an Folgendes weitergeleitet:

ghcr.io/github/github-mcp-server

Der offizielle Server empfängt genau:

GITHUB_TOOLSETS=context,issues,pull_requests,actions,projects

Keine nicht verwandten Toolsets werden stillschweigend aktiviert.

Konfiguration und Herkunft

Der Launcher verlangt alle drei externen Konfigurationswerte und schlägt geschlossen fehl, bevor er einen authentifizierten Container startet, wenn einer fehlt oder ungültig ist:

• GITHUB_APP_ID — positive numerische GitHub-App-Kennung.

• GITHUB_APP_INSTALLATION_ID — positive numerische Installationskennung.

• GITHUB_APP_PRIVATE_KEY_PATH — erforderlicher absoluter oder auflösbarer Host-Pfad.

Die bekannten Arbeitswerte GITHUB_APP_ID=4618233 und GITHUB_APP_INSTALLATION_ID=154276908 stammen aus der bestehenden VS-Code-GitHub-MCP-Konfiguration des Benutzers und dem früheren Compose-Setup für die GitHub-App bp-agent-github-app. Sie sind dokumentierte Herkunft für diese Bereitstellung, keine Paketstandards. Jede Installation muss ihre eigenen Werte bereitstellen. Die GitHub-Installations-/Einstellungsseite bleibt die Quelle der Wahrheit für den Repository-Zugriff. Die App wurde ursprünglich für brycepelletier/environment-controller installiert.

Das Paket hat bewusst keinen Standard-Host-PEM-Dateinamen. Früheres Material legt nur fest, dass es irgendwo unter C:/Users/bryce/.ssh/ lag; das reicht nicht für eine sichere Vermutung. Die konfigurierte Host-Datei wird schreibgeschützt am festen Containerpfad /secrets/github-app.pem eingehängt. Der Schlüssel wird niemals in das npm-Paket kopiert, gedruckt, als Tool-Eingabe akzeptiert oder über MCP zurückgegeben.

Host-Voraussetzungen und MCP-Lebenszyklus

• Node.js 24 LTS oder eine kompatible Node-24-Version

• Docker mit Linux-Container-Unterstützung

• GitHub-App-PEM, lesbar durch den vertrauenswürdigen hostseitigen Launcher

• Ein lokaler Git-Workspace, der über MCP-Roots bereitgestellt wird

• Netzwerkzugriff von den Remote-Git- und offiziellen GitHub-Containern

Der offizielle GitHub-Kinderserver startet verzögert, wenn Tools aufgelistet oder ein API-Tool aufgerufen wird. Git-Laufzeitimages werden beim ersten Git-Vorgang verzögert gebaut und über ein lokales, von Paketversion/Inhalt abgeleitetes Tag wiederverwendet; Git-Operationscontainer sind ephemer (--rm). SIGINT/SIGTERM schließt den offiziellen Kindertransport.

Der offizielle GitHub-Container hat einen eindeutigen, infrastruktur-generierten Namen für jeden Fassadenprozess. MCP-stdin-EOF/-Schließen, SIGINT, SIGTERM, SIGHUP und fatale Prozessfehler lösen eine idempotente Bereinigung aus: Die Fassade schließt den Kindertransport und entfernt dann explizit ihren eigenen benannten Container als Fallback. Containernamen und Bereinigungsziele werden niemals aus MCP-Tool-Eingaben akzeptiert, und gleichzeitige VS-Code-Sitzungen teilen sich kein Bereinigungsziel.

Lokale Verknüpfung

Aus Git Bash in diesem Paketverzeichnis:

npm run link

Verknüpfung aufheben mit:

npm run unlink

VS-Code-Konfiguration

Stellen Sie den Host-PEM-Pfad als Umgebungskonfiguration bereit und legen Sie einen MCP-Eintrag offen:

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

Alle drei Werte sind Pflicht. Die numerischen Kennungen wählen die App und Installation des Aufrufers; das Paket liefert niemals eine mandantenspezifische Identität.

Migration von github-token-broker

Der alte private Broker lauschte auf 0.0.0.0:8080 und gab Installationstokens von GET /credential im Git-Credential-Helper-Format zurück. Diese Architektur ist ausgemustert: Dieses Paket hat keinen HTTP-Listener, keinen Credential-Endpunkt und keine Token-Antwort. Der bestehende Broker-Quellcode wird für Audit-/Migrationshistorie aufbewahrt, wird aber von diesem Paket nicht ausgeliefert.

Seit agent-env-mcp 0.4.0 wurden dessen Git-Dienst und öffentliches git_command entfernt. Der Engineering-Dienst maskiert weiterhin echtes .git und erhält niemals das PEM, Installationstokens oder GitHub-MCP-Tools.

Lizenz

MIT. Siehe LICENSE.