Dev Workflow MCP Server

🚀 開發工作流MCP服務器

這是一個MCP（模型上下文協議）服務器，它有助於強化開發規範和遵循最佳工作流程實踐。該服務器就像你編碼時的“良心”，時刻提醒你遵循正確的開發流程。

🚀 快速開始

本MCP服務器引導你遵循規範的開發工作流程：

1. 明確目標 - 清楚你要編寫的代碼內容。
2. 修復/實現 - 編寫代碼。
3. 創建測試 - 始終對你的更改進行測試。
4. 運行測試 - 測試必須通過（顯示綠色）。
5. 文檔記錄 - 更新文檔。
6. 提交併推送 - 驗證通過後，讓服務器暫存、提交併推送你的更改（如果之後你進行了新的編輯，工作流程將自動回到此步驟）。
7. 發佈 - 推送成功後，記錄發佈詳情，然後完成任務。

✨ 主要特性

🛡️ 彈性特性

• 啟動彈性：外部數據庫的連接超時時間為5秒。
• 後臺加載：非關鍵資產（兼容性鏡像）在後臺初始化，以確保亞秒級啟動。
• 診斷模式：自動將啟動計時日誌顯示在標準錯誤輸出中。

v1.8.0版本新特性

• 模塊化處理程序架構 – tools/handlers.js 現在重新導出專注的處理程序模塊，提高了可維護性和打包器性能。
• 組織化測試套件 – 1000行的 tests/handlers.test.js 已拆分為多個 handlers-*.test.js 文件，並使用共享輔助函數，減少了重複代碼並明確了意圖。
• 共享測試實用工具 – 新的 tests/test-helpers.js 集中了工作流狀態設置、請求構建器和Git模擬。
• 文檔更新 – 產品需求文檔（PRD）移至 docs/PRD.md 根目錄，狀態更新為v1.8.0，並更新了發佈說明以反映當前工作流程。
• 發佈規範 – 推薦的流程現在包括 npm run release:<type> ，然後執行 git push --follow-tags origin main 以保持階段清晰。

📦 安裝指南

選項1：作為項目依賴安裝（推薦）

每個項目都會有自己獨立的工作流狀態文件。

npm install @programinglive/dev-workflow-mcp-server

這將在你運行 npm install 的項目中自動創建一個 .state/workflow-state.json 文件（使用npm的 INIT_CWD），使每個項目的工作流歷史記錄保持獨立。如果你是在安裝包本身（在 node_modules 內部），腳本會跳過創建步驟，以免汙染共享包目錄。

選項2：從源代碼安裝

git clone https://github.com/programinglive/dev-workflow-mcp-server.git
cd dev-workflow-mcp-server
npm install

Windows系統前置要求：從源代碼安裝依賴項時會編譯本地模塊，如 better-sqlite3。在運行 npm install 之前，請確保已安裝Python 3（並添加到系統路徑）和Visual Studio Build Tools的 “使用C++進行桌面開發” 工作負載。否則，npm將因 “需要Python” 或構建錯誤而失敗。

選項3：在Plesk主機上安裝

Plesk通過其Node.js擴展支持Node.js應用程序。要在Plesk訂閱中部署MCP服務器，請按照以下步驟操作：

1. 啟用Node.js支持 – 確保Plesk管理員已安裝Node.js擴展併為你的訂閱啟用了SSH訪問。
2. 上傳項目 – 可以克隆存儲庫或將存檔上傳到你要運行它的目錄（例如 httpdocs/dev-workflow-mcp-server）。你可以通過SSH運行以下命令：

   cd httpdocs
   git clone https://github.com/programinglive/dev-workflow-mcp-server.git
   cd dev-workflow-mcp-server
   

