@brycepelletier/github-app-mcp

Единый MCP stdio-фасад для роли GitHub Operator. Он объединяет ограниченные Git-операции над активным рабочим пространством с инструментами GitHub API, делегированными официальному MCP-серверу GitHub. Он никогда не возвращает закрытый ключ 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. Этот пакет — единственная предполагаемая модель-ориентированная поверхность Git/GitHub для github-operator.agent.md.

Фасад обнаруживает рабочее пространство с помощью MCP roots/list, требует ровно один локальный корень file:, отклоняет файловые корни и требует реальные метаданные .git. Никакой параметр инструмента модели не может выбрать путь хоста, PEM, образ, набор инструментов или аргумент Docker.

Границы доверия и поведение 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, pull только с fast-forward, push и ls_remote, с ограниченными полями remote/ref. Он требует удалённый репозиторий https://github.com/owner/repository без учётных данных, выводит идентичность репозитория из этого настроенного remote и запрашивает установочный токен, ограниченный этим репозиторием, с правами contents:write и workflows:write. Токен создаётся внутри эфемерного рантайма, передаётся Git через приватный помощник askpass, удаляется из вывода и уничтожается вместе с контейнером. pull сначала выполняет аутентифицированный fetch, затем слияние --ff-only без учётных данных.

Хуки Git, глобальная/системная конфигурация, файловый транспорт, рекурсия подмодулей, интерактивные редакторы, подпись GPG и запросы учётных данных в терминале отключены. Вывод ограничен и очищен от паттернов токенов GitHub и URL с учётными данными.

GitHub Issues, pull request'ы, ревью, Actions, Projects и поиск не переimplementированы. Они проксируются через MCP на:

ghcr.io/github/github-mcp-server

Официальный сервер получает ровно:

GITHUB_TOOLSETS=context,issues,pull_requests,actions,projects

Никакие несвязанные наборы инструментов не включаются молча.

Конфигурация и происхождение

Запускатор распознаёт:

• GITHUB_APP_ID — по умолчанию 4618233.

• GITHUB_APP_INSTALLATION_ID — по умолчанию 154276908.

• GITHUB_APP_PRIVATE_KEY_PATH — обязательный абсолютный или разрешимый путь хоста.

Два числовых значения по умолчанию — документированные рабочие значения из существующей конфигурации MCP GitHub в VS Code пользователя и более ранней настройки compose для GitHub App bp-agent-github-app. Это значения по умолчанию, а не необъяснимые секреты пакета, и их можно переопределить. Страница установки/настроек GitHub остаётся источником истины для доступа к репозиторию. Приложение изначально было установлено для brycepelletier/environment-controller.

Пакет намеренно не имеет имени файла PEM хоста по умолчанию. Более ранние материалы лишь устанавливают, что он находился где-то в C:/Users/bryce/.ssh/; этого недостаточно для безопасного предположения. Настроенный файл хоста монтируется только для чтения по фиксированному пути контейнера /secrets/github-app.pem. Ключ никогда не копируется в npm-пакет, не печатается, не принимается как ввод инструмента и не возвращается через MCP.

Требования к хосту и жизненный цикл MCP

• Node.js 24 LTS или совместимый релиз Node 24

• Docker с поддержкой Linux-контейнеров

• PEM GitHub App, читаемый доверенным запускатором на стороне хоста

• Одно локальное Git-рабочее пространство, предоставленное через корни MCP

• Сетевой доступ из контейнеров удалённого Git и официального GitHub

Официальный дочерний сервер GitHub запускается лениво при перечислении инструментов или вызове API-инструмента. Образы рантайма Git собираются лениво при первой Git-операции и переиспользуются локальным тегом, производным от версии пакета/содержимого; контейнеры Git-операций эфемерны (--rm). SIGINT/SIGTERM закрывает официальный дочерний транспорт.

Локальная привязка

Из 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.1.0"],
      "env": {
        "GITHUB_APP_PRIVATE_KEY_PATH": "<exact-host-path-to-existing-pem>"
      }
    }
  }
}

Рабочие ID приложения и установки не нужно повторять, если только вы не переопределяете документированные значения по умолчанию.

Миграция с github-token-broker

Старый приватный брокер слушал на 0.0.0.0:8080 и возвращал установочные токены из GET /credential в формате Git credential-helper. Эта архитектура устарела: у этого пакета нет HTTP-слушателя, конечной точки учётных данных или ответа с токеном. Существующий исходный код брокера сохраняется для истории аудита/миграции, но не поставляется этим пакетом.

После того как этот пакет заработает, выполните последующие действия в agent-env-mcp, удалив его Git-сервис и публичный git_command. Это намеренно вне рамок данного изменения. Инженерный сервис должен продолжать скрывать реальный .git и никогда не должен получать PEM, установочные токены или инструменты MCP GitHub.