1. 为什么我把 Spec Workflow MCP 接进了日常开发流Spec Workflow MCP 是一个基于 Model Context Protocol 的开源服务端专门为规范驱动开发Spec-Driven Development设计。简单说它把「需求 → 设计 → 任务 → 实现」这条链路做成了 AI 能直接读写的结构化文档再配一个实时仪表盘让你看到每份规范走到哪一步。适合谁适合那些被「AI 写完代码但没人知道需求从哪来」折磨过的团队也适合一个人写项目、想让 AI 帮忙把需求先理清楚再动手的开发者。我第一次接触它是因为一个老问题用 AI 写代码很快但需求文档、设计决策、任务拆解全靠脑子记过两周回头看完全不知道当时为什么这么设计。Spec Workflow MCP 的思路是把这些中间产物落成 Markdown 文件放在项目的.spec-workflow/目录里AI 通过 MCP 工具去创建、查询、审批这些文档。它自带 Web 仪表盘和 VSCode 扩展支持多语言界面跨 Windows/macOS/Linux。但真正落地时有个绕不开的环节模型接入。Spec Workflow MCP 本身是工具层它要调用大模型来生成规范文档、做审批摘要、执行任务。如果你用多个客户端Claude Desktop、Cursor、Cline每个都要单独配 Key 和 Base URL管理起来很碎。我实测下来用 TaoToken 做统一 Key 和 API 通道会省事很多——一个 Key 覆盖多个客户端Base URL 指向同一入口模型 ID 按需切换。下面从拉项目开始把配置、验证、排错一次讲清楚。2. 从 GitHub 拉取 Spec Workflow MCP 并梳理工具链项目地址在 GitHub 上搜Pimzino/spec-workflow-mcp就能找到。我建议先 clone 到本地看结构再决定用 npx 跑还是装到项目里。git clone https://github.com/Pimzino/spec-workflow-mcp.git cd spec-workflow-mcp ls -la你会看到src/下面是 MCP 服务端实现templates/是文档模板库dashboard/是 Web 仪表盘前端。核心工具链分几类规范创建类生成需求/设计/任务文档、进度跟踪类实时任务状态、审批工作流类文档审批、反馈、修订、模板类预建 Markdown 模板、归档类完成规范归档。这些工具通过 MCP 协议暴露给 AI 客户端AI 在对话里用spec-workflow触发。环境要求不复杂Node.js 18npm 8内存 2GB 起步推荐 4GB。我用的 Node 20跑起来没遇到兼容问题。快速启动可以直接 npxnpx -y pimzino/spec-workflow-mcplatest /path/to/your/project --AutoStartDashboard --port 3456这条命令做了三件事把 MCP 服务端挂到你的项目目录、自动启动仪表盘、指定端口 3456。仪表盘起来后浏览器访问http://localhost:3456就能看到规范列表和进度条。工具链里我常用的几个create-spec-doc创建规范文档spec-list列出所有规范spec-status查具体规范状态get-spec-context拿详细上下文manage-tasks管理任务request-approval发起审批。这些命令在 AI 对话里用自然语言触发也行比如「spec-workflow 创建用户认证功能的规范」。配置文件用config.toml放在项目根目录projectDir /path/to/your/project port 3456 autoStartDashboard true dashboardOnly false lang zh [mcp] enabled true host localhost port 8080 [notifications] sound_enabled true approval_sound chime completion_sound success环境变量也可以覆盖export SPEC_PROJECT_DIR/path/to/your/project export SPEC_PORT3000 export SPEC_LANGzh export SPEC_AUTO_STARTtrue这里有个坑projectDir必须是绝对路径相对路径在 npx 启动时解析会出问题。我第一次用./my-project结果仪表盘读不到.spec-workflow/目录改成绝对路径就好了。3. 用 TaoToken 统一 Key 接入 MCP 客户端Spec Workflow MCP 要调模型就得在客户端侧配好 API 通道。我用 TaoToken 做统一入口官网在https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endAPI 地址是https://taotoken.net/api。先去控制台建 Key然后按客户端分别配。Claude Desktop 的配置在claude_desktop_config.json{ mcpServers: { spec-workflow: { command: npx, args: [ -y, pimzino/spec-workflow-mcplatest, /path/to/your/project, --AutoStartDashboard ], env: { OPENAI_API_KEY: 你的TaoToken Key, OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_MODEL: claude-sonnet-4-20250514 } } } }Cursor IDE 的配置在.cursor/mcp.json{ mcpServers: { spec-workflow: { command: npx, args: [ -y, pimzino/spec-workflow-mcplatest, /path/to/your/project ], env: { OPENAI_API_KEY: 你的TaoToken Key, OPENAI_BASE_URL: https://taotoken.net/api, OPENAI_MODEL: claude-sonnet-4-20250514 } } } }如果你用 Cline 或 CC Switch配置逻辑一样三件套必须写全Base URL 指向https://taotoken.net/apiKey 填 TaoToken 控制台生成的Model ID 按你需要的模型填。Codex 的auth.json里也是同样三个字段。注意Base URL 末尾不要加/v1TaoToken 的入口已经处理了路径。我试过加/v1结果 404去掉就正常。环境变量方式更适合多项目切换export OPENAI_API_KEY你的TaoToken Key export OPENAI_BASE_URLhttps://taotoken.net/api export OPENAI_MODELclaude-sonnet-4-20250514这样 Spec Workflow MCP 启动时会自动读取不用每个客户端单独配。我实测下来统一 Key 最大的好处是换模型不用改多处配置改一个环境变量就行。4. 端到端验证从规范生成到调用链路跑通配置完别急着写业务先做一次最小验证。我用的流程是启动 MCP 服务端 → 在 AI 对话里创建一份规范 → 检查仪表盘 → 确认模型调用成功。第一步启动服务端并确认仪表盘npx -y pimzino/spec-workflow-mcplatest /path/to/your/project --AutoStartDashboard --port 3456终端会输出类似Dashboard running at http://localhost:3456的信息。浏览器打开能看到空规范列表。第二步在 Claude Desktop 或 Cursor 里发一条指令spec-workflow 创建用户登录功能的规范文档类型是 requirements如果模型调用链路正常AI 会返回一份结构化的需求文档包含功能描述、用户故事、验收标准。同时项目目录下会出现.spec-workflow/specs/user-login/requirements.md。第三步检查仪表盘。刷新http://localhost:3456应该能看到user-login这条规范状态是draft进度条显示需求阶段完成。第四步验证模型调用确实走了 TaoToken。在 TaoToken 控制台的用量日志里能看到这次请求的记录模型 ID 和你配的一致。如果日志为空说明客户端没读到环境变量检查OPENAI_BASE_URL和OPENAI_API_KEY是否拼写正确。我踩过的一个坑Claude Desktop 的配置文件路径在 macOS 上是~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 上是%APPDATA%\Claude\claude_desktop_config.json。改完必须完全退出 Claude Desktop 再重启不是关窗口是右键退出。否则配置不生效AI 里spec-workflow根本没反应。验证通过后你可以继续用manage-tasks把需求拆成任务用request-approval走审批流。整个链路跑通一次后面就是重复使用。5. 常见报错排查401、local proxy failed、reading choices接入过程中最容易撞的几个错我按实际遇到的顺序列出来。401 UnauthorizedKey 没填对或者 Base URL 写错。检查OPENAI_API_KEY是不是 TaoToken 控制台生成的完整字符串OPENAI_BASE_URL是不是https://taotoken.net/api。如果 Key 复制时带了空格也会 401。我建议重新生成一个 Key 再试。local proxy failed / connection refusedMCP 服务端没起来或者端口被占。先确认npx命令的终端还在运行没被关掉。然后检查 3456 端口是否被其他程序占用lsof -i :3456如果有输出换个端口重启比如--port 3457。reading choices of undefined这是模型返回格式不对通常是 Base URL 指向了错误的路径。TaoToken 的 API 入口是https://taotoken.net/api不要加/v1或/chat/completions。另外确认 Model ID 是 TaoToken 支持的填错模型名也会返回空响应导致这个错。OAuth 相关报错如果你在 Cursor 里看到 OAuth 失败说明客户端在尝试走它自己的登录流程而不是用你配的 Key。检查.cursor/mcp.json里env字段是否被正确读取有时候 Cursor 会缓存旧配置重启 IDE 能解决。仪表盘空白 / 读不到规范projectDir路径不对或者.spec-workflow/目录没生成。先确认projectDir是绝对路径然后手动在项目里跑一次创建规范的操作看目录是否出现。如果目录出现了但仪表盘还是空检查config.toml里的port和启动命令的--port是否一致。审批流卡住request-approval发起了但状态不变通常是审批人配置没写对。检查config.toml里的[approval]段approvers列表里的角色名要和实际使用的一致。我建议先用单级审批测试跑通再加多级。提示每次改完配置文件MCP 服务端和客户端都要重启。MCP 服务端重启是 CtrlC 再跑一次 npx 命令客户端重启是退出应用再打开。6. 把 Spec Workflow MCP 用顺手的几个实操建议跑通之后我总结了几条让这套流程真正省事的做法。第一模板先定制。templates/目录下的 Markdown 模板可以改把你们团队的需求格式、验收标准写法固化进去。这样 AI 生成的规范直接符合内部规范不用每次手动调。第二审批流从简到繁。一开始别配多级审批先用单级跑通确认文档流转没问题再按风险等级加条件审批。config.toml里的approval_rules支持按risk_level字段分流高风险的走三人审批低风险的一个人确认就行。第三仪表盘常开。--AutoStartDashboard让它跟着 MCP 服务端一起起浏览器标签页留着任务进度实时更新。WebSocket 推送比手动刷新靠谱。第四Key 和模型分离管理。TaoToken 的 Key 放在环境变量里模型 ID 按项目需要切换。比如规范生成用强模型任务拆解用快模型改OPENAI_MODEL就行不用动 Key。如果你要长期跑编码和 Agent 任务可以看看 TaoToken 的 Coding Plan按量用比单次调用划算。模型对话入口在https://taotoken.net/api对应的控制台里API Keys 管理也在那。接入文档在官网的 doc 页面Claude Code 相关的配置参考 ClaudeCodeAnthropic 那节。最后说个真实体验Spec Workflow MCP 最大的价值不是让 AI 写更多代码而是让 AI 写代码之前先把「为什么写」落成文档。我用它之后回头看两周前的项目打开.spec-workflow/目录就能还原当时的决策链路。这个习惯一旦养成AI 辅助开发才真正可控。