Related Pages

Related topics: System Architecture

Getting Started

A comprehensive guide to setting up and running the Spec-Workflow MCP server for AI-assisted specification-based development workflows.

Overview

Spec-Workflow MCP is a Model Context Protocol (MCP) server that enables AI coding assistants to work with structured specifications. It provides a systematic approach to development by maintaining specs, tracking tasks, managing approvals, and logging implementation details.

Key Capabilities:

• Specification management with version control and approval workflows
• Task tracking and progress monitoring
• Implementation logging for code artifacts
• Integration with multiple AI coding tools (Claude Desktop, Cursor, VSCode, etc.)
• Web dashboard and VSCode extension for visualization

Prerequisites

Before installation, ensure your environment meets the following requirements:

Sources: README.md

Installation Methods

Method 1: Quick Setup via npx

The simplest way to get started is using npx, which downloads and executes the package without global installation:

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

Command Arguments:

Sources: README.md:1-20

Method 2: Global Installation

For persistent installation across sessions:

npm install -g @pimzino/spec-workflow-mcp

Then execute:

spec-workflow-mcp /path/to/your/project

Method 3: Docker Deployment

For isolated, containerized 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 becomes available at: http://localhost:5000

Sources: README.md:85-95

MCP Server Configuration

After installation, configure the MCP server for your preferred AI coding tool.

Claude Desktop

Add to claude_desktop_config.json:

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

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

Sources: README.md:55-70

Claude Code CLI

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

Windows Alternative:

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

Sources: README.md:35-50

Cursor IDE

Add to your Cursor settings (settings.json):

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

VSCode (Cline/Claude Dev)

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

Continue IDE Extension

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

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

Codex

Add to ~/.codex/config.toml:

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

OpenCode

Add to opencode.json:

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

Sources: README.md:100-145

Choosing Your Interface

Spec-Workflow MCP offers two interfaces for interacting with specifications. Choose based on your workflow.

Option A: Web Dashboard

Recommended for: CLI users, team collaboration, remote access

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

Access the dashboard at: http://localhost:5000

Key Features:

• Real-time task progress visualization
• Specification document management
• Approval workflow interface
• Implementation artifact tracking
• Project statistics dashboard

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

Sources: README.ko.md:20-35

Option B: VSCode Extension

Recommended for: VSCode users, integrated workflow, inline annotations

The VSCode extension provides:

• Inline spec annotations in code
• Task status indicators
• Quick actions for spec management
• Integrated approval interface

Sources: README.ko.md:30-35

Project Structure

After initialization, Spec-Workflow creates a .spec-workflow directory with the following structure:

your-project/
├── .spec-workflow/
│   ├── approvals/          # Pending approval documents
│   ├── archive/           # Archived specifications
│   ├── specs/             # Active specifications
│   ├── steering/          # Steering/prompt documents
│   ├── templates/         # Built-in templates
│   ├── user-templates/    # Custom user templates
│   └── config.example.toml # Configuration template

Sources: README.md:20-35

Development Setup

For contributing to the project or running from source:

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Available npm Scripts

Sources: README.fr.md:25-40

Architecture Overview

graph TD
    A[AI Coding Assistant] -->|MCP Protocol| B[Spec-Workflow MCP Server]
    B --> C[.spec-workflow Directory]
    C --> D[Specs]
    C --> E[Tasks]
    C --> F[Approvals]
    C --> G[Implementation Logs]
    
    H[Web Dashboard] <-->|HTTP API| B
    I[VSCode Extension] <-->|VSCode API| B
    
    J[Project Files] -->|Read/Write| B
    
    style B fill:#e1f5fe
    style H fill:#fff3e0
    style I fill:#e8f5e9

Security Features

Spec-Workflow MCP includes enterprise-grade security controls:

Sources: README.md:100-115

Quick Start Workflow

graph LR
    A[Install MCP Server] --> B[Configure AI Tool]
    B --> C[Initialize Project]
    C --> D[Create Specification]
    D --> E[AI Generates Code]
    E --> F[Review & Approve]
    F --> G[Implementation Logged]
    
    style A fill:#ffcdd2
    style D fill:#fff9c4
    style F fill:#c8e6c9

Troubleshooting

Common Issues

Issue: Dashboard not accessible

• Ensure port 5000 is available
• Check if another instance is running
• Verify firewall settings

Issue: MCP server connection failed

• Verify the project path is absolute, not relative
• Check that Node.js version meets requirements
• Ensure the npx cache is up to date: npx -y

Issue: Permissions error with .spec-workflow directory

• Ensure the directory has appropriate read/write permissions
• On Linux/Mac: chmod -R 755 .spec-workflow

Sources: docs/TROUBLESHOOTING.md

Next Steps

After completing the getting started guide:

1. Create your first specification using the spec template
2. Explore the dashboard at http://localhost:5000
3. Review documentation:

• Development Guide - Contributing and development setup
• Tools Reference - Complete tools documentation
• Prompting Guide - Advanced prompting examples
• Interfaces Guide - Dashboard and VSCode extension details

License

Spec-Workflow MCP is released under the GPL-3.0 license.

Sources: README.md:45-50

Related Pages

Related topics: Getting Started, System Architecture

Project Structure

Overview

The spec-workflow-mcp project is a Model Context Protocol (MCP) server that provides AI-powered specification-driven development workflow management. The project is organized into multiple subsystems that work together to enable seamless specification management, task tracking, and approval workflows for development projects.

High-Level Architecture

The project follows a modular architecture with three main interface options:

graph TD
    A[AI Tools / LLM Clients] -->|MCP Protocol| B[MCP Server]
    B --> C[Core Engine]
    B --> D[Dashboard Backend]
    B --> E[Dashboard Frontend]
    B --> F[VSCode Extension]
    
    C -->|File System| G[.spec-workflow/]
    D --> G
    G --> H[specs/]
    G --> I[approvals/]
    G --> J[archive/]
    G --> K[steering/]
    G --> L[templates/]

Directory Structure

The .spec-workflow directory is created within your project and contains all specification-related data:

your-project/
  .spec-workflow/
    approvals/          # Pending approval items
    archive/            # Archived specifications
    specs/              # Active specification documents
    steering/           # Steering/prompting files
    templates/          # Default templates
    user-templates/     # User-defined templates
    config.example.toml # Configuration file template

Core Components

MCP Server (`src/`)

The MCP server is the central component that exposes tools and resources to AI clients. It handles:

• Specification document parsing and management
• Task status tracking
• Approval workflow execution
• Implementation logging

Dashboard Backend

The backend provides REST API endpoints for the web dashboard:

Sources: src/dashboard_frontend/src/modules/api/api.tsx:1-20

Dashboard Frontend

The web dashboard is a React-based interface located at src/dashboard_frontend/. It provides pages for:

• TasksPage - View and manage tasks within specifications
• SettingsPage - Configure automated cleanup jobs
• JobExecutionHistory - View historical job executions

#### Frontend API Integration

The frontend uses typed API calls to communicate with the backend:

const api = {
  getSpecTasksProgress: (name: string) => getJson(`${prefix}/specs/${encodeURIComponent(name)}/tasks/progress`),
  updateTaskStatus: (specName: string, taskId: string, status: 'pending' | 'in-progress' | 'completed' | 'blocked', reason?: string) =>
    putJson(`${prefix}/specs/${encodeURIComponent(specName)}/tasks/${encodeURIComponent(taskId)}/status`, { status, ...(reason && { reason }) }),
  approvalsAction: (id, action, body) => postJson(`${prefix}/approvals/${encodeURIComponent(id)}/${action}`, body),
};

