github-token-mcp

Реализация spec.md. MCP-сервер, предназначенный только для хоста, который выдает GitHub App installation access token по запросу агентам внутри devcontainer.

Техническая структура

• MCP server: @modelcontextprotocol/server v2 (createMcpHandler + McpServer) в режиме Streamable HTTP

• GitHub App аутентификация: @octokit/auth-app с createAppAuth (JWT-генерация и обмен токенами не реализуются вручную)

• Получение закрытого ключа: @1password/sdk с DesktopAuth — запрос биометрической/системной аутентификации через 1Password desktop app при каждом обращении, без вызова CLI

• Bearer-аутентификация: @modelcontextprotocol/express с requireBearerAuth. Сторона devcontainer предъявляет фиксированный общий токен

Related MCP server: GitHub MCP Server

Настройка

npm install
cp .env.example .env  # 値を埋める

• GITHUB_APP_ID / GITHUB_APP_INSTALLATION_ID: целевое GitHub App / установка

• GITHUB_APP_PRIVATE_KEY_OP_REF: secret reference закрытого ключа в 1Password (op://vault/item/field)

• OP_ACCOUNT_NAME: имя учётной записи, отображаемое на боковой панели 1Password desktop app (для DesktopAuth)

• MCP_BEARER_TOKEN: общий секрет, который сторона devcontainer предъявляет в заголовке Authorization: Bearer <token>

На стороне 1Password desktop app необходимо включить Settings > Developer > Integrate with other apps.

npm run dev    # tsx watch で起動
npm run build && npm start

Статус реализации (основное)

• Определение типа и валидация ввода для инструмента get_installation_token

• Проверка покрытия репозиториев → repo_not_installed

• Проверка подмножества разрешений → permission_escalation_denied

• Получение закрытого ключа через 1Password → key_unavailable

• Делегирование выдачи токена @octokit/auth-app → github_api_error

• Доставка через Streamable HTTP + Bearer-аутентификация

• Проверка работы с реальным GitHub App / хранилищем 1Password (требуется подготовка учётных данных человеком)

• Шаблон использования на стороне devcontainer (явно отложен в spec.md)

Структура каталогов

src/
  config.ts                       環境変数ロード
  errors.ts                       spec.md の4種類のエラーコードに対応するTokenError
  op-secret.ts                    1Password DesktopAuth 経由の秘密鍵取得
  github-auth.ts                  installation repos/permissions 検証 + createAppAuth 呼び出し
  tools/get-installation-token.ts get_installation_token ツール本体
  server.ts                       McpServer ファクトリ（ツール登録）
  index.ts                        HTTPエントリポイント（bearer認証 + createMcpHandler配信）