3. 安裝依賴項 – 在Plesk的 Node.js 面板中使用 “NPM install”（或通過SSH運行 npm install --production）。Linux主機已經預裝了 better-sqlite3 所需的Python/構建工具鏈；如果你的計劃使用Windows主機，請事先安裝Python 3和Visual Studio Build Tools，或者要求你的提供商啟用它們。
4. 定義環境變量 – 在Node.js面板中添加你需要的任何環境變量（例如 DEV_WORKFLOW_USER_ID 或 DEV_WORKFLOW_STATE_FILE）。如果需要，這可以將狀態文件保存在Web根目錄之外。
5. 配置應用程序 – 將 應用程序啟動文件 設置為 index.js，將 應用程序模式 設置為 production。Plesk將使用 node index.js 運行服務器。
6. 啟動/重啟應用程序 – 點擊 “Restart App”，使Plesk使用新配置啟動MCP服務器。當你更新代碼時，重新運行 “NPM install” 並重啟。

提示：MCP服務器通過標準輸入輸出進行通信。如果你只需要將其作為CLI工具使用，也可以直接在SSH會話中運行 npx @programinglive/dev-workflow-mcp-server，而無需在Node.js面板下保持其運行。

重要提示：MCP客戶端（如Windsurf、Claude Desktop等）必須通過標準輸入輸出在本地啟動服務器進程。在公共域名上託管儀表板並不會暴露MCP接口。如果沒有SSH或其他在服務器上執行 node index.js 的方法，用戶無法將其MCP客戶端連接到託管實例。

選項4：使用Docker在Google Cloud上部署

使用Docker和PostgreSQL將MCP服務器部署到Google Cloud Compute Engine，以實現生產就緒的雲託管設置。 快速開始：

1. 通過SSH連接到你的GCP實例。
2. 運行設置腳本：bash scripts/setup-gcp-instance.sh。
3. 克隆存儲庫並配置 .env 文件。
4. 啟動容器：docker-compose up -d。
5. 更新本地MCP客戶端配置以通過SSH連接。

優點：

• ✅ 使用PostgreSQL數據庫實現強大的數據持久化。
• ✅ 容器化部署確保一致性。
• ✅ 可通過SSH隧道進行遠程訪問。
• ✅ 易於更新和回滾。

請參閱 GCP部署指南 以獲取完整的分步說明。

💻 使用示例

配置客戶端

兩種使用模式

• 本地（源代碼）：將你的MCP客戶端指向 index.js。這將直接從源代碼運行，無需構建步驟。推薦用於MCP使用場景。
• 生產（已構建）：運行一次 npm run build 以生成 dist/ 目錄。這將創建一個優化的捆綁包，但在MCP使用場景中不是必需的。

在Windsurf/Claude Desktop中配置

將你的MCP客戶端指向服務器入口點。將 <PROJECT_ROOT> 替換為你機器上此存儲庫的絕對路徑。

macOS

• Windsurf (~/Library/Application Support/Windsurf/config.json)：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "cwd": "<PROJECT_ROOT>",
      "args": ["index.js"],
      "env": {
        "DEV_WORKFLOW_DB_TYPE": "postgres",
        "DEV_WORKFLOW_DB_URL": "postgres://USER:PASS@HOST:5432/devworkflow"
      }
    }
  }
}

• Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>/index.js"]
    }
  }
}

Windows

• Windsurf (%APPDATA%\Windsurf\config.json)：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>\\index.js"]
    }
  }
}

• Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json)：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>\\index.js"]
    }
  }
}

Linux

• Windsurf (~/.config/windsurf/config.json)：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>/index.js"]
    }
  }
}

• Claude Desktop (~/.config/claude/claude_desktop_config.json)：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>/index.js"]
    }
  }
}

注意：在Windows系統的JSON文件中，路徑需要使用轉義反斜槓（例如 "C:\\path\\to\\project"）。

完整的Windsurf MCP配置示例（macOS）

