Spec Workflow MCP

A Model Context Protocol (MCP) server for structured spec-driven development with real-time dashboard and VSCode extension.

☕ Support This Project

📺 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.

✨ Key Features

• Structured Development Workflow - Sequential spec creation (Request Spec → Requirements → Design → Test Design → Tasks)
• Real-Time Web Dashboard - Monitor specs, tasks, and progress with live updates
• VSCode Extension - Integrated sidebar dashboard for VSCode users
• Approval Workflow - Complete approval process with revisions
• Task Progress Tracking - Visual progress bars and detailed status
• Implementation Logs - Searchable logs of all task implementations with code statistics
• Multi-Language Support - Available in 11 languages

🌍 Supported Languages

🇺🇸 English • 🇯🇵 日本語 • 🇨🇳 中文 • 🇪🇸 Español • 🇧🇷 Português • 🇩🇪 Deutsch • 🇫🇷 Français • 🇷🇺 Русский • 🇮🇹 Italiano • 🇰🇷 한국어 • 🇸🇦 العربية

📖 Documentation in your language:

English | 日本語 | 中文 | Español | Português | Deutsch | Français | Русский | Italiano | 한국어 | العربية

🚀 Quick Start

Option 1: Claude Code Plugin (Recommended for Claude Code users)

Install directly as a Claude Code plugin — skills, agents, rules, hooks, and MCP server are all configured automatically:

claude plugin add --from https://github.com/arimakouyou/spec-workflow-mcp

Two plugin variants are available:

| Plugin | Description | |--------|-------------| | spec-workflow-mcp | MCP server + skills/agents/rules/hooks | | spec-workflow-mcp-with-dashboard | MCP server only (lightweight, no skills/agents/rules/hooks) |

Note: The spec-workflow-mcp-with-dashboard variant is a minimal configuration containing only the MCP server. To use the dashboard, start it separately with npx -y @arimakouyou/spec-workflow-mcp@latest --dashboard.

What the plugin includes:

• MCP server for spec-driven development workflow
• Skills: spec-request-spec, spec-requirements, spec-design, spec-test-design, spec-tasks, spec-implement, spec-review, integration-test, TDD, and more
• Agents: code-simplifier, review-worker, unit-test-engineer, parallel-worker, etc.
• Rules: project architecture, quality checks, security, design principles, etc.
• Hooks: automated task read guards

Option 2: Manual MCP Configuration

Add to your MCP configuration (see client-specific setup below):

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

Step 2: Choose your interface

Option A: Web Dashboard (Required for CLI users) Start the dashboard (runs on port 5000 by default):

npx -y @arimakouyou/spec-workflow-mcp@latest --dashboard

The dashboard will be accessible at: http://localhost:5000

Note: Only one dashboard instance is needed. All your projects will connect to the same dashboard.

Option B: VSCode Extension (Recommended for VSCode users)

Install Spec Workflow MCP Extension from the VSCode marketplace.

📝 How to Use

Simply mention spec-workflow in your conversation:

• "Create a spec for user authentication" - Creates complete spec workflow
• "List my specs" - Shows all specs and their status
• "Execute task 1.2 in spec user-auth" - Runs a specific task

See more examples →

🔧 MCP Client Setup

Configure in your Augment settings:

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

Add to your MCP configuration:

claude mcp add spec-workflow npx @arimakouyou/spec-workflow-mcp@latest -- /path/to/your/project

Important Notes:

• The -y flag bypasses npm prompts for smoother installation
• The -- separator ensures the path is passed to the spec-workflow script, not to npx
• Replace /path/to/your/project with your actual project directory path

Alternative for Windows (if the above doesn't work):

claude mcp add spec-workflow cmd.exe /c "npx @arimakouyou/spec-workflow-mcp@latest /path/to/your/project"

Add to claude_desktop_config.json:

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

Important: Run the dashboard separately with --dashboard before starting the MCP server.

Add to your MCP server configuration:

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

Add to your Continue configuration:

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

Add to your Cursor settings (settings.json):

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

Add to your opencode.json configuration file:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "spec-workflow": {
      "type": "local",
      "command": ["npx", "-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"],
      "enabled": true
    }
  }
}

Add to your ~/.codeium/windsurf/mcp_config.json configuration file:

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

Add to your ~/.codex/config.toml configuration file:

