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.

> Note: This package is published to a private NPM registry. See Installation for setup instructions.

📺 Showcase

$3

_See how the approval system works: create documents, request approval through the dashboard, provide feedback, and track revisions._

$3

_Explore the real-time dashboard: view specs, track progress, navigate documents, and monitor your development workflow._

Installation

$3

For detailed installation and setup instructions, see SETUP.md.

Prerequisites: Private NPM registry authentication is required. See SETUP.md for details.

``bash


Quick start with dashboard

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

Or add to your MCP client configuration

See SETUP.md for client-specific instructions

`

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

For complete setup instructions, see SETUP.md.

$3

1. Web Dashboard (Required for CLI users)

`bash
npx -y @uniswap/spec-workflow-mcp@latest /path/to/project --dashboard
`

2. VSCode Extension (Recommended for VSCode users)
- Install from VSCode Marketplace
- No separate dashboard needed - integrated into VSCode

See SETUP.md for detailed interface options.

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:

$3

- "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

$3

- "List my specs" - Shows all specs and their current status
- "Show me the user-auth progress" - Displays detailed progress information

$3

- "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

See SETUP.md for detailed configuration instructions for:

- Augment Code
- Claude Code CLI
- Claude Desktop
- Cline/Claude Dev
- Continue IDE
- Cursor IDE
- OpenCode

Example configuration:

`json
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"type": "stdio",
"args": [
"-y",
"@uniswap/spec-workflow-mcp@latest",
"/path/to/your/project",
"--AutoStartDashboard"
]
}
}
}
`

Available Tools

$3

- spec-workflow-guide - Complete guide for the spec-driven workflow process
- steering-guide - Guide for creating project steering documents

$3

- create-spec-doc - Create/update spec documents (requirements, design, tasks)
- spec-list - List all specs with status information
- spec-status - Get detailed status of a specific spec
- manage-tasks - Comprehensive task management for spec implementation

$3

- get-template-context - Get markdown templates for all document types
- get-steering-context - Get project steering context and guidance
- get-spec-context - Get context for a specific spec

$3

- create-steering-doc - Create project steering documents (product, tech, structure)

$3

- request-approval - Request user approval for documents
- get-approval-status - Check approval status
- delete-approval - Clean up completed approvals

User Interfaces

$3

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

$3

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

$3

`
steering-guide → create-steering-doc (product, tech, structure)
`

Creates foundational documents to guide your project development.

$3

`
spec-workflow-guide → create-spec-doc → [review] → implementation
`

Sequential process: Requirements → Design → Tasks → Implementation

$3

- Use get-spec-context for detailed implementation context
- Use manage-tasks to track task completion
- Monitor progress via the web dashboard

File Structure

`
your-project/
.spec-workflow/
steering/
product.md # Product vision and goals
tech.md # Technical decisions
structure.md # Project structure guide
specs/
{spec-name}/
requirements.md # What needs to be built
design.md # How it will be built
tasks.md # Implementation breakdown
approval/
{spec-name}/
{document-id}.json # Approval status tracking
`

Development

`bash


Install dependencies

npm install

Build the project

npm run build

Run in development mode (with auto-reload)

npm run dev

Start the production server

npm start

Clean build artifacts

npm run clean
``

Troubleshooting

For comprehensive troubleshooting information, see SETUP.md.

$3

- Dashboard issues: Check SETUP.md for port and connection problems
- Authentication: See Private NPM registry setup
- MCP client issues: Refer to client-specific setup

$3

- 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