Sources: src/dashboard_frontend/src/modules/api/api.tsx:5-8

VSCode Extension

The VSCode extension (vscode-extension/) provides an integrated experience within the VSCode editor. It includes:

• Webview-based UI - React components rendered in VSCode
• App Component - Main application entry point
• LogEntryCard Component - Displays implementation log entries

#### Webview Structure

graph LR
    A[index.html] --> B[main.tsx]
    B --> C[App.tsx]
    C --> D[TasksPage]
    C --> E[SettingsPage]
    C --> F[LogEntryCard]

The extension uses a webview to render the dashboard UI, with localization support through i18n modules.

Sources: vscode-extension/src/webview/index.html:1-15

Implementation Log System

The implementation log tracks code artifacts and changes made during development:

graph TD
    A[Implementation Entry] --> B[Statistics]
    A --> C[Files Modified]
    A --> D[Files Created]
    A --> E[Artifacts]
    
    E --> E1[API Endpoints]
    E --> E2[Components]
    E --> E3[Functions]
    E --> E4[Classes]
    E --> E5[Integrations]

Artifact Types

Sources: vscode-extension/src/webview/components/LogEntryCard.tsx:30-50

Development Workflow Structure

graph LR
    A[Create Spec] --> B[Generate Tasks]
    B --> C[Implement Code]
    C --> D[Log Artifacts]
    D --> E[Request Approval]
    E --> F[Approve/Request Changes]
    F -->|Approve| G[Archive Spec]
    F -->|Changes| C

Template System

Templates define the structure of specification documents. The project includes:

• structure-template.md - Defines code organization patterns
• user-templates/ - Custom user-defined templates

#### Template Sections

The structure template includes guidelines for:

1. File Organization - How to structure code files
2. Function/Method Organization - Patterns for function design
3. Code Organization Principles - Single responsibility, modularity, testability
4. Module Boundaries - Defining inter-module interactions
5. Code Size Guidelines - Limits for file and function sizes

Sources: src/markdown/templates/structure-template.md:1-60

Configuration

The project uses TOML configuration files. The example configuration template is located at:

.spec-workflow/config.example.toml

Configuration options include:

• Dashboard connection settings
• Cleanup job schedules
• Template preferences
• Approval workflow settings

Project Statistics Display

The dashboard displays project statistics including:

These statistics are aggregated from the .spec-workflow directory and displayed in both the web dashboard and VSCode extension.

Sources: vscode-extension/src/webview/App.tsx:10-40

Summary

The spec-workflow-mcp project is organized into distinct layers:

1. Core Layer - MCP server handles AI tool interactions
2. Backend Layer - REST API for dashboard operations
3. Frontend Layer - Web dashboard and VSCode extension
4. Data Layer - File-based storage in .spec-workflow/

This separation of concerns allows the project to serve multiple interfaces while maintaining a single source of truth for specification data.

Related Pages

Related topics: MCP Server Implementation, Web Dashboard, Spec Management

System Architecture

Overview

The Spec-Workflow MCP (Model Context Protocol) system is designed as a bridge between AI coding assistants and structured software development workflows. It provides a specification-driven approach to managing software development tasks, approvals, and implementation tracking.

The architecture follows a multi-tier design with distinct components for MCP protocol handling, project management, dashboard services, and frontend interfaces.

High-Level Architecture

graph TD
    subgraph "Client Layer"
        VSCode[VSCode Extension]
        CLI[Claude CLI]
        Desktop[Claude Desktop]
    end

    subgraph "MCP Server Layer"
        MCPServer[MCP Server]
        Tools[Tool Handlers]
    end

    subgraph "Dashboard Layer"
        Dashboard[Web Dashboard]
        MultiServer[Multi-Server Manager]
        ProjectManager[Project Manager]
    end

    subgraph "Core Services"
        Registry[Project Registry]
        GlobalDir[Global Directory]
        ApprovalEngine[Approval Engine]
    end

    subgraph "Storage Layer"
        SpecWorkflowDir[.spec-workflow/]
        Config[Config Files]
        Specs[Specs Data]
        Approvals[Approvals]
    end

    VSCode <--> MCPServer
    CLI <--> MCPServer
    Desktop <--> MCPServer
    
    MCPServer <--> Dashboard
    Dashboard <--> Registry
    Dashboard <--> ProjectManager
    ProjectManager <--> GlobalDir
    Registry <--> SpecWorkflowDir
    ApprovalEngine <--> SpecWorkflowDir

Core Components

MCP Server (`src/server.ts`)

The MCP server acts as the central protocol handler that bridges AI tools with the spec workflow system.

Sources: README.md (MCP configuration documentation)

Project Registry (`src/core/project-registry.ts`)

The project registry maintains a centralized record of all projects connected to the spec workflow system.

Sources: README.md (project structure documentation)

Dashboard Multi-Server Manager (`src/dashboard/multi-server.ts`)

Manages multiple MCP server instances and provides centralized coordination.

graph LR
    A[Dashboard UI] --> B[Multi-Server Manager]
    B --> C[Server 1]
    B --> D[Server 2]
    B --> N[Server N]
    
    C --> E[Project 1]
    D --> F[Project 2]
    N --> G[Project N]

Project Manager (`src/dashboard/project-manager.ts`)

Handles project lifecycle operations including initialization, status tracking, and data synchronization.

Global Directory (`src/core/global-dir.ts`)

Provides cross-project data management and shared resources.

The global directory stores shared configuration and data at:

~/.spec-workflow/

Sources: README.md (project structure documentation)

Directory Structure

Each project managed by spec-workflow follows a standardized directory layout:

your-project/
  .spec-workflow/
    approvals/          # Approval requests and responses
    archive/            # Archived specifications
    specs/              # Active specifications
    steering/           # Steering configurations
    templates/          # Specification templates
    user-templates/      # Custom user templates
    config.example.toml # Example configuration

Sources: README.md (project structure documentation)

Dashboard Architecture

The dashboard provides a web-based interface for managing specs and tasks across connected projects.

Frontend Stack

Sources: vscode-extension/src/webview/App.tsx, src/dashboard_frontend/src/modules/api/api.tsx

Backend Services

The dashboard binds to 127.0.0.1 by default to prevent network exposure.

Sources: README.md (security documentation)

API Architecture

graph TD
    subgraph "API Client (Frontend)"
        TasksPage[TasksPage]
        SettingsPage[SettingsPage]
    end

    subgraph "API Endpoints"
        GET_SPECS[GET /specs/:name/all]
        UPDATE_TASK[PUT /specs/:name/tasks/:id/status]
        APPROVALS[POST /approvals/:id/:action]
    end

    TasksPage --> GET_SPECS
    SettingsPage --> UPDATE_TASK
    TasksPage --> APPROVALS

Key API Endpoints

Sources: src/dashboard_frontend/src/modules/api/api.tsx

Security Architecture

The system implements enterprise-grade security controls suitable for corporate environments.

Sources: README.md (security documentation)

Deployment Options

Docker Deployment

graph LR
    A[Docker Compose] --> B[Dashboard Container]
    B --> C[spec-workflow data]
    D[Projects] --> C

# Using Docker Compose
cd containers
docker-compose up --build

# Dashboard available at http://localhost:5000

