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.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Pimzino/spec-workflow-mcp with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Pimzino/spec-workflow-mcp'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/pimzino--spec-workflow-mcp)HTML
<a href="/listings/pimzino--spec-workflow-mcp"><img src="/api/listings/pimzino--spec-workflow-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Step 1: Add to your AI tool
Add to your MCP configuration (see client-specific setup below):
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/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 @pimzino/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](https://marketplace.visualstudio.com/items?itemName=Pimzino.spec-workflow-mcp) from the VSCode marketplace.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 33 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "name": "spec-workflow-mcp-marketplace",
- "owner": {
- "name": "Pimzino"
- },
- "metadata": {
- "description": "Spec Workflow MCP provides structured spec-driven development with a sequential workflow (Requirements → Design → Tasks), real-time web dashboard, and VSCode extension support. Includes human approval gates at each stage and project steering guidance."
- },
- "plugins": [
- {
- "name": "spec-workflow-mcp",
- "version": "2.2.6",
- "description": "MCP server for structured spec-driven development with real-time web dashboard and VSCode extension.",
- "author": {
- "name": "Pimzino"
- },
- "license": "GPL-3.0",
- "homepage": "https://github.com/Pimzino/spec-workflow-mcp",
- "source": "./.claude-plugin"
- },
- {
- "name": "spec-workflow-mcp-with-dashboard",
- "version": "2.2.6",
- "description": "MCP server with auto-started dashboard for structured spec-driven development.",
- "author": {
- "name": "Pimzino"
- },
- "license": "GPL-3.0",
- "homepage": "https://github.com/Pimzino/spec-workflow-mcp",
- "source": "./.claude-plugin/with-dashboard"
- }
- ]
- }
README.md · README · 376 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Spec Workflow MCP
- *I HAVE TAKEN A SMALL BREAK FROM THIS REPO FOR PERSONAL REASONS BUT I WILL BE BACK WITH SOME UPDATES IN THE NEAR FUTURE*
- *THANK YOU FOR YOUR UNDERSTANDING*
- [](https://www.npmjs.com/package/@pimzino/spec-workflow-mcp)
- [](https://marketplace.visualstudio.com/items?itemName=Pimzino.spec-workflow-mcp)
- A Model Context Protocol (MCP) server for structured spec-driven development with real-time dashboard and VSCode extension.
- ## ☕ Support This Project
- <a href="https://buymeacoffee.com/Pimzino" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
- ## 📺 Showcase
- ### 🔄 Approval System in Action
- <a href="https://www.youtube.com/watch?v=C-uEa3mfxd0" target="_blank">
- <img src="https://img.youtube.com/vi/C-uEa3mfxd0/maxresdefault.jpg" alt="Approval System Demo" width="600">
- </a>
- *See how the approval system works: create documents, request approval through the dashboard, provide feedback, and track revisions.*
- ### 📊 Dashboard & Spec Management
- <a href="https://www.youtube.com/watch?v=g9qfvjLUWf8" target="_blank">
- <img src="https://img.youtube.com/vi/g9qfvjLUWf8/maxresdefault.jpg" alt="Dashboard Demo" width="600">
- </a>
- *Explore the real-time dashboard: view specs, track progress, navigate documents, and monitor your development workflow.*
- ## ✨ Key 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 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](README.md) | [日本語](README.ja.md) | [中文](README.zh.md) | [Español](README.es.md) | [Português](README.pt.md) | [Deutsch](README.de.md) | [Français](README.fr.md) | [Русский](README.ru.md) | [Italiano](README.it.md) | [한국어](README.ko.md) | [العربية](README.ar.md)
- ## 🚀 Quick Start
- ### Step 1: Add to your AI tool
- Add to your MCP configuration (see client-specific setup below):
- ```json
- {
- "mcpServers": {
- "spec-workflow": {
- "command": "npx",
- "args": ["-y", "@pimzino/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):
- ```bash
- npx -y @pimzino/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](https://marketplace.visualstudio.com/items?itemName=Pimzino.spec-workflow-mcp) 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 →](docs/PROMPTING-GUIDE.md)
- ## 🔧 MCP Client Setup
- <details>
- <summary><strong>Augment Code</strong></summary>
- Configure in your Augment settings:
- ```json
- {
- "mcpServers": {
- "spec-workflow": {
- "command": "npx",
- "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
- }
- }
- }
- ```
- </details>
- <details>
- <summary><strong>Claude Code CLI</strong></summary>
- Add to your MCP configuration:
- ```bash
- claude mcp add spec-workflow npx @pimzino/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):**
- ```bash
- claude mcp add spec-workflow cmd.exe /c "npx @pimzino/spec-workflow-mcp@latest /path/to/your/project"
- ```
- </details>
- <details>
- <summary><strong>Claude Desktop</strong></summary>
- Add to `claude_desktop_config.json`:
- ```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.
- </details>
- <details>
- <summary><strong>Cline/Claude Dev</strong></summary>
- Add to your MCP server configuration:
- ```json
- {
- "mcpServers": {
- "spec-workflow": {
- "command": "npx",
- "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
- }
- }
- }
- ```
- </details>
- <details>
- <summary><strong>Continue IDE Extension</strong></summary>
- Add to your Continue configuration:
- ```json
- {
- "mcpServers": {
- "spec-workflow": {
- "command": "npx",
- "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
- }
- }
- }
- ```
- </details>
- <details>
- <summary><strong>Cursor IDE</strong></summary>
- Add to your Cursor settings (`settings.json`):
- ```json
- {
- "mcpServers": {
- "spec-workflow": {
- "command": "npx",
- "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
- }
- }
- }
- ```
- </details>
- <details>
- <summary><strong>OpenCode</strong></summary>
- Add to your `opencode.json` configuration file:
- ```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
- }
- }
- }
- ```
- </details>
- <details>
- <summary><strong>Windsurf</strong></summary>
- Add to your `~/.codeium/windsurf/mcp_config.json` configuration file:
- ```json
- {
- "mcpServers": {
- "spec-workflow": {
- "command": "npx",
- "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
- }
- }
- }
- ```
- </details>
- <details>
- <summary><strong>Codex</strong></summary>
- Add to your `~/.codex/config.toml` configuration file:
- ```toml
- [mcp_servers.spec-workflow]
- command = "npx"
- args = ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
- ```
- </details>
- ## 🐳 Docker Deployment
- Run the dashboard in a Docker container for isolated deployment:
- ```bash
- # 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 →](containers/README.md)
- ## 🔒 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
- ```nginx
- # 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 →](containers/README.md#security-configuration)
- ## 🔒 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:
- ```bash
- SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace
- ```
- [See Configuration Guide →](docs/CONFIGURATION.md#environment-variables)
- ## 📚 Documentation
- - [Configuration Guide](docs/CONFIGURATION.md) - Command-line options, config files
- - [User Guide](docs/USER-GUIDE.md) - Comprehensive usage examples
- - [Workflow Process](docs/WORKFLOW.md) - Development workflow and best practices
- - [Interfaces Guide](docs/INTERFACES.md) - Dashboard and VSCode extension details
- - [Prompting Guide](docs/PROMPTING-GUIDE.md) - Advanced prompting examples
- - [Tools Reference](docs/TOOLS-REFERENCE.md) - Complete tools documentation
- - [Development](docs/DEVELOPMENT.md) - Contributing and development setup
- - [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions
- ## 📁 Project Structure
- ```
- your-project/
- .spec-workflow/
- approvals/
- archive/
- specs/
- steering/
- templates/
- user-templates/
- config.example.toml
- ```
- ## 🛠️ Development
- ```bash
- # Install dependencies
- npm install
- # Build the project
- npm run build
- # Run in development mode
- npm run dev
- ```
- [See development guide →](docs/DEVELOPMENT.md)
- ## 📄 License
- GPL-3.0
- ## ⭐ Star History
- <a href="https://www.star-history.com/#Pimzino/spec-workflow-mcp&Date">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Pimzino/spec-workflow-mcp&type=Date&theme=dark" />
- <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Pimzino/spec-workflow-mcp&type=Date" />
- <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Pimzino/spec-workflow-mcp&type=Date" />
- </picture>
- </a>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.