superpowers-mcp

v6.4.7

Published

3 days ago

Superpowers skills library (TDD, debugging, collaboration workflows) as an MCP server for VSCode and Antigravity

0High
0Medium
0Low

poseidoncode

mcp ai skills tdd debugging collaboration best-practices workflows copilot agent

Superpowers MCP Toolpack 使用指南

本文檔總結了將 Superpowers 技能庫與自主 Agent 工作流架構打包成獨立、高效能且安全加固的 Model Context Protocol (MCP) 伺服器之相關資訊與使用說明。

🚀 安裝與使用方式

支援的環境與 Agent 平台

AI 程式碼編輯器與 IDE：Antigravity (AGY)、Cursor、VSCode（GitHub Copilot）、VSCode Insiders（GitHub Copilot）、Devin Desktop、Trae、Cline、Kilo Code、Qoder、Kiro、MiniMax Code Desktop（需手動配置）、Codex。
AI 桌面應用與 Agent 工具：Claude Desktop、Pi Desktop、QwenPaw、Hermes Desktop、Kimi Work、Goose、OpenClaw。
開源與私有化 AI 平台：AnythingLLM、LibreChat。

提供之 MCP 協議功能

與 AI Agent 對話（基礎操作）

安裝或配置完成後，MCP 客戶端即可發現 Superpowers 的 tools、prompts 與 resources。MCP prompt 必須由使用者選取；之後是否載入技能，取決於 Agent 是否遵循 prompt 並呼叫 read_skill。

基礎互動範例：

初始化工程規範：「套用 session-start prompt」（注入 Superpowers 技能體系與工程紀律）
查詢所有可用技能：「列出所有 superpowers 技能」
載入單一技能：「使用 read_skill 讀取 brainstorming 技能並幫我分析需求」

⚡ 快速全域一鍵設定 (Targeted One-Click Setup)

為了讓您在最短時間內啟用 Superpowers，我們提供了精確指定、尊重環境隱私、杜絕批量侵入的跨平台一鍵安裝工具。

[!NOTE] 可在系統任何目錄下直接執行：您不需要預先切換到特定專案目錄，也無須 clone 本儲存庫。在終端機的任意目錄皆可直接執行以下指令！安裝程式會自動鎖定您系統中的全域設定檔（以使用者家目錄為基準），一次設定、全域與所有專案皆可自動生效。

ChatWise 與 Cherry Studio 需手動匯入，請見桌面版匯入指南。

1. 選擇您的 AI Agent / 編輯器（一鍵精準設定）

請依據您使用的客戶端，在終端機複製並執行對應指令：

(若偏好使用 Bun，指令可加上 --bun，例如 npx -y superpowers-mcp setup --target cursor --bun)

2. 透過 Curl / PowerShell 一鍵設定

macOS / Linux（透過 Curl 指定目標）：

curl -fsSL https://raw.githubusercontent.com/Poseidoncode/superpowers-mcp/main/scripts/install.sh | bash -s -- --target cursor

Windows（透過 PowerShell 指定目標）：

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Poseidoncode/superpowers-mcp/main/scripts/install.ps1))) -Target cursor

常用進階參數：

--dry-run：預覽即將修改的檔案與配置內容，不實際寫入磁碟。
--remove：從指定目標 Harness 安全移除 Superpowers 配置。
--backup：修改前建立時間戳記 .bak 備份檔（預設為關閉，維持系統純淨零殘留）。
--bun：在產生的設定中改用 bunx 啟動，享受極速啟動效能。
--target <name>：指定目標名稱（支援常用別名，如 code、vscode、kimi-code 等）。

🛠️ 手動 MCP 配置 (Manual Configuration)

若您偏好手動設定，可將以下設定加入您的 IDE 或 MCP 客戶端（例如 Cursor、Antigravity、VSCode、AnythingLLM 等）。

方法：NPX / BUNX（推薦）

這是最簡單的方式，因為它會自動處理路徑解析。

使用 Bun（較快）

{
  "superpowers": {
    "command": "bunx",
    "args": ["-y", "superpowers-mcp"]
  }
}

使用 Node/NPM

{
  "superpowers": {
    "command": "npx",
    "args": ["-y", "superpowers-mcp"]
  }
}

🔄 技能編排與工作流流水線 (Skill Compositions & Pipelines)

當執行多步驟的複雜任務時，請使用以下互動式工作流啟動器。它會啟動 Agent 引導的流程，並在設計、計畫審閱與分支收尾時等待使用者決定；它不是伺服器端無人值守自動化。詳見 docs/skill-compositions.zh-TW.md。

