@brycepelletier/github-app-mcp

Una única fachada MCP stdio para el rol de operador de GitHub. 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 capacidad 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 las raíces del sistema de archivos y requiere metadatos .git reales. Ningún parámetro de herramienta del modelo puede seleccionar una ruta del host, un PEM, una imagen, un conjunto de herramientas o un argumento de Docker.

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

El Git local y el 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 solo acepta fetch, un pull de solo avance rápido, push y ls_remote, con campos de remoto/ref acotados. Exige un remoto https://github.com/owner/repository sin credenciales, deriva la identidad del repositorio de ese remoto configurado y solicita un token de instalación restringido a ese repositorio con contents:write y workflows:write. El token se genera dentro del entorno de ejecución efímero, se suministra a Git a través de un helper privado askpass, se elimina 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 por archivos, la recursión de submódulos, los editores interactivos, el firmado GPG y las solicitudes de credenciales en la terminal están deshabilitados. La salida está acotada y se depura para detectar patrones de token de GitHub y URL con credenciales.

Los Issues de GitHub, las pull requests, las revisiones, las Actions, los Projects y las búsquedas no se reimplementan. Se envían mediante proxy 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 reconoce:

• GITHUB_APP_ID — el valor predeterminado es 4618233.

• GITHUB_APP_INSTALLATION_ID — el valor predeterminado es 154276908.

• GITHUB_APP_PRIVATE_KEY_PATH — se requiere una ruta del host absoluta o resoluble.

Los dos valores numéricos predeterminados son valores de trabajo documentados de la configuración MCP de GitHub existente en VS Code del usuario y de la configuración de compose anterior para la GitHub App bp-agent-github-app. Son valores predeterminados, no secretos inexplicados de todo el paquete, y pueden sobrescribirse. La página de instalación/configuración de GitHub sigue siendo la fuente de verdad para el acceso a los repositorios. 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 adivinar de forma segura. El archivo de host configurado se monta como solo lectura en la ruta fija del contenedor /secrets/github-app.pem. La clave nunca se copia en el paquete npm, ni se imprime, ni se acepta como entrada de herramienta, ni se devuelve a través de MCP.

Requisitos 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 proporcionado a través de las raíces de MCP

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

El servidor hijo oficial de GitHub se inicia de forma diferida cuando se listan las herramientas o se llama a una herramienta de API. Las imágenes de tiempo de ejecución 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.

Enlace local

Desde Git Bash en el directorio de este paquete:

npm run link

Para desvincular:

npm run unlink

Configuración de VS Code

Proporcione la ruta del PEM del host como configuración de entorno y exponga una entrada de MCP:

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

Los ID de App y de instalación en uso no necesitan repetirse a menos que se sobrescriban los valores predeterminados documentados.

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.

Una vez que este paquete esté operativo, haga un seguimiento en agent-env-mcp eliminando su servicio de Git y el git_command público. Eso está intencionalmente fuera de este cambio. El servicio de ingeniería debe seguir enmascarando el .git real y nunca debe recibir el PEM, los tokens de instalación ni las herramientas MCP de GitHub.