@brycepelletier/github-app-mcp

Una fachada MCP stdio única para el rol de GitHub Operator. Combina operaciones Git acotadas sobre el espacio de trabajo activo con herramientas de la API de GitHub delegadas al servidor MCP oficial de GitHub. Nunca devuelve una clave privada de GitHub App ni un token de instalación.

Arquitectura y división de responsabilidades

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 sigue siendo la superficie de capacidades de ingeniería. Su contenedor de ingeniería enmascara físicamente .git y no recibe ninguna credencial de GitHub. Este paquete es la única superficie Git/GitHub orientada al modelo prevista para github-operator.agent.md.

La fachada descubre el espacio de trabajo con MCP roots/list, exige exactamente una raíz local file:, rechaza raíces de sistema de archivos y requiere metadatos reales de .git. Ningún parámetro de herramienta del modelo puede seleccionar una ruta de host, PEM, imagen, conjunto de herramientas o argumento de Docker.

Related MCP server: github-mcp-tool

Límites de confianza y comportamiento de 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 local y Git remoto tienen modos de ejecución diferentes. git_local expone una enumeración de operaciones y campos tipificados en lugar de un shell o una matriz arbitraria de argumentos de Git. Su contenedor tiene .git real, pero sin red y sin material de credenciales.

git_remote acepta únicamente fetch, pull solo con avance rápido, push, ls_remote, auth_check y push_dry_run, con campos remoto/ref acotados. Requiere un remoto GitHub HTTPS o SSH sin credenciales, deriva la identidad del repositorio de ese remoto configurado, canoniza internamente las formas SSH a HTTPS sin credenciales sin cambiar .git/config, y solicita un token de instalación restringido a ese repositorio con contents:write y workflows:write. El token se acuña dentro del runtime efímero, se suministra a Git mediante un helper askpass privado, se redacta de la salida y se descarta con el contenedor. pull realiza primero un fetch autenticado, seguido de una fusión --ff-only sin credenciales.

Los hooks de Git, la configuración global/del sistema, el transporte de archivos, la recursión de submódulos, los editores interactivos, el firmado GPG y los avisos de credenciales en terminal están deshabilitados. La salida está acotada y se depura en busca de patrones de token de GitHub y URL con credenciales.

Verificación de autenticación

git ls-remote no es prueba de autenticación: puede tener éxito de forma anónima para un repositorio público. auth_check, en cambio, acuña un token de instalación restringido al repositorio y llama al endpoint autenticado de repositorio de GitHub. Su respuesta fija confirma la autenticación de la App y la autorización del repositorio sin devolver la respuesta de la API ni ninguna credencial:

