@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.

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

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

Проверка аутентификации

git ls-remote не является доказательством аутентификации: он может успешно выполниться анонимно для публичного репозитория. auth_check вместо этого создаёт установочный токен, ограниченный репозиторием, и вызывает аутентифицированную конечную точку репозитория GitHub. Его фиксированный ответ подтверждает аутентификацию App и авторизацию репозитория, не возвращая ответ API или какие-либо учётные данные:

{ "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, флаги принудительной отправки или refspec удаления. GitHub оценивает предлагаемое обновление, но ни локальные, ни удалённые refs не изменяются.

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

Эти проверки требуют установленного App с запрошенными правами contents:write и workflows:write, доступа к репозиторию, сетевого доступа и точного настроенного пути PEM. Они не доказывают, что несвязанные репозитории авторизованы, и не проверяют результаты защиты веток за пределами dry-run-ответа GitHub.

Запускайте автоматические проверки с помощью npm test или полную локальную проверку пакета с помощью npm run validate. Необязательная живая проверка должна записывать идентификатор объекта удалённой ветки с помощью git ls-remote до и после auth_check и push_dry_run, затем подтверждать совпадение идентификаторов и что все возвращённые поля credential_exposed равны false. Никогда не заменяйте обычным push.

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

ghcr.io/github/github-mcp-server

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

GITHUB_TOOLSETS=context,issues,pull_requests,actions,projects

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

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

Запускающий модуль требует все три внешних значения конфигурации и завершается с ошибкой до запуска аутентифицированного контейнера, если какое-либо отсутствует или недействительно:

• GITHUB_APP_ID — положительный числовой идентификатор GitHub App.

• GITHUB_APP_INSTALLATION_ID — положительный числовой идентификатор установки.

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

Известные рабочие значения GITHUB_APP_ID=4618233 и GITHUB_APP_INSTALLATION_ID=154276908 взяты из существующей конфигурации GitHub MCP в VS Code пользователя и более ранней compose-настройки для GitHub App bp-agent-github-app. Это документированное происхождение для данного развёртывания, а не значения по умолчанию пакета. Каждая установка должна предоставить свои собственные значения. Страница установки/настроек GitHub остаётся источником истины для доступа к репозиториям. App изначально был установлен для 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 закрывает официальный дочерний транспорт.

Официальный контейнер GitHub имеет уникальное имя, сгенерированное инфраструктурой, для каждого процесса фасада. EOF/закрытие MCP stdin, SIGINT, SIGTERM, SIGHUP и фатальные ошибки процесса запускают идемпотентную очистку: фасад закрывает дочерний транспорт, а затем явно удаляет свой собственный именованный контейнер как запасной вариант. Имена контейнеров и цели очистки никогда не принимаются из ввода инструментов MCP, и параллельные сеансы VS Code не разделяют цель очистки.

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

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

Все три значения обязательны. Числовые идентификаторы выбирают App и установку вызывающего; пакет никогда не предоставляет идентичность, специфичную для арендатора.

Миграция с 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.