# kunwarvivek/mcp-github-project-manager architecture

> Architecture diagram of the GitHub repository kunwarvivek/mcp-github-project-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kunwarvivek/mcp-github-project-manager
- Repository: https://github.com/kunwarvivek/mcp-github-project-manager

## Overview

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: [`src/infrastructure/tools`](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/tools) (Tool core), [`src/services`](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/services) (Project workflows), [`src/services/ai`](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/services/ai) (AI services), [`src/infrastructure/github`](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/github) (GitHub adapter)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entrypoints"]
  node_src_index["MCP server<br/>entrypoint<br/>[index.ts]"]
  node_src_cli["CLI<br/>entrypoint<br/>[cli.ts]"]
end

subgraph group_domain["Domain"]
  node_domain_core["Domain model<br/>contracts"]
  node_domain_schemas["Resource schemas<br/>zod schemas"]
end

subgraph group_services["Services"]
  node_services_project["Project workflows<br/>orchestration"]
  node_services_trace["Traceability<br/>pipeline"]
  node_services_ai["AI services<br/>orchestration"]
  node_services_context["Context generation<br/>analysis"]
  node_services_validation["Content validation<br/>validators"]
end

subgraph group_infra["Infrastructure"]
  node_infra_github[("GitHub adapter")]
  node_infra_resource[("Resource state<br/>state management")]
  node_infra_events["Events & sync"]
  node_infra_cache[("Cache layer")]
  node_infra_observability["Observability<br/>cross-cutting"]
  node_infra_http["Webhook server<br/>transport<br/>[WebhookServer.ts]"]
end

subgraph group_tools["MCP Tools"]
  node_infra_tools_registry["Tool core<br/>tooling"]
  node_infra_tools_project["Project tools<br/>mcp tools"]
  node_infra_tools_ai["AI tools<br/>mcp tools"]
  node_infra_tools_support["Supporting tools<br/>mcp tools"]
end

subgraph group_test["Tests"]
  node_tests_e2e(("E2E suite<br/>tests"))
  node_tests_unit(("Unit & integration<br/>tests"))
end

node_src_index -->|"boots"| node_infra_tools_registry
node_src_cli -->|"invokes"| node_src_index
node_infra_tools_registry -->|"registers"| node_infra_tools_project
node_infra_tools_registry -->|"registers"| node_infra_tools_ai
node_infra_tools_registry -->|"registers"| node_infra_tools_support
node_infra_tools_registry -->|"validates against"| node_domain_core
node_infra_tools_project -->|"calls"| node_services_project
node_infra_tools_ai -->|"calls"| node_services_ai
node_infra_tools_ai -->|"calls"| node_services_trace
node_infra_tools_support -->|"calls"| node_services_project
node_services_project -->|"uses"| node_infra_github
node_services_project -->|"uses"| node_infra_resource
node_services_project -->|"depends on"| node_domain_core
node_services_trace -->|"uses"| node_services_context
node_services_trace -->|"uses"| node_services_validation
node_services_ai -->|"uses"| node_infra_github
node_services_ai -->|"uses"| node_infra_observability
node_services_ai -->|"depends on"| node_domain_core
node_services_context -->|"depends on"| node_domain_core
node_services_validation -->|"validates"| node_domain_schemas
node_infra_github -->|"maps to"| node_domain_core
node_infra_resource -->|"persists through"| node_infra_cache
node_infra_events -->|"updates"| node_infra_resource
node_infra_http -->|"ingests"| node_infra_events
node_infra_observability -->|"wraps"| node_infra_github
node_tests_e2e -.->|"exercises"| node_src_index
node_tests_e2e -.->|"exercises"| node_infra_tools_registry
node_tests_unit -.->|"covers"| node_services_project
node_tests_unit -.->|"covers"| node_infra_github
node_tests_unit -.->|"covers"| node_infra_resource
node_tests_unit -.->|"covers"| node_services_ai

