🧠 dev-mcp: AI Engineering Operating System (v2.2.0)

dev-mcp is a production-grade Model Context Protocol (MCP) server that turns your AI assistants (Claude, Cursor, Gemini, Cline, Roo Code, Windsurf, Antigravity CLI) into autonomous Technical Project Managers and Desktop Automation Engineers.

Rather than treating LLMs as stateless code generators, dev-mcp establishes a persistent Project Brain directly in your workspace repository. It preserves context, PRD specifications, phase timelines, task dependencies, architectural guards, and desktop verification states across multiple AI sessions and platforms.

👥 Author & Maintainer Profile

For inquiries, support, or technical contributions, reach out to:

• Name: Pranjal Yadav
• Email: 2k24.cs1l.2410719@gmail.com
• LinkedIn: linkedin.com/in/-pranjal22/
• GitHub: github.com/pranjal2410719

⚡ What's New in v2.1.0?

• 91 Registered MCP Tools across 18 specialized modules.
• Dynamic Tool Profiling (DEV_MCP_PROFILE): Slash LLM prompt token consumption by up to 75% by loading only the tools relevant to your workflow (code, planning, audit, desktop, or all).
• Desktop GUI Automation & Verification (tools/desktop_ops.py): 16 dedicated tools plus a universal dispatcher (desktop_action) integrating with agent-desktop (Linux AT-SPI / X11 / Wayland, macOS, Windows) for 100% full-coverage GUI inspection, clicking, typing, shortcut dispatching, and window automation.
• High-Speed Filesystem & Search:
  • 26.2× faster path validation in security.py (0.087ms vs 2.28ms).
  • Sliced reads (start_line, end_line), line numbering, and safety truncation (>2,500 lines).
  • Atomic writing via temporary files and os.replace.
  • In-place string editing with exact count control and whitespace mismatch assistance.
  • Multi-file atomic batch replacements (batch_replace).
  • File metadata inspection (file_info).
  • Automatic noise filtering (.git, node_modules, __pycache__, .venv, .next, dist, build).
  • Native Ripgrep (rg) search with Python regex fallback.
• AST Dependency & Blast Radius Caching: mtime-backed AST parse caching (_FILE_PARSE_CACHE) reduces dependency traversal times to sub-millisecond speeds.
• Persistent Git Hook Automation (install_git_hooks): Automatically generates a Git pre-commit hook that syncs .project_brain on every native terminal commit.

🏗️ Architecture Overview

                  Developer / AI Host Client
      (Cursor, Claude Desktop, Windsurf, Antigravity CLI)
                              │
                              ▼
                       dev-mcp Server
               (FastMCP 3.4.2 · Python 3.10+)
                              │
  ┌───────────────────────────┼───────────────────────────┐
  │                           │                           │
  ▼                           ▼                           ▼
Project Workspace       Security Sandbox           Desktop Automation
├── Source Files        ├── Path Jailing (safe)     ├── agent-desktop CLI
├── Git Repository      ├── Allowed Dirs (lab)      ├── AT-SPI Accessibility
└── .project_brain/     └── Command Filter          └── Screen / Window Ops
    ├── config.yaml
    ├── prd/
    ├── tasks/
    └── handoffs/

🌟 Enhanced Startup Banner

On server boot, dev-mcp renders a rich visual banner with active profile status and host diagnostics:

╭──────────────────────────────────────────────────────────────────────────────╮
│                                                                              │
│                         ▄▀▀ ▄▀█ █▀▀ ▀█▀ █▀▄▀█ █▀▀ █▀█                        │
│                         █▀  █▀█ ▄▄█  █  █ ▀ █ █▄▄ █▀▀                        │
│                                                                              │
│                                FastMCP 3.4.2                                 │
│                            https://gofastmcp.com                             │
│                                                                              │
│                  🖥  Server:      dev-mcp, 3.4.2                              │
│                  🎯 Profile:     ALL (91 Tools / 18 Modules)                 │
│                  🚀 Deploy free: https://horizon.prefect.io                  │
│                                                                              │
╰──────────────────────────────────────────────────────────────────────────────╯

🎯 Tool Profiles & Token Optimization (DEV_MCP_PROFILE)

Loading 91 tools into an LLM context consumes ~12,500 system prompt tokens on every turn. Set the DEV_MCP_PROFILE environment variable in your client configuration to load only what you need:

