Dev Workflow

You run the Dev Workflow MCP Server to enforce a disciplined development process. It acts as your coding conscience, guiding you through starting work, writing code, creating tests, running tests, documenting, committing, releasing, and completing tasks, while tracking progress and history for each project.

How to use

You connect your MCP client to this server using the local, stdio-based workflow. Start tasks, implement changes, add tests, run tests, document your work, and then commit, push, and record releases in a guided sequence. The server ensures you don’t skip steps and provides reminders and progress tracking so you can learn and improve your workflow while keeping project history isolated.

How to install

# Prerequisites:
# - Node.js and npm installed
# - Git installed

# Option 1: Install as a project dependency (recommended)
npm install @programinglive/dev-workflow-mcp-server

# This creates a per-project workflow state at .state/workflow-state.json

# Option 2: Install from source
# (clone, then install dependencies)
git clone https://github.com/programinglive/dev-workflow-mcp-server.git
cd dev-workflow-mcp-server
npm install

# Option 3: Run locally for development
# Use the local entry point; you can start with index.js via node
node index.js

# Option 4: Run via npx if you prefer a CLI approach
npx @programinglive/dev-workflow-mcp-server

Note: On Windows, ensure Python 3 and Visual Studio Build Tools are installed if you build native modules during npm install. The MCP server can be run directly from the local source or via npm scripts when the package is installed in a project.

## Configuration and usage notes

Database support includes SQLite (default), MySQL, and PostgreSQL. You control the database type and connection string with environment variables or a .env file.

Key environment variables you may use include DEV\_WORKFLOW\_DB\_TYPE, DEV\_WORKFLOW\_DB\_URL, DEV\_WORKFLOW\_USER\_ID, DEV\_WORKFLOW\_STATE\_FILE, and DEV\_WORKFLOW\_DB\_PATH for SQLite. You can override the workflow state location or user identity to keep histories separated per tool or per project.

## Additional sections

MCP client configuration examples exist for Windsurf and Claude Desktop. You point the client to the server entry point and provide environment values when needed to connect to a remote database or set a per-tool user identity. The server times its own startup and logs the duration to stderr, enabling you to monitor startup performance in IDEs and dashboards.

You can run multiple clients on the same project by assigning different user IDs (DEV\_WORKFLOW\_USER\_ID) to keep each tool’s workflow state isolated. The web dashboard can show user-specific history and workflow status when you point the client to the correct user.

For organization-wide releases, you can use the built-in workflow steps to record releases after committing and pushing changes. The system enforces that tests pass and documentation is present before completing a release.

## Security and best practices

Keep workflow state local to each developer by ignoring the .state directory in version control. Use a unique DEV\_WORKFLOW\_USER\_ID per tool or per developer to prevent history collisions between Antigravity, Windsurf, and other MCP clients.

When hosting on shared infrastructure, prefer stdio-based usage (local node process) rather than exposing the MCP interface on a public domain. Clients should connect locally or via SSH tunnels to ensure secure access.

## Troubleshooting and tips

If the server startup is slow or you want to optimize startup time for IDE integrations, pointing the client directly to index.js via node can reduce startup overhead compared to using npx.

If you want to test adapters or a specific database, set DEV\_WORKFLOW\_DB\_URL to the correct connection string and run the test suite to verify behavior across SQLite, MySQL, and PostgreSQL adapters.

## Examples and workflow guidance

Typical usage involves starting a new task, implementing the change, creating tests, running tests, documenting, and then committing and pushing. You can also view task history and workflow status to understand what remains to be done.

## Available tools

### start\_task

Begin a new coding task with a clear description and task type to set your intention

### mark\_bug\_fixed

Mark the feature or bug as fixed and remind yourself to create tests next

### create\_tests

Confirm that necessary tests have been created before recording results

### skip\_tests

Record a justification for skipping automated tests when necessary

### run\_tests

Record test results; only proceed if tests pass (GREEN)

### create\_documentation

Mark documentation as created or updated to accompany the change

### check\_ready\_to\_commit

Verify all steps are completed and ready to commit and push

### commit\_and\_push

Automatically run git add, commit, and push after readiness is confirmed

### perform\_release

Record release details after a successful commit/push

### complete\_task

Mark the task as complete and reset state for the next task

### drop\_task

Abandon the current task with optional context and reset state