# pranjal2410719/dev-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/pranjal2410719/dev-mcp
- Repository: https://github.com/pranjal2410719/dev-mcp

## Overview

dev-mcp is an MCP server that gives AI-host clients project-management and engineering tools backed by persistent workspace context. A typical workflow is to initialize or read project context, define requirements and phases, track dependent tasks, then use coding and desktop tools; the Project Brain also supports session handoffs and checks implementation progress against workspace reality. The README documents additional Git, search, terminal, security, and desktop capabilities. Some modules were not sampled, so their relationships are shown only where the README supports them.

Main entry points: [`app.py`](https://github.com/pranjal2410719/dev-mcp/blob/main/app.py) (Tool Registry), [`context.py`](https://github.com/pranjal2410719/dev-mcp/blob/main/context.py) (Project Context), [`brain/todo_engine.py`](https://github.com/pranjal2410719/dev-mcp/blob/main/brain/todo_engine.py) (Todo Engine), [`brain/orchestrator.py`](https://github.com/pranjal2410719/dev-mcp/blob/main/brain/orchestrator.py) (Workflow Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP Runtime"]
  node_server["MCP Server<br/>[server.py]"]
  node_registry["Tool Registry<br/>[app.py]"]
  node_resources["Context Resources<br/>[definitions.py]"]
end

subgraph group_brain["Project Brain"]
  node_context_tools["Context Tools<br/>[context_mgmt.py]"]
  node_project_context[("Project Context<br/>[context.py]")]
  node_prd["PRD Manager<br/>[prd_manager.py]"]
  node_phases["Phase Manager<br/>[phase_manager.py]"]
  node_tasks["Todo Engine<br/>[todo_engine.py]"]
  node_dependencies["Task Dependencies<br/>[dependency.py]"]
  node_orchestrator["Workflow Orchestrator<br/>[orchestrator.py]"]
  node_handoffs["Session Handoffs<br/>[handoff_engine.py]"]
  node_workspace_state[("Project Brain Data")]
end

subgraph group_workspace["Workspace Engineering"]
  node_file_ops["File Operations<br/>[file_ops.py]"]
  node_search["Code Search<br/>[search.py]"]
  node_git["Git Operations<br/>[git_ops.py]"]
  node_terminal["Terminal<br/>[terminal.py]"]
  node_desktop["Desktop Automation<br/>[desktop_ops.py]"]
end

subgraph group_assurance["Project Assurance"]
  node_security["Path Security<br/>[security.py]"]
  node_sync["Reality Sync<br/>[sync_engine.py]"]
  node_guardian["Architecture Guardian<br/>[guardian.py]"]
  node_readiness["Project Readiness"]
  node_requirements["Requirements<br/>[requirements.py]"]
end

node_host(("AI Host"))

node_host -->|"invokes tools"| node_server
node_server -->|"runs server"| node_registry
node_context_tools -->|"registers tools"| node_registry
node_context_tools -->|"reads and updates"| node_project_context
node_registry -->|"loads context"| node_project_context
node_resources -->|"registers resources"| node_registry
node_resources -->|"exposes context"| node_project_context
node_prd -->|"reads and writes PRDs"| node_workspace_state
node_prd -->|"reads active tasks"| node_tasks
node_tasks -->|"stores task records"| node_workspace_state
node_tasks -->|"syncs task status"| node_project_context
node_orchestrator -->|"loads tasks"| node_tasks
node_orchestrator -->|"retrieves handoff"| node_handoffs
node_orchestrator -->|"reads PRD"| node_workspace_state
node_handoffs -->|"writes handoffs"| node_workspace_state
node_handoffs -->|"reads project details"| node_project_context
node_sync -->|"reads task records"| node_workspace_state
node_sync -.->|"checks workspace Git state"| node_git
node_dependencies -.->|"evaluates task dependencies"| node_workspace_state
node_phases -.->|"manages phase data"| node_workspace_state
node_guardian -.->|"checks project constraints"| node_workspace_state
node_readiness -.->|"assesses project state"| node_workspace_state
node_requirements -.->|"manages requirements"| node_workspace_state
node_file_ops -->|"validates paths"| node_security
node_registry -->|"validates workspace root"| node_security
node_host -.->|"requests desktop actions"| node_desktop
node_host -.->|"requests Git operations"| node_git
node_host -.->|"requests code search"| node_search
node_host -.->|"requests commands"| node_terminal

click node_server "https://github.com/pranjal2410719/dev-mcp/blob/main/server.py"
click node_registry "https://github.com/pranjal2410719/dev-mcp/blob/main/app.py"
click node_context_tools "https://github.com/pranjal2410719/dev-mcp/blob/main/tools/context_mgmt.py"
click node_project_context "https://github.com/pranjal2410719/dev-mcp/blob/main/context.py"
click node_prd "https://github.com/pranjal2410719/dev-mcp/blob/main/brain/prd_manager.py"
click node_phases "https://github.com/pranjal2410719/dev-mcp/blob/main/brain/phase_manager.py"
click node_tasks "https://github.com/pranjal2410719/dev-mcp/blob/main/brain/todo_engine.py"
click node_dependencies "https://github.com/pranjal2410719/dev-mcp/blob/main/brain/dependency.py"
click node_orchestrator "https://github.com/pranjal2410719/dev-mcp/blob/main/brain/orchestrator.py"
click node_handoffs "https://github.com/pranjal2410719/dev-mcp/blob/main/brain/handoff_engine.py"
click node_file_ops "https://github.com/pranjal2410719/dev-mcp/blob/main/tools/file_ops.py"
click node_search "https://github.com/pranjal2410719/dev-mcp/blob/main/tools/search.py"
click node_git "https://github.com/pranjal2410719/dev-mcp/blob/main/tools/git_ops.py"
click node_terminal "https://github.com/pranjal2410719/dev-mcp/blob/main/tools/terminal.py"
click node_desktop "https://github.com/pranjal2410719/dev-mcp/blob/main/tools/desktop_ops.py"
click node_security "https://github.com/pranjal2410719/dev-mcp/blob/main/security.py"
click node_sync "https://github.com/pranjal2410719/dev-mcp/blob/main/brain/sync_engine.py"
click node_guardian "https://github.com/pranjal2410719/dev-mcp/blob/main/brain/guardian.py"
click node_readiness "https://github.com/pranjal2410719/dev-mcp/blob/main/brain/project_readiness.py"
click node_requirements "https://github.com/pranjal2410719/dev-mcp/blob/main/brain/requirements.py"
click node_resources "https://github.com/pranjal2410719/dev-mcp/blob/main/resources/definitions.py"

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_server,node_registry,node_resources toneBlue
class node_context_tools,node_project_context,node_prd,node_phases,node_tasks,node_dependencies,node_orchestrator,node_handoffs,node_workspace_state toneAmber
class node_file_ops,node_search,node_git,node_terminal,node_desktop toneMint
class node_security,node_sync,node_guardian,node_readiness,node_requirements toneRose
class node_host toneIndigo
```

## Components

### MCP Runtime

- [MCP Server](https://github.com/pranjal2410719/dev-mcp/blob/main/server.py): `server.py`
- [Tool Registry](https://github.com/pranjal2410719/dev-mcp/blob/main/app.py): `app.py`
- [Context Resources](https://github.com/pranjal2410719/dev-mcp/blob/main/resources/definitions.py): `resources/definitions.py`

### Project Brain

- [Context Tools](https://github.com/pranjal2410719/dev-mcp/blob/main/tools/context_mgmt.py): `tools/context_mgmt.py`
- [Project Context](https://github.com/pranjal2410719/dev-mcp/blob/main/context.py): `context.py`
- [PRD Manager](https://github.com/pranjal2410719/dev-mcp/blob/main/brain/prd_manager.py): `brain/prd_manager.py`
- [Phase Manager](https://github.com/pranjal2410719/dev-mcp/blob/main/brain/phase_manager.py): `brain/phase_manager.py`
- [Todo Engine](https://github.com/pranjal2410719/dev-mcp/blob/main/brain/todo_engine.py): `brain/todo_engine.py`
- [Task Dependencies](https://github.com/pranjal2410719/dev-mcp/blob/main/brain/dependency.py): `brain/dependency.py`
- [Workflow Orchestrator](https://github.com/pranjal2410719/dev-mcp/blob/main/brain/orchestrator.py): `brain/orchestrator.py`
- [Session Handoffs](https://github.com/pranjal2410719/dev-mcp/blob/main/brain/handoff_engine.py): `brain/handoff_engine.py`
- **Project Brain Data**

### Workspace Engineering

- [File Operations](https://github.com/pranjal2410719/dev-mcp/blob/main/tools/file_ops.py): `tools/file_ops.py`
- [Code Search](https://github.com/pranjal2410719/dev-mcp/blob/main/tools/search.py): `tools/search.py`
- [Git Operations](https://github.com/pranjal2410719/dev-mcp/blob/main/tools/git_ops.py): `tools/git_ops.py`
- [Terminal](https://github.com/pranjal2410719/dev-mcp/blob/main/tools/terminal.py): `tools/terminal.py`
- [Desktop Automation](https://github.com/pranjal2410719/dev-mcp/blob/main/tools/desktop_ops.py): `tools/desktop_ops.py`

### Project Assurance

- [Path Security](https://github.com/pranjal2410719/dev-mcp/blob/main/security.py): `security.py`
- [Reality Sync](https://github.com/pranjal2410719/dev-mcp/blob/main/brain/sync_engine.py): `brain/sync_engine.py`
- [Architecture Guardian](https://github.com/pranjal2410719/dev-mcp/blob/main/brain/guardian.py): `brain/guardian.py`
- [Project Readiness](https://github.com/pranjal2410719/dev-mcp/blob/main/brain/project_readiness.py): `brain/project_readiness.py`
- [Requirements](https://github.com/pranjal2410719/dev-mcp/blob/main/brain/requirements.py): `brain/requirements.py`

### Other components

- **AI Host**

## Connections

- AI Host → MCP Server: invokes tools (evidence: `README.md`)
- MCP Server → Tool Registry: runs server (evidence: `README.md`)
- Context Tools → Tool Registry: registers tools (evidence: `tools/context_mgmt.py`)
- Context Tools → Project Context: reads and updates (evidence: `tools/context_mgmt.py`)
- Tool Registry → Project Context: loads context (evidence: `app.py`)
- Context Resources → Tool Registry: registers resources (evidence: `resources/definitions.py`)
- Context Resources → Project Context: exposes context (evidence: `resources/definitions.py`)
- PRD Manager → Project Brain Data: reads and writes PRDs (evidence: `brain/prd_manager.py`)
- PRD Manager → Todo Engine: reads active tasks (evidence: `brain/prd_manager.py`)
- Todo Engine → Project Brain Data: stores task records (evidence: `brain/todo_engine.py`)
- Todo Engine → Project Context: syncs task status (evidence: `brain/todo_engine.py`)
- Workflow Orchestrator → Todo Engine: loads tasks (evidence: `brain/orchestrator.py`)
- Workflow Orchestrator → Session Handoffs: retrieves handoff (evidence: `brain/orchestrator.py`)
- Workflow Orchestrator → Project Brain Data: reads PRD (evidence: `brain/orchestrator.py`)
- Session Handoffs → Project Brain Data: writes handoffs (evidence: `brain/handoff_engine.py`)
- Session Handoffs → Project Context: reads project details (evidence: `brain/handoff_engine.py`)
- Reality Sync → Project Brain Data: reads task records (evidence: `brain/sync_engine.py`)
- Reality Sync → Git Operations: checks workspace Git state
- Task Dependencies → Project Brain Data: evaluates task dependencies
- Phase Manager → Project Brain Data: manages phase data
- Architecture Guardian → Project Brain Data: checks project constraints
- Project Readiness → Project Brain Data: assesses project state
- Requirements → Project Brain Data: manages requirements
- File Operations → Path Security: validates paths (evidence: `tools/file_ops.py`)
- Tool Registry → Path Security: validates workspace root (evidence: `app.py`)
- AI Host → Desktop Automation: requests desktop actions (evidence: `README.md`)
- AI Host → Git Operations: requests Git operations (evidence: `README.md`)
- AI Host → Code Search: requests code search (evidence: `README.md`)
- AI Host → Terminal: requests commands (evidence: `README.md`)