dev-mcp
Provides tools for managing git repositories, including staging and committing changes, and synchronizing workspace with commit history.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@dev-mcpassess project readiness"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
๐ง 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 BrainRelated MCP server: MCP Memory Server
๐ 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-guideOr, 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.
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/user_manual.md.
๐ Integration & Security Documentation
For detailed integration guides and architecture specifications, refer to:
docs/security.md: Safety modes (
safe,trusted,lab), Workspace Lock, and command blacklist controls.docs/workspaces.md: Sibling workspace directory layout and Project Brain isolation.
docs/open-design.md: Design-to-code integrations and Open Design metadata tracking.
docs/antigravity.md: Connecting the server to the Google DeepMind Antigravity CLI.
docs/architecture-v2.md: Architectural layout and multi-agent execution boundaries.
docs/release-notes-v2.0.0.md: Details of changes and new features introduced in
dev-mcpv2.0.0.
๐ฅ Author & Maintainer Profile
For issues, questions, or collaboration requests, contact:
Name: Pranjal Yadav
Email: 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/pythonAbsolute 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.jsonWindows:
%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
Go to Settings โ Features โ MCP.
Click + Add New MCP Server.
Configure:
Name:
dev-mcpType:
commandCommand:
/home/dev/Desktop/projects/mcp/dev-mcp/.venv/bin/python /home/dev/Desktop/projects/mcp/dev-mcp/server.py
Click Save.
3. Windsurf
Open Settings โ Advanced โ MCP Configurations.
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:
assess_project_readinessโ Evaluates directory files and computes a project readiness score (0-100%) and maturity level (Levels 0-5).doctorโ Run a complete diagnostic health check on your Project Brain, context, configuration, and setup.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 currentREADME.mdto 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:
extract_requirementsโ Extracts requirements and keywords intorequirements.json.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:
project_dashboardโ View uncommitted git changes, milestones, active tasks, and code health logs.next_best_actionโ Asks the engine to determine the next unblocked priority task.sync_workspaceโ Matches physical file changes and commit history to detect completed work.verify_workโ Gathers file existences, test paths, and guardian violations to compile a verification dossier.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:
end_sessionโ Generates a markdown session handoff log.prepare_commitโ Analyzes changes and suggests a conventional commit message (e.g.feat(auth): add login form).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:
archive_project_brainโ Moves your active context and project brain configurations to.project_brain_archive/with a timestamp to preserve history.reset_project_brainโ Wipes the context store and.project_brainfiles 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 |
|
| Scan the workspace and evaluate its onboarding readiness score (0-100%) against required Project Brain documents. |
|
| Generate a formatted Markdown project readiness report showing missing files, scoring audit, and recommended actions. |
|
| Auto-generate template files and directories (PRD, milestones, active tasks, config yaml) to instantly onboard an unknown repository. |
|
| Scan an existing legacy codebase (directories, package lists, readmes) and generate context, PRDs, milestones, and audit tasks. |
|
| Check the diagnostic health and configuration integrity of the Project Brain and MCP server. |
|
| Wipe all Project Brain configuration, tasks, and context metadata inside the selected project. Leaves git and source code untouched. |
|
| Archive current Project Brain settings and context files to |
2. Session Orchestration (brain/orchestrator.py)
These tools drive the session sprint loop, planning, and safe Git committing.
Tool Name | Parameters | Description |
|
| Generate a complete aggregated Project Brain dashboard showing current status, phase, active/blocked tasks, recent changes, and recommendations. |
|
| Intelligently calculate and recommend the next best task to work on based on phase, priority, dependencies, and file hints. |
|
| Start a development session. Loads state, PRD, active tasks, and latest handoff to generate a detailed Session Brief for the AI. |
|
| End the current session, update progress, and generate a handoff file (does not auto-commit changes). |
|
| Analyze modified workspace files and generate a suggested conventional git commit message and summary for approval. |
|
| 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 a new task with phase, priority, dependencies, and description. |
|
| Update a task's status, priority, or description by ID. |
|
| Mark a task as completed with optional notes. |
|
| Get the highest-priority task that is ready to work on (dependencies met, current phase). |
|
| List all tasks that are blocked, either by dependencies or explicitly. |
|
| 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 the current active phase and its status. |
|
| Set the current active development phase. Only tasks in this phase are considered 'in scope'. |
|
| Mark the current phase as completed and optionally advance to the next phase. |
|
| Mark current phase as complete and advance to the next phase in sequence. |
|
| List all phases and their status (completed, active, pending). |
|
| Define a milestone with a target date and associated features. |
|
| Show all milestones and their status. |
5. PRD & Requirements Traceability (brain/prd_manager.py & brain/requirements.py)
These tools manage scope files and check if the implemented codebase corresponds to the PRD.
Tool Name | Parameters | Description |
|
| Retrieve a PRD document (PRD, VISION, SCOPE, REQUIREMENTS). Returns the content of the specified document. |
|
| Create or update a PRD document (PRD, VISION, SCOPE, REQUIREMENTS). |
|
| Summarize key requirements from PRD documents into a concise bullet list. |
|
| Compare current project context and tasks against PRD requirements to check alignment. |
|
| Parse PRD markdown files to extract structured requirements and save them into |
|
| Scan codebase to map requirement keywords and verify their implementation status and feature coverage. |
|
| Perform outcome audits verifying user flows, business goals, and objective completion based on target tasks. |
6. Workspace Sync & Verification (brain/sync_engine.py)
These tools check if code changes match physical files and track completeness metrics.
Tool Name | Parameters | Description |
|
| Scan the physical workspace (Git diff, new files, current branch, commits) and compare to the Todo plan to auto-detect finished work. |
|
| Perform deep sanity, test, git diff, and architecture checks against a task to output a reality verification dossier. |
|
| Generate a unified Project Manager Dashboard combining phase state, todo progress, git status, architecture violations, and a project health score. |
7. Handoff & Sprint History (brain/handoff_engine.py)
These tools record and retrieve AI context handoffs across sessions.
Tool Name | Parameters | Description |
|
| Generate a session summary capturing what was done, what's next, and current project state for handoff to another AI. |
|
| Retrieve the most recent AI handoff document so a new AI session has full context. |
|
| List all AI session handoffs with dates. |
8. Architecture & Dependency Control (brain/guardian.py & brain/dependency.py)
These tools ensure structural health, dependency blast radius checks, and technology rules enforcement.
Tool Name | Parameters | Description |
|
| Scan the codebase and validate imports/technologies against the project's architectural guidelines and forbidden tools. |
|
| Scan files and construct a complete mapping of dependencies and references in the project. |
|
| Calculate direct and transitive downstream files affected if a given file is modified. |
9. Context Management (tools/context_mgmt.py)
These tools provide generic getters/setters for .project-context.json.
Tool Name | Parameters | Description |
|
| Initialize or auto-detect project context. Scans project files to detect tech stack, languages, and frameworks. |
|
| Get the full project context as formatted JSON/text. Optionally filter by dot path (e.g. |
|
| Update a specific field in the project context using dot notation (e.g. |
|
| Add an item to a list field in the context (e.g. |
|
| Register a key file with its purpose and optional details in the project context. |
|
| Add an active task to the project context. |
|
| Log an architecture decision record (ADR) in the project context. |
|
| Export the project context as a Markdown document for sharing with other LLMs and AI tools. |
|
| Remove an item from a list in the project context by index. |
|
| Reset the project context to default values (clears all data). |
|
| Get information about the current project environment (languages, frameworks, file counts). |
10. File Operations (tools/file_ops.py)
These tools provide sandbox-constrained file manipulation utilities.
Tool Name | Parameters | Description |
|
| Read the contents of a file at the given path. |
|
| Write content to a file, creating it if it doesn't exist. |
|
| Edit a file by replacing an exact string with a new string. Use this for targeted code changes. |
|
| Delete a file or an empty directory. |
|
| Recursively delete a file or directory tree. Use with caution. |
|
| List files and directories inside a given directory. |
|
| Find files matching a glob pattern (e.g. |
|
| Create one or more directories (like |
11. Terminal, Git & Code Search (tools/terminal.py, tools/search.py & tools/git_ops.py)
These tools provide controlled shell command runs, pattern search, and Git operations.
Tool Name | Parameters | Description |
|
| Run a shell command and return its output. Always set a reasonable timeout. Avoid destructive commands. |
|
| Search for a text pattern across files in the project using ripgrep (or Python fallback). |
|
| Show the working tree status (git status). |
|
| Show staged and unstaged changes (git diff). |
|
| Show recent commit history (git log). |
|
| List local branches (git branch). |
|
| Stage file(s) for commit (git add). |
|
| Commit staged changes with a message (git commit). |
|
| Create and switch to a new git branch (git checkout -b). |
๐งฉ Prompts Reference
The server registers 4 Prompt Templates that can be loaded in supported MCP Clients:
project-overviewโ Injects the entire project context JSON in markdown format, outputting development guidelines for the model.code-reviewโ Loads the project conventions and tech stack to provide specific checklists for reviewing code.architectural-decisionโ Provides a structured markdown template to record Architecture Decision Records (ADRs).feature-planโ Generates a blueprint template for planning branches, milestones, tasks, and target files.
๐ฆ Resources Reference
The server exposes 2 resources matching the current active project root:
project://context/jsonโ Returns.project-context.jsoncontent as JSON.project://context/markdownโ Returns.project-context.jsoncontext parsed as a Markdown layout.
โ๏ธ Workspace Configuration (.project_brain/config.yaml)
Each project generates a local YAML configuration for customization:
project_type: auto # 'auto' or 'legacy'
language: auto # Primary codebase language
framework: auto # Primary web framework
readiness_threshold: 80 # Score threshold to begin tasks
verification_threshold: 85 # Verification confidence to autocomplete
auto_sync: true # Automatically parse changes in dashboard๐ Security Sandbox
All file tools are sandboxed for security. Paths must resolve within directories in:
The server's current working directory.
DEV_MCP_ALLOWED_DIRSenvironment variable (colon-separated list of paths).The user's home directory (
$HOME).
To restrict allowed directories:
export DEV_MCP_ALLOWED_DIRS="/home/user/project1:/home/user/project2"๐ Troubleshooting & Connection Lifecycle
When developing or updating code in dev-mcp, keep in mind how MCP clients handle the process lifecycle:
Stateful Connection: Most AI clients (like Cursor or Claude Desktop) cache the active
stdiopipe connection to the server process.Out-of-Sync State: If the server is updated or restarted, the clientโs stdio connection can become stale, resulting in
EOForclient closingerrors.Project Switching (No Context Leakage): The global context cache in app.py checks if the target root is different from the cached path during tool execution (
_root != target_root), preventing tasks and metadata from leakages across projects.
How to Reconnect Across Clients:
Cursor: Go to Settings โ Features โ MCP โ find
dev-mcpand click Restart.Claude Desktop: Fully Quit the app from your taskbar/dock and reopen it to force Claude to spawn a new MCP process.
Cline / Roo Code: Restart the extension or trigger a reconnect via
/mcp restart dev-mcp.Windsurf: Reload the editor window or restart the workspace connection.
๐งช Running Validation Tests
Ensure server correctness and E2E workflow consistency by executing the pipeline script:
.venv/bin/python tests/validate_mcp_flow.pyFor guidelines on coding conventions, code style, and how to write custom tools for this server, see CONTRIBUTING.md.
This server cannot be installed
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Latest Blog Posts
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/pranjal2410719/dev-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server