Dev MCP

🧠 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

---

⚡ 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 c