🚀 規範工作流MCP
這是一個模型上下文協議(MCP)服務器,為人工智能輔助軟件開發提供結構化的規範驅動開發工作流工具。其特色在於具備一個即時的Web儀表盤,可用於監控和管理項目進度。

🚀 快速開始
-
添加到您的AI工具配置中(請參閱下面的MCP客戶端設置):
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
注意:可以不指定項目路徑,但某些MCP客戶端可能無法從當前目錄啟動服務器。
-
啟動Web儀表盤(必需):
npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project --dashboard
npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project --dashboard --port 3000
npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project --dashboard --port=8080
選項:
--dashboard
- 啟動Web儀表盤(必需)
--port <number>
- 可選的自定義端口(1024 - 65535)。如果未指定,將使用臨時端口
⚠️ 重要提示
儀表盤對於工作流的正常運行是必需的。沒有它:
- 文檔審批將無法工作
- 任務進度跟蹤將被禁用
- 規範狀態更新將不可用
- 審批系統將無法正常工作
注意:MCP服務器和儀表盤現在是獨立的服務。您必須同時運行兩者:用於AI工具集成的MCP服務器和用於工作流管理、審批和進度跟蹤的儀表盤。
✨ 主要特性
- 結構化開發工作流 - 按順序創建規範(需求 → 設計 → 任務)
- 即時Web儀表盤 - 通過即時更新監控規範、任務和進度
- 文檔管理 - 從儀表盤查看和管理所有規範文檔
- 任務進度跟蹤 - 可視化進度條和詳細的任務狀態
- 指導文檔 - 項目願景、技術決策和結構指導
- 缺陷工作流 - 完整的缺陷報告和解決跟蹤
- 模板系統 - 所有文檔類型的預建模板
- 跨平臺 - 可在Windows、macOS和Linux上運行
💻 使用示例
基礎用法
您可以在對話中簡單提及 spec-workflow
或您為MCP服務器指定的任何名稱。AI將自動處理完整的工作流,或者您可以使用以下示例提示:
創建規範
- "Create a spec for user authentication" - 為該功能創建完整的規範工作流
- "Create a spec called payment-system" - 構建完整的需求 → 設計 → 任務
- "Build a spec for @prd" - 使用您現有的PRD創建完整的規範工作流
- "Create a spec for shopping-cart - include add to cart, quantity updates, and checkout integration" - 詳細的功能規範
獲取信息
- "List my specs" - 顯示所有規範及其當前狀態
- "Show me the user-auth progress" - 顯示詳細的進度信息
實施
- "Execute task 1.2 in spec user-auth" - 運行規範中的特定任務
- Copy prompts from dashboard - 使用儀表盤任務列表中的“Copy Prompt”按鈕
代理會自動處理審批工作流、任務管理,並引導您完成每個階段。
📚 詳細文檔
MCP客戶端設置
Augment Code
在您的Augment設置中進行配置:
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
Claude Code CLI
添加到您的MCP配置中:
claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest /path/to/your/project
注意 :在Windows上,您可能需要將命令包裝在 cmd.exe /c "npx -y @pimzino/spec-workflow-mcp@latest /path/to/your/project"
中。
Claude Desktop
添加到 claude_desktop_config.json
中:
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
Cline/Claude Dev
添加到您的MCP服務器配置中:
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
Continue IDE Extension
添加到您的Continue配置中:
{
"mcpServers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
Cursor IDE
添加到您的Cursor設置(settings.json
)中:
{
"mcp.servers": {
"spec-workflow": {
"command": "npx",
"args": ["-y", "@pimzino/spec-workflow-mcp@latest", "/path/to/your/project"]
}
}
}
OpenCode
添加到您的 opencode.json
配置文件(可以是全局的 ~/.config/opencode/opencode.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
}
}
}
注意:將 /path/to/your/project
替換為您希望規範工作流運行的項目目錄的實際路徑。
可用工具
工作流指南
spec-workflow-guide
- 規範驅動工作流過程的完整指南
steering-guide
- 創建項目指導文檔的指南
規範管理
create-spec-doc
- 創建/更新規範文檔(需求、設計、任務)
spec-list
- 列出所有帶有狀態信息的規範
spec-status
- 獲取特定規範的詳細狀態
manage-tasks
- 用於規範實施的全面任務管理
上下文和模板
get-template-context
- 獲取所有文檔類型的Markdown模板
get-steering-context
- 獲取項目指導上下文和指導
get-spec-context
- 獲取特定規範的上下文
指導文檔
create-steering-doc
- 創建項目指導文檔(產品、技術、結構)
審批系統
request-approval
- 請求用戶對文檔進行審批
get-approval-status
- 檢查審批狀態
delete-approval
- 清理已完成的審批
工作流過程
1. 項目設置(推薦)
steering-guide → create-steering-doc (product, tech, structure)
創建基礎文檔以指導您的項目開發。
2. 功能開發
spec-workflow-guide → create-spec-doc → [review] → implementation
按順序進行:需求 → 設計 → 任務 → 實施
3. 實施支持
- 使用
get-spec-context
獲取詳細的實施上下文
- 使用
manage-tasks
跟蹤任務完成情況
- 通過Web儀表盤監控進度
Web儀表盤
儀表盤是一個獨立的服務,必須與MCP服務器一起手動啟動。每個項目都有自己在臨時端口上運行的專用儀表盤。儀表盤提供:
- 即時項目概覽 - 規範和進度的即時更新
- 文檔查看器 - 閱讀需求、設計和任務文檔
- 任務進度跟蹤 - 可視化進度條和任務狀態
- 指導文檔 - 快速訪問項目指導
- 暗模式 - 自動啟用以提高可讀性
儀表盤特性
- 規範卡片 - 每個規範的概述,帶有狀態指示器
- 文檔導航 - 在需求、設計和任務之間切換
- 任務管理 - 查看任務進度並複製實施提示
- 即時更新 - 通過WebSocket連接實現即時項目狀態更新
🔧 技術細節
文件結構
your-project/
.spec-workflow/
steering/
product.md # 產品願景和目標
tech.md # 技術決策
structure.md # 項目結構指南
specs/
{spec-name}/
requirements.md # 需要構建的內容
design.md # 如何構建
tasks.md # 實施分解
approval/
{spec-name}/
{document-id}.json # 審批狀態跟蹤
開發
npm install
npm run build
npm run dev
npm start
npm run clean
故障排除
常見問題
-
儀表盤未啟動
- 確保在啟動儀表盤服務時使用了
--dashboard
標誌
- 儀表盤必須與MCP服務器分開啟動
- 檢查控制檯輸出以獲取儀表盤URL和任何錯誤消息
- 如果使用
--port
,確保端口號有效(1024 - 65535)且未被其他應用程序使用
-
審批無法工作
- 驗證儀表盤是否與MCP服務器一起運行
- 儀表盤對於文檔審批和任務跟蹤是必需的
- 檢查兩個服務是否指向同一項目目錄
-
MCP服務器未連接
- 驗證配置中的文件路徑是否正確
- 確保項目已使用
npm run build
進行構建
- 檢查系統路徑中是否有Node.js
-
端口衝突
- 如果收到“端口已被使用”錯誤,請使用
--port <different-number>
嘗試不同的端口
- 使用
netstat -an | find ":3000"
(Windows)或 lsof -i :3000
(macOS/Linux)檢查端口使用情況
- 省略
--port
參數以自動使用可用的臨時端口
-
儀表盤未更新
- 儀表盤使用WebSocket進行即時更新
- 如果連接丟失,請刷新瀏覽器
- 檢查控制檯是否有任何JavaScript錯誤
獲取幫助
- 查看 問題 頁面以瞭解已知問題
- 使用提供的模板創建新問題
- 使用工具中的工作流指南獲取分步說明
📄 許可證
GPL - 3.0
⭐ 星標歷史
📺 展示
🔄 審批系統演示
查看審批系統的工作方式:創建文檔、通過儀表盤請求審批、提供反饋並跟蹤修訂。
📊 儀表盤和規範管理
探索即時儀表盤:查看規範、跟蹤進度、導航文檔並監控開發工作流。
☕ 支持本項目