如果你將此存儲庫檢出到 /Users/alex/code/dev-workflow-mcp-server 並希望將Windsurf指向託管的PostgreSQL實例，請將以下內容放入 ~/Library/Application Support/Windsurf/mcp_config.json：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "cwd": "/Users/alex/code/dev-workflow-mcp-server",
      "args": ["index.js"],
      "env": {
        "DEV_WORKFLOW_DB_TYPE": "postgres",
        "DEV_WORKFLOW_DB_URL": "postgres://devworkflow:devworkflow_secure_password@34.50.121.142:5432/devworkflow"
      }
    }
  }
}

這與之前版本中共享的Windows配置類似，但通過直接啟動本地的 index.js 避免了在macOS上使用 npx 時的查找問題。

重啟Windsurf/Claude Desktop

添加配置後，重啟應用程序以加載MCP服務器。

在Antigravity中配置

Antigravity用戶應在其 mcp_config.json 中配置MCP服務器。 Windows：%APPDATA%\Antigravity\mcp_config.json 或 C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>\\index.js"]
    }
  }
}

請參閱 Antigravity入門指南 以獲取詳細說明和故障排除信息。

⚡ 性能優化（推薦）

為確保最快的啟動速度（這對於像Claude Desktop這樣集成到IDE中的客戶端至關重要），我們建議直接使用 node 指向 index.js，而不是使用 npx。這可以避免檢查包更新的開銷。 優化配置：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["<PROJECT_ROOT>\\index.js"],
      "env": {
        "DEV_WORKFLOW_USER_ID": "your_user_id"
      }
    }
  }
}

服務器會自動記錄其啟動時間並將其記錄到標準錯誤輸出中： Dev Workflow MCP Server running on stdio (startup took 15ms)

📚 詳細文檔

⚙️ 配置

數據庫設置

服務器支持 SQLite（默認）、MySQL 和 PostgreSQL。

通過 .env 文件配置

1. 將 .env.example 複製為 .env：

   cp .env.example .env
   

2. 使用你的設置編輯 .env 文件：

   DEV_WORKFLOW_DB_TYPE=mysql
   DEV_WORKFLOW_DB_URL=mysql://user:pass@localhost:3306/db
   

通過環境變量配置

或者，直接導出變量：

變量	描述	默認值
DEV_WORKFLOW_DB_TYPE	數據庫驅動（sqlite、mysql、postgres）	sqlite
DEV_WORKFLOW_DB_URL	MySQL/Postgres的連接字符串	null
DEV_WORKFLOW_DB_PATH	覆蓋SQLite數據庫文件的路徑	<project>/.state/dev-workflow.db

示例

MySQL：

export DEV_WORKFLOW_DB_TYPE=mysql
export DEV_WORKFLOW_DB_URL="mysql://user:password@localhost:3306/dev_workflow"

PostgreSQL：

export DEV_WORKFLOW_DB_TYPE=postgres
export DEV_WORKFLOW_DB_URL="postgresql://user:password@localhost:5432/dev_workflow"

🛠️ 數據庫模式規範化（Postgres/MySQL）

為確保與現有報告儀表板兼容，PostgresAdapter 和 MysqlAdapter 會自動規範化列名：

• task_description → 數據庫列：description
• timestamp → 數據庫列：completed_at 適配器在查詢中使用別名，因此MCP工具仍然可以接收到預期的 task_description 和 timestamp 字段。

👤 用戶ID處理（Postgres/MySQL）

這些數據庫使用 INTEGER 列來存儲 user_id。

• 數字字符串（例如 "1"）會直接解析為整數。
• 非數字字符串（例如 "programinglive"）會自動哈希為一個一致的正整數，以確保與模式兼容，同時保持用戶隔離。

用戶與狀態管理

變量	描述
DEV_WORKFLOW_USER_ID	覆蓋自動生成的用戶ID（例如，設置為你的姓名/電子郵件）
DEV_WORKFLOW_STATE_FILE	覆蓋 workflow-state.json 文件的位置

使用多個客戶端（Antigravity & Windsurf）