[mcp_servers.spec-workflow]
command = "npx"
args = ["-y", "@arimakouyou/spec-workflow-mcp@latest", "/path/to/your/project"]

🐳 Docker Deployment

Run the dashboard in a Docker container for isolated deployment:

# Using Docker Compose (recommended)
cd containers
docker-compose up --build

# Or using Docker CLI
docker build -f containers/Dockerfile -t spec-workflow-mcp .
docker run -p 5000:5000 -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" spec-workflow-mcp

The dashboard will be available at: http://localhost:5000

See Docker setup guide →

🔒 Security

Spec-Workflow MCP includes enterprise-grade security features suitable for corporate environments:

✅ Implemented Security Controls

| Feature | Description | |---------|-------------| | Localhost Binding | Binds to 127.0.0.1 by default, preventing network exposure | | Rate Limiting | 120 requests/minute per client with automatic cleanup | | Audit Logging | Structured JSON logs with timestamp, actor, action, and result | | Security Headers | X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, CSP, Referrer-Policy | | CORS Protection | Restricted to localhost origins by default | | Docker Hardening | Non-root user, read-only filesystem, dropped capabilities, resource limits |

⚠️ Not Yet Implemented

| Feature | Workaround | |---------|------------| | HTTPS/TLS | Use a reverse proxy (nginx, Apache) with TLS certificates | | User Authentication | Use a reverse proxy with Basic Auth or OAuth2 Proxy for SSO |

For External/Network Access

If you need to expose the dashboard beyond localhost, we recommend:

1. Keep dashboard on localhost (127.0.0.1)
2. Use nginx or Apache as a reverse proxy with:
   • TLS/HTTPS termination
   • Basic authentication or OAuth2
3. Configure firewall rules to restrict access

# Example nginx reverse proxy with auth
server {
    listen 443 ssl;
    server_name dashboard.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    auth_basic "Dashboard Access";
    auth_basic_user_file /etc/nginx/.htpasswd;
    
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

See Docker security guide →

🔒 Sandboxed Environments

For sandboxed environments (e.g., Codex CLI with sandbox_mode=workspace-write) where $HOME is read-only, use the SPEC_WORKFLOW_HOME environment variable to redirect global state files to a writable location:

SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @arimakouyou/spec-workflow-mcp@latest /workspace

See Configuration Guide →

📚 Documentation

• Configuration Guide - Command-line options, config files
• User Guide - Comprehensive usage examples
• Workflow Process - Development workflow and best practices
• Interfaces Guide - Dashboard and VSCode extension details
• Prompting Guide - Advanced prompting examples
• Tools Reference - Complete tools documentation
• Development - Contributing and development setup
• Troubleshooting - Common issues and solutions

📁 Project Structure

Working Directory (per project)

your-project/
  .spec-workflow/
    approvals/
    archive/
    specs/
    steering/
    templates/
    user-templates/
    config.example.toml

Plugin Structure (distributed via .claude-plugin/)

.claude-plugin/
  plugin.json              # Plugin manifest
  marketplace.json         # Marketplace listing
  .mcp.json                # MCP server configuration
  hooks/
    hooks.json             # Hook definitions (PostToolUse, etc.)
    tasks-read-guard.sh    # Task read guard script
  skills/                  # Spec-driven workflow skills
    spec-requirements/     # Requirements creation
    spec-design/           # Design document creation
    spec-test-design/      # Test design creation
    spec-tasks/            # Task breakdown
    spec-implement/        # Implementation workflow
    spec-review/           # Code review
    integration-test/      # Integration testing
    tdd-skills/            # TDD workflow
    tdd-skills-rust/       # Rust-specific TDD
    knowhow-capture/       # Knowledge capture
  agents/                  # Specialized sub-agents
    code-simplifier.md     # Code simplification
    review-worker.md       # Review automation
    unit-test-engineer.md  # Unit test generation
    parallel-worker.md     # Parallel task execution
    integ-test-worker.md   # Integration test worker
    integ-test-auditor.md  # Integration test auditor
  rules/                   # Project rules and conventions
    quality-checks.md      # Quality enforcement
    security.md            # Security guidelines
    design-principles.md   # Design principles
    ...
  with-dashboard/          # Dashboard variant plugin
    plugin.json
    .mcp.json

🛠️ Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

See development guide →

📄 License

GPL-3.0

⭐ Star History