1. 端到端新功能開發管線 (Feature Development Pipeline)

brainstorming ➔ writing-plans ➔ using-git-worktrees ➔ subagent-driven-development (TDD) ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch

啟動方式：從客戶端的 MCP Prompts 選單選取 feature-pipeline，提供必要的 feature_name 與選填的 requirements。
流程特色： 需求確認 (Spec) ➔ 任務拆解 (Plan) ➔ Worktree 隔離 ➔ 獨立 Subagent + TDD 實作 ➔ 全套測試驗證 ➔ 專家代碼審查 ➔ 分支收尾。

2. 結構化多點除錯管線 (Structured Troubleshooting Pipeline)

systematic-debugging ➔ using-git-worktrees ➔ dispatching-parallel-agents ➔ test-driven-development ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch

啟動方式：從 MCP Prompts 選單選取 structured-debug，提供錯誤描述或失敗測試。
流程特色： 根因分析拆解假說 ➔ Worktree 隔離平行排查 ➔ 多 Agent 驗證 ➔ 編寫失敗測試並修復 ➔ 全套迴歸驗證 ➔ 審查結果解決 ➔ 分支合併收尾。

3. 動態技能導引 (Dynamic Workflow Guide)

啟動方式：選取 skill-composition 取得重構、遷移或舊系統的流程建議；這些情境目前沒有各自獨立的啟動 prompt。
流程特色： 針對大型重構、舊代碼防護網建立或團隊新人上手，動態推薦最佳步驟：
- 大型重構與遷移 (Pipeline 3)： brainstorming ➔ writing-plans (skeleton-first) ➔ using-git-worktrees ➔ subagent-driven-development ➔ verification-before-completion ➔ requesting-code-review ➔ finishing-a-development-branch
- 舊專案工程防護網 (Pipeline 4)： brainstorming ➔ writing-plans ➔ test-driven-development (characterization) ➔ systematic-debugging ➔ verification-before-completion

📋 支援技能總覽 (15 項核心技能與適用情境)

為了讓您能快速選用合適的技能，我們將 15 個技能依照軟體開發生命週期 (SDLC) 進行分類，並整合其核心用途與社群推薦使用情境：

🆕 最近更新

v6.4.7（最新版）