MCP Client Integration

Sources: README.md (MCP integration documentation)

Implementation Log System

The implementation log tracks all changes made during development.

graph TD
    A[Implementation Entry] --> B[Files Modified]
    A --> C[Files Created]
    A --> D[Artifacts]
    D --> E[API Endpoints]
    D --> F[Components]
    D --> G[Functions]
    D --> H[Classes]
    D --> I[Integrations]

Log Entry Structure

Sources: src/dashboard/implementation-log-manager.ts, src/core/implementation-log-migrator.ts

Task Management Flow

graph TD
    A[Create Task] --> B[pending]
    B --> C{inProgress?}
    C -->|Yes| D[in-progress]
    C -->|No| E[blocked]
    D --> F{Completed?}
    F -->|Yes| G[completed]
    F -->|No| D
    E --> H{Blocked Reason Required}
    H --> I[Save Blocked Reason]
    I --> B

Task States

Sources: src/dashboard_frontend/src/modules/pages/TasksPage.tsx

Configuration Schema

MCP Server Configuration

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

Project Configuration (`config.toml`)

Summary

The spec-workflow-mcp architecture provides:

1. Protocol Bridge: Seamless MCP integration with AI coding tools
2. Specification-Driven Workflow: Structured approach to software development
3. Multi-Project Management: Centralized dashboard for all projects
4. Enterprise Security: Production-ready security controls
5. Flexible Deployment: Docker and native deployment options

This architecture enables teams to maintain consistent development practices while leveraging AI assistance throughout the development lifecycle.

Related Pages

Related topics: Approval Workflow System, Spec Management, Steering Documents

MCP Server Implementation

Overview

The MCP Server Implementation provides a Model Context Protocol (MCP) server that integrates the spec-workflow system into AI coding assistants. It exposes structured tools that AI agents can invoke to manage specification-driven development workflows, including approvals, spec tracking, and implementation logging.

Purpose:

• Bridge AI coding assistants with the spec-workflow specification management system
• Enable AI agents to create, review, and update specification documents
• Provide human-in-the-loop approval workflows for AI-generated code
• Track implementation progress across multiple specification phases

Scope: The server operates as a local MCP server that connects to a project directory, providing tools for steering documentation, spec creation, approval management, and implementation logging. It works alongside a dashboard server for human review and approval.

Architecture

System Components

The MCP server architecture consists of three interconnected layers:

graph TD
    A["AI Coding Assistant<br/>(Cline, Cursor, VS Code)"] --> B["MCP Server<br/>(spec-workflow-mcp)"]
    B --> C["Dashboard Server<br/>(Port 5000)"]
    B --> D["Project Directory<br/>(.spec-workflow)"]
    C --> D
    
    B --> E["Tools"]
    E --> E1["approvals"]
    E --> E2["spec-status"]
    E --> E3["spec-workflow-guide"]
    E --> E4["steering-guide"]
    E --> E5["log-implementation"]
    E --> E6["prompt-generation"]

MCP Server Entry Point

The server is initialized in src/index.ts and configured via command-line arguments. The primary execution path:

1. Parse command-line arguments for project path and mode
2. Initialize the MCP server with stdio transport
3. Register all available tools and resources
4. Begin message processing loop

Configuration Example:

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

Sources: README.md:1

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

Available Tools

Tool Overview

Approvals Tool

The approvals tool manages the human-in-the-loop approval workflow. All AI-generated specs require explicit human approval before proceeding.

Actions:

Workflow Integration:

graph LR
    A[AI Creates Spec] --> B[Request Approval]
    B --> C{Human Reviews}
    C -->|Approved| D[Delete Approval]
    C -->|Needs Revision| E[AI Updates Spec]
    E --> B
    D --> F[Proceed to Implementation]

Approval Status States:

Sources: src/tools/approvals.ts

Spec Status Tool

The spec-status tool tracks the lifecycle state of individual specifications.

Supported States:

Operations:

• Query current status of any spec
• Update status after phase transitions
• Retrieve history of status changes

Sources: src/tools/spec-status.ts

Spec Workflow Guide

Provides structured guidance for the specification creation workflow. The guide defines a 4-phase process:

graph TD
    P1[Phase 1: Design] --> P2[Phase 2: Spec]
    P2 --> P3[Phase 3: Tasks]
    P3 --> P4[Phase 4: Implementation]
    
    P1 --> P1A[product.md]
    P2 --> P2A[design.md]
    P3 --> P3A[tasks.md]
    P4 --> P4A[Code Files]

Phase Details:

Sources: src/tools/spec-workflow-guide.ts

Steering Guide

Defines the steering documentation workflow for project-wide guidance:

Steering Phases:

Template Resolution:

graph TD
    A[Need Template] --> B{user-templates exist?}
    B -->|Yes| C[Use user-templates]
    B -->|No| D[Use templates]
    C --> E[Load Template]
    D --> E

Templates are resolved first from .spec-workflow/user-templates/ directory, falling back to .spec-workflow/templates/ if no custom templates exist.

Sources: src/tools/steering-guide.ts

Log Implementation Tool

Records and tracks implementation artifacts generated during the coding phase. Enables the AI to maintain a structured record of what was built.

Artifact Types:

Implementation Log Entry Structure:

interface ImplementationLogEntry {
  timestamp: string;
  specName: string;
  filesCreated: string[];
  filesModified: string[];
  artifacts: {
    apiEndpoints?: ApiEndpoint[];
    components?: Component[];
    functions?: Function[];
    classes?: Class[];
    integrations?: Integration[];
  };
  statistics: {
    linesAdded: number;
    linesRemoved: number;
  };
}

Sources: src/dashboard/implementation-log-manager.ts

Workflow Integration

Initialization Sequence

sequenceDiagram
    participant User
    participant Dashboard
    participant MCP
    participant AI
    
    User->>Dashboard: Start dashboard (port 5000)
    User->>MCP: Start MCP server with project path
    User->>AI: Configure AI client with MCP
    AI->>MCP: List available tools
    MCP-->>AI: Return tool definitions
    AI->>MCP: Call steering-guide
    MCP-->>AI: Return workflow instructions
    AI->>MCP: Create spec via prompts
    AI->>MCP: Request approval
    MCP->>Dashboard: Store approval request
    User->>Dashboard: Review and approve
    Dashboard->>MCP: Update approval status
    MCP-->>AI: Approval granted

Client Configuration

The MCP server supports multiple AI coding assistant clients:

Sources: README.md:1

Dashboard Server Integration

The dashboard server runs independently on port 5000 and provides:

• Approval Management UI: Review pending approvals with file diffs
• Spec Overview: View all specs and their current states
• Statistics Dashboard: Track progress across specs and tasks
• Implementation Logs: Browse logged implementation artifacts

Single Instance Model:

Note: Only one dashboard instance is required. All projects connect to the same dashboard server.

# Start dashboard
npx -y @pimzino/spec-workflow-mcp@latest --dashboard

# Dashboard accessible at http://localhost:5000

Sources: README.md:1

Project Directory Structure

The MCP server expects and manages the following directory structure within each project:

your-project/
  .spec-workflow/
    approvals/          # Active approval requests
    archive/            # Completed/archived specs
    specs/              # Individual spec directories
      {spec-name}/
        design.md
        tasks.md
    steering/           # Project-level steering docs
      product.md
      tech.md
      structure.md
    templates/          # Default templates
    user-templates/     # Project-specific custom templates
    config.example.toml

