github-token-mcp

Implementación de spec.md. Servidor MCP exclusivo para el host que emite un token de acceso de instalación de GitHub App en cada ocasión para los agentes dentro de devcontainer.

Arquitectura técnica

• MCP server: @modelcontextprotocol/server v2 (createMcpHandler + McpServer) servido mediante Streamable HTTP.

• Autenticación de GitHub App: createAppAuth de @octokit/auth-app (la generación de JWT y el intercambio de tokens no se implementan manualmente).

• Obtención de la clave privada: DesktopAuth de @1password/sdk — solicita cada vez el aviso de autenticación biométrica/del sistema en la aplicación de escritorio de 1Password, en lugar de un shell out a la CLI.

• Autenticación Bearer: requireBearerAuth de @modelcontextprotocol/express. El lado devcontainer presenta un token compartido fijo.

Related MCP server: Git Repo Auth MCP

Configuración

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

• GITHUB_APP_ID / GITHUB_APP_INSTALLATION_ID: la GitHub App / instalación de destino.

• GITHUB_APP_PRIVATE_KEY_OP_REF: referencia secreta de 1Password de la clave privada (op://vault/item/field).

• OP_ACCOUNT_NAME: nombre de cuenta mostrado en la barra lateral de la aplicación de escritorio de 1Password (para DesktopAuth).

• MCP_BEARER_TOKEN: secreto compartido que el lado devcontainer presenta mediante Authorization: Bearer <token>.

En la aplicación de escritorio de 1Password, debe habilitarse Settings > Developer > Integrate with other apps.

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

Estado de implementación (resumen)

• Definición de tipos y validación de entrada de la herramienta get_installation_token.

• Verificación de cobertura de repos → repo_not_installed.

• Verificación de subconjunto de permisos → permission_escalation_denied.

• Obtención de la clave privada a través de 1Password → key_unavailable.

• Delegación de emisión de tokens a @octokit/auth-app → github_api_error.

• Distribución mediante Streamable HTTP + autenticación Bearer.

• Verificación de funcionamiento con una GitHub App / vault de 1Password reales (requiere la preparación manual de credenciales de autenticación).

• Patrón de uso en el lado devcontainer (explícitamente pospuesto en spec.md).

Estructura de directorios

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配信）