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:

```typescript
// 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`)

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

### Claude Desktop

```json
{
  "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