Prompt Generation

The prompt-generation resource provides AI-usable prompts for each workflow phase, enabling consistent spec creation behavior.

Prompt Categories:

Sources: src/prompts/index.ts

Error Handling

The MCP server implements several error handling strategies:

Critical Workflow Constraint:

If approval deletion fails after acceptance, the workflow must stop and return to polling status. The implementation cannot proceed until the approval cleanup succeeds.

Sources: src/tools/steering-guide.ts

Development

Building the Server

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

Source Organization

Summary

The MCP Server Implementation provides a comprehensive bridge between AI coding assistants and the spec-workflow specification management system. By exposing structured tools for approvals, spec tracking, implementation logging, and workflow guidance, it enables AI agents to participate in human-controlled development workflows while maintaining full transparency and auditability of all generated artifacts.

Related Pages

Related topics: Approval Workflow System, Steering Documents, MCP Server Implementation

Spec Management

Overview

Spec Management is the core system within spec-workflow-mcp that enables structured project specification, task planning, and implementation tracking. This system provides a standardized approach to converting project ideas into actionable, trackable implementation tasks through a Markdown-based specification document format.

The spec management system serves as the foundation for the entire workflow, bridging the gap between high-level project requirements and concrete implementation tasks. It ensures that every feature or change is properly documented, validated, and tracked throughout its lifecycle.

Architecture Overview

graph TD
    A[User] --> B[Spec Creation]
    B --> C[Spec Templates]
    C --> D[Requirements Template]
    C --> E[Design Template]
    C --> F[Tasks Template]
    D --> G[Core Parser]
    E --> G
    F --> H[Task Parser]
    G --> I[Spec Document]
    H --> J[Task Validation]
    J --> K[Task Status Tracking]
    I --> L[Dashboard / VSCode Extension]
    K --> L

Spec Document Structure

Directory Layout

Specs are stored within each project's .spec-workflow directory following a standardized structure:

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

Sources: README.fr.md

Specification Components

Each specification document is composed of multiple template sections that capture different aspects of the project requirements.

Requirements Template

The requirements template establishes the foundation of a specification by capturing the essential "what" of the feature or change.

Key Sections

The requirements template includes structured fields for:

• Title and Description: Clear identification of the feature
• Purpose: The motivation behind the feature
• Leverage: Existing code, patterns, or systems to build upon
• Requirements: Specific constraints and conditions that must be met
• Acceptance Criteria: Measurable outcomes that define success

Sources: src/markdown/templates/requirements-template.md

Purpose Field

The purposes array captures multiple reasons for a given feature:

// Task structure showing purposes field
interface Task {
  purposes: string[];
  requirements: string[];
  leverage?: string;
  prompt?: string;
}

Sources: src/dashboard_frontend/src/modules/pages/TasksPage.tsx

Design Template

The design template documents the "how" of implementation, capturing architectural decisions and technical approach.

Structure

The design template typically includes:

• Code Organization: Guidelines for file and module structure
• Module Boundaries: Defining how different parts interact
• Function/Method Organization: Patterns for organizing code logic
• Code Size Guidelines: Limits on file and function complexity

Sources: src/markdown/templates/design-template.md

Design Principles

The template enforces several key principles:

Tasks Template

The tasks template breaks down the implementation into granular, actionable items that can be tracked and completed independently.

Task Properties

Each task within the tasks template supports the following properties:

Sources: src/dashboard_frontend/src/modules/pages/TasksPage.tsx

Spec Parsing System

Core Parser

The core parser (src/core/parser.ts) is responsible for reading and interpreting spec documents, extracting structured data from Markdown content.

graph LR
    A[Markdown Spec File] --> B[Core Parser]
    B --> C[Extracted Metadata]
    B --> D[Tasks Array]
    B --> E[Requirements]
    B --> F[Design Decisions]

Sources: src/core/parser.ts

Task Parser

The task parser (src/core/task-parser.ts) specializes in extracting and organizing task information from the tasks section of spec documents.

Capabilities:

• Extract task ID and status
• Parse purpose and requirements arrays
• Handle nested task hierarchies
• Support both ordered and unordered task formats

Sources: src/core/task-parser.ts

Task Validator

The task validator (src/core/task-validator.ts) ensures that parsed tasks meet the required structural and content requirements.

Validation Checks:

• Required fields presence
• Status value validity
• Purpose array non-empty
• Requirement completeness

Sources: src/core/task-validator.ts

Task Status Workflow

State Machine

stateDiagram-v2
    [*] --> Pending
    Pending --> InProgress : Start Work
    InProgress --> Completed : Finish Task
    InProgress --> Blocked : Encounter Blocker
    Blocked --> InProgress : Resolve Blocker
    Completed --> [*]
    Blocked --> [*] : Cancel Task

Status Transitions API

updateTaskStatus: (
  specName: string, 
  taskId: string, 
  status: 'pending' | 'in-progress' | 'completed' | 'blocked', 
  reason?: string
) => void

Sources: src/dashboard_frontend/src/modules/api/api.tsx

Implementation Tracking

Implementation Log Entry Structure

As tasks are completed, the system tracks implementation artifacts through the ImplementationLogManager:

interface ImplementationLogEntry {
  id: string;
  timestamp: Date;
  filesModified: string[];
  filesCreated: string[];
  statistics: {
    linesAdded: number;
    linesRemoved: number;
  };
  artifacts?: {
    apiEndpoints?: ApiEndpoint[];
    components?: Component[];
    functions?: Function[];
    classes?: Class[];
    integrations?: Integration[];
  };
}

Sources: src/dashboard/implementation-log-manager.ts

Artifact Types

Sources: src/core/implementation-log-migrator.ts

Dashboard Integration

Project Statistics

The dashboard provides an overview of spec and task progress:

Sources: vscode-extension/src/webview/App.tsx

Spec Operations

The dashboard supports the following operations:

Sources: src/dashboard_frontend/src/modules/api/api.tsx

Task Progress Calculation

const progress = spec.taskProgress?.total
  ? Math.round((spec.taskProgress.completed / spec.taskProgress.total) * 100)
  : 0;

Sources: src/dashboard_frontend/src/modules/pages/SpecsPage.tsx

Steering Documents

Steering documents provide project-level guidance and are managed separately from individual specs:

Sources: src/dashboard_frontend/src/modules/pages/SteeringPage.tsx

AI Integration

Spec Creation Prompts

The system uses structured prompts for AI-assisted spec creation:

interface CreateSpecInput {
  featureName: string;
  description: string;
  leverage?: string;
  requirements?: string[];
}

Sources: src/prompts/create-spec.ts

Task Implementation Prompts

When implementing tasks, the AI receives contextual information including:

• Task purposes and requirements
• Leverage information (existing code to build upon)
• Design guidelines from the spec
• Implementation log context

interface ImplementTaskInput {
  task: Task;
  spec: Spec;
  leverage: string;
  context: ImplementationLogEntry[];
}

Sources: src/prompts/implement-task.ts

Execution History

The system tracks job executions for auditing and debugging purposes:

// Duration formatting
{(execution.duration / 1000).toFixed(2)}s

Sources: src/dashboard_frontend/src/modules/pages/JobExecutionHistory.tsx

Execution Statistics

Best Practices

Writing Effective Specs