To check the active profile programmatically, call get_dev_mcp_profile().

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

Launch the built-in interactive terminal helper at any time:

dev-mcp-guide

Or, while running the dev-mcp server interactively in a terminal, press ?, h, or / to display the modal overlay.

• ← / → or Tab: Switch tabs (General, Commands, Shortcuts).
• ↑ / ↓: Scroll list entries.
• esc / q: Return to the server loop.

🚀 Full Setup & Installation

1. Prerequisites

• Python 3.10+
• Git
• (Optional) agent-desktop (npm install -g agent-desktop) for GUI testing on Linux, macOS, or Windows.
• (Optional) ripgrep (sudo apt install ripgrep) for high-speed file searches.

2. Installation Options

Package Installation (PyPI: braynix-dev-mcp)

# One-time installation
uv tool install braynix-dev-mcp

# Run the server
dev-mcp

# Or run without a permanent installation
uvx --from braynix-dev-mcp dev-mcp

# Open the interactive guide
dev-mcp-guide

Alternatively using pip or pipx:

pipx install braynix-dev-mcp
# or in a virtualenv:
pip install braynix-dev-mcp

Local Development Clone

# Clone the repository
git clone https://github.com/pranjal2410719/dev-mcp.git
cd dev-mcp

# Setup virtual environment with uv
uv venv
source .venv/bin/activate
uv pip install -e .

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

⚙️ Configuring AI Clients

Clients can invoke dev-mcp directly (if installed globally or in PATH) or via its virtual environment Python executable.

1. Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json (Linux/macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "dev-mcp": {
      "command": "dev-mcp",
      "env": {
        "DEV_MCP_PROFILE": "all"
      }
    }
  }
}

(If running from a local source checkout, set "command": "/path/to/dev-mcp/.venv/bin/python" and "args": ["/path/to/dev-mcp/server.py"])

2. Cursor

1. Go to Settings → Features → MCP.
2. Click + Add New MCP Server.
3. Set Name to dev-mcp, Type to command, and Command to:

   dev-mcp
   

   (or /path/to/dev-mcp/.venv/bin/python /path/to/dev-mcp/server.py for source checkouts)

3. Windsurf

Add to your mcp_config.json:

{
  "mcpServers": {
    "dev-mcp": {
      "command": "dev-mcp",
      "env": {
        "DEV_MCP_PROFILE": "code"
      }
    }
  }
}

4. Antigravity CLI (Google DeepMind)

Add to ~/.gemini/antigravity-cli/mcp_config.json:

{
  "mcpServers": {
    "dev-mcp": {
      "command": "dev-mcp"
    }
  }
}

Host Client vs MCP Server Boundary: Slash commands (/goal, /schedule, /grill-me, /teamwork, /learn) are specialized execution loops of host clients like Antigravity CLI. Dev MCP provides the 91 deterministic MCP tools, state persistence (.project_brain/), and safety guardrails that host agents invoke during those workflows.

👑 The Onboarding & Execution Workflow

                         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()
                                     │
                                     ▼
        [GUI Verification] ──► desktop_verify_element()
                                     │
                                     ▼
        [Audit Goal] ──►       verify_outcome()
                                     │
                                     ▼
                                end_session()
                                     │
                                     ▼
                          prepare_commit() ──► commit_changes()

🛠️ Complete MCP Tool Catalog (91 Tools)

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

• assess_project_readiness(path="."): Scan directory and calculate structural onboarding readiness score (0-100%) across PRD, tasks, git, and tests.
• project_readiness_report(path="."): Generate formatted Markdown readiness report.
• bootstrap_project(path="."): Initialize PRD templates, milestones, and brain structure.
• adopt_existing_project(path="."): Scan existing legacy repository and draft PRD, context, and backlog.
• doctor(path="."): Run diagnostic health audit across 7 layers.
• reset_project_brain(path="."): Reset project metadata while preserving source code and git.
• archive_project_brain(path="."): Backup project brain state into .project_brain_archive/.
• create_project_workspace(name, template="blank", path="."): Create isolated sibling workspace directory.

2. Session Orchestration (brain/orchestrator.py)

• generate_project_brain(path="."): Consolidate current sprint metrics into a single dashboard.
• next_best_action(path="."): Recommend the highest-priority unblocked task.
• start_session(path="."): Begin a sprint and generate an AI task briefing.
• end_session(session_summary, known_issues="", path="."): Conclude sprint and record handoff.
• prepare_commit(session_summary, path="."): Suggest conventional commit message based on Git diff.
• commit_changes(message, path="."): Stage workspace changes and commit cleanly.

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

