Dev Mcp

🧠 dev-mcp: AI Engineering Operating System

dev-mcp is a custom Model Context Protocol (MCP) server that turns your AI assistants (Claude, Cursor, Gemini, Cline, Roo Code, Windsurf) into active Technical Project Managers.

Rather than treating the AI as a stateless code generator, dev-mcp establishes a persistent Project Brain in your workspace directory. This allows you to switch between different AI models and platforms seamlessly without losing context, project goals, tasks, or guidelines.

🏗️ Architecture

  Antigravity
       │
       ▼
(dev-mcp + Open Design)
       │
       ▼
Project Workspace
       │
       ▼
 Project Brain

🌟 Enhanced Startup Banner

The server now displays an eye‑catching banner on startup, showcasing the FastMCP version and deployment information with rich styling. This banner appears before the interactive hint line.

# Example banner output
╭──────────────────────────────────────────────────────────────────────────────╮
│                                                                              │
│                         ▄▀▀ ▄▀█ █▀▀ ▀█▀ █▀▄▀█ █▀▀ █▀█                        │
│                         █▀  █▀█ ▄▄█  █  █ ▀ █ █▄▄ █▀▀                        │
│                                                                              │
│                                                                              │
│                                                                              │
│                                FastMCP 3.4.2                                 │
│                            https://gofastmcp.com                             │
│                                                                              │
│                  🖥  Server:      dev-mcp, 3.4.2                              │
│                  🚀 Deploy free: https://horizon.prefect.io                  │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

The banner is rendered using the rich library and can be customized by editing the _print_banner function in server.py.

🕹️ Interactive Keyboard Shortcut Guide (dev-mcp-guide)

dev-mcp now includes an interactive terminal-based guide showing transport settings, MCP commands, and keyboard shortcut configurations:

dev-mcp-guide

Or, while running the dev-mcp server interactively in your terminal, press ?, h, or / to temporarily open/overlay the guide directly from the active server process!

Shortcuts:

• ← / → or Tab: Switch tabs (General, Commands, Shortcuts).
• ↑ / ↓: Scroll inside lists.
• esc / q: Close guide and return to the server loop.

