Structured Workflow MCP

🚀 結構化工作流MCP服務器

本項目是一個MCP服務器，它通過要求AI助手在開發的每個階段審核其工作並生成經過驗證的輸出來強制推行規範的編程實踐。

🚀 快速開始

零安裝（推薦）

• 添加到AI助手配置：自動使用npx。
  • 注意：建議使用@latest以確保始終獲得最新功能和修復。如果不使用@latest，npx可能會緩存舊版本。
  • VS Code / Cursor / Windsurf：添加到MCP設置：

{
  "mcp": {
    "servers": {
      "structured-workflow": {
        "command": "npx",
        "args": ["structured-workflow-mcp@latest"],
        "env": {}
      }
    }
  }
}

- **Claude Desktop**：添加到`claude_desktop_config.json`：

{
  "mcpServers": {
    "structured-workflow": {
      "command": "npx",
      "args": ["structured-workflow-mcp@latest"],
      "env": {}
    }
  }
}

全局安裝（可選）

可以使用NPM在本地機器上全局安裝：

npm install -g structured-workflow-mcp

然後在AI助手配置中使用：

{
  "mcp": {
    "servers": {
      "structured-workflow": {
        "command": "structured-workflow-mcp",
        "args": [],
        "env": {}
      }
    }
  }
}

使用自定義輸出目錄：

{
  "mcp": {
    "servers": {
      "structured-workflow": {
        "command": "structured-workflow-mcp",
        "args": ["--output-dir", "/home/user/workflow-outputs"],
        "env": {}
      }
    }
  }
}

通過Smithery自動安裝

Smithery提供了多種直接安裝到應用程序的方法，例如Claude Desktop：

npx -y @smithery/cli install structured-workflow-mcp --client claude

手動安裝

對於開發者，可以克隆倉庫並在本地構建：

git clone https://github.com/kingdomseed/structured-workflow-mcp
cd structured-workflow-mcp
npm install && npm run build

✨ 主要特性

• 強制工作流階段：AI必須按順序完成特定階段（設置、審核、分析、規劃、實施、測試等）。
• 強制輸出工件：每個階段都需要結構化文檔或經過驗證的輸出才能繼續。
• 多種工作流類型：
  • 用於代碼改進的重構工作流。
  • 具有集成測試的功能開發工作流。
  • 用於提高測試覆蓋率的測試工作流。
  • 測試驅動開發（TDD）週期。
  • 滿足特定需求的自定義工作流。
• 輸出驗證：服務器驗證輸出包含有意義的內容和正確的結構。
• 會話狀態管理：跟蹤進度並防止跳過階段。

📚 詳細文檔

工作原理

AI通過以下步驟完成結構化工作流：

graph TD
    A[🚀 開始工作流] --> B[AI獲取階段指導]
    B --> C{創建階段輸出}
    C --> D[自動保存，使用編號命名<br/>00-setup-confirmation-2025-01-07.md]
    D --> E[階段驗證]
    E --> F{所有階段完成?}
    F -->|否| G[進入下一階段]
    G --> B
    F -->|是| H[工作流完成!]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style D fill:#e8f5e8
    style E fill:#fff9c4
    style H fill:#e8f5e8

每個步驟的說明：

1. 開始工作流：AI調用工作流工具（refactor_workflow、create_feature_workflow等）。
2. AI獲取階段指導：服務器為當前階段提供具體說明（審核、分析、實施等）。
3. 創建階段輸出：AI完成階段工作並創建文檔/工件。
4. 自動保存：文件以編號命名自動保存在任務目錄中。
5. 階段驗證：服務器驗證輸出是否滿足要求後再繼續。
6. 下一階段：重複此過程直到工作流完成。

這種分解的好處之一是AI代理只接收與當前階段相關的指令集，而不是整個工作流的指令。這有助於防止AI在整個工作流中迷失方向，而是專注於當前階段。可以在此處閱讀相關文章：LLMs Get Lost In Multi-Turn Conversation。

工作流輸出

AI生成的文檔

服務器在工作流階段推進時建議使用編號的工作流文件。AI助手使用自己的工具處理實際文件創建：

workflows/
├── your-task-name/
│   ├── 01-audit-inventory-2025-01-04.md
│   ├── 02-compare-analyze-2025-01-04.json
│   ├── 03-question-determine-2025-01-04.md
│   ├── 04-write-or-refactor-2025-01-04.md
│   ├── 05-test-2025-01-04.json
│   ├── 06-lint-2025-01-04.json
│   ├── 07-iterate-2025-01-04.md
│   └── 08-present-2025-01-04.md

工作流架構

• 文件處理：服務器提供建議的路徑和格式，但不直接寫入文件。相反，它指示AI助手使用自己的文件系統訪問權限創建這些文件。
• 一致命名：文件遵循標準化的命名約定，包含階段編號、名稱和時間戳。
• 環境獨立性：該架構可在AI具有適當文件系統權限的任何環境中工作。
• 優雅降級：如果AI無法創建文件，工作流將繼續以僅內存模式運行，不會中斷進度。

工具

工作流入口點

