Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/pimzino--spec-workflow-mcp/badge.svg)](/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

i

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)

  1. {
  2. "name": "spec-workflow-mcp-marketplace",
  3. "owner": {
  4. "name": "Pimzino"
  5. },
  6. "metadata": {
  7. "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."
  8. },
  9. "plugins": [
  10. {
  11. "name": "spec-workflow-mcp",
  12. "version": "2.2.6",
  13. "description": "MCP server for structured spec-driven development with real-time web dashboard and VSCode extension.",
  14. "author": {
  15. "name": "Pimzino"
  16. },
  17. "license": "GPL-3.0",
  18. "homepage": "https://github.com/Pimzino/spec-workflow-mcp",
  19. "source": "./.claude-plugin"
  20. },
  21. {
  22. "name": "spec-workflow-mcp-with-dashboard",
  23. "version": "2.2.6",
  24. "description": "MCP server with auto-started dashboard for structured spec-driven development.",
  25. "author": {
  26. "name": "Pimzino"
  27. },
  28. "license": "GPL-3.0",
  29. "homepage": "https://github.com/Pimzino/spec-workflow-mcp",
  30. "source": "./.claude-plugin/with-dashboard"
  31. }
  32. ]
  33. }
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)

  1. # Spec Workflow MCP
  2. *I HAVE TAKEN A SMALL BREAK FROM THIS REPO FOR PERSONAL REASONS BUT I WILL BE BACK WITH SOME UPDATES IN THE NEAR FUTURE*
  3. *THANK YOU FOR YOUR UNDERSTANDING*
  4. [![npm version](https://img.shields.io/npm/v/@pimzino/spec-workflow-mcp)](https://www.npmjs.com/package/@pimzino/spec-workflow-mcp)
  5. [![VSCode Extension](https://vsmarketplacebadges.dev/version-short/Pimzino.spec-workflow-mcp.svg)](https://marketplace.visualstudio.com/items?itemName=Pimzino.spec-workflow-mcp)
  6. A Model Context Protocol (MCP) server for structured spec-driven development with real-time dashboard and VSCode extension.
  7. ## ☕ Support This Project
  8. <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>
  9. ## 📺 Showcase
  10. ### 🔄 Approval System in Action
  11. <a href="https://www.youtube.com/watch?v=C-uEa3mfxd0" target="_blank">
  12. <img src="https://img.youtube.com/vi/C-uEa3mfxd0/maxresdefault.jpg" alt="Approval System Demo" width="600">
  13. </a>
  14. *See how the approval system works: create documents, request approval through the dashboard, provide feedback, and track revisions.*
  15. ### 📊 Dashboard & Spec Management
  16. <a href="https://www.youtube.com/watch?v=g9qfvjLUWf8" target="_blank">
  17. <img src="https://img.youtube.com/vi/g9qfvjLUWf8/maxresdefault.jpg" alt="Dashboard Demo" width="600">
  18. </a>
  19. *Explore the real-time dashboard: view specs, track progress, navigate documents, and monitor your development workflow.*
  20. ## ✨ Key Features
  21. - **Structured Development Workflow** - Sequential spec creation (Requirements → Design → Tasks)
  22. - **Real-Time Web Dashboard** - Monitor specs, tasks, and progress with live updates
  23. - **VSCode Extension** - Integrated sidebar dashboard for VSCode users
  24. - **Approval Workflow** - Complete approval process with revisions
  25. - **Task Progress Tracking** - Visual progress bars and detailed status
  26. - **Implementation Logs** - Searchable logs of all task implementations with code statistics
  27. - **Multi-Language Support** - Available in 11 languages
  28. ## 🌍 Supported Languages
  29. 🇺🇸 English • 🇯🇵 日本語 • 🇨🇳 中文 • 🇪🇸 Español • 🇧🇷 Português • 🇩🇪 Deutsch • 🇫🇷 Français • 🇷🇺 Русский • 🇮🇹 Italiano • 🇰🇷 한국어 • 🇸🇦 العربية
  30. **📖 Documentation in your language:**
  31. [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)
  32. ## 🚀 Quick Start
  33. ### Step 1: Add to your AI tool
  34. Add to your MCP configuration (see client-specific setup below):
  35. ```json
  36. {
  37. "mcpServers": {
  38. "spec-workflow": {
  39. "command": "npx",
  40. "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
  41. }
  42. }
  43. }
  44. ```
  45. ### Step 2: Choose your interface
  46. **Option A: Web Dashboard** (Required for CLI users)
  47. Start the dashboard (runs on port 5000 by default):
  48. ```bash
  49. npx -y @pimzino/spec-workflow-mcp@latest --dashboard
  50. ```
  51. The dashboard will be accessible at: http://localhost:5000
  52. > **Note:** Only one dashboard instance is needed. All your projects will connect to the same dashboard.
  53. **Option B: VSCode Extension** (Recommended for VSCode users)
  54. Install [Spec Workflow MCP Extension](https://marketplace.visualstudio.com/items?itemName=Pimzino.spec-workflow-mcp) from the VSCode marketplace.
  55. ## 📝 How to Use
  56. Simply mention spec-workflow in your conversation:
  57. - **"Create a spec for user authentication"** - Creates complete spec workflow
  58. - **"List my specs"** - Shows all specs and their status
  59. - **"Execute task 1.2 in spec user-auth"** - Runs a specific task
  60. [See more examples →](docs/PROMPTING-GUIDE.md)
  61. ## 🔧 MCP Client Setup
  62. <details>
  63. <summary><strong>Augment Code</strong></summary>
  64. Configure in your Augment settings:
  65. ```json
  66. {
  67. "mcpServers": {
  68. "spec-workflow": {
  69. "command": "npx",
  70. "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
  71. }
  72. }
  73. }
  74. ```
  75. </details>
  76. <details>
  77. <summary><strong>Claude Code CLI</strong></summary>
  78. Add to your MCP configuration:
  79. ```bash
  80. claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/project
  81. ```
  82. **Important Notes:**
  83. - The `-y` flag bypasses npm prompts for smoother installation
  84. - The `--` separator ensures the path is passed to the spec-workflow script, not to npx
  85. - Replace `/path/to/your/project` with your actual project directory path
  86. **Alternative for Windows (if the above doesn't work):**
  87. ```bash
  88. claude mcp add spec-workflow cmd.exe /c "npx @pimzino/spec-workflow-mcp@latest /path/to/your/project"
  89. ```
  90. </details>
  91. <details>
  92. <summary><strong>Claude Desktop</strong></summary>
  93. Add to `claude_desktop_config.json`:
  94. ```json
  95. {
  96. "mcpServers": {
  97. "spec-workflow": {
  98. "command": "npx",
  99. "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
  100. }
  101. }
  102. }
  103. ```
  104. > **Important:** Run the dashboard separately with `--dashboard` before starting the MCP server.
  105. </details>
  106. <details>
  107. <summary><strong>Cline/Claude Dev</strong></summary>
  108. Add to your MCP server configuration:
  109. ```json
  110. {
  111. "mcpServers": {
  112. "spec-workflow": {
  113. "command": "npx",
  114. "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
  115. }
  116. }
  117. }
  118. ```
  119. </details>
  120. <details>
  121. <summary><strong>Continue IDE Extension</strong></summary>
  122. Add to your Continue configuration:
  123. ```json
  124. {
  125. "mcpServers": {
  126. "spec-workflow": {
  127. "command": "npx",
  128. "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
  129. }
  130. }
  131. }
  132. ```
  133. </details>
  134. <details>
  135. <summary><strong>Cursor IDE</strong></summary>
  136. Add to your Cursor settings (`settings.json`):
  137. ```json
  138. {
  139. "mcpServers": {
  140. "spec-workflow": {
  141. "command": "npx",
  142. "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
  143. }
  144. }
  145. }
  146. ```
  147. </details>
  148. <details>
  149. <summary><strong>OpenCode</strong></summary>
  150. Add to your `opencode.json` configuration file:
  151. ```json
  152. {
  153. "$schema": "https://opencode.ai/config.json",
  154. "mcp": {
  155. "spec-workflow": {
  156. "type": "local",
  157. "command": ["npx", "-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"],
  158. "enabled": true
  159. }
  160. }
  161. }
  162. ```
  163. </details>
  164. <details>
  165. <summary><strong>Windsurf</strong></summary>
  166. Add to your `~/.codeium/windsurf/mcp_config.json` configuration file:
  167. ```json
  168. {
  169. "mcpServers": {
  170. "spec-workflow": {
  171. "command": "npx",
  172. "args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
  173. }
  174. }
  175. }
  176. ```
  177. </details>
  178. <details>
  179. <summary><strong>Codex</strong></summary>
  180. Add to your `~/.codex/config.toml` configuration file:
  181. ```toml
  182. [mcp_servers.spec-workflow]
  183. command = "npx"
  184. args = ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
  185. ```
  186. </details>
  187. ## 🐳 Docker Deployment
  188. Run the dashboard in a Docker container for isolated deployment:
  189. ```bash
  190. # Using Docker Compose (recommended)
  191. cd containers
  192. docker-compose up --build
  193. # Or using Docker CLI
  194. docker build -f containers/Dockerfile -t spec-workflow-mcp .
  195. docker run -p 5000:5000 -v "./workspace/.spec-workflow:/workspace/.spec-workflow:rw" spec-workflow-mcp
  196. ```
  197. The dashboard will be available at: http://localhost:5000
  198. [See Docker setup guide →](containers/README.md)
  199. ## 🔒 Security
  200. Spec-Workflow MCP includes enterprise-grade security features suitable for corporate environments:
  201. ### ✅ Implemented Security Controls
  202. | Feature | Description |
  203. |---------|-------------|
  204. | **Localhost Binding** | Binds to `127.0.0.1` by default, preventing network exposure |
  205. | **Rate Limiting** | 120 requests/minute per client with automatic cleanup |
  206. | **Audit Logging** | Structured JSON logs with timestamp, actor, action, and result |
  207. | **Security Headers** | X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, CSP, Referrer-Policy |
  208. | **CORS Protection** | Restricted to localhost origins by default |
  209. | **Docker Hardening** | Non-root user, read-only filesystem, dropped capabilities, resource limits |
  210. ### ⚠️ Not Yet Implemented
  211. | Feature | Workaround |
  212. |---------|------------|
  213. | **HTTPS/TLS** | Use a reverse proxy (nginx, Apache) with TLS certificates |
  214. | **User Authentication** | Use a reverse proxy with Basic Auth or OAuth2 Proxy for SSO |
  215. ### For External/Network Access
  216. If you need to expose the dashboard beyond localhost, we recommend:
  217. 1. **Keep dashboard on localhost** (`127.0.0.1`)
  218. 2. **Use nginx or Apache** as a reverse proxy with:
  219. - TLS/HTTPS termination
  220. - Basic authentication or OAuth2
  221. 3. **Configure firewall rules** to restrict access
  222. ```nginx
  223. # Example nginx reverse proxy with auth
  224. server {
  225. listen 443 ssl;
  226. server_name dashboard.example.com;
  227. ssl_certificate /path/to/cert.pem;
  228. ssl_certificate_key /path/to/key.pem;
  229. auth_basic "Dashboard Access";
  230. auth_basic_user_file /etc/nginx/.htpasswd;
  231. location / {
  232. proxy_pass http://127.0.0.1:5000;
  233. proxy_http_version 1.1;
  234. proxy_set_header Upgrade $http_upgrade;
  235. proxy_set_header Connection "upgrade";
  236. }
  237. }
  238. ```
  239. [See Docker security guide →](containers/README.md#security-configuration)
  240. ## 🔒 Sandboxed Environments
  241. 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:
  242. ```bash
  243. SPEC_WORKFLOW_HOME=/workspace/.spec-workflow-mcp npx -y @pimzino/spec-workflow-mcp@latest /workspace
  244. ```
  245. [See Configuration Guide →](docs/CONFIGURATION.md#environment-variables)
  246. ## 📚 Documentation
  247. - [Configuration Guide](docs/CONFIGURATION.md) - Command-line options, config files
  248. - [User Guide](docs/USER-GUIDE.md) - Comprehensive usage examples
  249. - [Workflow Process](docs/WORKFLOW.md) - Development workflow and best practices
  250. - [Interfaces Guide](docs/INTERFACES.md) - Dashboard and VSCode extension details
  251. - [Prompting Guide](docs/PROMPTING-GUIDE.md) - Advanced prompting examples
  252. - [Tools Reference](docs/TOOLS-REFERENCE.md) - Complete tools documentation
  253. - [Development](docs/DEVELOPMENT.md) - Contributing and development setup
  254. - [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions
  255. ## 📁 Project Structure
  256. ```
  257. your-project/
  258. .spec-workflow/
  259. approvals/
  260. archive/
  261. specs/
  262. steering/
  263. templates/
  264. user-templates/
  265. config.example.toml
  266. ```
  267. ## 🛠️ Development
  268. ```bash
  269. # Install dependencies
  270. npm install
  271. # Build the project
  272. npm run build
  273. # Run in development mode
  274. npm run dev
  275. ```
  276. [See development guide →](docs/DEVELOPMENT.md)
  277. ## 📄 License
  278. GPL-3.0
  279. ## ⭐ Star History
  280. <a href="https://www.star-history.com/#Pimzino/spec-workflow-mcp&Date">
  281. <picture>
  282. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=Pimzino/spec-workflow-mcp&type=Date&theme=dark" />
  283. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=Pimzino/spec-workflow-mcp&type=Date" />
  284. <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=Pimzino/spec-workflow-mcp&type=Date" />
  285. </picture>
  286. </a>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.