1. Clear Purpose Statements: Each task should have at least one well-defined purpose
2. Leverage Existing Code: Always reference existing patterns or utilities to build upon
3. Measurable Requirements: Requirements should be verifiable and testable
4. Appropriate Granularity: Tasks should be small enough to complete in one session

Task Naming Conventions

• Use descriptive task IDs
• Group related tasks under section headers
• Mark section headers with isHeader: true
• Keep task titles concise but informative

Progress Tracking

• Update task status promptly when work begins
• Use the blocked status with reasons when encountering obstacles
• Review implementation logs regularly to ensure accuracy

Related Pages

Related topics: Spec Management, Web Dashboard, VSCode Extension

Approval Workflow System

Overview

The Approval Workflow System is a core component of the spec-workflow-mcp project that enforces structured document review and revision processes. It ensures that all specifications, designs, and implementation tasks undergo explicit human approval before proceeding to subsequent phases.

Key Responsibilities:

• Managing approval requests with associated metadata (title, description, file path)
• Tracking approval status through polling mechanisms
• Enforcing sequential workflow progression (no phase skipping)
• Blocking operations when approvals fail or cleanup is unsuccessful
• Providing cross-platform interfaces (web dashboard and VS Code extension)

Sources: src/tools/steering-guide.ts src/dashboard/approval-storage.ts

Related Pages

Related topics: Spec Management, Approval Workflow System

Steering Documents

Overview

Steering Documents are foundational markdown files that guide the development process by defining the product vision, technical architecture, and codebase organization. They serve as the single source of truth for maintaining alignment between development decisions and project goals.

The Steering Documents system consists of three core documents that work together to provide comprehensive guidance for the project.

Document Types

1. Product Vision Document (`product.md`)

The product document defines the what and why of the project.

Template Location: src/markdown/templates/product-template.md

2. Technical Architecture Document (`tech.md`)

The tech document defines the how of the technical implementation.

Template Location: src/markdown/templates/tech-template.md

3. Codebase Structure Document (`structure.md`)

The structure document defines the where of code organization.

Template Location: src/markdown/templates/structure-template.md

Workflow

graph TD
    A[Create/Update Steering Documents] --> B{Document Type}
    B -->|product.md| C[Define Vision & Features]
    B -->|tech.md| D[Document Architecture]
    B -->|structure.md| E[Map Codebase Organization]
    
    C --> F[Review with AI Assistant]
    D --> F
    E --> F
    
    F --> G[Store in Project Root]
    G --> H[Reference During Development]

Steering Guide Tool

The steering-guide.ts module provides the core functionality for managing steering documents.

Location: src/tools/steering-guide.ts

Key Functions

Configuration Options

interface SteeringConfig {
  outputDir: string;        // Directory for steering documents
  templateDir: string;      // Location of markdown templates
  autoSync: boolean;        // Auto-sync with project changes
  validationLevel: 'strict' | 'loose' | 'none';
}

Document Templates

Product Template Structure

# Product Vision
[High-level product description]

# Target Users
[User personas and use cases]

# Key Features
- Feature 1
- Feature 2

# Business Objectives
[Success metrics and goals]

Tech Template Structure

# Technology Stack
[Languages, frameworks, tools]

# Architecture Decisions
[Key technical decisions]

# Development Principles
[Code standards and practices]

Structure Template Structure

# Directory Structure
[Folder organization]

# Module Architecture
[Code partitioning]

# Key Files
[Important file responsibilities]

Integration with VSCode Extension

The VSCode extension provides a user interface for managing steering documents.

Location: vscode-extension/src/webview/App.tsx

Steering Tab Features

interface SteeringDocument {
  name: 'product' | 'tech' | 'structure';
  exists: boolean;
  lastModified?: Date;
  path: string;
}

User Interface Flow

sequenceDiagram
    participant User
    participant VSCode as VSCode Extension
    participant FS as File System
    
    User->>VSCode: Open Steering Tab
    VSCode->>FS: Check document existence
    FS-->>VSCode: Return file metadata
    VSCode-->>User: Display document list
    
    User->>VSCode: Copy creation instructions
    VSCode->>User: Copy prompt to clipboard
    
    User->>VSCode: Click "Open" on document
    VSCode->>FS: Open file in editor

Implementation Log Integration

Steering documents are referenced in the implementation log system.

Location: src/dashboard/implementation-log-manager.ts

The implementation log can include references to steering documents as part of task completion records, linking development work back to the guiding documents.

Best Practices

1. Keep Documents Updated: Review and update steering documents when significant changes occur
2. Consistent Location: Always store in project root for easy access
3. Version Control: Track changes to steering documents in version history
4. AI Reference: Use documents as context for AI-assisted development

File Reference Summary

Related Components

• Prompt Generator: src/prompts/create-steering-doc.ts - Generates prompts for AI document creation
• Steering Guide: src/tools/steering-guide.ts - Core tool for document management
• VSCode Extension: vscode-extension/src/webview/App.tsx - UI for document interaction
• Dashboard Frontend: src/dashboard_frontend/src/modules/pages/SteeringPage.tsx - Web dashboard integration

Related Pages

Related topics: VSCode Extension, Docker Deployment, System Architecture

Web Dashboard

The Web Dashboard is the primary user interface for the spec-workflow-mcp system. It provides a real-time, visual interface for monitoring project specifications, tracking task progress, reviewing implementation logs, and managing automated workflows across all connected projects.

Overview

The dashboard serves as a centralized monitoring and management hub that complements the MCP (Model Context Protocol) server functionality. While the MCP server handles code execution and specification enforcement, the dashboard offers:

• Real-time monitoring of spec files and implementation progress
• Visual task tracking with filtering and completion indicators
• Implementation log visualization with file change statistics
• Automated cleanup job management with execution history
• Multi-project support via WebSocket connections

The dashboard runs as a separate service (default port 5000) and communicates with connected projects through a file-watching system and WebSocket connections Sources: README.md.

Architecture

System Components

graph TD
    A[Browser Client] <-->|HTTP/WebSocket| B[Dashboard Server :5000]
    B <-->|File System Events| C[.spec-workflow Directory]
    B <-->|WebSocket| D[VSCode Extension Webview]
    C <-->|File Watching| E[Project Specs]
    C <-->|File Watching| F[Steering Documents]
    C <-->|File Watching| G[Implementation Logs]

Frontend Architecture

The dashboard frontend is a React-based single-page application located in src/dashboard_frontend/. It uses a modular structure:

src/dashboard_frontend/
├── src/
│   ├── modules/
│   │   ├── app/App.tsx           # Main application shell
│   │   ├── pages/               # Page components
│   │   │   ├── SettingsPage.tsx
│   │   │   ├── TasksPage.tsx
│   │   │   ├── LogsPage.tsx
│   │   │   └── JobExecutionHistory.tsx
│   │   ├── ws/                   # WebSocket integration
│   │   │   └── WebSocketProvider.tsx
│   │   └── mdx-editor/           # MDX editing capabilities
│   │       └── MDXEditorWrapper.tsx
│   └── i18n.ts                   # Internationalization

The WebSocketProvider establishes and maintains a persistent connection to the dashboard server, enabling real-time updates without page refreshes Sources: src/dashboard_frontend/src/modules/ws/WebSocketProvider.tsx.

Backend Server

The server is implemented in src/server.ts and provides:

• Express.js HTTP server for static file serving
• WebSocket server for real-time client communication
• File system watcher integration
• REST API endpoints for project data retrieval

Pages and Features

