Spec Workflow MCP

🚀 規範工作流MCP

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

🚀 快速開始

1. 添加到您的AI工具配置中（請參閱下面的MCP客戶端設置）：

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

   注意：可以不指定項目路徑，但某些MCP客戶端可能無法從當前目錄啟動服務器。

2. 啟動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客戶端設置

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

claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest /path/to/your/project

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

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

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

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

{
  "$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

故障排除

常見問題

1. 儀表盤未啟動

   • 確保在啟動儀表盤服務時使用了 --dashboard 標誌
   • 儀表盤必須與MCP服務器分開啟動
   • 檢查控制檯輸出以獲取儀表盤URL和任何錯誤消息
   • 如果使用 --port，確保端口號有效（1024 - 65535）且未被其他應用程序使用

2. 審批無法工作

   • 驗證儀表盤是否與MCP服務器一起運行
   • 儀表盤對於文檔審批和任務跟蹤是必需的
   • 檢查兩個服務是否指向同一項目目錄

3. MCP服務器未連接

   • 驗證配置中的文件路徑是否正確
   • 確保項目已使用 npm run build 進行構建
   • 檢查系統路徑中是否有Node.js

4. 端口衝突

   • 如果收到“端口已被使用”錯誤，請使用 --port <different-number> 嘗試不同的端口
   • 使用 netstat -an | find ":3000"（Windows）或 lsof -i :3000（macOS/Linux）檢查端口使用情況
   • 省略 --port 參數以自動使用可用的臨時端口

5. 儀表盤未更新

   • 儀表盤使用WebSocket進行即時更新
   • 如果連接丟失，請刷新瀏覽器
   • 檢查控制檯是否有任何JavaScript錯誤

獲取幫助

• 查看 問題 頁面以瞭解已知問題
• 使用提供的模板創建新問題
• 使用工具中的工作流指南獲取分步說明

📄 許可證

GPL - 3.0

⭐ 星標歷史

📺 展示

🔄 審批系統演示

查看審批系統的工作方式：創建文檔、通過儀表盤請求審批、提供反饋並跟蹤修訂。

📊 儀表盤和規範管理

探索即時儀表盤：查看規範、跟蹤進度、導航文檔並監控開發工作流。

☕ 支持本項目