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

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

Related MCP server: MCP Memory Server

⚡ What's New in v2.2.2?

• Top-Pinned Terminal Viewport & Windowed Scrolling:

  • dev-mcp-guide dynamically calculates terminal window dimensions (lines - 9) and windows table rows, completely eliminating viewport overflow and auto-scrolling to the bottom.

  • Every view starts pinned at Row 1 / Tool #1 / Section 1.

  • Full manual keyboard scrolling: ↑/↓ (or j/k) for row navigation, PgUp/PgDn for page jumps, and Home/End (or g/G) for jumping directly to top/bottom.

  • General quickstart paginates section-by-section with live progress indicators (● 1 ○ 2 ○ 3 ○ 4 ○ 5).

• Python 3.10 / 3.11 Backward Compatibility (v2.2.1):

  • Resolved Python 3.10/3.11 SyntaxError in tools/git_ops.py for nested f-strings.

• Streamlined Single-Panel Diagnostic Banner:

  • Suppressed duplicate internal FastMCP startup notices (show_banner=False) and routes all diagnostics cleanly to sys.stderr.

• Zero-Install PyPI Distribution (braynix-dev-mcp) & MCP Registry:

  • Run instantly anywhere via uvx --from braynix-dev-mcp dev-mcp.

  • Registered under namespace io.github.pranjal2410719/dev-mcp.

• 91 Registered MCP Tools across 18 specialized modules.

• Dynamic Tool Profiling (DEV_MCP_PROFILE): Slash LLM prompt token consumption by up to 75% (code, planning, audit, desktop, all).

🏗️ 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 clean, single-panel diagnostic banner pinned cleanly at the top of your terminal without duplicate boxes:

╭─ 🧠 dev-mcp v2.2.2 — AI Engineering Operating System ───────────────────────────────────╮
│                                                                                         │
│        Status:  ● Running (stdio transport)                                             │
│       Profile:  all (18 modules · 91 tools)                                             │
│     Workspace:  Jailed Lock Active · Mode: safe                                         │
│  Distribution:  PyPI: braynix-dev-mcp · Registry: io.github.pranjal2410719/dev-mcp      │
│    Docs & Web:  https://dev-mcp.me                                                      │
│                                                                                         │
╰─────────────────────────── Press ? for Interactive Guide · q to stop ───────────────────╯

🎯 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.

• Top Pinned: Viewport always starts pinned at Row 1 / Tool #1 / Section 1.

• ← / → or Tab / Shift+Tab: Switch tabs (general, commands, shortcuts).

• ↑ / ↓ or j / k: Scroll list entries or navigate sections.

• PgUp / PgDn (or b / space): Page up and down by full viewport.

• Home / End (or g / G): Jump to top or bottom.

• ?: Jump directly to Shortcuts reference.

• esc / q: Return to the server loop or terminal cleanly.

🚀 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