spec-workflow-mcp: putting a spec lifecycle behind an MCP server and a dashboard

What the MCP server actually wraps

The project is a Model Context Protocol server, which means it exposes tools to an AI assistant rather than being an assistant itself. Its stated purpose is structured spec-driven development: you ask for a spec, it produces a sequence of documents in a defined order, and it tracks the resulting work as tasks.

The ordering is the actual product. The feature list names it as sequential spec creation, Requirements then Design then Tasks, and the usage examples are phrased as conversation: create a spec for user authentication, list my specs, execute task 1.2 in spec user-auth. That third example is the important one, because it implies tasks are addressable identifiers you can invoke individually rather than a batch the agent works through on its own.

Interaction is by naming the tool in conversation rather than by calling a CLI subcommand, which is why there is no argument parser to learn. The README points to a separate prompting guide in `docs/` for more examples. The package itself is published as `@pimzino/spec-workflow-mcp` at version 2.2.7, written in TypeScript, distributed as compiled output from `dist/index.js`, and licensed GPL-3.0.

One piece of context is easy to miss and matters for expectations. The README opens with a notice that the author has taken a break from the repository for personal reasons and will return with updates. That sits above the badges, which means it is meant to be read before you plan around the project.

One dashboard for every project, running on port 5000

There are two front ends, and the README is explicit that the web dashboard is required for command-line users while the VSCode extension is the recommended path for people already in the editor. The extension is published to the Visual Studio marketplace as Pimzino.spec-workflow-mcp.

The dashboard starts separately from the MCP server, which surprises people the first time. You launch it explicitly:

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

It listens on port 5000 by default and is reached at localhost:5000. The most consequential detail in that section is the note that only one dashboard instance is needed, because all of your projects connect to the same dashboard. That makes the architecture clear: the MCP server holds the project context, and the dashboard is a shared view across projects rather than something you run per repository.

What the dashboard gives you is a monitoring surface rather than an editor. The feature list covers viewing specs, tracking tasks and progress with live updates, navigating documents, and visual progress bars with detailed status. Implementation logs are searchable and carry code statistics, which is the feature that turns the dashboard from a task board into a record of what actually happened to the code.

The approval workflow is the other half, and the README documents it in a video rather than in prose: create documents, request approval through the dashboard, provide feedback, and track revisions. A revision trail attached to a spec approval step is a meaningfully different design from asking an agent to proceed and reviewing the diff afterwards.

Eleven client configurations and the two that differ

The bulk of the README is a per-client setup section, and reading it is informative because it shows how much of the configuration burden the project pushes onto you. Augment, Claude Desktop, Cline, Continue, Cursor and Windsurf all take the same standard JSON shape, where the server is invoked through npx with the project path passed as an argument:

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

Two clients need different treatment and the README explains both, which is genuinely useful detail rather than boilerplate. For the Claude Code CLI there is an add command, and the notes flag two specific traps: the `-y` flag bypasses npm prompts for smoother installation, and the `--` separator ensures the path is passed to the spec-workflow script rather than to npx itself. Getting that separator wrong is the kind of mistake that produces a confusing error, so the documentation naming it saves a debugging session. A Windows alternative using `cmd.exe /c` is provided for cases where the first form does not work.

For Codex the configuration is TOML rather than JSON, and lives in the Codex config file:

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

OpenCode differs again with a schema key and a command given as an array. Across all of them the project path is passed as a trailing argument to the package, which is why that value is the one thing you edit in every configuration.

Multi-language support is a real feature rather than a boast: the repository root carries eleven README files, and the list includes English, Japanese, Chinese, Spanish, Portuguese, German, French, Russian, Italian, Korean and Arabic. There is a `validate:i18n` script in `package.json` to keep those in step, which suggests translations are checked in CI rather than drifting.

A repository shaped like a product, with no published releases

The file tree is broader than a typical MCP server, and the reason is visible in the names: `vscode-extension/` for the sidebar, `containers/` for the Docker deployment path, `e2e/` with two Playwright configurations, one of them for worktrees, and `scripts/` carrying i18n validation, MDX validation, static asset copying and a plugin version sync.

That plugin version sync is worth a second look. The presence of a `check:plugin-version` script and a `.claude-plugin/` directory at the root suggests the same rules are packaged for Claude Code plugins alongside the MCP server, and that the version is kept in sync automatically rather than by hand. The tree also carries `playwright.config.ts`, `vitest.config.ts` and `tsconfig.json`, so the project has both unit and end-to-end testing configured at the root.

The build script is more revealing than a typical one-liner. `npm run build` runs internationalisation validation, then a clean, then the TypeScript compile, then the dashboard build. The dashboard itself is a Vite application living under `src/dashboard_frontend/`, built separately and then copied into the published output by a script. In other words the npm package ships a compiled web front end alongside the server, which is why the dashboard can be a single command rather than something you host yourself.

Here is an inconsistency worth naming rather than resolving. The repository reports no published releases at all, yet `package.json` is at version 2.2.7 and a `CHANGELOG.md` sits at the root as one of the four files included in the published npm tarball. Both facts are true: development is tracked through the changelog and the package version, and GitHub releases are simply not used as a distribution channel. Check the changelog for what changed, not the releases page.

Where this sits against plain spec-driven discipline

The useful comparison is not with other MCP servers but with what you would otherwise do, which is write the specification yourself and hand it to an agent. Against that baseline, this project adds three things and charges you for them.

The first is enforced ordering. If requirements can only be followed by design, and design by tasks, the model cannot skip to code generation and call it done. The second is a review gate with a revision trail rather than a diff review after the fact. The third is a log that records what happened during implementation, with code statistics attached, which is the raw material for judging whether the agent did what the spec said.

The costs are real and mostly procedural. You now maintain documents that a tool expects to be well formed. You run a second process on port 5000. You adopt a GPL-3.0 dependency into your toolchain. And for teams who already run a lightweight spec practice in pull requests, the overhead may not buy much, because the approval step is the part that replaces an existing habit rather than filling a gap.

Where it is likely to pay off is on work that has an approval gate already: a data migration, an auth change, anything where a human with domain knowledge needs to sign off on the plan before code exists. That is a narrower case than the README's framing suggests, and it is also the case the feature list is actually built for.

The docs directory holds the prompting guide referenced from the usage examples, so that is the place to look for how the tool expects you to phrase requests before judging whether it fits your team. Docker deployment is described in the README as a way to run the dashboard in a container, which matters if port 5000 is not available to you on a shared machine.

Editorial conclusion

The mechanism worth understanding here is the ordering. Requirements, then design, then tasks, then an approval request, then implementation logs with code statistics, which means the tool is trying to make a document review gate sit between an agent's plan and an agent's writes. That is the piece that separates this from a prompt template, and it is also the piece that costs you the most process overhead. Two things to check before adopting it. The repository carries a notice that the author is on a break, with updates promised later, and the last push was 2026-07-03, so treat version 2.2.7 in `package.json` as the fixed point rather than expecting a cadence. And note that the project ships under GPL-3.0 while its whole purpose is to sit inside your development toolchain, so read the licence before wiring it into a proprietary codebase. Start with one spec end to end in a scratch repository, watch the approval round in the dashboard, and only then turn it loose on real work.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. Pimzino/spec-workflow-mcp on GitHub
4. README