如果你在同一個項目上同時使用多個AI編碼工具（例如Antigravity和Windsurf），默認情況下它們將共享相同的工作流狀態。 為每個工具維護 獨立的會話，請為每個工具配置唯一的 DEV_WORKFLOW_USER_ID。 Antigravity配置 (mcp_config.json)：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["path/to/server/index.js"],
      "env": {
        "DEV_WORKFLOW_USER_ID": "antigravity_user"
      }
    }
  }
}

Windsurf配置： 在你的Windsurf MCP設置中添加環境變量：

{
  "mcpServers": {
    "dev-workflow": {
      "command": "node",
      "args": ["path/to/server/index.js"],
      "env": {
        "DEV_WORKFLOW_USER_ID": "windsurf_user"
      }
    }
  }
}

✅ 測試

項目使用Node.js的原生測試運行器（node --test）。

npm test

這將運行：

• 工作流邏輯的單元測試。
• .env 配置的集成測試。
• 數據庫適配器測試（始終測試SQLite；如果配置了MySQL/Postgres，則也會測試）。

測試數據庫適配器

要驗證MySQL或PostgreSQL適配器，請在設置環境變量的情況下運行測試：

# 測試MySQL
export DEV_WORKFLOW_DB_URL="mysql://root:pass@localhost:3306/test_db"
node --test tests/db-adapters.test.js

# 測試PostgreSQL
export DEV_WORKFLOW_DB_URL="postgres://postgres:pass@localhost:5432/test_db"
node --test tests/db-adapters.test.js

腳本

• npm run build - 將源代碼打包到 dist/index.mjs 中以供分發。
• npm run dev - 在開發模式下運行，並監視文件更改。
• npm run local - 從源代碼運行的別名（與 npm start 相同）。
• npm run web - 啟動輕量級工作流儀表板，用於瀏覽任務歷史記錄（請參閱 Web儀表板文檔）。

npm run web

此命令將啟動 web/server.js 中定義的儀表板，讓你快速查看工作流歷史記錄和摘要統計信息。

npm run web
# 🌐 Dev Workflow Dashboard running at http://localhost:3111

• 默認端口：3111（如果被佔用，則使用下一個可用端口）。
• 環境覆蓋：優先使用 PORT（在Plesk/Render等主機上常見）或 DEV_WORKFLOW_WEB_PORT，然後再進行自動選擇。
• 查詢參數：?user=<id> 允許你查看其他用戶的歷史記錄（默認為 default）。
• API端點：
  • GET /api/version → 從 package.json 中獲取當前包版本（儀表板用於動態顯示版本）。
  • GET /api/summary?user=<id> → 用戶的總體統計信息。
  • GET /api/history?user=<id>&page=1&pageSize=20&startDate=YYYY-MM-DD&endDate=YYYY-MM-DD → 分頁的任務歷史記錄。
  • GET /api/history-summary?user=<id>&frequency=daily|monthly|yearly → 隨時間聚合的計數。

在瀏覽器中打開 http://localhost:3111 以查看儀表板UI（web/index.html）。

構建輸出

運行 npm run build 會生成：

• dist/index.mjs - 優化的ES模塊捆綁包。
• 源映射和其他構建工件。
• dist/docs/ - 通過 scripts/build-docs.js 從Markdown預渲染的HTML文檔。 構建過程會捆綁所有源文件，同時將Node.js內置模塊和依賴項外部化，從而生成單個文件分發。

使用方法

對於MCP服務器的使用，將你的客戶端指向 index.js（源代碼），以避免標準輸入輸出傳輸兼容性問題。構建後的 dist/index.mjs 主要用於：

• npm包分發。
• 性能優化。
• 嵌入其他項目。

MCP工具註冊表（發佈）

此包已配置為使用 npm包部署 到官方MCP工具註冊表。

• package.json 聲明 mcpName: "io.github.programinglive/dev-workflow-mcp-server"。
• server.json 描述服務器並將其鏈接到npm包 @programinglive/dev-workflow-mcp-server。 要將新的服務器版本發佈到註冊表，請執行以下操作：