Overview Page

The landing page displays project statistics aggregated from all connected projects:

The overview uses progress bars to visualize completion status and shows recent activity feed Sources: vscode-extension/src/webview/App.tsx.

Tasks Page

The tasks page provides comprehensive task management capabilities:

• Filtering controls for narrowing down task lists
• View mode switcher between list and other display formats
• Progress visualization with percentage indicators
• Task status indicators (in-progress, blocked, completed)

Tasks display metadata including leverage scores and AI prompts when available, with expandable sections for detailed information Sources: src/dashboard_frontend/src/modules/pages/TasksPage.tsx.

Logs Page

Implementation logs are displayed with comprehensive statistics:

graph LR
    A[File Change Event] --> B[Log Entry Created]
    B --> C[Statistics Calculated]
    C --> D[Markdown Rendered]
    D --> E[Client Displayed]

Log entries include:

• Statistics: Lines added/removed, files changed, net change
• Files Modified: List with syntax-highlighted file paths
• Files Created: Newly created files in the project
• Artifacts: API endpoints, components, functions, and classes documented during implementation

Sources: src/dashboard_frontend/src/modules/pages/LogsPage.tsx.

Settings Page

The settings page manages automated cleanup jobs:

• Section-based layout with expandable/collapsible panels
• Job configuration controls
• Loading states with spinner indicators
• Error handling with styled alert boxes

The automated cleanup section allows management of jobs that run across all connected projects Sources: src/dashboard_frontend/src/modules/pages/SettingsPage.tsx.

Job Execution History

A dedicated panel displays execution statistics:

Success rates are color-coded: green for 100%, yellow for 50-99%, and red for below 50% Sources: src/dashboard_frontend/src/modules/pages/JobExecutionHistory.tsx.

Real-time Updates

WebSocket Communication

The dashboard uses WebSocket for bidirectional real-time communication:

1. Connection establishment: Client connects to /ws endpoint
2. Project updates: Server pushes spec and task changes immediately
3. Language preferences: Users can change language with instant UI update

The WebSocket provider handles message routing and maintains connection state:

// Message types supported
type MessageType = 
  | 'specs-updated'    // Spec files changed
  | 'tasks-updated'    // Task status changed
  | 'language-changed' // UI language update

Sources: src/dashboard_frontend/src/modules/ws/WebSocketProvider.tsx.

File Watching

The watcher system monitors the .spec-workflow directory:

sequenceDiagram
    participant FS as File System
    participant Watcher as Watcher Service
    participant Server as Dashboard Server
    participant WS as WebSocket Clients
    
    FS->>Watcher: File change detected
    Watcher->>Server: Process change
    Server->>WS: Broadcast update
    WS->>Client: Trigger re-render

When spec files, steering documents, or implementation logs change, the watcher triggers updates to all connected clients Sources: src/dashboard/watcher.ts.

Internationalization

The dashboard supports multiple languages through src/dashboard_frontend/src/i18n.ts. All user-facing strings are externalized and can be translated. Language changes are propagated to all connected clients via WebSocket.

Supported translations in the repository include:

• English (default)
• Korean (README.ko.md)
• French (README.fr.md)
• German
• Portuguese
• Russian
• Italian
• Arabic

MDX Editor Integration

The MDXEditorWrapper component provides in-browser editing capabilities for specification documents. This allows users to:

• Edit spec files directly in the browser
• Preview rendered markdown
• Auto-save changes to the file system

Deployment Options

Standalone Server

Start the dashboard with the --dashboard flag:

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

The server binds to 127.0.0.1:5000 by default, preventing network exposure Sources: README.md.

Docker Deployment

Docker deployment provides isolated execution:

# containers/docker-compose.yml
services:
  dashboard:
    build: 
      context: .
      dockerfile: containers/Dockerfile
    ports:
      - "5000:5000"
    volumes:
      - ./workspace/.spec-workflow:/workspace/.spec-workflow:rw

Sources: containers/docker-compose.yml.

Security Features

The dashboard implements enterprise-grade security:

Sources: README.md.

VSCode Extension Integration

The VSCode extension embeds the dashboard as a webview, providing:

• In-editor dashboard access
• Seamless integration with the development environment
• Real-time updates within VSCode

The webview uses the same React components as the standalone dashboard but is packaged for VSCode's webview API Sources: vscode-extension/src/webview/App.tsx.

Configuration

The dashboard behavior is configured through the project's .spec-workflow/config.toml:

[dashboard]
port = 5000
host = "127.0.0.1"

Multiple projects can connect to a single dashboard instance, allowing centralized monitoring across a development environment.

Related Pages

Related topics: Web Dashboard, Approval Workflow System

VSCode Extension

Overview

The spec-workflow-mcp VSCode Extension provides an integrated development experience for managing specification-based workflows directly within Visual Studio Code. It serves as the recommended interface option for VSCode users, offering a native sidebar panel, approval management tools, and real-time project monitoring capabilities.

Sources: vscode-extension/README.md

Purpose and Scope

The extension complements the CLI-based web dashboard by providing:

• Inline project management - View and manage specs without leaving the editor
• Approval workflow integration - Review, approve, or reject specification changes
• Task tracking - Monitor implementation progress across specs and tasks
• Implementation logging - Track code artifacts generated during development
• Multi-project support - Connect to multiple specification projects simultaneously

Sources: vscode-extension/src/extension.ts

Architecture

Component Overview

The extension follows a modular architecture with clear separation between VSCode integration layers and UI components.

graph TD
    subgraph "VSCode Host Layer"
        EXT[extension.ts]
        SIDEBAR[SidebarProvider]
        CMDS[ApprovalCommandService]
        EDITOR[ApprovalEditorService]
    end
    
    subgraph "Webview Layer"
        APP[App.tsx]
        LOGS[LogsPage]
        TASKS[TasksPage]
        CARDS[LogEntryCard]
        MODAL[comment-modal]
    end
    
    subgraph "Communication"
        MSG[vscode.postMessage]
        EVENTS[Event System]
    end
    
    EXT --> SIDEBAR
    SIDEBAR --> MSG
    MSG --> APP
    APP --> LOGS
    APP --> TASKS
    APP --> CARDS
    LOGS --> MODAL
    CARDS --> MODAL
    
    CMDS --> EVENTS
    EDITOR --> EVENTS
    EVENTS --> MSG

Directory Structure

vscode-extension/
├── package.json                    # Extension manifest and configuration
├── src/
│   ├── extension.ts                # Entry point, registers commands and providers
│   ├── extension/
│   │   ├── providers/
│   │   │   └── SidebarProvider.ts  # Sidebar webview container management
│   │   └── services/
│   │       ├── ApprovalCommandService.ts   # Command execution logic
│   │       └── ApprovalEditorService.ts    # Editor-related operations
│   └── webview/
│       ├── App.tsx                 # Main webview application
│       ├── components/
│       │   └── LogEntryCard.tsx    # Implementation log entry display
│       ├── pages/
│       │   ├── LogsPage.tsx        # Implementation logs view
│       │   └── TasksPage.tsx       # Task management view
│       ├── comment-modal.tsx       # Comment input modal
│       ├── comment-modal.html      # Modal HTML template
│       └── globals.css             # Global styles
└── webview-dist/                   # Compiled webview assets
    ├── comment-modal.js
    ├── i18n.js
    └── globals.css

Sources: vscode-extension/package.json

Core Components

Extension Entry Point