• create_task(title, description, phase="", priority="medium", depends_on="", path="."): Add task.
• update_task(task_id, status="", priority="", title="", path="."): Update task attributes.
• complete_task(task_id, notes="", path="."): Close task with completion notes.
• next_task(path="."): Get next ready task.
• blocked_tasks(path="."): List tasks blocked by unfulfilled dependencies.
• list_tasks(phase="", status="", priority="", path="."): Query tasks by phase, status, or priority.

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

• get_current_phase(path="."): Retrieve active development phase.
• set_phase(phase_name, description="", path="."): Set active scope phase.
• complete_phase(notes="", path="."): Conclude current phase.
• next_phase(phase_name, description="", path="."): Advance to next phase.
• list_phases(path="."): List all defined phases.
• add_milestone(name, target_date="", features="", path="."): Define project milestone.
• list_milestones(path="."): Enumerate all milestones.

5. PRD & Requirements Traceability (brain/prd_manager.py, brain/requirements.py)

• get_prd(document="PRD", path="."): Read markdown PRD specification document.
• update_prd(document, content, path="."): Update PRD specification document.
• summarize_prd(path="."): Generate bullet-point requirements summary.
• compare_work_to_prd(path="."): Audit backlog against PRD specifications.
• extract_requirements(path="."): Extract structured requirements into requirements.json.
• verify_requirements(feature_name="", path="."): Verify code implementation coverage against PRD section keywords (pair with verify_work for unit test coverage).
• verify_outcome(task_id, path="."): Deep outcome audit verifying end-to-end user journeys.

6. Workspace Sync & Verification (brain/sync_engine.py)

• sync_workspace(path="."): Match Git branch names, commit logs, and modified files to tasks to compute heuristic completion confidence scores.
• verify_work(task_id, path="."): Gather git diff, tests, and architecture rules to compile verification dossier.
• project_dashboard(path="."): Unified manager dashboard combining Git, tasks, and code health.

7. Sprint Handoffs (brain/handoff_engine.py)

• generate_handoff(session_summary="", known_issues="", path="."): Save sprint handoff log.
• get_last_handoff(path="."): Load latest session handoff.
• list_handoffs(path="."): List historical handoffs with timestamps.

8. Architecture & Dependency Control (brain/guardian.py, brain/dependency.py)

• validate_architecture(path="."): Check code imports against forbidden and required technology rules.
• build_dependency_graph(path="."): Build complete dependency graph with cached AST parser.
• impact_analysis(file_path, path="."): Calculate blast radius and affected downstream files before refactoring.

9. Context Management (tools/context_mgmt.py)

• init_context(path="."): Initialize or auto-detect project context.
• get_context(dot_path="", path="."): Query context field using dot notation.
• update_context(dot_path, value, path="."): Set context field value.
• add_to_context_list(dot_path, item, path="."): Append item to list field.
• add_key_file(file_path, purpose, details="", root_path="."): Track critical codebase file.
• add_task(task_id, description, status="pending", branch="", notes="", path="."): Add task record.
• add_decision(decision, reason, alternatives="", path="."): Log Architecture Decision Record (ADR).
• export_context_markdown(path="."): Export project context to .project-context.md.
• remove_context_item(dot_path, index, path="."): Remove item from list by index.
• reset_context(path="."): Reset context to defaults.
• project_info(path="."): Inspect project file count, frameworks, and runtime metrics.

10. High-Performance File Operations (tools/file_ops.py)

• read_file(path, start_line=None, end_line=None, line_numbers=False): Read sandboxed files with slicing and safety limits.
• write_file(path, content, append=False): Atomic file writes with directory auto-creation and append support.
• edit_file(path, old_string, new_string, count=None): Surgical in-place editing with whitespace mismatch detection.
• batch_replace(file_paths, old_string, new_string): Atomic multi-file text replacement.
• file_info(path): Get file size, line count, permissions, and modification timestamp.
• delete_path(path): Delete single file or empty folder.
• delete_recursive(path): Recursively delete folder trees (blocked in safe mode).
• list_directory(path): List directory entries with human-readable sizes and noise filtering.
• glob_files(pattern, base_path="."): Find files with glob patterns and noise filtering.
• create_directory(path): Recursively create directory paths (mkdir -p).