• refactor_workflow：啟動結構化重構過程，包含所需的分析和規劃階段。
• create_feature_workflow：開發新功能，具有集成測試和文檔要求。
• test_workflow：添加測試覆蓋率，強制分析需要測試的內容。
• tdd_workflow：實施測試驅動開發，強制遵循紅-綠-重構週期。
• build_custom_workflow：創建具有自定義階段和驗證要求的工作流。

階段指導工具

• audit_inventory_guidance：強制進行徹底的代碼分析和變更編目。
• compare_analyze_guidance：要求評估多種方法的優缺點。
• question_determine_guidance：強制進行澄清和最終規劃。
• phase_output：驗證並記錄每個階段的結構化輸出。
• workflow_status：檢查當前進度和驗證狀態。

使用方法

服務器通過強制階段來實施結構化工作流。每種工作流類型有不同的階段要求：

• 重構工作流：AUDIT_INVENTORY → COMPARE_ANALYZE → QUESTION_DETERMINE → WRITE_OR_REFACTOR → LINT → ITERATE → PRESENT
• 功能工作流：PLANNING → QUESTION_DETERMINE → WRITE_OR_REFACTOR → TEST → LINT → ITERATE → PRESENT
• 測試工作流：AUDIT_INVENTORY → QUESTION_DETERMINE → WRITE_OR_REFACTOR → TEST → ITERATE → PRESENT
• TDD工作流：PLANNING → WRITE_OR_REFACTOR → TEST → （紅-綠-重構週期） → LINT → PRESENT

輸入驗證

服務器要求：

• task（字符串）：描述要完成的任務。
• outputArtifacts（數組）：每個完成階段的結構化文檔。

輸出驗證

每個階段完成時會驗證以下內容：

• 有意義的內容長度（至少10個字符）。
• 結構化輸出的有效JSON格式。
• 特定階段的內容要求。
• 決策和分析的正確文檔記錄。

安全規則

在修改文件之前必須先讀取文件。這可以防止意外數據丟失，並確保進行有依據的更改。

示例輸出工件

服務器強制AI生成如下結構化輸出：

AUDIT_INVENTORY階段輸出：

{
  "filesAnalyzed": ["lib/auth/user_service.dart", "lib/auth/auth_middleware.dart"],
  "dependencies": {
    "providers": ["userProvider", "authStateProvider"],
    "models": ["User", "AuthToken"]
  },
  "issues": [
    "Single Responsibility Principle violation - handles too many concerns",
    "File approaching 366 lines - recommended to keep widgets smaller"
  ],
  "changesList": [
    {
      "action": "CREATE",
      "file": "lib/auth/components/auth_form.dart",
      "description": "Extract authentication form logic",
      "justification": "Component focused on form validation only"
    }
  ]
}

COMPARE_ANALYZE階段輸出：

{
  "approaches": [
    {
      "name": "Incremental Component Extraction",
      "complexity": "Medium",
      "risk": "Low", 
      "timeEstimate": "30-45 minutes"
    }
  ],
  "recommendation": "Incremental Component Extraction",
  "justification": "Provides best balance of benefits vs. risk",
  "selectedImplementationOrder": [
    "1. Extract form component (lowest risk)",
    "2. Create validation service",
    "3. Refactor main view"
  ]
}

每個階段都要求進行文檔化的分析和規劃，然後AI才能進入實施階段。

開發

npm run dev      # TypeScript編譯器處於監視模式
npm run lint     # 運行代碼檢查工具
npm run typecheck # 進行類型檢查
npm test         # 運行測試

測試MCP服務器

可以使用本倉庫中包含的測試提示和輔助腳本來快速試用結構化工作流MCP服務器。

1. 構建服務器（如果尚未構建）：

npm run build

2. 啟動服務器：

node dist/index.js

3. 在首選的MCP兼容AI客戶端中打開測試提示文件docs/test_prompt/mcp_server_test_prompt.md並粘貼內容。
4. 或者，打開位於refactor-test/的示例項目進行端到端的重構工作流演示。按照其README.md中的步驟運行並觀察結構化工作流的實際運行情況。
5. 觀察AI在每個階段的進展，並驗證生成的結構化輸出。

示例提示

docs/sample_prompts目錄包含幾個現成的提示，展示了典型的工作流：

• feature_workflow_prompt.md
• refactor_workflow_prompt.md
• test_workflow_prompt.md
• tdd_workflow_prompt.md
• custom_workflow_prompt.md

可以將這些作為起點，並根據項目進行調整。

構建

npm install
npm run build

服務器使用TypeScript和@modelcontextprotocol/sdk，並通過stdio傳輸在本地運行。

貢獻

歡迎並鼓勵提交拉取請求！無論是修復錯誤、添加功能還是改進文檔，您的貢獻都非常有價值。

請遵循以下步驟：

1. 在GitHub上分叉倉庫。
2. 創建新分支：git checkout -b feature/your-feature。
3. 進行更改並使用清晰、描述性的消息提交。
4. 為任何新功能編寫測試，並確保所有現有測試都通過。
5. 推送到您的分支：git push origin feature/your-feature。
6. 打開拉取請求並清晰描述您的更改。

有關更多詳細信息，請參閱CONTRIBUTING.md（如果有）。

感謝您的貢獻！

📄 許可證

此MCP服務器根據MIT許可證授權。這意味著您可以自由使用、修改和分發該軟件，但需遵守MIT許可證的條款和條件。