superpowers-mcp

Superpowers MCP Toolpack Usage Guide

English | 繁體中文

This document summarizes the information and usage instructions for packaging the original Superpowers skills library into an independent MCP Toolpack.

🚀 How to Install and Use

Supported Environments

Antigravity, Cursor, VSCode, and other AI editors that support the MCP toolchain.

Chatting with the AI Agent

Once installed or configured, your AI Agent (such as Copilot or Antigravity Cascade) will be able to recognize the Superpowers Skills.

You can ask things like:

• "List all superpowers skills"
• "Use read_skill to read the brainstorming skill, and then help me analyze the implementation of this feature"
• "Apply the session-start prompt" (Simulates the original startup injection mechanism)

🛠️ MCP Configuration

Add the following settings to your IDE (e.g., Cursor, Antigravity, or VSCode MCP settings).

Method : NPX / BUNX (Recommended)

This is the easiest way as it handles path resolution automatically.

Using Bun (Faster)

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

Using Node/NPM

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

💡 Common Skills & Scenarios

Skill Name	Community Recommended Scenario	Core Value
brainstorming	Before starting a new feature, exploring requirements and design.	Prevents the AI from jumping straight into writing code.
writing-plans	Before multi-file refactoring or complex migrations.	Establishes a clear execution blueprint.
systematic-debugging	When encountering any errors or abnormal behavior.	Enforces "root cause analysis" instead of guessing.
test-driven-development	When implementing logically challenging features.	Ensures code is accompanied by tests, achieving Red-Green-Refactor.
verification-before-completion	Before claiming "it's fixed" or "it's done".	Evidence-based completion confirmation.

🔄 Recommended Prompt Sequences

1. New Feature Development Sequence

• "Read the brainstorming skill to confirm requirements and architecture."
• "Read the writing-plans skill to create an execution plan with specific steps."
• "Read the test-driven-development skill to implement the feature with tests."
• "Read the verification-before-completion skill to run test suites and ensure everything works."

2. Emergency Hotfix Sequence

• "Read the systematic-debugging skill to locate the root cause of the current issue."
• "Read the test-driven-development skill to write a failing test for the bug and fix it."
• "Read the verification-before-completion skill to validate the applied hotfix."

📋 Supported Skills Overview (14 Total)

To help you choose the right skill, we've categorized them into 6 logical phases of software development:

🚀 1. Planning & Design

• brainstorming: Software design and requirements analysis process
  • Visual Companion for browser-based mockups and design reviews (just-in-time)
• writing-plans: Creating detailed implementation plans

💻 2. Implementation & Debugging

• executing-plans: Executing created implementation plans
• test-driven-development: TDD (Test-Driven Development) workflow
• systematic-debugging: Systematic debugging and root cause analysis

🛡️ 3. Quality & Review

• verification-before-completion: Evidence-based verification before completion
• requesting-code-review: Initiating pre-checks for code reviews
• receiving-code-review: Receiving and addressing code review feedback
• finishing-a-development-branch: Finalizing and integrating feature branches

🌿 4. Version Control

• using-git-worktrees: Managing multiple branches using Git Worktrees

🤖 5. Advanced Agent Controls

These skills are designed for orchestrating complex meta-execution patterns within supported IDEs (like Antigravity or Cursor).

• subagent-driven-development: Driving sub-agents to execute tasks
  • Usage: Used to execute a predefined plan task-by-task. The system spawns a fresh "implementer" sub-agent per task, followed by a consolidated task reviewer (spec compliance + code quality) sub-agent, plus a whole-branch final review at the end. A Pre-Flight Plan Review scans for task conflicts before execution begins.
  • Model Selection: Choose sub-agent models based on task complexity — cheaper models for mechanical work, capable models for architecture and subtle concurrency changes.
  • Example: "Read the subagent-driven-development skill, then execute the tasks listed in docs/plans/feature-plan.md one by one."
• dispatching-parallel-agents: Dispatching tasks to parallel agents
  • Usage: Used for tackling multiple independent issues (e.g., 3 unrelated failing tests or 3 separate web research topics). The AI will adopt a parallel-execution mindset, addressing each task independently without crossing state or experiencing context pollution, significantly speeding up output generation.
  • Debugging Example: "Read the dispatching-parallel-agents skill, then dispatch 3 parallel agents to investigate the independently failing tests A, B, and C."
  • Research Example: "Read the dispatching-parallel-agents skill, then search the web for React 19 features, Vue 3.5 updates, and Svelte 5 Runes in parallel — summarize each independently."

⚙️ 6. Customization & Meta

• using-superpowers: Guidelines and self-checks for using Superpowers
• writing-skills: Writing and expanding new custom skills

🆕 Recent Updates

v6.0.2 (Latest)

• Modular Refactoring & Performance Upgrades:

  • Decoupled Architecture: Extracted file system access, metadata caching, and parsing logic into a dedicated src/skills-manager.ts, leaving src/server.ts purely focused on MCP protocol handling.
  • O(1) Map-Based Cache: Replaced the $O(N)$ double-array scan with case-insensitive, dual-key (by name and directory name) memory caches for fast $O(1)$ lookups.
  • Async I/O Pipeline: Swapped synchronous file API calls (readdirSync, readFileSync) with promises and Promise.all concurrent execution, unlocking high-throughput performance.
  • Markdown Cache: Cached stripped skill content in memory to avoid repetitive disk reads when tools are invoked frequently.