The extension.ts file serves as the main entry point for the VSCode extension. It performs the following initialization tasks:

1. Command Registration - Registers VSCode commands for approval actions
2. Sidebar Provider Registration - Establishes the sidebar webview container
3. Event Listeners - Sets up communication between VSCode and webviews

Sources: vscode-extension/src/extension.ts

SidebarProvider

The SidebarProvider class manages the lifecycle of the sidebar webview panel.

The provider implements the WebviewViewProvider interface and creates a webview with:

• Local resource roots - Access to extension's local file resources
• Scripts enabled - JavaScript execution for interactivity
• State persistence - Maintains view state across sessions

Sources: vscode-extension/src/extension/providers/SidebarProvider.ts

ApprovalCommandService

This service handles command execution related to the approval workflow system.

Sources: vscode-extension/src/extension/services/ApprovalCommandService.ts

ApprovalEditorService

The ApprovalEditorService manages editor-related operations for reviewing specification changes.

Sources: vscode-extension/src/extension/services/ApprovalEditorService.ts

Webview UI

App Component

The App.tsx serves as the main container for the sidebar webview, organizing content into logical sections.

interface ProjectStats {
  activeSpecs: number;      // Total specs in active development
  completedSpecs: number;   // Fully approved specs
  archivedSpecs: number;    // Archived specifications
  totalSpecs: number;       // Combined total
  totalTasks: number;       // All tasks across specs
  completedTasks: number;   // Completed implementation tasks
}

Sources: vscode-extension/src/webview/App.tsx

Project Overview Card

Displays aggregate statistics about the connected project:

• Active Specs - Shows completedSpecs / activeSpecs ratio
• Archived Specs - Count of archived specifications
• Total Specs - Combined specification count
• Tasks - Shows completedTasks / totalTasks progress

Sources: vscode-extension/src/webview/App.tsx

TasksPage

The tasks view renders individual specification tasks with the following metadata:

Sources: src/dashboard_frontend/src/modules/pages/TasksPage.tsx

LogEntryCard

Displays implementation log entries with artifact tracking:

interface ImplementationLogEntry {
  id: string;
  timestamp: string;
  message: string;
  filesModified: string[];
  filesCreated: string[];
  artifacts: {
    apiEndpoints: ApiEndpoint[];
    components: Component[];
    functions: Function[];
    classes: Class[];
    integrations: Integration[];
  };
  statistics?: {
    linesAdded: number;
    linesRemoved: number;
  };
}

Sources: vscode-extension/src/webview/components/LogEntryCard.tsx

Artifact Sections

Each artifact type has a dedicated display section:

Sources: src/dashboard_frontend/src/modules/pages/LogsPage.tsx

Comment Modal

The comment modal provides a dialog for adding notes to approvals:

HTML Template Structure:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Add Comment</title>
</head>
<body>
  <div id="root"></div>
  <script type="module" src="./comment-modal.tsx"></script>
</body>
</html>

Compiled Version:

<script type="module" crossorigin src="/comment-modal.js"></script>
<link rel="modulepreload" crossorigin href="/i18n.js">
<link rel="stylesheet" crossorigin href="/globals.css">

Sources: vscode-extension/src/webview/comment-modal.html Sources: vscode-extension/webview-dist/comment-modal.html

Communication Protocol

Message Flow

The extension uses VSCode's postMessage API for bidirectional communication between the host and webview.

sequenceDiagram
    participant User
    participant Webview
    participant VSCode
    participant Backend
    
    User->>Webview: Click action
    Webview->>VSCode: postMessage({ type, payload })
    VSCode->>Backend: HTTP API call
    Backend-->>VSCode: JSON response
    VSCode-->>Webview: WebviewPanel.webview.postMessage()
    Webview-->>User: Updated UI

Message Types

Configuration

Extension Settings

The extension supports project-specific configuration through TOML files:

# .spec-workflow/config.example.toml
[project]
name = "my-project"
dashboard_url = "http://localhost:5000"
auto_refresh = true
refresh_interval = 30

VSCode Configuration

{
  "spec-workflow.projectPath": "/path/to/project",
  "spec-workflow.dashboardUrl": "http://localhost:5000",
  "spec-workflow.autoRefresh": true
}

Integration with Dashboard

The VSCode extension operates independently from the web dashboard while sharing the same backend API:

graph LR
    subgraph "Development Environment"
        VSCODE[VSCode Extension]
        WEBVIEW[Sidebar Webview]
    end
    
    subgraph "Backend Services"
        API[REST API]
        FILES[File System]
    end
    
    VSCODE --> API
    WEBVIEW --> API
    API --> FILES
    
    subgraph "Optional Services"
        DASHBOARD[Web Dashboard]
    end
    
    API <--> DASHBOARD

Key Points:

• Only one dashboard instance is needed per machine
• All projects connect to the same dashboard
• VSCode extension can work standalone with direct file access
• Approval actions sync across both interfaces

Sources: vscode-extension/README.md

Installation

From VSCode Marketplace

1. Open VSCode
2. Navigate to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "spec-workflow"
4. Click Install

From Command Line

code --install-extension pimzino.spec-workflow

Configuration Required

After installation, configure the project path in VSCode settings:

{
  "spec-workflow.projectPath": "/absolute/path/to/your/project"
}

Sources: vscode-extension/README.md

Feature Comparison

Extension Commands

The extension registers the following VSCode commands:

Sources: vscode-extension/src/extension.ts

Dependencies

The extension depends on the following packages:

Sources: vscode-extension/package.json

Troubleshooting

Sidebar Not Loading

1. Verify project path is correctly configured
2. Check that .spec-workflow/ directory exists in project root
3. Run "Developer: Reload Window" command

API Connection Errors

1. Ensure web dashboard is running (if using shared backend)
2. Check spec-workflow.dashboardUrl setting
3. Verify network connectivity

Webview Scripts Blocked

The webview requires script execution. If scripts are blocked:

1. Check webview.csp setting in VSCode
2. Ensure no security policies are preventing execution

Sources: vscode-extension/README.md

Related Pages

Related topics: Web Dashboard

Docker Deployment

Overview

The spec-workflow-mcp project provides a containerized dashboard deployment option for isolated and secure execution in Docker environments. This deployment method is designed for users who prefer not to install Node.js locally or require a self-contained, portable solution for running the specification workflow management system.

The Docker deployment bundles the Node.js runtime (version 24-alpine), the dashboard application, and all required dependencies into a single image that can be run consistently across different host systems.

Architecture

graph TD
    A[User Host Machine] -->|HTTP Requests| B[Docker Container]
    B -->|Port Mapping| C[Dashboard Application]
    C -->|Volume Mount| D[.spec-workflow Directory]
    
    E[Docker Networking] -->|Security Control| F[127.0.0.1:5000:5000]
    E -->|Optional External| G[0.0.0.0:5000:5000]
    
    style C fill:#f9f,stroke:#333,stroke-width:2px
    style D fill:#ff9,stroke:#333,stroke-width:2px

Container Components

Quick Start

Building the Image

# Build using Docker CLI
docker build -f containers/Dockerfile -t spec-workflow-mcp .

# Verify the image was created
docker images spec-workflow-mcp

Running the Container

# Basic run with default settings
docker run -p 5000:5000 \
  -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" \
  spec-workflow-mcp

The dashboard becomes accessible at: http://localhost:5000 Sources: README.md:1-10

Docker Compose Deployment

