breakpilot-core/pitch-deck/mcp-server/README.md

# BreakPilot Pitch MCP Server

MCP server that lets Claude Code directly manage pitch versions, invite investors, and assign versions — without touching the browser admin UI.

## What it does

11 tools exposed to Claude Code:

| Tool | Description |
|------|-------------|
| `list_versions` | List all pitch versions with status + investor counts |
| `create_version` | Create a draft (snapshot base tables or fork from parent) |
| `get_version` | Get full version detail with all 12 data table snapshots |
| `get_table_data` | Get one table's data (company, team, financials, market, etc.) |
| `update_table_data` | Replace a table's data in a draft version |
| `commit_version` | Lock a draft as immutable |
| `fork_version` | Create new draft by copying an existing version |
| `diff_versions` | Per-table diff between any two versions |
| `list_investors` | List all investors with stats + version assignments |
| `assign_version` | Assign a committed version to an investor |
| `invite_investor` | Send magic-link email to a new investor |

All actions go through the existing admin API at `pitch.breakpilot.com`, so they show up in the audit log.

## Setup

### 1. Build

```bash
cd pitch-deck/mcp-server
npm install
npm run build
```

### 2. Get the admin secret

The `PITCH_ADMIN_SECRET` is stored in orca secrets on the server. SSH in and retrieve it:

```bash
ssh breakpilot-infra-vm1
cat ~/orca/services/breakpilot-dsms/secrets.json | grep PITCH_ADMIN_SECRET
```

### 3. Configure

Edit `.mcp.json` in the **breakpilot-core** repo root (already created):

```json
{
  "mcpServers": {
    "pitch-versions": {
      "command": "node",
      "args": ["pitch-deck/mcp-server/dist/index.js"],
      "env": {
        "PITCH_API_URL": "https://pitch.breakpilot.com",
        "PITCH_ADMIN_SECRET": "paste-your-secret-here"
      }
    }
  }
}
```

> **Important:** `.mcp.json` contains a secret. It's already in `.gitignore` — never commit it.

### 4. Restart Claude Code

Exit and reopen Claude Code, or run `/mcp` to check it loaded:

```
/mcp
```

You should see `pitch-versions` listed with 11 tools.

## Usage examples

Just talk to Claude naturally:

- **"List all pitch versions"** → calls `list_versions`
- **"Create a new version called 'Series A Aggressive'"** → calls `create_version`
- **"Show me the company data from version X"** → calls `get_table_data`
- **"Update the company tagline to 'AI-Powered Compliance' in version X"** → calls `update_table_data`
- **"Commit version X"** → calls `commit_version`
- **"Fork version X into a new draft called 'Conservative'"** → calls `fork_version`
- **"Compare version X with version Y"** → calls `diff_versions`
- **"Assign version X to investor jane@vc.com"** → calls `assign_version`
- **"Invite john@fund.com from Big Fund"** → calls `invite_investor`

## Data tables

Each version stores 12 data tables as JSONB snapshots:

| Table | Content |
|-------|---------|
| `company` | Name, tagline (DE/EN), mission (DE/EN), website, HQ city |
| `team` | Members with roles, bios, equity, expertise (all bilingual) |
| `financials` | Year-by-year revenue, costs, MRR, ARR, customers, employees |
| `market` | TAM/SAM/SOM with values, growth rates, sources |
| `competitors` | Names, customer counts, pricing, strengths, weaknesses |
| `features` | Feature comparison matrix (BreakPilot vs competitors) |
| `milestones` | Timeline with dates, titles, descriptions, status (bilingual) |
| `metrics` | Key metrics with labels (bilingual) and values |
| `funding` | Round details, amount, instrument, use of funds breakdown |
| `products` | Product tiers with pricing, LLM specs, features (bilingual) |
| `fm_scenarios` | Financial model scenario names, colors, default flag |
| `fm_assumptions` | Per-scenario assumptions (growth rate, ARPU, churn, etc.) |

## Architecture

```
Claude Code ←stdio→ MCP Server ←HTTP→ pitch.breakpilot.com/api/admin/*
                     (local)           (deployed on orca)
```

The MCP server is a thin HTTP client. All auth, validation, and audit logging happens on the server side. The bearer token authenticates as a CLI admin actor.

## Troubleshooting

**"PITCH_ADMIN_SECRET is required"** → The env var is missing in `.mcp.json`

**401 errors** → The secret is wrong or the pitch-deck container isn't running. Check: `curl -s -H "Authorization: Bearer YOUR_SECRET" https://pitch.breakpilot.com/api/admin/investors`

**MCP server not showing in `/mcp`** → Make sure you're in the `breakpilot-core` directory when you launch Claude Code (`.mcp.json` is project-scoped)