From 27479ee553feef7cccfd76085ca9ecfa39e77e2f Mon Sep 17 00:00:00 2001
From: Sharang Parnerkar <30073382+mighty840@users.noreply.github.com>
Date: Mon, 13 Apr 2026 10:36:54 +0200
Subject: [PATCH] docs(mcp-server): add README + gitignore .mcp.json

Setup instructions for the pitch version MCP server.
.mcp.json contains the admin secret and is gitignored.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .gitignore                      |   1 +
 pitch-deck/mcp-server/README.md | 123 ++++++++++++++++++++++++++++++++
 2 files changed, 124 insertions(+)
 create mode 100644 pitch-deck/mcp-server/README.md

diff --git a/.gitignore b/.gitignore
index c268c9a..0d79c56 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,6 +7,7 @@
 secrets/
 *.pem
 *.key
+.mcp.json
 
 # Node
 node_modules/
diff --git a/pitch-deck/mcp-server/README.md b/pitch-deck/mcp-server/README.md
new file mode 100644
index 0000000..5878f74
--- /dev/null
+++ b/pitch-deck/mcp-server/README.md
@@ -0,0 +1,123 @@
+# 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)