Docker Compose is the recommended deployment method as it provides additional security hardening and simplified management.

Default Configuration

Create a .env file for environment configuration:

# .env file
DASHBOARD_PORT=5000
SPEC_WORKFLOW_PATH=./workspace

Start the dashboard:

cd containers
docker-compose up --build

Management Commands

# Start in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the dashboard
docker-compose down

# Rebuild and restart
docker-compose up --build

Configuration Options

Environment Variables

Sources: containers/README.md:80-100

Custom Port Configuration

# Using Docker CLI
docker run -p 8080:8080 \
  -e DASHBOARD_PORT=8080 \
  -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" \
  spec-workflow-mcp

Volume Mounts

The dashboard requires read-write access to the .spec-workflow directory:

-v "/path/to/project/.spec-workflow:/workspace/.spec-workflow:rw"

Important Notes:

• The volume mount must be read-write (:rw) for the dashboard to function properly
• Only the .spec-workflow directory needs to be mounted
• The directory will be created automatically if it doesn't exist Sources: containers/README.md:60-70

Security Features

Implemented Security Controls

The Docker image includes enterprise-grade security features suitable for corporate environments:

Network Security Models

graph LR
    A[Localhost Only] -->|127.0.0.1:5000:5000| B[Recommended - Secure]
    C[Network Access] -->|0.0.0.0:5000:5000| D[Available - Requires Firewall]

Option 1: Localhost Only (Secure Default)

The default docker-compose.yml uses localhost-only port mapping:

ports:
  - "127.0.0.1:5000:5000"  # Only accessible from host machine

Or with Docker CLI:

docker run -p 127.0.0.1:5000:5000 \
  -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" \
  spec-workflow-mcp

Option 2: Network Access (Exposes to Network)

docker run -p 5000:5000 \
  -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" \
  spec-workflow-mcp

⚠️ Security Warning: This configuration exposes the dashboard to your network. The application displays a security warning in the logs. Only use when necessary and ensure proper network security measures (firewall, VPN) are in place. Sources: containers/README.md:110-140

Docker Compose Security Hardening

The provided docker-compose.yml includes additional security settings:

# Read-only root filesystem
read_only: true

# Drop all Linux capabilities
cap_drop:
  - ALL

# Prevent privilege escalation
security_opt:
  - no-new-privileges:true

# Resource limits (prevent DoS)
deploy:
  resources:
    limits:
      cpus: '1.0'
      memory: 512M

Best Practices

1. Use localhost port mapping when possible (127.0.0.1:5000:5000)
2. Never expose to public internet without proper authentication/firewall
3. Keep rate limiting enabled in production
4. Use the provided docker-compose.yml for security hardening
5. Run as non-root user (default in the image)
6. Mount volumes read-write only when necessary Sources: containers/README.md:150-165

Audit Logging

All API requests are logged to a structured JSON audit log for compliance and debugging.

Log Location

<project>/.spec-workflow/audit.log

Log Format

{
  "timestamp": "2025-12-06T10:30:45.123Z",
  "actor": "127.0.0.1",
  "action": "GET /api/projects/list",
  "resource": "/api/projects/list",
  "result": "success",
  "details": {
    "statusCode": 200,
    "duration": 45,
    "userAgent": "Mozilla/5.0..."
  }
}

Viewing Logs

# View recent logs
tail -f .spec-workflow/audit.log

# Parse as JSON (requires jq)
cat .spec-workflow/audit.log | jq '.'

# Filter by result
cat .spec-workflow/audit.log | jq 'select(.result == "denied")'

Advanced Configuration

Auto-Restart on Failure

docker run -d \
  --name spec-workflow-dashboard \
  --restart unless-stopped \
  -p 5000:5000 \
  -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" \
  spec-workflow-mcp

Health Checks

The dashboard does not currently include built-in health checks. You can verify connectivity manually:

curl http://localhost:5000

Testing the Docker Image

A comprehensive test script validates Docker image configurations:

# From the containers directory
./test-docker.sh

Sources: README.md:50-75

Troubleshooting

Container Does Not Start

Error: Container exits immediately after starting

Solutions:

• Check logs: docker logs <container-id>
• Verify volume mount path exists and is correct
• Ensure port 5000 (or your configured port) is not already in use

Cannot Connect to Dashboard

Error: Unable to access http://localhost:5000

Solutions:

• Verify container is running: docker ps
• Check port is properly mapped: docker port <container-id>
• Ensure firewall allows connections on the port

Build Fails

Error: Build fails with COPY or dependency errors

Solutions:

• Build from repository root: docker build -f containers/Dockerfile -t spec-workflow-mcp .
• Verify all source files are present
• Confirm package.json and package-lock.json exist Sources: containers/README.md:40-60

Inspecting the Container

# View container details
docker inspect <container-id>

# Access container shell
docker exec -it <container-id> /bin/sh

External Access with Authentication

The dashboard does not include built-in authentication. For external access scenarios, use a reverse proxy:

nginx with Basic 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;
    }
}

Sandbox 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 @pimzino/spec-workflow-mcp@latest /workspace

This approach works similarly in Docker:

docker run -p 5000:5000 \
  -e SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp \
  -v "/path/to/project:/workspace" \
  spec-workflow-mcp

Sources: README.md:100-110

Security Comparison Table

See Also

• Configuration Guide - Additional configuration options
• Interfaces Guide - Dashboard and VSCode extension details
• Development Guide - Local development setup
• Troubleshooting - Common issues and solutions

Doramagic Pitfall Log

Doramagic extracted 11 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: [Bug]: approval categoryName path traversal writes outside approvals directory

• Severity: medium
• Finding: Installation risk is backed by a source signal: [Bug]: approval categoryName path traversal writes outside approvals directory. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Pimzino/spec-workflow-mcp/issues/220

2. Configuration risk: Configuration risk needs validation

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Configuration risk needs validation. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.host_targets | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | host_targets=mcp_host, claude, claude_code

3. Configuration risk: [Bug]: Bug Report for spec-workflow-mcp

• Severity: medium
• Finding: Configuration risk is backed by a source signal: [Bug]: Bug Report for spec-workflow-mcp. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Pimzino/spec-workflow-mcp/issues/218

4. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | README/documentation is current enough for a first validation pass.

5. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | last_activity_observed missing

6. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium

7. Security or permission risk: No sandbox install has been executed yet; downstream must verify before user use.

• Severity: medium
• Finding: No sandbox install has been executed yet; downstream must verify before user use.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.safety_notes | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | No sandbox install has been executed yet; downstream must verify before user use.

8. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | no_demo; severity=medium

9. Security or permission risk: [Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: [Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/Pimzino/spec-workflow-mcp/issues/201

10. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | issue_or_pr_quality=unknown

11. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:1033865617 | https://github.com/Pimzino/spec-workflow-mcp | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using spec-workflow-mcp with real data or production workflows.

• [[Bug]: approval categoryName path traversal writes outside approvals dir](https://github.com/Pimzino/spec-workflow-mcp/issues/220) - github / github_issue
• [[Bug]: Bug Report for spec-workflow-mcp](https://github.com/Pimzino/spec-workflow-mcp/issues/218) - github / github_issue
• [[Bug]: Improper Validation of FilePaths Enabling Arbitrary File Reads](https://github.com/Pimzino/spec-workflow-mcp/issues/201) - github / github_issue
• Configuration risk needs validation - GitHub / issue