1. 發佈新的npm版本（例如）：
   • npm test
   • npm run release:patch（運行現有的發佈管道併發布到npm）
2. 驗證新的版本是否存在於npm上：
   • npm view @programinglive/dev-workflow-mcp-server version
3. 安裝MCP發佈者CLI（每臺機器只需安裝一次）：
   • brew install mcp-publisher（或遵循 https://modelcontextprotocol.info/tools/registry/publishing/ 上的文檔）
4. 從該存儲庫的根目錄進行身份驗證併發布：
   • mcp-publisher login github
   • mcp-publisher publish
5. 可選：在註冊表中驗證：
   • curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.programinglive/dev-workflow-mcp-server"

PowerShell CLI提示

從PowerShell調用輕量級CLI時，使用 --% 以防止PowerShell重寫JSON參數，例如：

node --% index.js call start_task --args "{\"description\":\"Convert docs to HTML during build\",\"type\":\"feature\"}"

--% 前綴和轉義的雙引號確保JSON數據完整地傳遞給MCP服務器。

📁 特定項目的工作流狀態

當你在項目中安裝此包時，會在項目根目錄自動創建一個 .state/workflow-state.json 文件。該文件：

• 存儲特定項目的工作流歷史記錄。
• 獨立跟蹤每個項目的任務進度。
• 應添加到Git忽略列表（默認情況下已在 .gitignore 中）。
• 跨會話持久化，以保留你的工作流狀態。
• 保持集中管理，即使你從嵌套的構建輸出（如 dist/）中運行服務器。MCP服務器會回溯到項目根目錄（查找 .git 或 package.json），然後再讀取或寫入工作流狀態，因此你無需在構建目錄下創建重複的副本。

每個項目都維護自己獨立的工作流歷史記錄，因此你可以同時處理多個項目而不會混淆它們的歷史記錄。在 .state 目錄中，MCP服務器會自動為每個用戶創建一個唯一的子目錄（例如 .state/users/user-abc123/）。生成的標識符會在本地持久化，因此多個共享同一存儲庫的開發人員不會相互覆蓋工作流文件。如果你希望使用特定的名稱，請在啟動服務器之前設置 DEV_WORKFLOW_USER_ID，該值將代替自動生成的ID。

選擇用戶ID

使用場景：

1. 讓服務器選擇 – 無需進行任何操作，當你第一次運行任何MCP工具時，服務器會創建 .state/users/<random-id>/ 目錄。儀表板的 User ID 過濾器可以接受該值（可在文件夾名稱或工作流響應中看到）。
2. 設置顯式ID – 在啟動服務器之前，導出 DEV_WORKFLOW_USER_ID：

   # macOS/Linux
   export DEV_WORKFLOW_USER_ID=alice
   node index.js
   
   # Windows PowerShell
   $env:DEV_WORKFLOW_USER_ID = "alice"
   node index.js
   

   現在，該會話的所有歷史記錄都將存儲在 .state/users/alice/ 目錄中，並且可以在儀表板中使用 alice 進行過濾。
3. 一臺主機上的多個用戶 – 使用不同的 DEV_WORKFLOW_USER_ID 值運行單獨的進程（或MCP客戶端）。每個用戶的工作流狀態將保持獨立。

提示：Web儀表板只是讀取現有的記錄。在工作流會話將歷史記錄寫入 .state/users/<that-id>/ 目錄之前，在 User ID 過濾器中輸入新值將不會返回任何結果。

添加到 .gitignore

如果你使用此包，請將以下內容添加到項目的 .gitignore 文件中：

.state/

這將使工作流狀態保留在每個開發人員的本地機器上。

需要覆蓋位置？ 在啟動服務器之前（或在你的MCP客戶端配置中）設置 DEV_WORKFLOW_STATE_FILE=/absolute/path/to/your/project/.state/workflow-state.json。服務器將使用該路徑，讓你可以集中安裝包，同時維護每個項目的工作流歷史記錄。

🛠️ 可用工具

工具參數要求