click node_src_index "https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/index.ts"
click node_src_cli "https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/cli.ts"
click node_domain_core "https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/domain"
click node_domain_schemas "https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/domain/resource-schemas.ts"
click node_services_project "https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/services"
click node_services_trace "https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/services/RequirementsTraceabilityService.ts"
click node_services_ai "https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/services/ai"
click node_services_context "https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/services/context"
click node_services_validation "https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/services/validation/ContextQualityValidator.ts"
click node_infra_tools_registry "https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/tools"
click node_infra_tools_project "https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/infrastructure/tools/project-lifecycle-tools.ts"
click node_infra_tools_ai "https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/tools/ai-tasks"
click node_infra_tools_support "https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/infrastructure/tools/issue-intelligence-tools.ts"
click node_infra_github "https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/github"
click node_infra_resource "https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/resource"
click node_infra_events "https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/events"
click node_infra_cache "https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/cache"
click node_infra_observability "https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/observability"
click node_infra_http "https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/infrastructure/http/WebhookServer.ts"
click node_tests_e2e "https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/__tests__/e2e"
click node_tests_unit "https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_index,node_src_cli toneBlue
class node_domain_core,node_domain_schemas toneAmber
class node_services_project,node_services_trace,node_services_ai,node_services_context,node_services_validation toneMint
class node_infra_github,node_infra_resource,node_infra_events,node_infra_cache,node_infra_observability,node_infra_http toneRose
class node_infra_tools_registry,node_infra_tools_project,node_infra_tools_ai,node_infra_tools_support toneIndigo
class node_tests_e2e,node_tests_unit toneTeal
```

## Components

### Entrypoints

Startup surfaces and packaging

- [MCP server](https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/index.ts): entrypoint · Main stdio/HTTP server bootstrap · `src/index.ts`
- [CLI](https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/cli.ts): entrypoint · Command-line startup and invocation surface · `src/cli.ts`

### Domain

Contracts, types, schemas, and validation primitives

- [Domain model](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/domain): contracts · Canonical project, resource, AI, and MCP types plus errors · `src/domain`
- [Resource schemas](https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/domain/resource-schemas.ts): zod schemas · Shared schemas, guards, and payload shape definitions · `src/domain/resource-schemas.ts`

### Services

Business workflows and orchestration

- [Project workflows](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/services): orchestration · Project, milestone, sprint, status, template, linking, and sub-issue orchestration · `src/services`
- [Traceability](https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/services/RequirementsTraceabilityService.ts): pipeline · Requirements to features, use cases, tasks, and context generation · `src/services/RequirementsTraceabilityService.ts`
- [AI services](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/services/ai): orchestration · PRD, task, roadmap, issue intelligence, and fallback-aware AI workflows · `src/services/ai`
- [Context generation](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/services/context): analysis · Code, dependency, and reference context helpers for AI workflows · `src/services/context`
- [Content validation](https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/services/validation/ContextQualityValidator.ts): validators · Quality checks for generated PRDs and task context · `src/services/validation/ContextQualityValidator.ts`

### Infrastructure

Adapters, persistence, transport, and cross-cutting runtime support

- [GitHub adapter](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/github): adapter · Repository factory, API config, error handling, and GitHub repository implementations · `src/infrastructure/github`
- [Resource state](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/resource): state management · Resource lifecycle, relationships, optimistic locking, and persistence-backed caches · `src/infrastructure/resource`
- [Events & sync](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/events): sync · Event store, subscriptions, webhook handling, and GitHub state synchronization · `src/infrastructure/events`
- [Cache layer](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/cache): cache · Resource and embedding caches plus persistence glue · `src/infrastructure/cache`
- [Observability](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/observability): cross-cutting · Correlation, tracing logs, health, and resilience policies · `src/infrastructure/observability`
- [Webhook server](https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/infrastructure/http/WebhookServer.ts): transport · HTTP webhook entrypoint for external GitHub event intake · `src/infrastructure/http/WebhookServer.ts`

### MCP Tools

Tool registry and MCP-facing capability layer

- [Tool core](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/tools): tooling · Tool registry, schema validation, coercion, and result formatting · `src/infrastructure/tools`
- [Project tools](https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/infrastructure/tools/project-lifecycle-tools.ts): mcp tools · Project lifecycle and advanced project operations exposed to MCP clients · `src/infrastructure/tools/project-lifecycle-tools.ts`
- [AI tools](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/infrastructure/tools/ai-tasks): mcp tools · PRD, task, traceability, sprint, and roadmap AI tool surface · `src/infrastructure/tools/ai-tasks`
- [Supporting tools](https://github.com/kunwarvivek/mcp-github-project-manager/blob/main/src/infrastructure/tools/issue-intelligence-tools.ts): mcp 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](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/src/__tests__/e2e): tests · End-to-end MCP, resource, and tool workflow coverage · `src/__tests__/e2e`
- [Unit & integration](https://github.com/kunwarvivek/mcp-github-project-manager/tree/main/tests): tests · Focused coverage for services, infrastructure, and tool wiring · `tests`

## Connections

- 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