• Security Hardening:

  • ReDoS Prevention: Replaced regex-based frontmatter parser with a safe, line-by-line state machine parser, completely eliminating CPU exhaustion risks and supporting multiline YAML descriptions.
  • Path Traversal Shield: Added strict alphanumeric white-listing (/^[a-zA-Z0-9-_]+$/) on skill name inputs to prevent traversal attacks.
  • Directory Injection Check: Validated SKILLS_PATH to actively reject potentially hostile system root folders.
  • Path & Username Leak Protection: Caught native file system errors and masked them into generic, path-free McpError payloads.
  • Windows Build and Script Safety: Handled Windows chmodSync platform checks in esbuild.js and skipped Symlinks in copy-skills.js to prevent recursive file copy loops.

• Upstream Security Cherry-Picks: Applied security hardening from obra/superpowers v6.1.1:

  • WebSocket frame size validation: Added MAX_FRAME_PAYLOAD_BYTES (10 MB) check in decodeFrame() to prevent oversized frame attacks (CWE-789). Dual protection — BigInt extended-length and general post-resolution guard.
  • Hardlink containment: Added stat.nlink !== 1 check in isRegularFileInsideContentDir() prevents path traversal via hardlinks.
  • escapeHtmlText() extraction: Extracted inline escHtml closure into a reusable named function for consistent HTML escaping.
  • URL parsing refactor: Extracted pathnameOf() and queryKey() helpers, reducing duplicate inline URL logic in handleRequest().

• review-package Path Resolution Fix: Fixed sdd-workspace invocation to use absolute path resolution ($(cd "$(dirname "$0")" && pwd)) instead of relative path, fixing CWD-dependent failures.

• Windows Native Helper Scripts: Added PowerShell wrappers for Visual Companion startup/shutdown, SDD review/task helpers, and systematic-debugging polluter detection.

• Skill Documentation Enhancements:

  • subagent-driven-development: Added plan-mandated review guidance for handling plan conflicts.
  • writing-skills: Strengthened prohibition vs. recipe guidance with empirical evidence from wording tests.
  • test-driven-development: Fixed table formatting for clarity.
  • writing-skills/anthropic-best-practices: Updated image CDN URLs.

• helper.js Comment Alignment: Added 4 clarifying inline comments to align with upstream documentation without changing behavior. DOM-safe showTombstone() preserved (no innerHTML regression).

• Cleanup: Removed obsolete walkthrough.md (v5.1.0 upgrade guide).

v6.0.1

• Security Fix — Reflected XSS (#2): Fixed server-side reflected cross-site scripting in skills/brainstorming/scripts/server.cjs. The bootstrapPage() function was called with the user-supplied keyFromQuery parameter (even though validated via timingSafeEqualStr). Changed to use the server-side TOKEN constant instead, eliminating user-tainted data from the HTML response sink. Zero behavior change (the validated value is identical).

v6.0.0

• Upstream Sync with obra/superpowers v6.1.1: Major synchronization bringing upstream improvements across all skills.
• subagent-driven-development Redesign: Consolidated two-stage review (spec → code quality) into a single "task reviewer" sub-agent, plus added a broad whole-branch final review at completion. New Pre-Flight Plan Review catches task conflicts before execution begins. Added Model Selection Guidance to optimize cost vs. turn count.
• using-superpowers Simplified: Removed platform-specific sections and Graphviz diagram. Introduced per-platform reference files (antigravity-tools.md, pi-tools.md) and updated codex-tools.md for cleaner multi-environment support.
• brainstorming Visual Companion: Changed to just-in-time offering — no longer offered upfront, only when a visual question actually arises.
• Type Safety & Code Quality: Fixed Record<string,string> cast in server.ts with proper typeof guard. Replaced remaining innerHTML with safe DOM methods. Removed redundant checks and verbose comments across the codebase.

v5.1.2

• Security Hardening: Removed the last remaining innerHTML usage in skills/brainstorming/scripts/helper.js, replacing it with safe DOM creation methods — now zero innerHTML in the entire codebase.
• Dependency Security: Upgraded hono from 4.12.23 to 4.12.26 to patch 5 advisories including CORS origin reflection, Lambda body-limit bypass, and Set-Cookie header merging.
• Clean Slate: All 37 Dependabot advisories and npm audit warnings now fully resolved — zero outstanding vulnerabilities.

v5.1.1

• Security Audit & Hardening: Conducted a full-scale security audit and updated .gitignore rules to prevent potential secret leaks.
• Vulnerability Patches: Patched XSS vulnerability in brainstorming Visual Companion (helper.js) by replacing unsafe innerHTML usage with secure DOM APIs. Upgraded path-to-regexp to 8.4.2 to resolve a high-severity ReDoS vulnerability.
• Dev Dependencies: Bumped esbuild to 0.28.1.

v5.1.0

• Inline Self-Review: Replaced heavyweight subagent review loops (Spec Review, Plan Review) in brainstorming and writing-plans with lightweight inline self-review checklists, significantly improving efficiency by eliminating subagent overhead.
• Git Worktree Redesign: Rewrote using-git-worktrees and finishing-a-development-branch with a detect-and-defer mechanism, natively supporting AI editors' (like Claude Code) built-in worktree tools while safely falling back to git CLI commands.
• Token Optimization: Removed obsolete Integration sections from all skills, reducing prompt token footprints.
• Consolidation: Consolidated the independent code-reviewer agent directly into requesting-code-review.

v4.3.2

• Security: Fixed XSS vulnerability in brainstorming Visual Companion
• Docs: Updated README and SECURITY with accurate version info

v4.3.0

• Initial MCP server implementation
• 14 core skills migrated from original Superpowers

🙏 Acknowledgments

This project is a fork and adaptation of the original Superpowers project by obra. We are grateful for their work in defining the agentic skills framework and software development methodology that powers this MCP server.