How kunwarvivek/mcp-github-project-manager works
1. System purpose and boundary
- This repository is a Model Context Protocol (MCP) server for managing GitHub Projects v2 and related planning artifacts.
- It sits between MCP clients (Claude, Cursor, etc.) and external systems: GitHub GraphQL/REST APIs plus optional AI providers (Anthropic, OpenAI, Google, Perplexity).
2. Primary runtime entrypoints
- src/index.ts and src/cli.ts are the main startup surfaces.
- The server can run as a CLI/stdin-stdout MCP process and also supports HTTP/webhook-related infrastructure.
- Docker and GitHub Actions (.github/workflows/*) are used for packaging, CI, and release automation.
3. Layered architecture
- The codebase follows a Clean Architecture-style split:
- Domain: contracts, types, schemas, errors.
- Services: business workflows and orchestration.
- Infrastructure: GitHub, MCP, cache, persistence, events, logging, observability.
- Tools: MCP-facing capabilities exposed to clients.
- The main dependency direction is inward: infrastructure and tools depend on services/domain, not the reverse.
4. MCP tool surface
- src/infrastructure/tools/* contains the MCP tool definitions, schemas, validation, and registration.
- ToolRegistry, ToolValidator, ToolSchemas, and ToolResultFormatter centralize how tools are declared, validated, and rendered back to MCP clients.
- Tool groups map to product areas: project lifecycle, sprint planning, issue intelligence, AI tasks, status updates, sub-issues, templates, linking, and health.
5. Business logic services
- src/services/* contains the orchestration layer that implements the actual workflows behind tools.
- Key services include:
- ProjectManagementService, MilestoneService, SprintPlanningService, ProjectStatusService
- ProjectTemplateService, ProjectLinkingService, SubIssueService
- AI-centric services like PRDGenerationService, TaskGenerationService, RoadmapPlanningService, RequirementsTraceabilityService
- These services compose GitHub repositories, AI helpers, validators, and context generators into higher-level operations.
6. AI subsystem
- src/services/ai/* and src/infrastructure/tools/ai-tasks/* implement the AI-assisted workflow.
- The AI layer handles PRD creation, task decomposition, feature expansion, complexity analysis, roadmap/sprint recommendations, and issue enrichment.
- AIServiceFactory and resilience helpers provide multi-provider fallback and operational safety when a model/API is unavailable.
7. Requirements traceability pipeline
- A distinctive subsystem is the end-to-end traceability chain:
- business requirements → features → use cases → tasks
- This is supported by services such as RequirementsTraceabilityService, TaskContextGenerationService, and ContextQualityValidator.
- The generated artifacts are linked back into GitHub project resources, enabling coverage analysis, orphan detection, and impact analysis.
8. GitHub integration boundary
- src/infrastructure/github/* is the adapter layer to GitHub.
- Repositories like GitHubProjectRepository, GitHubIssueRepository, GitHubMilestoneRepository, GitHubSprintRepository, and GitHubStatusUpdateRepository encapsulate GitHub API access.
- GitHubRepositoryFactory, config, and error handling isolate API specifics, pagination, rate limiting, and GraphQL/REST conversion logic.
9. State, caching, and resource management
- The server maintains resource state through src/infrastructure/resource/*, src/infrastructure/cache/*, and src/infrastructure/persistence/*.
- ResourceManager, ResourceFactory, ResourceRelationshipManager, and OptimisticLockManager support versioned resources and conflict handling.
- EmbeddingCache and ResourceCache improve repeat access, while FilePersistenceAdapter and CachePersistence provide local persistence support.
- These components are the state boundary between volatile MCP requests and durable project/resource state.
10. Eventing, sync, and webhook path
- src/infrastructure/events/* includes EventStore, EventSubscriptionManager, and GitHubWebhookHandler.
- GitHubStateSyncService and the webhook server integrate external GitHub changes back into the server’s state model.
- This is the main data flow for bidirectional synchronization: GitHub changes in, resource/event updates out.
11. Observability, health, and resilience
- src/infrastructure/observability/* provides correlation and tracing-friendly logging.
- src/infrastructure/health/HealthService.ts exposes runtime health checks.
- src/infrastructure/resilience/* adds AI-specific circuit breaking and resilience policy controls.
- These concerns sit cross-cuttingly across the service and infrastructure layers, especially around long-running or API-dependent operations.
12. Validation and schema model
- src/domain/* defines the canonical types, error shapes, MCP/resource schemas, and type guards.
- Zod-based validation is used heavily for tool inputs, domain resources, and generated outputs.
- This makes the domain layer the source of truth for payload shape and prevents malformed MCP tool calls from reaching business logic.
13. Supporting analysis and context generation
- src/analysis/* and src/services/context/* provide supporting computation such as dependency graphs, keyword extraction, and code/reference context generation.
- These are used by AI/task tooling to enrich tasks, estimate effort, and build richer guidance without embedding that logic directly in MCP handlers.
14. Testing and operational confidence
- The repository has strong test separation: unit, integration, and E2E suites under src/__tests__ and tests/.
- E2E tests exercise the actual MCP interface and tool workflows, while integration tests validate wiring between services and infrastructure.
- This matters architecturally because the tool layer and GitHub/AI boundaries are heavily contract-driven.
15. Overall data flow
- A typical request flow is: MCP client → tool registry/schema validation → service orchestration → GitHub/AI/persistence adapters → formatted MCP response.
- For sync/event flows, the path is: GitHub webhook/state change → event/store/sync layer → resource/cache update → exposed MCP resources/tools.
- The design is centered on maintaining GitHub project state while optionally augmenting it with AI-generated planning artifacts and traceability metadata.
Main entry points: tools Tool core · services Project workflows · ai AI services · github GitHub adapter
Components 21
Entrypoints
Startup surfaces and packaging
- MCP server · Main stdio/HTTP server bootstrap
src/index.ts - CLI · Command-line startup and invocation surface
src/cli.ts
Domain
Contracts, types, schemas, and validation primitives
- Domain model · Canonical project, resource, AI, and MCP types plus errors
src/domain - Resource schemas · Shared schemas, guards, and payload shape definitions
src/domain/resource-schemas.ts
Services
Business workflows and orchestration
- Project workflows · Project, milestone, sprint, status, template, linking, and sub-issue orchestration
src/services - Traceability · Requirements to features, use cases, tasks, and context generation
src/services/RequirementsTraceabilityService.ts - AI services · PRD, task, roadmap, issue intelligence, and fallback-aware AI workflows
src/services/ai - Context generation · Code, dependency, and reference context helpers for AI workflows
src/services/context - Content validation · Quality checks for generated PRDs and task context
src/services/validation/ContextQualityValidator.ts
Infrastructure
Adapters, persistence, transport, and cross-cutting runtime support
- GitHub adapter · Repository factory, API config, error handling, and GitHub repository implementations
src/infrastructure/github - Resource state · Resource lifecycle, relationships, optimistic locking, and persistence-backed caches
src/infrastructure/resource - Events & sync · Event store, subscriptions, webhook handling, and GitHub state synchronization
src/infrastructure/events - Cache layer · Resource and embedding caches plus persistence glue
src/infrastructure/cache - Observability · Correlation, tracing logs, health, and resilience policies
src/infrastructure/observability - Webhook server · HTTP webhook entrypoint for external GitHub event intake
src/infrastructure/http/WebhookServer.ts
MCP Tools
Tool registry and MCP-facing capability layer
- Tool core · Tool registry, schema validation, coercion, and result formatting
src/infrastructure/tools - Project tools · Project lifecycle and advanced project operations exposed to MCP clients
src/infrastructure/tools/project-lifecycle-tools.ts - AI tools · PRD, task, traceability, sprint, and roadmap AI tool surface
src/infrastructure/tools/ai-tasks - Supporting tools · Issue intelligence, status update, sub-issue, template, linking, and health tools
src/infrastructure/tools/issue-intelligence-tools.ts
Tests
Unit, integration, and end-to-end coverage
- E2E suite · End-to-end MCP, resource, and tool workflow coverage
src/__tests__/e2e - Unit & integration · Focused coverage for services, infrastructure, and tool wiring
tests
Connections 31
- MCP server → Tool core: boots · Starts MCP server and registers tool surface
- CLI → MCP server: invokes · CLI delegates to server bootstrap
- Tool core → Project tools: registers · Declares project lifecycle tools
- Tool core → AI tools: registers · Declares AI-assisted tools
- Tool core → Supporting tools: registers · Declares non-AI supporting tools
- Tool core → Domain model: validates against · Uses domain schemas and types for tool contracts
- Project tools → Project workflows: calls · Tool handlers invoke project workflows
- AI tools → AI services: calls · AI tools invoke AI orchestration services
- AI tools → Traceability: calls · Traceability tools drive requirement decomposition pipeline
- Supporting tools → Project workflows: calls · Supporting tools rely on project workflow services
- Project workflows → GitHub adapter: uses · Persists and reads project state from GitHub
- Project workflows → Resource state: uses · Coordinates resource state and relationships
- Project workflows → Domain model: depends on · Consumes shared contracts and errors
- Traceability → Context generation: uses · Builds richer context for traceability outputs
- Traceability → Content validation: uses · Validates generated artifacts and context quality
- AI services → GitHub adapter: uses · Enriches GitHub projects and issues
- AI services → Observability: uses · Wraps long-running model calls with logging and resilience
- AI services → Domain model: depends on · Uses AI and task domain contracts
- Context generation → Domain model: depends on · Produces domain-shaped context payloads
- Content validation → Resource schemas: validates · Checks schema and content quality
- GitHub adapter → Domain model: maps to · Converts GitHub data into canonical domain structures
- Resource state → Cache layer: persists through · Resource state is cached and persisted
- Events & sync → Resource state: updates · Event and webhook changes update resource state
- Webhook server → Events & sync: ingests · Webhook transport feeds event handling and sync
- Observability → GitHub adapter: wraps · Provides operational support around API access
- E2E suite → MCP server: exercises · End-to-end tests run the actual MCP server path
- E2E suite → Tool core: exercises · Validates tool registration and behavior
- Unit & integration → Project workflows: covers · Unit and integration tests validate orchestration
- Unit & integration → GitHub adapter: covers · Tests repository adapters and API mapping
- Unit & integration → Resource state: covers · Tests resource management and locking
- Unit & integration → AI services: covers · Tests AI workflow services and fallbacks