mcp-github-project-manager AGENTS.md

Commands

Architecture (DDD, MCP stdio server)

• src/index.ts — entry; boots an McpServer (@modelcontextprotocol/server v2, 2026-07-28 spec) via serveStdio, which negotiates the protocol revision per connection. Each tool is registered with registerTool; all of them share one dispatchTool carrying the shutdown gate, in-flight tracking and result formatting. Wires ToolRegistry + ProjectManagementService through src/container.ts (tsyringe DI).
• Tool errors: an execution failure returns {content, isError: true} so the model can see and recover from it. A JSON-RPC error is reserved for protocol faults (unknown tool). Note v2 validates arguments against the declared inputSchema before the handler runs, so ToolValidator never sees a missing required field.
• src/domain/ — types, zod schemas, errors. No logic.
• src/services/ — business logic. ProjectManagementService orchestrates per-feature services; services/ai/ holds AI SDK providers.
• src/infrastructure/ — github/ (Octokit GraphQL/REST), tools/ (MCP tool defs + registry + validators), plus cache, persistence, resilience, events.
• src/env.ts + src/cli.ts — config. CLI flags override env vars.

Environment (.env or CLI flags; CLI wins)

• Required: GITHUB_TOKEN, GITHUB_OWNER, GITHUB_REPO.
• GitHub credential chain, first hit wins: --token CLI flag → $SECRETS_DIR/GITHUB_TOKEN file → GITHUB_TOKEN env → gh auth token. The gh fallback means a developer with a working gh login needs no configuration at all; disable it with GH_CLI_TOKEN_FALLBACK=false (it is also off automatically under NODE_ENV=test, so tests never shell out).
• GitHub App installation auth (optional, outranks the PAT when all three are set): GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_INSTALLATION_ID. A partial App config falls back to the PAT rather than failing, so a half-set environment cannot lock the server out.
• Every credential read goes through getSecret()/requireToken(). Do NOT read process.env.GITHUB_TOKEN directly — that bypasses the whole chain, which is exactly how SECRETS_DIR and --token were silently broken before.
• AI (optional, unlocks AI tools): ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENAI_API_KEY, PERPLEXITY_API_KEY; model overrides AI_MAIN_MODEL, AI_PRD_MODEL, AI_RESEARCH_MODEL, AI_FALLBACK_MODEL.
• Optional: SYNC_ENABLED, SYNC_TIMEOUT_MS, CACHE_DIRECTORY, WEBHOOK_SECRET, WEBHOOK_PORT, SSE_ENABLED.
• Webhook security: signature validation fails closed. With no WEBHOOK_SECRET, webhooks are rejected unless WEBHOOK_ALLOW_UNSIGNED=true (trusted dev only).
• Secrets: set SECRETS_DIR (e.g. /run/secrets) to load any config/secret from a file named after it (Docker/k8s secret convention), checked before env vars. getSecret(name) in env.ts reads fresh (rotation-aware). Vault/AWS SM are an extension point via SecretProvider (src/infrastructure/secrets/).
• Startup validation runs against the resolved config, not raw process.env — validating the environment directly meant a token supplied by file or CLI flag failed the required-field check and the process exited before the resolver ran.
• Logs are redacted: redactSecrets() in infrastructure/logger strips token/secret/password/apiKey/authorization-shaped keys from anything the logger stringifies, and GitHubConfig.token is non-enumerable so JSON.stringify cannot emit the PAT.