spec-workflow-mcp

给 AI 编程工具装上"项目管理大脑"

想象一下：你让 Claude 写一个用户登录功能，结果 Claude 一口气写完了所有代码，却没有告诉你它做了什么、用了多久、符不符合你的预期。等你去检查的时候，发现密码加密方式不是你想要的、测试用例也没写。这种"AI 干了活但你不清楚过程"的问题，正是 Spec Workflow MCP 要解决的痛点。

Spec Workflow MCP 是一个基于 Model Context Protocol（MCP）协议的工作流管理工具。它的核心理念是：让 AI 编程工具按照"规范文档 → 设计文档 → 任务清单"的结构化流程来工作，而不是一上来就埋头写代码。开发者可以在实时 Dashboard 或 VSCode 插件中全程监控 AI 的执行进度，就像监工一样看着施工队干活。

背景：AI 编程爆发，但"协作规范"成了新瓶颈

2023 年以来，Claude Code、Cursor、Cline、Augment Code 等 AI 编程工具迅速普及。但这些工具都有一个共同问题：它们太"自主"了。当你下达一个模糊的任务（比如"给这个项目加上用户认证"），AI 会立刻开始写代码，中途不会停下来问你密码用什么加密算法、要不要支持双因素认证——等你发现不对的时候，代码已经写完了。

MCP（Model Context Protocol）是由 Anthropic 主导推出的开放协议，允许 AI 工具调用外部工具和数据源。Pimzino 在 2024 年初创建了 spec-workflow-mcp 项目，将传统的"需求 → 设计 → 开发"工作流引入 AI 编程场景。目前该项目已获得超过 4200 颗 GitHub Stars，支持 11 种语言文档，社区活跃度在 MCP 相关工具中位居前列。

类比理解：给 AI 编程工具装上"项目经理"

可以把普通的 AI 编程工具想象成一个执行力强但不会主动汇报的实习生——你让它做什么它就做什么，但不会主动确认方向、不会分阶段汇报、不会等你审核关键决策。

Spec Workflow MCP 就是在实习生旁边安插了一个项目经理（MCP Server），负责：

• 拆解任务：把"实现用户认证"拆成 5 个子任务，逐个执行
• 阶段审批：每个关键步骤完成后停下来等你确认
• 实时监控：Dashboard 上实时显示当前在做什么、已完成多少、还剩多少
• 存档记录：所有操作都有日志，方便回溯

核心功能：三层架构打造完整工作流

规范驱动开发（Spec-Driven Workflow）

这是整个工具的核心理念。开发者用自然语言描述需求后，Spec Workflow MCP 会自动生成一套结构化文档体系：

• Requirements（需求文档）：描述要做什么
• Design（设计文档）：描述怎么做，包括技术选型、API 设计、数据模型
• Tasks（任务清单）：把设计拆成可执行的具体任务，带优先级和状态

这套流程的好处是：AI 在动手之前先写计划，开发者审核通过后再执行。不会出现"代码写完了才发现方向错了"的情况。

实时 Web Dashboard

Dashboard 基于 Fastify 后端 + React 前端，通过 WebSocket 实现真正的实时更新。界面包含 Spec 列表视图（支持状态筛选）、任务看板（拖拽排序）、审批系统（批量审批/驳回，带撤销）、实现日志（记录每个任务的具体操作和代码行数统计）。

VSCode 插件

对于习惯在 VSCode 中开发的用户，项目提供了专用侧边栏插件。插件功能与 Web Dashboard 基本一致，集成在 IDE 内部，无需切换浏览器。

图1：Dashboard 的批量审批界面，支持一次性处理多个待审核项

图2：任务操作后的即时反馈提示

支持 12 种主流 AI 编程工具

项目对 MCP 客户端的覆盖非常全面，几乎涵盖了市面上所有主流 AI 编程工具：Claude Code CLI、Cline、Augment Code、Cursor、Windsurf、Continue（VSCode/JetBrains）、Claude Desktop、OpenCode、Codex 等。这种广泛的兼容性让团队可以根据成员偏好选择不同工具，同时使用同一套工作流规范。

技术架构：TypeScript 全栈，Fastify + React 黄金组合

后端技术栈

Fastify 是项目选择的后端框架，相比 Express 有更好的类型安全和性能表现。项目使用了以下关键依赖：

• @modelcontextprotocol/sdk：MCP 协议官方 SDK，处理 AI 工具与外部服务的通信
• fastify-websocket：WebSocket 支持，实现 Dashboard 实时推送
• fastify-cors：跨域控制，默认仅允许 localhost 访问（安全加固）
• chokidar：文件系统监控，检测项目目录变化
• simple-git：Git 操作集成，追踪代码变更
• zod：运行时类型验证，确保配置合法性

前端技术栈

前端使用 React 18 + Vite 构建，UI 框架采用了 Tailwind CSS + shadcn/ui 风格的组件库。值得关注的是 @dnd-kit（任务看板拖拽）、@mdxeditor/editor（MDX 富文本编辑器）、mermaid（流程图渲染）、i18next（11种语言国际化）。

构建与测试

项目使用 Vitest 作为测试框架，配合 Playwright 做端到端测试。构建脚本中包含 i18n 校验，确保所有文档翻译完整。

安全性：企业级加固，但 HTTPS 需自建

项目在安全方面做了相当充分的考虑。默认配置下，Dashboard 仅绑定 127.0.0.1，不会暴露到公网；速率限制（120请求/分钟/客户端）、CORS 严格限制、Security Headers（X-Frame-Options、CSP 等）均已默认开启。

不过项目文档也坦诚说明了尚未实现的两个重要功能：HTTPS/TLS 加密和用户认证。如果需要网络访问，需要自己架设 nginx 反向代理并配置 Basic Auth 或 OAuth2 SSO。Docker 部署方面提供了加固配置：非 root 用户运行、文件系统只读、必要 Capabilities 剥离、资源限制。

局限与争议

1. MCP 协议本身的局限性

Spec Workflow MCP 的能力受限于 MCP 协议本身。目前 MCP 的工具调用是单向的（AI 调用工具），尚不支持工具主动向 AI 推送复杂事件通知。Dashboard 上的实时更新依赖 WebSocket 直连，而非通过 MCP 协议传递。

2. 仅支持本地项目

工具设计为监控本地文件系统上的项目，不支持远程项目管理。对于分布式团队，可能需要额外的共享文件系统方案（如 NFS）才能共用 Dashboard。

3. 过度规范可能降低效率

对于简单的一次性脚本或探索性项目，完整的 Spec → Design → Task 三阶段流程显得有些杀鸡用牛刀。项目文档中也承认这一点，建议在简单场景下直接跳过部分环节。

行业意义：填补 AI 编程"过程管理"空白

随着 AI 编程工具的普及，一个新问题浮出水面：如何确保 AI 的工作符合预期？传统的代码审查（Code Review）只能检查结果，无法干预过程。

Spec Workflow MCP 提供了一种过程前置的解决思路：不是等 AI 写完代码再审查，而是在 AI 动手之前就明确规范和边界。这种"先签合同再干活"的理念，对于需要高质量输出的企业级项目有重要价值。

目前项目 Star 增长曲线显示其在 2025 年初有明显加速，与 Claude Code 等工具的大规模采用时间点吻合。这说明市场确实存在对"有结构化流程的 AI 编程"的需求。Spec Workflow MCP 已经成为这个方向的标杆项目。

图3：项目通过 Buy Me a Coffee 接受社区资助，体现了独立开发者维护项目的模式

图4：Dashboard 的批量全选操作界面