spec-workflow-mcp

Implements a Model Context Protocol (MCP) server using StdioServerTransport that registers 13+ tools as JSON-RPC methods, enabling AI agents (Claude, Cursor, Codex) to invoke workflow operations through a standardized protocol. Tools return TOON-formatted responses with structured data and markdown content, abstracting the underlying file system and state management from the AI client.

Enforces a strict sequential workflow (Requirements → Design → Tasks → Implementation → Approval) by tracking phase state in the .spec-workflow/ directory structure and preventing out-of-order transitions. Each phase has dedicated tools and storage locations (specs/, approvals/, steering/, archive/), with the system validating phase prerequisites before allowing progression and maintaining an immutable audit trail of all transitions.

Stores all workflow state (.spec-workflow/ directory per project and ~/.spec-workflow-mcp/ global state) as files and directories, making state human-readable and version-controllable. The system supports environment variable overrides (SPEC_WORKFLOW_HOME) for sandboxed or containerized environments where $HOME is read-only, enabling deployment flexibility. State is organized hierarchically (specs/, tasks/, approvals/, archive/, implementation/) with each artifact as a separate file for granular version control.

Provides an i18n system that enables the web dashboard and VSCode extension to render in multiple languages. Language files are stored as JSON objects mapping keys to translated strings, and the system detects the user's locale from browser/VSCode settings and loads the appropriate language file. This allows teams in different regions to use the system in their native language without requiring separate deployments.

Provides Dockerfile configurations for containerized deployment with multi-stage builds that separate build and runtime stages, reducing image size. The system includes security hardening (non-root user, minimal base image, read-only file system where possible) and supports both standard and prebuilt image variants. Docker Compose configuration enables easy local development with both MCP server and dashboard running in containers with proper networking and volume mounts.

Records all significant events (tool invocations, approval decisions, phase transitions, file modifications) in audit logs stored in the .spec-workflow/ directory. Logs include timestamps, user identity, action type, and affected artifacts, enabling compliance audits and security investigations. The system supports structured logging formats (JSON) that can be ingested by SIEM systems or compliance tools for centralized monitoring.

Operates a Fastify-based HTTP server with WebSocket support that maintains real-time bidirectional communication with browser and VSCode extension clients. The dashboard aggregates state from multiple projects' .spec-workflow/ directories, broadcasts updates via WebSocket when files change (using file system watchers), and provides a unified view of all active projects without requiring clients to poll the file system directly.

Provides a VSCode extension that renders a sidebar panel connected to the dashboard server via WebSocket, displaying project status, task lists, and an interactive approval workflow interface. The extension allows developers to approve/reject implementations, view specifications, and manage tasks without leaving the editor, with all actions synchronized back to the .spec-workflow/ directory and broadcast to other connected clients.

Provides tools for creating and managing specification documents (requirements, design, task lists) stored in the specs/ directory with version tracking. Documents are stored as markdown files with optional JSON frontmatter for metadata, and the system supports templates for consistent structure. The workflow enforces that specifications must be created and approved before dependent phases can proceed, with all versions retained in the archive/ directory.

Parses specification documents to extract and decompose tasks into a structured task list stored in the tasks/ directory. The system identifies task boundaries (using markdown headers or explicit task markers), extracts dependencies and prerequisites, and generates task metadata (priority, estimated effort, assigned phase). Tasks are stored as JSON objects with references back to source specifications, enabling AI agents to understand the relationship between high-level requirements and concrete work items.

Captures implementation progress by logging code changes, commits, and artifacts as they are created. The system binds implementation artifacts (files, commits, pull requests) to their corresponding tasks and specifications, storing logs in the implementation/ directory with timestamps and metadata. This creates a complete audit trail from specification → task → code, enabling developers to understand why specific code was written and reviewers to trace implementations back to requirements.

Implements a structured approval process where implementations are submitted for review, reviewers can approve or request changes, and decisions are recorded with metadata (reviewer identity, timestamp, comments). The approval state is stored in the approvals/ directory as JSON objects, and the system prevents implementations from being marked complete until all required approvals are obtained. The VSCode extension and web dashboard provide UI for reviewers to inspect implementations and make approval decisions.

Maintains a global registry (activeProjects.json in ~/.spec-workflow-mcp/) that tracks all active projects and their metadata (path, status, last updated). The dashboard server reads this registry to discover which projects to monitor, and the MCP server registers itself with the registry when started. This enables the system to aggregate state across multiple projects and provide a unified view without requiring manual project configuration.

Provides 6+ interactive prompts that guide AI agents through workflow decisions and complex tasks. Prompts are registered as MCP resources that return structured guidance (context, options, examples) to help agents understand what to do next. The system uses prompts to handle ambiguous situations (e.g., 'should I create a new task or extend an existing one?') and to provide domain-specific guidance (e.g., 'how should I structure this specification?').