11. Code Search & Terminal Execution (tools/search.py, tools/terminal.py)

• search_code(pattern, path=".", glob_filter=None, max_results=50, context_lines=0): High-speed search using Ripgrep (rg) with regex fallback.
• run_command(command, timeout_seconds=60, workdir=None): Execute shell command inside sandbox with safety filtering.

12. Git Operations & Automation (tools/git_ops.py)

• git_status(repo_path="."): Get working tree status.
• git_diff(repo_path=".", staged=False): View staged or unstaged diffs.
• git_log(repo_path=".", max_count=10): Inspect commit history.
• git_branch(repo_path="."): List local branches.
• git_add(repo_path=".", files="."): Stage files for commit.
• git_commit(repo_path=".", message="update"): Commit staged files.
• git_create_branch(repo_path=".", branch_name=""): Create and checkout branch.
• install_git_hooks(repo_path="."): Install Git pre-commit hook to automatically sync .project_brain.

13. Desktop GUI Automation & Inspection (tools/desktop_ops.py — 16 Tools)

• desktop_status(): Inspect agent-desktop CLI installation and AT-SPI accessibility bus.
• desktop_list_apps(): List active desktop processes and window titles.
• desktop_list_windows(app=""): List desktop window IDs and geometry bounds.
• desktop_snapshot(app="", interactive_only=True, compact=True): Capture accessibility tree structure with @ref_ids.
• desktop_find(name="", role="", app=""): Locate UI elements (buttons, inputs, menus) by text or role.
• desktop_click(ref_id, headed=False): Trigger semantic or physical mouse click on target element.
• desktop_type(ref_id, text, headed=False): Send native keyboard text into target field.
• desktop_press(key_combo, headed=False): Send key shortcut combos (e.g. ctrl+c, return, escape, alt+tab).
• desktop_scroll(ref_id="", direction="down", amount=3, headed=False): Scroll element or window viewport.
• desktop_launch(app, activate=True): Launch desktop application and await window presentation.
• desktop_close_app(app, force=False): Gracefully close or force terminate an application.
• desktop_focus_window(app="", window_id=""): Bring target window to foreground and verify OS focus.
• desktop_clipboard(action="get|set|clear", text=""): Read, write, or clear system clipboard.
• desktop_verify_element(name, role="", app="", expected_state=""): Verify that expected GUI component exists and assert state.
• desktop_screenshot(app, output_path="screenshot.png"): Capture PNG screenshot of application window.
• desktop_action(command, args=None, timeout=30): Universal dispatcher executing ANY of the 50+ agent-desktop commands (is, get, hover, drag, wait, batch, session, etc.).

14. Server Profiling (server.py)

• get_dev_mcp_profile(): Inspect active profile mode, loaded modules, and tool counts.

🔒 Security Sandbox & Safety Modes

All file and process operations are governed by security.py:

• safe (Default): Workspace Lock active. Commands jailed to active project root. Recursive deletions and destructive commands (sudo, mkfs, rm -rf, git reset --hard) are blocked.
• trusted: Workspace Lock active. Folder deletions and checkout operations permitted within project bounds.
• lab: Workspace Lock disabled. Allows operations across allowed directories list (DEV_MCP_ALLOWED_DIRS).

For security specifications, see docs/security.md.

📚 In-Depth Documentation

• User Manual & Developer Guide: Complete guide to all 91 tools with parameter signatures and examples.
• v2.2.0 Release Notes: Local distribution, PyPI packaging, and MCP Registry metadata.
• v2.1.0 Release Notes: Performance benchmarks and upgrade guides.
• Architecture Specification: Architecture, data structures, and multi-agent isolation.
• Security Model: Workspace Lock, safety modes, and command authorization.
• Multi-Workspace Guide: Managing sibling workspaces and subagent isolation.
• Antigravity CLI Integration: DeepMind Antigravity CLI workflows.
• Open Design Integration: Design-to-code metadata synchronization.

🧪 Testing & Validation

# Run unit and optimization test suites
.venv/bin/python -m unittest discover -s tests -p "*.py" -v

# Run the end-to-end MCP workflow verification
.venv/bin/python tests/validate_mcp_flow.py

# Verify optimization benchmarks
.venv/bin/python tests/test_optimizations.py