Spec Workflow

The Spec Workflow MCP Server brings structure to AI-assisted software development. It creates a clear path from requirements to implementation through sequential specification stages.

The MCP server works alongside a real-time web dashboard that gives you visibility into your development process. You get a systematic approach to building features with proper documentation at each stage.

Features

• 🔄 Sequential spec creation (Requirements → Design → Tasks)
• 📊 Real-time dashboard with live project updates
• 📁 Centralized document management for all spec types
• 📈 Visual task progress tracking with status indicators
• 🧭 Steering documents for project vision and technical decisions
• 🐞 Complete bug reporting and resolution workflow
• 📝 Pre-built templates for consistent documentation
• 🌐 Works across Windows, macOS, and Linux environments

Use Cases

• Solo developers who struggle with keeping AI coding assistants focused often find themselves creating scattered features without proper documentation. Spec Workflow MCP provides the structure they need to maintain clear development paths and avoid feature creep.
• Small development teams collaborating on features frequently experience misalignment between what’s designed and what gets implemented. The approval system and shared dashboard in this tool creates visibility so everyone stays on the same page throughout the development process.
• Projects requiring thorough documentation for compliance or knowledge sharing benefit from the automatic generation of requirements, design, and task documents. The system ensures each feature has proper documentation without extra manual effort.
• Teams transitioning to AI-assisted development often lack guardrails for their AI tools. This MCP server creates boundaries that guide the AI through a structured process rather than jumping straight to implementation code.

How to Use It

1. Add the server to your AI assistant.

{
  "mcpServers": {
    "spec-workflow": {
      "command": "npx",
      "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
    }
  }
}

2. Start the web dashboard.

npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project --dashboard

You can specify a custom port if needed:

npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project --dashboard --port 3000

3. Interact with the system through natural language:

• “Create a spec for user authentication” generates complete requirements, design, and tasks
• “List my specs” shows all specifications with the current status
• “Show me the user-auth progress” displays detailed implementation status
• “Execute task 1.2 in spec user-auth” runs a specific implementation task

4. The dashboard provides a visual interface where you can view documents, track progress, and copy implementation prompts directly. Each project maintains its own file structure under .spec-workflow with steering documents and spec directories containing requirements, design, and tasks.

FAQs

Q: Why do I need to run the dashboard separately from the MCP server?
A: The dashboard handles the approval system and real-time updates that the MCP server alone can’t manage. It’s designed as a separate service to maintain clear separation between AI interaction (MCP server) and human workflow management (dashboard).

Q: What happens if I don’t start the dashboard?
A: Without the dashboard, the approval system won’t work, task progress tracking becomes unavailable, and spec status updates won’t function. The workflow essentially breaks at the review stage since approvals require human interaction through the dashboard interface.

Q: How do I resolve port conflicts when starting the dashboard?
A: If you encounter “port already in use” errors, try a different port number with the --port flag. Use netstat -an | find ":3000" on Windows or lsof -i :3000 on macOS/Linux to identify what’s using a specific port. Omit the port parameter to let the system select an available ephemeral port automatically.

Q: Can I use this without specifying a project path?
A: You can omit the path, but some MCP clients may not start the server from your current directory. Specifying the absolute path ensures the server operates in the correct project context, especially important when managing multiple projects.