Development Workflow MCP Server

An MCP (Model Context Protocol) server that helps enforce development discipline and workflow best practices. This server acts as your coding conscience, reminding you to follow proper development workflows.

🛡️ Resilience Features

• Startup Resilience: 5-second connection timeouts for external databases.
• Background Loading: Non-critical assets (compatibility mirrors) initialize in the background to ensure sub-second startup.
• Diagnostic Mode: Automatic startup timing logs displayed in stderr.

🎯 Purpose

This MCP server guides you through a disciplined development workflow:

1. Start Conscious - Be clear about what you're coding
2. Fix/Implement - Write your code
3. Create Tests - Always test your changes
4. Run Tests - Tests must pass (GREEN)
5. Document - Update documentation
6. Commit & Push - Let the server stage, commit, and push your changes once verification passes (if you make new edits afterward, the workflow moves back to this step automatically)
7. Release - After the push succeeds, record the release details before closing out the task

🆕 What's New in v1.8.0

• Modular Handler Architecture – tools/handlers.js now re-exports focused handler modules, improving maintainability and bundler behavior.
• Organized Test Suite – The 1k-line tests/handlers.test.js has been split into handlers-*.test.js files with shared helpers, reducing duplication and clarifying intent.
• Shared Test Utilities – New tests/test-helpers.js centralizes workflow state setup, request builders, and git mocks.
• Documentation Refresh – PRD moved to docs/PRD.md root, status bumped to v1.8.0, and release notes updated to reflect the current workflow.
• Release Hygiene – Recommended flow now includes npm run release:<type> followed by git push --follow-tags origin main to keep stages clean.

🚀 Installation

Option 1: Install as Dependency in Your Project (Recommended)

Each project gets its own isolated workflow state file.

npm install @programinglive/dev-workflow-mcp-server

This will automatically create a .state/workflow-state.json file in the project where you ran npm install (using npm's INIT_CWD), keeping workflow history separate per project. If you're installing the package itself (inside node_modules), the script skips creation so it never pollutes the shared package directory.

Option 2: Install from Source

git clone https://github.com/programinglive/dev-workflow-mcp-server.git
cd dev-workflow-mcp-server
npm install

Windows prerequisites: Installing dependencies from source compiles native modules such as better-sqlite3. Make sure Python 3 (added to PATH) and the Visual Studio Build Tools “Desktop development with C++” workload are installed before running npm install. Without them, npm will fail with a “need python” or build error.

Option 3: Install on Plesk Hosting

Plesk supports Node.js applications through its Node.js extension. To deploy the MCP server on a Plesk subscription:

1. Enable Node.js support – Ensure the Plesk administrator has installed the Node.js extension and enabled SSH access for your subscription.
2. Upload the project – Either clone the repository or upload an archive into the directory you will run it from (e.g., httpdocs/dev-workflow-mcp-server). From SSH you can run:
   bash

   Copy

   cd httpdocs
   git clone https://github.com/programinglive/dev-workflow-mcp-server.git
   cd dev-workflow-mcp-server
   

3. Install dependencies – In Plesk’s Node.js panel use “NPM install” (or run npm install --production over SSH). Linux hosts already ship the Python/build toolchain required for better-sqlite3; if your plan uses a Windows host, install Python 3 and the Visual Studio Build Tools beforehand or ask your provider to enable them.
4. Define environment variables – In the Node.js panel add any environment variables you need (for example DEV_WORKFLOW_USER_ID or DEV_WORKFLOW_STATE_FILE). This keeps state files outside the web root if desired.
5. Configure the application – Set Application startup file to index.js and Application mode to production. Plesk will run the server with node index.js.
6. Start/Restart the app – Click “Restart App” so Plesk launches the MCP server with the new configuration. When you update the code, rerun “NPM install” and restart.

Tip: The MCP server communicates over stdio. If you only need it as a CLI tool, you can also run npx @programinglive/dev-workflow-mcp-server directly in an SSH session without keeping it running under the Node.js panel.

Important: MCP clients (Windsurf, Claude Desktop, etc.) must launch the server process locally via stdio. Hosting the dashboard on a public domain does not expose the MCP interface. Without SSH or another way to execute node index.js on the server, users cannot connect their MCP clients to the hosted instance.

Option 4: Deploy with Docker on Google Cloud

Deploy the MCP server to Google Cloud Compute Engine using Docker and PostgreSQL for a production-ready, cloud-hosted setup.

Quick Start:

1. SSH into your GCP instance
2. Run the setup script: bash scripts/setup-gcp-instance.sh
3. Clone the repository and configure .env
4. Start containers: docker-compose up -d
5. Update your local MCP client config to connect via SSH

Benefits:

• ✅ PostgreSQL database for robust data persistence
• ✅ Containerized deployment for consistency
• ✅ Remote access via SSH tunneling
• ✅ Easy updates and rollbacks

See the GCP Deployment Guide for complete step-by-step instructions.

Two Usage Modes

• Local (source): Point your MCP client to index.js. This runs directly from source and requires no build step. Recommended for MCP usage.
• Production (built): Run npm run build once to generate dist/. This creates an optimized bundle but isn’t needed for MCP usage.

3. Configure in Windsurf/Claude Desktop

Point your MCP client to the server entry point. Replace <PROJECT_ROOT> with the absolute path to this repository on your machine.

macOS

• Windsurf (~/Library/Application Support/Windsurf/config.json):

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "cwd": "<PROJECT_ROOT>",
      "args": ["index.js"],
      "env": {
        "DEV_WORKFLOW_DB_TYPE": "postgres",
        "DEV_WORKFLOW_DB_URL": "postgres://USER:PASS@HOST:5432/devworkflow"
      }
    }
  }
}

• Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>/index.js"]
    }
  }
}

Windows

• Windsurf (%APPDATA%\Windsurf\config.json):

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>\\index.js"]
    }
  }
}

• Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>\\index.js"]
    }
  }
}

Linux

• Windsurf (~/.config/windsurf/config.json):

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>/index.js"]
    }
  }
}

• Claude Desktop (~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>/index.js"]
    }
  }
}

Note: On Windows paths in JSON require escaped backslashes (e.g., "C:\\path\\to\\project").

Full Windsurf MCP Config Example (macOS)

If you keep this repository checked out at /Users/alex/code/dev-workflow-mcp-server and want to point Windsurf at a hosted PostgreSQL instance, drop the following into ~/Library/Application Support/Windsurf/mcp_config.json:

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "cwd": "/Users/alex/code/dev-workflow-mcp-server",
      "args": ["index.js"],
      "env": {
        "DEV_WORKFLOW_DB_TYPE": "postgres",
        "DEV_WORKFLOW_DB_URL": "postgres://devworkflow:devworkflow_secure_password@34.50.121.142:5432/devworkflow"
      }
    }
  }
}

This mirrors the Windows configuration shared in previous releases, but avoids npx lookup issues on macOS by launching the local index.js directly.

4. Restart Windsurf/Claude Desktop

After adding the configuration, restart the application to load the MCP server.

5. Configure in Antigravity

Antigravity users should configure the MCP server in their mcp_config.json.

Windows: %APPDATA%\Antigravity\mcp_config.json or C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>\\index.js"]
    }
  }
}

See Antigravity Getting Started for detailed instructions and troubleshooting.

⚡ Performance Optimization (Recommended)

To ensure the fastest possible startup (critical for IDE-integrated clients like Claude Desktop), we recommend pointing directly to index.js using node rather than npx. This avoids the overhead of checking for package updates.

Optimized Configuration: