GearBox/docs/superpowers/specs/2026-04-03-mcp-server-design.md

MCP Server — Design Spec

Overview

Built-in MCP server running inside the GearBox Hono process, exposed via SSE transport at /mcp. Provides tools for managing the full gear collection with workflow guidance emphasizing research threads. Authenticates via API key.

Transport & Configuration

• Transport: SSE or Streamable HTTP at /mcp (use whichever the MCP SDK supports best at implementation time — the newer spec favors Streamable HTTP)
• Enabled by default, disable with GEARBOX_MCP=false env var
• Authentication: API key passed in MCP client config, sent as X-API-Key header
• SDK: @modelcontextprotocol/sdk TypeScript package

Integration with Hono

The MCP server mounts as a route on the existing Hono app:

// src/server/index.ts
if (process.env.GEARBOX_MCP !== "false") {
  app.route("/mcp", mcpRoutes);
}

The MCP route handler bridges SSE transport to the MCP server instance, which calls GearBox services directly (not via HTTP) for efficiency.

Tools

All tools include descriptive names and descriptions that guide Claude toward the research thread workflow.

Item Tools

Tool	Description
list_items	List all items in the gear collection. Optionally filter by category.
get_item	Get details of a specific item by ID.
create_item	Add a new item to the gear collection. Use this for items you've already decided on. For items you're still researching, use create_thread instead.
update_item	Update an existing item's details.
delete_item	Remove an item from the collection.

Category Tools

Tool	Description
list_categories	List all gear categories.
create_category	Create a new category for organizing gear.

Thread Tools (Primary Workflow)

Tool	Description
list_threads	List all research threads. Threads are the recommended way to evaluate gear purchases — create a thread, add candidates, compare them, then resolve to pick a winner.
get_thread	Get a thread with all its candidates and comparison data.
create_thread	Start a new research thread for evaluating a gear purchase. This is the preferred workflow: create a thread describing what you need, add candidate products, compare specs/weight/price, then resolve when you've decided.
resolve_thread	Resolve a thread by picking the winning candidate. This adds the winner to your collection as a new item and marks the thread as resolved.

Candidate Tools

Tool	Description
add_candidate	Add a candidate product to a research thread. Include weight, price, pros, cons, and optionally an image URL.
update_candidate	Update a candidate's details — weight, price, pros, cons, etc.
remove_candidate	Remove a candidate from a research thread.

Setup Tools

Tool	Description
list_setups	List all gear setups (named configurations of items).
get_setup	Get a setup with all its items, total weight, and total cost.
create_setup	Create a new gear setup.
update_setup	Update a setup's items or details.

Image Tools

Tool	Description
upload_image_from_url	Fetch an image from a URL and attach it to an item or candidate.

Resources

gearbox://collection-summary

Provides an overview of the current gear collection:

• Total items, total weight, total cost
• Items per category
• Active research threads
• Number of setups

This resource gives Claude context about the collection state before making tool calls.

Workflow Guidance

The MCP server's tool descriptions are crafted to guide Claude toward the research thread pattern:

1. When the user asks about buying gear, Claude should prefer create_thread over create_item
2. Candidates are added to threads for comparison before committing
3. resolve_thread is the way to finalize a purchase decision
4. Direct create_item is for items already owned or decided on

This guidance lives in the tool descriptions themselves — no separate system prompt needed. The collection-summary resource helps Claude understand what's already in the collection.

Implementation Structure

src/server/mcp/
  index.ts          — MCP server setup, tool/resource registration
  tools/
    items.ts        — Item tool handlers
    categories.ts   — Category tool handlers
    threads.ts      — Thread + candidate tool handlers
    setups.ts       — Setup tool handlers
    images.ts       — Image tool handlers
  resources/
    collection.ts   — Collection summary resource

Client Configuration

Claude Code (.claude/settings.json)

{
  "mcpServers": {
    "gearbox": {
      "type": "sse",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "X-API-Key": "<your-api-key>"
      }
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "gearbox": {
      "type": "sse",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "X-API-Key": "<your-api-key>"
      }
    }
  }
}

Testing

• Tool handler tests: each tool with valid/invalid inputs
• Auth test: requests without API key are rejected
• Resource test: collection summary returns accurate data
• Integration test: create thread -> add candidates -> resolve -> verify item created