{ "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 demuestra además que el transporte Git HTTPS autenticado puede negociar un push. El runtime siempre inserta --dry-run; los llamadores no pueden suministrar argumentos de Git, indicadores de fuerza ni refspecs de eliminación. GitHub evalúa la actualización propuesta, pero no se modifican ni las refs locales ni las remotas.

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

Estas comprobaciones requieren una App instalada con los permisos solicitados contents:write y workflows:write, acceso al repositorio, acceso a la red y una ruta PEM configurada exacta. No demuestran que repositorios no relacionados estén autorizados ni inspeccionan los resultados de la protección de ramas más allá de la respuesta dry-run de GitHub.

Ejecute las comprobaciones automatizadas con npm test o la validación completa del paquete local con npm run validate. La verificación en vivo opcional debe registrar el ID de objeto de la rama remota con git ls-remote antes y después de auth_check y push_dry_run, y luego confirmar que los ID coinciden y que todos los campos credential_exposed devueltos son false. Nunca sustituya un push normal.

GitHub Issues, pull requests, revisiones, Actions, Projects y búsquedas no se reimplementan. Se proxifican a través de MCP a:

ghcr.io/github/github-mcp-server

El servidor oficial recibe exactamente:

GITHUB_TOOLSETS=context,issues,pull_requests,actions,projects

No se habilitan silenciosamente conjuntos de herramientas no relacionados.

Configuración y procedencia

El lanzador requiere los tres valores de configuración externos y falla de forma segura antes de iniciar un contenedor autenticado si alguno falta o no es válido:

• GITHUB_APP_ID — identificador numérico positivo de GitHub App.

• GITHUB_APP_INSTALLATION_ID — identificador numérico positivo de instalación.

• GITHUB_APP_PRIVATE_KEY_PATH — ruta de host absoluta o resoluble obligatoria.

Los valores de trabajo conocidos GITHUB_APP_ID=4618233 y GITHUB_APP_INSTALLATION_ID=154276908 provienen de la configuración MCP de GitHub existente de VS Code del usuario y de la configuración compose anterior para GitHub App bp-agent-github-app. Son procedencia documentada para este despliegue, no valores predeterminados del paquete. Cada instalación debe proporcionar sus propios valores. La página de instalación/configuración de GitHub sigue siendo la fuente de verdad para el acceso al repositorio. La App se instaló originalmente para brycepelletier/environment-controller.

El paquete deliberadamente no tiene un nombre de archivo PEM de host predeterminado. El material anterior solo establece que estaba en algún lugar bajo C:/Users/bryce/.ssh/; eso no es suficiente para adivinarlo de forma segura. El archivo de host configurado se monta de solo lectura en la ruta fija del contenedor /secrets/github-app.pem. La clave nunca se copia en el paquete npm, se imprime, se acepta como entrada de herramienta ni se devuelve a través de MCP.

Requisitos previos del host y ciclo de vida de MCP

• Node.js 24 LTS o una versión compatible de Node 24

• Docker con soporte de contenedores Linux

• PEM de GitHub App legible por el lanzador de confianza del lado del host

• Un espacio de trabajo Git local suministrado a través de raíces MCP

• Acceso a la red desde los contenedores de Git remoto y de GitHub oficial

El servidor hijo oficial de GitHub se inicia de forma diferida cuando se enumeran las herramientas o se llama a una herramienta de API. Las imágenes de runtime de Git se construyen de forma diferida en la primera operación de Git y se reutilizan mediante una etiqueta local derivada de la versión/contenido del paquete; los contenedores de operaciones de Git son efímeros (--rm). SIGINT/SIGTERM cierra el transporte hijo oficial.

El contenedor oficial de GitHub tiene un nombre único generado por la infraestructura para cada proceso de fachada. El EOF/cierre de stdin de MCP, SIGINT, SIGTERM, SIGHUP y los errores fatales del proceso activan una limpieza idempotente: la fachada cierra el transporte hijo y luego elimina explícitamente su propio contenedor con nombre como respaldo. Los nombres de contenedor y los objetivos de limpieza nunca se aceptan desde la entrada de herramientas MCP, y las sesiones concurrentes de VS Code no comparten un objetivo de limpieza.

Vinculación local

Desde Git Bash en este directorio del paquete:

npm run link

Desvincule con:

npm run unlink

Configuración de VS Code

Proporcione la ruta PEM del host como configuración de entorno y exponga una entrada 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>"
      }
    }
  }
}

Los tres valores son obligatorios. Los identificadores numéricos seleccionan la App y la instalación del llamador; el paquete nunca suministra una identidad específica de inquilino.

Migración desde github-token-broker

El antiguo broker privado escuchaba en 0.0.0.0:8080 y devolvía tokens de instalación desde GET /credential en formato de credential-helper de Git. Esa arquitectura está retirada: este paquete no tiene listener HTTP, endpoint de credenciales ni respuesta de token. El código fuente del broker existente se conserva para el historial de auditoría/migración, pero este paquete no lo distribuye.

A partir de agent-env-mcp 0.4.0, su servicio Git y el git_command público se han eliminado. El servicio de ingeniería continúa enmascarando el .git real y nunca recibe el PEM, los tokens de instalación ni las herramientas MCP de GitHub.

Licencia

MIT. Consulte LICENSE.