完整專案安全性掃描（2026-10-09）：src/*.ts、brainstorming companion server、scripts/、esbuild.js、npm 打包與 lockfile 完整性、密鑰／權限衛生，以及所有自動化測試套件。基準控管重新驗證為乾淨——發佈程式碼中 eval / new Function / innerHTML / document.write / shell: true 為 0、child_process 僅用 argv、0 硬編碼密鑰、0 全域可寫的受追蹤檔案（詳見 SECURITY.md）。
--remove 可能在仍有存活的 MCP 項目時回報成功（CWE-459，已以實際執行重現）：TOML 會保留除最後一個 [[mcp_servers.superpowers]] 陣列表之外的所有項目，並使 [[mcp_servers.superpowers.env]] 淪為孤兒；JSON 只清除第一個含有 superpowers 項目的根層 key；YAML 移除對已填滿的 flow map superpowers: {…} 是無動作。因此呼叫端自選的 command 在回報成功的解除安裝之後，仍會持續自動啟動。
YAML --remove 可能刪除另一個父層的 superpowers 區塊（CWE-459）：新的根層守衛涵蓋了空映射重寫，但未涵蓋項目刪除，因此位於其他頂層 key 底下的巢狀 mcp_servers: 會失去其 superpowers 子樹——包含 env 等使用者 key。
SKILLS_PATH 的範圍限制是封鎖清單，而非允許清單（CWE-22，既有問題）：~/.ssh、~/.config/gh 與 /Users/Shared 之所以被接受，是因為它們存在；而 ~/.aws 被拒絕也只是因為不存在。在 Linux 上，文件中記載的 SKILLS_PATH=$(mktemp -d) 流程會解析到全域可寫的 /tmp，因此共用主機上的本機使用者可以植入技能內容，而 Agent 隨後會把它當作受信任的指令。
[MODEL] 對 sdd-task-reviewer / sdd-re-review 不再被丟棄（由本次掃描發現，並已於此修正）：這兩個範本原本都把該欄位寫成 model: [MODEL — REQUIRED: …]，其中不含任何字面 token，因此呼叫端的 model 值先前抵達渲染後 prompt 的次數為 zero，新的診斷訊息也無法看見它。兩者現皆改用 model: [MODEL] 加上一行 # 註解，與 implementer-prompt.md 一致，並由兩個「未帶入則失敗／帶入則通過」的斷言加以釘住。
CodeQL js/polynomial-redos #9/#10 已關閉——YAML 的受管理項目匹配器是二次複雜度（已以實際執行重現）：managedEntryPattern 把一個可選的 {…} 群組放在兩個 \s* 之間，因此任何它無法完成的行，都會讓引擎重試該空白 run 的每一種切分方式。不需要任何特殊的攻擊載 payload——superpowers: + 一段長空白 run + 一個多餘字元就是一般的格式錯誤設定行，而 200 KB 的一行在單次比對中耗時 18.3 s，足以卡住 setup。現已改用 managedEntryIndent() 這個單趟掃描器：18.3 s → 0.08 ms。可被接受的行集合可證明未變（針對被移除的 regex 做了 300 030 行的差異模糊測試，0 處不符），那三個同類 pattern 經量測為線性故保持原樣，並新增兩個 tests/setup_test.js 用例同時釘住時間表現與可接受的行集合（已驗證在舊實作上失敗、在新實作上通過）。
打包強化目標：npm pack 不會重新建置（prepublishOnly 只在發佈時執行，且 out/ 已被 gitignore，因此打包出的 tarball 會出貨未經審查的磁碟上 out/*.js——建置應該放在 prepack）；而 files: ["scripts"] 會連安裝程式一起出貨，它偏好同目錄的 setup.js。
驗證：npm test 全綠（10/10 套件）、PowerShell 套件 128/128、npx tsc --noEmit 乾淨、npm run build 正常、npm audit 0 漏洞、npm run drift 0（迴歸基準重新量測為 398 斷言：Node.js 238 + Bash 32 + PowerShell 128）。

v6.4.6

完整安全性掃描（2026-10-06）：src/*.ts、brainstorming companion server、scripts/ 與建置流程皆無新增發現——發佈程式碼中 eval / new Function / innerHTML / shell: true 為 0、子程序僅用 argv、crypto.randomBytes 暫存檔隨機值、0 硬編碼密鑰、0 全域可寫檔案（詳見 SECURITY.md）。
依賴安全諮詢已修復（npm audit 2 → 0）：GHSA-6qxp-vccf-f47h（高危，MCP SDK OAuth 憑證外洩）透過升級 @modelcontextprotocol/sdk 至 ^1.32.1 修復；GHSA-jqcg-44mw-7w3h（嚴重，經由 express 的 proxy-addr IP 偽造）以新增 overrides.proxy-addr ^2.0.8 下限修復。兩者皆僅存在於建置期，stdio-only 的發佈包無法觸及。
v6.4.5 之後的原始碼修復正式記錄：brainstorming frame 注入改用 function replacer 保留字面 $ token；單飛技能掃描、引號 YAML 根鍵處理（含空映射輸出與 CRLF 保留）、以及 placeholder-key 提示附加守衛。
驗證：npm test 全綠（基準 409 斷言：setup 78/78、edge-cases 12/12、brainstorming 35/35、prompts 18/18），tsc 乾淨，npm audit 0 漏洞。

v6.4.5

上游同步至 obra/superpowers@8ca22db（上游 v6.4.2，2026-09-25，PR #2384「leaner plans」）：writing-plans 改為記錄實作時需要的決策（函式簽章、測試斷言、spec 數值），而非抄寫程式碼——新增明確 Spec: 路徑的 spec 優先計畫標頭、新增 ## What a Step Contains 步驟範本、## Bite-Sized Task Granularity 更名為 ## Step Granularity，以及含七項檢查的 ## Self-Review。
三方合併保留 fork 內容：fork 獨有的 ## Two Plan Shapes 段落與 skeleton-first-plans.md 完整保留；plan-document-reviewer-prompt.md 留在 fork，因為 src/server.ts 用它產生 plan-reviewer MCP prompt。
Drift baseline 重錄於 8ca22db（74/74 上游 skill 檔案，npm run drift 已歸零）；tests/upstream_sync_test.js 新增回歸測試 Test 19 (v6.4.2)。
文件與掃描衛生：README 技能矩陣與 docs/skill-compositions.* 範例已對齊目前的 writing-plans 範本（改用精確檔案參照，不再提到早已移除的「檔案契約」）；npm run drift 不再把系統雜項（.DS_Store）列為 fork 獨有檔案。

v6.4.4

CodeQL 修復與安全更新（2026-09-28）：
- Code scanning 已 0 未修復 / 7 已修復：補上 v6.4.3 通報的 3 個 src/setup-runner.ts 警報（詳見 SECURITY.md）。
- TOML ReDoS 修復：引號表格偵測 regex 改為線性掃描，惡意設定行不再造成多項式回溯；fail-closed 行為不變。
- 原型污染防護：巢狀 JSON serverPath（openclaw 目標使用）寫入前拒絕 __proto__ / constructor / prototype 與非識別字 key。
- 合法設定行為不變；驗證：npm test 全綠（基準 389/389），tsc 乾淨，npm audit 0 漏洞。

v6.4.3

Codex 支援與文件清理（2026-09-28）：
- 新增 codex 一鍵目標：setup --target codex 寫入 ~/.codex/config.toml（[mcp_servers.superpowers]），零依賴 TOML 合併，支援 --dry-run / --backup / --bun / --remove。
- 新增 openclaw / goose 目標：前者寫入 ~/.openclaw/openclaw.json（mcp.servers）；後者寫入 goose config.yaml 的 extensions 區塊（保留使用者的 enabled/timeout/envs）。
- 刪除設定章節多餘的「透明與零污染」TIP（與一鍵設定標題重複）；安全細節保留於進階參數與 SECURITY.md。
- docs/desktop-setup.md 改為純英文的 ChatWise / Cherry Studio 匯入指南（setup --print-config）；LM Studio / Roo Code 維持表格一鍵指令。刪除過時的「尚未發布」說明（lmstudio、roo、--print-config 已於 v6.3.9 發布）。
- 補上 7 語系 README 導覽（新增西 / 葡 / 印版本）、西 / 葡 / 印 skill-composition 指南，以及 CJK 粗體符號修正。
- MiniMax Code Desktop 標註（需手動配置）（設定檔路徑未驗證）。
- 驗證：npm test 全綠，基準 389/389（新增 17 個 setup-target 案例），npm audit 0 漏洞。

v6.4.2

v6.4.2 安全審計與程式碼審計（2026-09-24）：補上 MCP 伺服器、安裝腳本、建置管線與測試工具的審計缺口（詳見 SECURITY.md）。
- 路徑穿越與錯誤訊息修正：技能名稱先解碼再通過白名單驗證，double-encoding 的 ..%2f / %2e%2e 載荷會以 InvalidParams 拒絕；未知工具與 Prompt 改回傳具體可操作的 InvalidParams，不再誤報 MethodNotFound。
- TOCTOU 與破壞性路徑防護：符號連結檢查後重新驗證 canonical path、快取清理須通過 copy manifest 閘門（fork 自有技能絕不會被誤刪）、drift/coverage 記錄改以暫存檔 + rename 原子寫入。
- 無競態建置與軟失敗同步：out/setup.js 建置加上獨佔鎖與 mtime 新鮮度重查、watch 模式輸出補上 chmod 執行權限、上游來源缺漏時優雅結束而不是誤報 drift。
- 誠實的測試工具：watchdog 加 ref、server exit/close 處理器杜絕靜默掛死、drift 測試加上網路封鎖、特權降級的 skip 不再計為通過 — 回歸基準維持 365/365 斷言。

v6.4.1

上游同步至 obra/superpowers v6.4.1：
- 原生會話內執行：重寫的 executing-plans 以新版 task-start / task-done 跑完全部計畫，最後再做一次全分支審查，不再中途停下來確認。
- 新技能 diagnosing-superpowers：依據磁碟紀錄做會話鑑識並附引證，可產出脫敏 bundle 與 GitHub issue 草稿（共 15 個技能）。
- 審查行為：以合理使用者期望評斷未載明行為、Declined to judge 清單、BASE_SHA 改用 git merge-base origin/main HEAD。
- 計畫 Review Focus：新增模板章節與自查項，將規格隱含的邊界案例釘到負責的任務。
- 新平台參照：Muse 與 Claude Code 工具對照；Devin / OpenCode 參照保留。
- 腳本一律透過直譯器（bash / node）呼叫，避免市集打包剝除執行位元導致失效。
Windows 對等與迴歸防線：
- 新增 task-start.ps1 / task-done.ps1 與 sh/ps1 對稱測試。
- 既有 PR 採用內容全數保留（Discoveries 帳本、審查檔契約、greenfield 腳本、遠端安全邊界）；drift 基準重錄，零殘留差異。
全方位安全審計與回歸測試底線（SECURITY.md）：
- 全套件 365 項自動化測試斷言（Node.js: 170、Bash: 67、PowerShell: 128）100% 通過，0 漏洞、0 敏感資訊外洩。
- 會話內 task-done 以 argv 執行操作者指定的測試（"$@" / & $exe @rest），不是 shell；帳本內容僅供顯示。
- diagnosing-superpowers 僅讀本機紀錄、匯出需對方同意；脫敏為盡力而為，分享前仍須人工檢查。
- 延後發現匯出已涵蓋 Final: minor (deferred):，且不會誤抓完成列的 parked 計數。
- 本機 Devin 設定（.devin/）已列入 gitignore。

v6.3.10

全域安裝引擎鍵名衝突化解與使用者設定無損保留：
- 自動探索既有的 servers、mcp、mcpServers，防止在不同 AI Client 環境中重複建立互相矛盾的設定區塊。
- 重新執行安裝時自動合併並無損保留使用者自訂的 env、cwd、disabled、alwaysAllow 等欄位。
- 徹底消除 disabled: true 與 enabled: true 同時並存的矛盾無效狀態。
- 嚴格校驗命令列引數，拒絕未預期的位置參數（結束碼 1）；全面以 process.exitCode 取代突兀退出，確保非同步串流完整沖刷。
核心技能引擎單次 Stat 快照校驗與世代隔離：
- 引入單次 fs.stat 快照校驗 (dev, ino, size, mtimeMs)，若符號連結或實體檔案遭置換立即失效快取，無需重新遍歷整個目錄。
- clearCache() 採用單調遞增的 scanEpoch 並重設 loadingEpoch，杜絕慢速異步掃描在快取重設後的髒覆寫。
- 權威描述元 Inode 校驗 (readFileNoFollow) 消除 TOCTOU 描述元置換競態。
MCP Prompt 模板健壯性與去重機制：
- 遇到空白或遺失模板時主動輸出結構化 stderr 並拋出標準 McpError(ErrorCode.InternalError)。
- 以 appliedInterpolations 追蹤已替換標記，防止多餘參數重複追加。
全方位安全審計與回歸測試底線：
- 全套件 292 項自動化測試斷言（Node.js: 163 項、Bash: 35 項、PowerShell: 94 項）100% 通過，0 漏洞、0 敏感資訊外洩。

v6.3.9

永久 ReDoS 防禦（CodeQL Alert #4 關閉）：
- 將 YAML 解析（updateYamlConfig）中的多項式回溯正則改為單一無歧義前綴匹配與原生 String.prototype.trim()。
- 引入 extractInlineComment 線性掃描器（$O(N)$），徹底杜絕長空白填充下的多項式回溯；GitHub CodeQL Alert #4 (js/polynomial-redos) 經遠端靜態分析確認正式關閉。
- 於 tests/setup_test.js 增加 60,000 字元極限空白填充壓力測試，確保線性執行耗時（<1ms）。
目標客戶端生態系擴充（支援 17 款 AI Agent 客戶端）：
- 新增 LM Studio（lmstudio，指向 ~/.lmstudio/mcp.json）與 VS Code 桌面版 Roo Code（roo，指向 rooveterinaryinc.roo-cline/settings/mcp_settings.json）跨平台安裝目標。
- 增強 YAML 解析器，在更新與移除流程中完美保留 mcp_servers: 與 superpowers: 宣告的行內註解與檔案標頭註解。
桌面端安全匯入工具與退出碼完整性：
- 提供 setup --print-config（支援 --bun）輸出純淨 MCP JSON 設定，方便 ChatWise、Cherry Studio 等桌面客戶端無副作用匯入。
- 修正 src/server.ts setup 命令轉發機制，完整繼承 CLI 返回之 process.exitCode。
桌面整合指南：
- 新增完整文件 docs/desktop-setup.md，涵蓋 LM Studio、Roo Code、ChatWise 與 Cherry Studio 步驟指引。

👉 更多歷史版本更新紀錄，請參閱完整的 CHANGELOG.md。

🙏 致謝

本專案是透過 fork 與改編自 obra 的原始 Superpowers 專案。我們非常感謝他們在定義 Agentic 技能框架與軟體工程工作流上的開創性貢獻，這些構成了本 MCP Server 的基石。