所有工具調用在運行之前都會驗證其 arguments 有效負載：

• 字符串將被解析為JSON，並且必須解析為對象（鍵/值對）。
• 傳遞非對象數據（數字、數組、純文本）會觸發指導錯誤。
• 缺少或格式錯誤的參數將安全地默認為空輸入，以便工具可以提供可操作的提醒。

示例（字符串化的JSON對象）：

{
  "name": "start_task",
  "arguments": "{\"description\":\"Add reporting endpoint\",\"type\":\"feature\"}"
}

start_task

開始一個新的編碼任務。這是你的第一步 - 明確你要編寫的代碼內容。 參數：

• description（字符串，必需）：你要編寫的代碼的清晰描述。
• type（枚舉，必需）：任務類型 - "feature"、"bugfix"、"refactor" 或 "other"。 示例：

使用 start_task 工具，參數如下：
- description: "Add user authentication to the login page"
- type: "feature"

mark_bug_fixed

標記錯誤/功能已修復。提醒：現在你必須創建測試！ 參數：

• summary（字符串，必需）：已修復/實現內容的簡要總結。

create_tests

確認你已經為更改創建了必要的測試。在記錄測試結果之前需要執行此步驟。 參數：無

skip_tests

當自動化測試不可行時，記錄明確的理由。將測試標記為已通過，以便你可以繼續進行文檔記錄和驗證，同時標記該任務需要手動質量保證。 參數：

• reason（字符串，必需）：跳過自動化測試的原因。

run_tests

記錄測試結果。測試失敗時切勿提交！ 只有所有測試都通過（顯示綠色）才能繼續。 參數：

• passed（布爾值，必需）：所有測試是否都通過？
• testCommand（字符串，必需）：運行的測試命令。
• details（字符串，可選）：測試結果詳細信息。 示例：

使用 run_tests 工具，參數如下：
- passed: true
- testCommand: "npm test"
- details: "All 15 tests passed"

create_documentation

標記文檔已創建/更新。在提交之前需要執行此步驟。 參數：

• documentationType（枚舉，必需）："PRD"、"README"、"RELEASE_NOTES"、"inline-comments"、"API-docs"、"changelog" 或 "other"。
• summary（字符串，必需）：記錄的內容。

check_ready_to_commit

檢查所有工作流步驟是否都已完成，以及你是否準備好提交併推送。

commit_and_push

在準備檢查通過後，自動運行 git add、git commit 和 git push。 自動檢測主分支：如果未指定 branch，工具將自動檢測項目的主分支，首先檢查 origin/main，然後回退到 origin/master。這消除了大多數項目中指定分支參數的需要。 參數：

• commitMessage（字符串，必需）：要使用的常規提交消息。
• branch（字符串，可選）：要推送的目標分支。如果省略，將自動檢測主分支（main或master）。

perform_release

在提交併推送後記錄發佈信息。在完成任務之前需要執行此步驟。 參數：

• command（字符串，必需）：執行的發佈命令（例如 npm run release）。
• notes（字符串，可選）：額外的發佈說明。

complete_task

在成功提交併推送後標記任務已完成。重置工作流以開始下一個任務。 參數：

• commitMessage（字符串，必需）：使用的提交消息。

drop_task

放棄當前任務，而不完成工作流。保留帶有上下文的審核條目，然後重置狀態，以便你可以重新開始。 參數：

• reason（字符串，可選）：放棄任務的額外詳細原因。

get_workflow_status

獲取當前工作流狀態以及下一步需要做什麼。

view_history

查看已完成任務的工作流歷史記錄。 參數：

• limit（數字，可選）：顯示的最近任務數量（默認值：10）。

📋 可用提示

workflow_reminder

獲取開發工作流規範的完整提醒。

pre_commit_checklist

獲取提交前的檢查清單，以確保在提交前不會遺漏任何內容。

🔄 典型工作流

以下是在典型的編碼會話中如何使用此MCP服務器：