> [!TIP] > Complete User Manual Available > For the comprehensive guide, including detailed setup, loops, slash commands, and a complete catalog of all 70 MCP tools with parameter signatures, see the [docs/usermanual.md](file:///home/dev/Desktop/projects/mcp/dev-mcp/docs/usermanual.md).

📚 Integration & Security Documentation

For detailed integration guides and architecture specifications, refer to:

• [docs/security.md](file:///home/dev/Desktop/projects/mcp/dev-mcp/docs/security.md): Safety modes (safe, trusted, lab), Workspace Lock, and command blacklist controls.
• [docs/workspaces.md](file:///home/dev/Desktop/projects/mcp/dev-mcp/docs/workspaces.md): Sibling workspace directory layout and Project Brain isolation.
• [docs/open-design.md](file:///home/dev/Desktop/projects/mcp/dev-mcp/docs/open-design.md): Design-to-code integrations and Open Design metadata tracking.
• [docs/antigravity.md](file:///home/dev/Desktop/projects/mcp/dev-mcp/docs/antigravity.md): Connecting the server to the Google DeepMind Antigravity CLI.
• [docs/architecture-v2.md](file:///home/dev/Desktop/projects/mcp/dev-mcp/docs/architecture-v2.md): Architectural layout and multi-agent execution boundaries.
• [docs/release-notes-v2.0.0.md](file:///home/dev/Desktop/projects/mcp/dev-mcp/docs/release-notes-v2.0.0.md): Details of changes and new features introduced in dev-mcp v2.0.0.

---

👥 Author & Maintainer Profile

For issues, questions, or collaboration requests, contact:

• Name: Pranjal Yadav
• Email: [2k24.cs1l.2410719@gmail.com](mailto:2k24.cs1l.2410719@gmail.com)
• Phone: +91 9219920362
• LinkedIn: linkedin.com/in/-pranjal22/
• GitHub: github.com/pranjal2410719

---

🚀 Full Setup & Installation Guide

1. Prerequisites

• Python 3.10+
• Git

2. Local Installation

Navigate to your dev-mcp directory and set up a virtual environment:

# Navigate to the server directory
cd /home/dev/Desktop/projects/mcp/dev-mcp

# Create a virtual environment using uv (recommended)
uv venv
source .venv/bin/activate
uv pip install -e .

# OR using standard python venv
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

---

⚙️ Configuring AI Clients (Cross-Platform)

Add the server command below to your editor of choice.

• Absolute Command Path: /home/dev/Desktop/projects/mcp/dev-mcp/.venv/bin/python
• Absolute Argument Path: /home/dev/Desktop/projects/mcp/dev-mcp/server.py

1. Claude Desktop

Add the following to your configuration file:

• Linux/macOS: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "dev-mcp": {
      "command": "/home/dev/Desktop/projects/mcp/dev-mcp/.venv/bin/python",
      "args": ["/home/dev/Desktop/projects/mcp/dev-mcp/server.py"]
    }
  }
}

2. Cursor

1. Go to Settings → Features → MCP.
2. Click + Add New MCP Server.
3. Configure:

• Name: dev-mcp
• Type: command
• Command: /home/dev/Desktop/projects/mcp/dev-mcp/.venv/bin/python /home/dev/Desktop/projects/mcp/dev-mcp/server.py

1. Click Save.

3. Windsurf

1. Open Settings → Advanced → MCP Configurations.
2. Add the configuration to your global list:

{
  "mcpServers": {
    "dev-mcp": {
      "command": "/home/dev/Desktop/projects/mcp/dev-mcp/.venv/bin/python",
      "args": ["/home/dev/Desktop/projects/mcp/dev-mcp/server.py"]
    }
  }
}

4. VS Code (Cline / Roo Code)

If using Cline, open the extension settings, select MCP Settings, and add:

{
  "mcpServers": {
    "dev-mcp": {
      "command": "/home/dev/Desktop/projects/mcp/dev-mcp/.venv/bin/python",
      "args": ["/home/dev/Desktop/projects/mcp/dev-mcp/server.py"]
    }
  }
}

---

👑 The Onboarding & Execution Workflow

dev-mcp establishes a strict project development lifecycle. The AI assistant evaluates codebase context dynamically, plans development sprints, tracks tasks, validates architecture requirements, syncs workspace files to real-world git events, and closes sessions safely.

                         assess_project_readiness()
                                     │
                 ┌───────────────────┴───────────────────┐
                 ▼ (If score < 80, empty)                ▼ (If score < 80, legacy)
         bootstrap_project()                     adopt_existing_project()
                 │                                       │
                 └───────────────────┬───────────────────┘
                                     ▼
                               doctor() (diagnostics)
                                     │
                                     ▼
                               start_session()
                                     │
                                     ▼
                               project_dashboard()
                                     │
                                     ▼
                               next_best_action()
                                     │
                                     ▼
        [Sync Plan] ──►       sync_workspace()
                                     │
                                     ▼
        [Audit Code] ──►        verify_work()
                                     │
                                     ▼
        [Audit Goal] ──►       verify_outcome()
                                     │
                                     ▼
                                end_session()
                                     │
                                     ▼
                          prepare_commit() ──► commit_changes()

Step 1: Onboard a Codebase

Open any code repository on your computer and run:

1. assess_project_readiness — Evaluates directory files and computes a project readiness score (0-100%) and maturity level (Levels 0-5).
2. doctor — Run a complete diagnostic health check on your Project Brain, context, configuration, and setup.
3. Bootstrap or Migrate:

• For new/empty projects: Run bootstrap_project() to write empty directories, project contexts, and milestones.
• For existing legacy codebases: Run adopt_existing_project() to scan language extensions, parse the current README.md to draft goals, and populate initial task backlogs.

Step 2: Set the Scope

Open the generated .project_brain/prd/PRD.md file and verify your goals. Run:

1. extract_requirements — Extracts requirements and keywords into requirements.json.
2. start_session — Bootstraps a development sprint and prints a Markdown brief for the model.

Step 3: Run the Session Loop

During active coding, keep alignment checked:

1. project_dashboard — View uncommitted git changes, milestones, active tasks, and code health logs.
2. next_best_action — Asks the engine to determine the next unblocked priority task.
3. sync_workspace — Matches physical file changes and commit history to detect completed work.
4. verify_work — Gathers file existences, test paths, and guardian violations to compile a verification dossier.
5. verify_outcome — Audits the code structure for database mutations, inputs, and routing to verify business goals.

Step 4: Safe Session Conclusion

When the task is complete, close the session without corrupting git history:

1. end_session — Generates a markdown session handoff log.
2. prepare_commit — Analyzes changes and suggests a conventional commit message (e.g. feat(auth): add login form).
3. commit_changes — Stages and commits changes with the approved message.

Step 5: Project Lifecycle & Resetting

If you need to archive, rotate, or re-initialize a project context:

1. archive_project_brain — Moves your active context and project brain configurations to .project_brain_archive/ with a timestamp to preserve history.
2. reset_project_brain — Wipes the context store and .project_brain files for the target folder, leaving your source code and git repository untouched.

---

🛠️ Complete MCP Tool Reference (70 Tools)

Here is the exhaustive catalog of all 70 registered tools on the dev-mcp server, grouped logically by module and function.

1. Onboarding & Diagnostics (brain/project_readiness.py)

These tools handle project onboarding, configuration sanity auditing, resets, and archiving.

| Tool Name | Parameters | Description | | :--- | :--- | :--- | | assess_project_readiness | path: str = "." | Scan the workspace and evaluate its onboarding readiness score (0-100%) against required Project Brain documents. | | project_readiness_report | path: str = "." | Generate a formatted Markdown project readiness report showing missing files, scoring audit, and recommended actions. | | bootstrap_project | path: str = "." | Auto-generate template files and directories (PRD, milestones, active tasks, config yaml) to instantly onboard an unknown repository. | | adopt_existing_project | path: str = "." | Scan an existing legacy codebase (directories, package lists, readmes) and generate context, PRDs, milestones, and audit tasks. | | doctor | path: str = "." | Check the diagnostic health and configuration integrity of the Project Brain and MCP server. | | reset_project_brain | path: str = "." | Wipe all Project Brain configuration, tasks, and context metadata inside the selected project. Leaves git and source code untouched. | | archive_project_brain | path: str = "." | Archive current Project Brain settings and context files to .project_brain_archive/ before a reset or pivot, preserving history. |

2. Session Orchestration (brain/orchestrator.py)

These tools drive the session sprint loop, planning, and safe Git committing.

| Tool Name | Parameters | Description | | :--- | :--- | :--- | | generate_project_brain | path: str = "." | Generate a complete aggregated Project Brain dashboard showing current status, phase, active/blocked tasks, recent changes, and recommendations. | | next_best_action | path: str = "." | Intelligently calculate and recommend the next best task to work on based on phase, priority, dependencies, and file hints. | | start_session | path: str = "." | Start a development session. Loads state, PRD, active tasks, and latest handoff to generate a detailed Session Brief for the AI. | | end_session | session_summary: str, known_issues: str = "", path: str = "." | End the current session, update progress, and generate a handoff file (does not auto-commit changes). | | prepare_commit | session_summary: str, path: str = "." | Analyze modified workspace files and generate a suggested conventional git commit message and summary for approval. | | commit_changes | message: str, path: str = "." | Stage all workspace changes and commit them to Git with the approved commit message. |

3. Task & Todo Management (brain/todo_engine.py)

These tools support granular planning, priorities, and dependency-aware task backlogs.

| Tool Name | Parameters | Description | | :--- | :--- | :--- | | create_task | title: str, description: str, phase: str = "", priority: str = "medium", depends_on: str = "", path: str = "." | Create a new task with phase, priority, dependencies, and description. | | update_task | task_id: str, title: str = "", description: str = "", phase: str = "", status: str = "", priority: str = "", depends_on: str = "", path: str = "." | Update a task's status, priority, or description by ID. | | complete_task | task_id: str, notes: str = "", path: str = "." | Mark a task as completed with optional notes. | | next_task | path: str = "." | Get the highest-priority task that is ready to work on (dependencies met, current phase). | | blocked_tasks | path: str = "." | List all tasks that are blocked, either by dependencies or explicitly. | | list_tasks | phase: str = "", status: str = "", path: str = "." | List all active tasks, optionally filtered by phase or status. |

4. Phase & Milestone Management (brain/phase_manager.py)

These tools handle project timeline scoping, phase progression, and release milestones.

| Tool Name | Parameters | Description | | :--- | :--- | :--- | | get_current_phase | path: str = "." | Get the current active phase and its status. | | set_phase | phase_name: str, description: str = "", path: str = "." | Set the current active development phase. Only tasks in this phase are considered 'in scope'. | | complete_phase | notes: str = "", path: str = "." | Mark the current phase as completed and optionally advance to the next phase. | | next_phase | phase_name: str, description: str = "", path: str = "." | Mark current phase as complete and advance to the next phase in sequence. | | list_phases | path: str = "." | List all phases and their status (completed, active, pending). | | add_milestone | name: str, target_date: str = "", features: str = "", path: str = "." | Define a milestone with a target date and associated features. | | `lis

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pranjal2410719
• Source: pranjal2410719/dev-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.