The Spec Workflow MCP server provides a comprehensive AI-assisted, spec-driven development environment that streamlines structured workflows from requirements to implementation.
Core Capabilities:
Guided Workflows: Step-by-step spec creation and project steering guidance
Spec Management: Create, update, and track specifications with status monitoring and comprehensive listing
Steering Documents: Establish foundational project guidance through product vision, technical decisions, and structure documents
Task Management: Handle spec implementation tasks with status tracking (pending, in-progress, completed) and context retrieval
Template System: Access built-in templates for specs, bugs, and steering documents
Approval System: Request, track, and manage human approvals for documents and actions
Real-Time Dashboard: Monitor progress, view documents, and manage tasks via a live web interface
IDE Integration: Works seamlessly with Claude Desktop, Cursor IDE, Continue IDE, Cline/Claude Dev, and other AI development tools
The server enables you to progress systematically from requirements through design to implementation while maintaining project context and facilitating collaboration through its integrated approval and monitoring systems.
Provides support link for the project through Buy Me A Coffee donation platform
Features embedded YouTube video demonstrations showcasing the approval system and dashboard functionality
Spec Workflow MCP
A Model Context Protocol (MCP) server that provides structured spec-driven development workflow tools for AI-assisted software development, featuring a real-time web dashboard and VSCode extension for monitoring and managing your project's progress directly in your development environment.
📺 Showcase
🔄 Approval System in Action
See how the approval system works: create documents, request approval through the dashboard, provide feedback, and track revisions.
📊 Dashboard & Spec Management
Explore the real-time dashboard: view specs, track progress, navigate documents, and monitor your development workflow.
☕ Support This Project
Features
- Structured Development Workflow - Sequential spec creation (Requirements → Design → Tasks)
- Real-Time Web Dashboard - Monitor specs, tasks, and progress with live updates
- VSCode Extension - Integrated sidebar dashboard for developers working in VSCode
- Document Management - View and manage all spec documents from dashboard or extension
- Archive System - Organize completed specs to keep active projects clean
- Task Progress Tracking - Visual progress bars and detailed task status
- Approval Workflow - Complete approval process with approve, reject, and revision requests
- Steering Documents - Project vision, technical decisions, and structure guidance
- Sound Notifications - Configurable audio alerts for approvals and task completions
- Bug Workflow - Complete bug reporting and resolution tracking
- Template System - Pre-built templates for all document types
- Cross-Platform - Works on Windows, macOS, and Linux
Quick Start
- Add to your AI tool configuration (see MCP Client Setup below):With Auto-Started Dashboard (opens dashboard automatically with MCP server):With Custom Port:Note: Can be used without path to your project, but some MCP clients may not start the server from the current directory.
- Choose your interface:
Option A: Web Dashboard (REQUIRED for CLI users)
Command-Line Options:--help
- Show comprehensive usage information and examples--dashboard
- Run dashboard-only mode (no MCP server)--AutoStartDashboard
- Auto-start dashboard with MCP server--port <number>
- Specify dashboard port (1024-65535). Works with both--dashboard
and--AutoStartDashboard
Option B: VSCode Extension (Recommended for VSCode users)
Install the Spec Workflow MCP Extension from the VSCode marketplace:
- Open VSCode in your project directory containing
.spec-workflow/
- The extension automatically provides the dashboard functionality within VSCode
- Access via the Spec Workflow icon in the Activity Bar
- No separate dashboard needed - everything runs within your IDE
Extension Features:
- Integrated sidebar dashboard with real-time updates
- Archive system for organizing completed specs
- Full approval workflow with VSCode native dialogs
- Sound notifications for approvals and completions
- Editor context menu actions for approvals and comments
IMPORTANT: For CLI users, the web dashboard is mandatory. For VSCode users, the extension replaces the need for a separate web dashboard while providing the same functionality directly in your IDE.
How to Use
You can simply mention spec-workflow or whatever name you gave the MCP server in your conversation. The AI will handle the complete workflow automatically or you can use some of the example prompts below:
Creating Specs
- "Create a spec for user authentication" - Creates complete spec workflow for that feature
- "Create a spec called payment-system" - Builds full requirements → design → tasks
- "Build a spec for @prd" - Takes your existing PRD and creates the complete spec workflow from it
- "Create a spec for shopping-cart - include add to cart, quantity updates, and checkout integration" - Detailed feature spec
Getting Information
- "List my specs" - Shows all specs and their current status
- "Show me the user-auth progress" - Displays detailed progress information
Implementation
- "Execute task 1.2 in spec user-auth" - Runs a specific task from your spec
- Copy prompts from dashboard - Use the "Copy Prompt" button in the task list on your dashboard
The agent automatically handles approval workflows, task management, and guides you through each phase.
MCP Client Setup
Configure in your Augment settings:
Add to your MCP configuration:
Note: You may need to wrap the command in cmd.exe /c "npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project" for Windows.
Add to claude_desktop_config.json
:
Or with auto-started dashboard:
Add to your MCP server configuration:
Add to your Continue configuration:
Add to your Cursor settings (settings.json
):
Add to your opencode.json
configuration file (either global at ~/.config/opencode/opencode.json
or project-specific):
Note: Replace
/path/to/your/project
with the actual path to your project directory where you want the spec workflow to operate.
Available Tools
Workflow Guides
spec-workflow-guide
- Complete guide for the spec-driven workflow processsteering-guide
- Guide for creating project steering documents
Spec Management
create-spec-doc
- Create/update spec documents (requirements, design, tasks)spec-list
- List all specs with status informationspec-status
- Get detailed status of a specific specmanage-tasks
- Comprehensive task management for spec implementation
Context & Templates
get-template-context
- Get markdown templates for all document typesget-steering-context
- Get project steering context and guidanceget-spec-context
- Get context for a specific spec
Steering Documents
create-steering-doc
- Create project steering documents (product, tech, structure)
Approval System
request-approval
- Request user approval for documentsget-approval-status
- Check approval statusdelete-approval
- Clean up completed approvals
User Interfaces
Web Dashboard
The web dashboard is a separate service for CLI users. Each project gets its own dedicated dashboard running on an ephemeral port. The dashboard provides:
- Live Project Overview - Real-time updates of specs and progress
- Document Viewer - Read requirements, design, and tasks documents
- Task Progress Tracking - Visual progress bars and task status
- Steering Documents - Quick access to project guidance
- Dark Mode - Automatically enabled for better readability
Dashboard Features
- Spec Cards - Overview of each spec with status indicators
- Document Navigation - Switch between requirements, design, and tasks
- Task Management - View task progress and copy implementation prompts
- Real-Time Updates - WebSocket connection for live project status
VSCode Extension
The VSCode extension provides all dashboard functionality directly within your IDE:
- Sidebar Integration - Access everything from the Activity Bar
- Archive Management - Switch between active and archived specs
- Native Dialogs - VSCode confirmation dialogs for all actions
- Editor Integration - Context menu actions for approvals and comments
- Sound Notifications - Configurable audio alerts
- No External Dependencies - Works entirely within VSCode
Extension Advantages for VSCode Users
- Single Environment - No need to switch between browser and IDE
- Native Experience - Uses VSCode's native UI components
- Better Integration - Context menu actions and editor integration
- Simplified Setup - No separate dashboard service required
Workflow Process
1. Project Setup (Recommended)
Creates foundational documents to guide your project development.
2. Feature Development
Sequential process: Requirements → Design → Tasks → Implementation
3. Implementation Support
- Use
get-spec-context
for detailed implementation context - Use
manage-tasks
to track task completion - Monitor progress via the web dashboard
File Structure
Development
Troubleshooting
Common Issues
- Dashboard not starting
- Ensure you're using the
--dashboard
flag when starting the dashboard service - The dashboard must be started separately from the MCP server
- Check console output for the dashboard URL and any error messages
- If using
--port
, ensure the port number is valid (1024-65535) and not in use by another application
- Ensure you're using the
- Approvals not working
- Verify the dashboard is running alongside the MCP server
- The dashboard is required for document approvals and task tracking
- Check that both services are pointing to the same project directory
- MCP server not connecting
- Verify the file paths in your configuration are correct
- Ensure the project has been built with
npm run build
- Check that Node.js is available in your system PATH
- Port conflicts
- If you get a "port already in use" error, try a different port with
--port <different-number>
- Use
netstat -an | find ":3000"
(Windows) orlsof -i :3000
(macOS/Linux) to check what's using a port - Omit the
--port
parameter to automatically use an available ephemeral port
- If you get a "port already in use" error, try a different port with
- Dashboard not updating
- The dashboard uses WebSockets for real-time updates
- Refresh the browser if connection is lost
- Check console for any JavaScript errors
Getting Help
- Check the Issues page for known problems
- Create a new issue using the provided templates
- Use the workflow guides within the tools for step-by-step instructions
License
GPL-3.0
Star History
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
Provides structured spec-driven development workflow tools for AI-assisted software development with sequential spec creation (Requirements → Design → Tasks). Features a real-time web dashboard for monitoring project progress and managing development workflows.
Related MCP Servers
- AsecurityAlicenseAqualityAn AI-powered automation tool development platform that provides modular architecture with tool hot-reloading, enterprise-grade integration capabilities, and real-time updates with zero-downtime deployment.Last updated -155MIT License
- AsecurityFlicenseAqualityAI-driven tool that helps developers create beautiful UI components instantly through natural language descriptions, integrating with popular IDEs like Cursor, Windsurf, and VSCode.Last updated -32
- AsecurityAlicenseAqualityFacilitates spec-driven development workflows by providing structured prompts for generating requirements in EARS format, design documents, and implementation code following a systematic approach.Last updated -72289MIT License