1. 開始任務：

   要求Cascade使用 start_task：
   "Start a new task: implementing user profile page, type: feature"
   

2. 編寫功能/修復
   • 像往常一樣編寫代碼。
3. 標記為已修復：

   "Mark the feature as fixed: User profile page with avatar and bio completed"
   

4. 創建測試：
   • 編寫測試。
   • 服務器將提醒你這是必需的步驟！
5. 運行測試：

   "Record test results: passed=true, command='npm test'"
   

   • 如果測試失敗，服務器將 阻止 你繼續！
6. 文檔記錄：

   "Create documentation: type=README, summary='Added user profile section to docs'"
   

7. 檢查準備情況：

   "Check if I'm ready to commit"
   

8. 提交併推送：

   "Commit and push: commitMessage='feat: add user profile page with tests and docs'"
   

9. 記錄發佈：

"Record release: command='npm run release', notes='v1.2.3'"

11. 完成任務：

"Complete the task with commit message: 'feat: add user profile page'"

12. 放棄任務（可選）：

"Drop task: reason='Switching to a different feature'"

🚫 不遵循工作流步驟的發佈限制

該包附帶了一個發佈保護程序（release-wrapper.js），用於支持 npm run release:* 腳本。保護程序會拒絕運行，除非滿足以下條件：

• 當前工作流階段為 發佈。
• check_ready_to_commit 和 commit_and_push 已完成。
• 尚未為當前任務記錄任何發佈信息。 如果缺少任何要求，保護程序將退出並提供指導，讓你返回MCP工具。這可以防止在管理工作流之外意外提升版本或標記發佈。要正確發佈，請執行以下操作：

1. 通過MCP客戶端使用 perform_release {"command":"patch"}（或 minor/major），或者如果不適用發佈操作，則使用 skip_release {"reason":"<explanation>"}。
2. 保護程序將自動運行，驗證工作流狀態，並在允許你完成 complete_task 之前記錄發佈信息。

自動化npm發佈

此存儲庫附帶了 .github/workflows/npm-publish.yml，每當推送匹配 v* 的Git標籤（例如 v1.1.14）時，它會將包發佈到npm。要啟用此工作流，請執行以下操作：

1. 創建具有發佈權限的npm自動化令牌（npm token create --read-only false）。
2. 在存儲庫設置中，添加一個名為 NPM_TOKEN 的秘密，其中包含該令牌。
3. 確保你的發佈過程在運行 npm run release:<type> 後推送標籤，以便觸發工作流。
4. 確認 npm run build 在本地成功運行；工作流在發佈之前會運行構建，因此損壞的捆綁包將阻止發佈。
5. 通過 npm publish --provenance 啟用GitHub來源驗證。保持GitHub Actions的默認OIDC權限啟用，以便作業可以請求ID令牌。
6. 確保 package.json 中的 repository.url 字段指向此GitHub存儲庫。如果不匹配構建包的存儲庫，來源驗證將失敗。 工作流在發佈之前會驗證標籤版本是否與 package.json 匹配，如果不匹配則會快速失敗。

🔧 技術細節

狀態管理

服務器在 .state/workflow-state.json 中維護狀態，包含以下信息：

• 當前階段
• 任務描述
• 每個步驟的完成狀態
• 已完成任務的歷史記錄

此文件由服務器自動創建和管理，包含本地機器特定的進度，並且被Git忽略，因此每個環境可以管理自己的工作流歷史記錄，而不會相互干擾。

與現有規則集成

此MCP服務器與你現有的開發規則保持一致：

• ✅ 強制遵循測試優先的規範。
• ✅ 防止提交測試失敗的代碼。
• ✅ 提醒進行文檔記錄。
• ✅ 跟蹤工作流狀態。
• ✅ 維護歷史記錄。

📄 許可證

本項目採用MIT許可證。

🙏 貢獻

歡迎根據你的特定工作流需求自定義此服務器！

📜 項目治理

• 行為準則
• 貢獻指南
• 安全策略
• 許可證