circuit-mcp 2.0.1 → 2.3.0

package/README.md

@@ -1,10 +1,18 @@
-# Circuit MCP
+# circuit-mcp
 
-Connect [Circuit](https://withcircuit.com) to Cursor and Claude Code via MCP (Model Context Protocol).
+Customer feedback in. Engineering specs out. Solve it with your AI coding tool.
 
-Circuit turns customer feedback into engineering specs. The MCP puts your priorities and briefs directly in your AI coding assistant — so you build what matters without switching tabs.
+Connect [Circuit](https://withcircuit.com) to **Cursor** and **Claude Code** via the Model Context Protocol.
 
-## Quick Start
+---
+
+## Setup
+
+### Claude Code
+
+```bash
+claude mcp add circuit -- npx circuit-mcp
+```
 
 ### Cursor
 
@@ -21,166 +29,148 @@ Add to `~/.cursor/mcp.json`:
 }
 ```
 
-### Claude Code
-
-```bash
-claude mcp add circuit -- npx circuit-mcp
-```
-
-### First Run
-
-On first use, Circuit opens your browser to authenticate. Your token is cached at `~/.circuit/token.json`.
-
-```
-Circuit MCP
-
-First time setup — let's connect your account.
-Opening browser to authenticate...
-
-✓ Connected!
-```
+First run opens your browser to authenticate. Token is cached at `~/.circuit/token.json` (30-day expiry).
 
 ---
 
-## Tools
+## 4 Tools
 
-Four tools. Everything you need to go from "what should I build?" to "shipped."
+### `circuit.priorities`
 
-### `circuit.priorities` — What should I work on?
+What should I work on? Ranked customer priorities with trends, confidence, and pattern matching.
 
-Returns ranked priorities with trend data, confidence scores, and pattern matching from your shipping history.
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `weekly` | boolean | Set to `true` to get the weekly digest instead (movements, new entries, drops, spikes) |
+| `lens` | string | How to rank: `volume`, `urgency`, `revenue`, `retention`, `delight`, `feature` |
+| `segment` | string | Customer segment: `enterprise`, `smb`, `all` |
+| `limit` | number | Number of results (default: 5, max: 20) |
+| `category` | string | Filter: `Bug`, `Feature`, `Friction`, `Complaint`, `Praise` |
 
-| Parameter | Description |
-|-----------|-------------|
-| `lens` | How to rank: `volume`, `urgency`, `revenue`, `retention`, `delight`, `feature` |
-| `segment` | Filter by customer segment: `enterprise`, `smb`, `all` |
-| `limit` | Number of priorities to return (default: 5, max: 20) |
-| `category` | Filter: `Bug`, `Feature`, `Friction`, `Complaint`, `Praise` |
+**Also returns:** Session context (last ship, in-progress builds, suggested next action) and instinct confidence (pattern matching from your shipping history).
 
-Each priority includes a `matches_pattern` flag — Circuit learns what you tend to ship and surfaces priorities that fit your instincts.
+**Weekly mode** (`weekly: true`): Returns priority movements (rank changes), new entries, dropped items, and volume spikes compared to last week.
 
-**Try it:** *"What are my top priorities by revenue impact for enterprise customers?"*
+### `circuit.spec`
 
-### `circuit.brief` — The full engineering spec
+Full engineering spec for a priority. 5 sections: What to Build, Why It Matters, Customer Voice (verbatim quotes), Files to Touch, Done When.
 
-Returns the complete brief for a priority: **What** to build, **Why** it matters, **Voice of the customer**, **Files** to touch, and **Done** criteria. Includes customer quotes, version history, and context from previous ships.
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `priority_id` | string | Priority ID from `circuit.priorities` |
+| `spec_id` | string | Spec ID directly (alternative to priority_id) |
+| `include_history` | boolean | Include version history and ship memory (default: true) |
+| `batch` | boolean | Set to `true` to export multiple specs as markdown |
+| `spec_ids` | string[] | Specific spec IDs to export (batch mode) |
+| `status` | string | Filter specs by status in batch mode: `ready`, `building`, `shipped` |
+| `limit` | number | Number of specs in batch mode (default: 10, max: 50) |
 
-| Parameter | Description |
-|-----------|-------------|
-| `priority_id` or `build_id` | Which priority to get the brief for |
-| `include_history` | Include version history and related ship memory (default: true) |
+**Also returns:** Post-ship signal (new feedback since shipping), effort estimate, codebase context (tech stack, related PRs, AI config files like CLAUDE.md), and related memories from previous ships.
 
-Uses a 3-layer matching strategy to find the right brief, even with partial or ambiguous IDs.
+**Batch mode** (`batch: true`): Exports multiple specs as formatted markdown for sprint planning or documentation.
 
-**Try it:** *"Get the brief for priority #1"*
+### `circuit.act`
 
-### `circuit.act` — Take action
-
-One tool, four actions. Move work forward without leaving your editor.
+Take action. Start building, ship it, share back, assign, correct, submit feedback, or submit a transcript.
 
 | Action | What it does |
 |--------|-------------|
-| `build` | Mark a brief as "building" — you're working on it |
-| `ship` | Mark shipped. Auto-notifies customers who submitted feedback via the widget. Creates a ship memory so Circuit learns your patterns. |
-| `correct` | Fix an AI classification that got it wrong. Writes a correction memory and recomputes pattern matching. |
-| `submit` | Add new feedback directly via MCP |
-
-**Try it:** *"Mark the login brief as building"* → build it → *"Ship it"*
+| `build` | Mark spec as "building" |
+| `ship` | Mark as shipped, record memory |
+| `share` | Notify customers who submitted feedback (email, widget, or both) |
+| `assign` | Assign spec to a team member by email or user ID |
+| `correct` | Fix a priority's category classification (Circuit remembers corrections) |
+| `submit` | Add new feedback from your terminal |
+| `transcript` | Submit a customer interview, sales call, or support transcript |
 
-### `circuit.ask` — Search across everything
+**Share parameters** (when `action: "share"`):
 
-Semantic search across feedback, priorities, briefs, and help docs. Also returns your behavioral patterns — ship count, top categories, segment affinity — so your assistant has full context.
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `spec_id` | string | Spec ID (required) |
+| `channel` | string | `email`, `widget`, `both`, `skip` |
+| `message` | string | Custom message to include in notifications (optional) |
 
-**Try it:** *"Search for feedback about onboarding friction"*
+**Transcript parameters** (when `action: "transcript"`):
 
----
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `text` | string | Full transcript text (min 50 chars, required) |
+| `title` | string | Title, e.g. "Sales call with Acme Corp" |
+| `type` | string | `interview`, `sales_call`, `support`, `other` |
+| `customer_name` | string | Customer name (optional) |
+| `customer_email` | string | Customer email (optional, for close-the-loop notifications) |
+| `revenue_band` | string | `enterprise`, `paid`, `free` |
 
-## Example Workflow
+### `circuit.ask`
 
-A typical session looks like this:
-
-```
-You:     "What should I work on?"
-Circuit: → circuit.priorities (lens: urgency)
-         Returns top 5, #1 is "Login timeout on slow connections"
+Semantic search across all your data: feedback, priorities, specs, and help articles. Returns your shipping patterns and behavioral insights. Also searches your connected GitHub repo for code context.
 
-You:     "Get me the brief for that"
-Circuit: → circuit.brief (priority_id: ...)
-         Returns spec: what to build, affected files, done criteria
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `question` | string | Natural language, e.g. "What are enterprise customers saying about onboarding?" |
 
-You:     "I'm on it"
-Circuit: → circuit.act (action: build)
-         Marked as building
+---
 
-         ... you write the code ...
+## Workflow
 
-You:     "Done, ship it"
-Circuit: → circuit.act (action: ship)
-         Marked as shipped. 12 customers notified.
 ```
-
-Feedback in. Spec out. Code shipped. Customers notified. That's the circuit.
+> circuit.priorities {weekly: true}          # What changed since last week?
+> circuit.priorities                         # See what matters
+> circuit.spec {priority_id: "..."}          # Get the spec
+> circuit.act {action: "build", ...}         # Start building
+> ... write the code ...
+> circuit.act {action: "ship", ...}          # Ship it.
+> circuit.act {action: "share", channel: "both"} # Share back. Customers notified.
+> circuit.spec {batch: true, status: "shipped"} # Export shipped specs
+```
 
 ---
 
-## Commands
+## CLI Commands
 
 ```bash
-npx circuit-mcp            # Start MCP server (used by Cursor/Claude Code)
-npx circuit-mcp setup      # Show setup instructions
-npx circuit-mcp auth       # Re-authenticate
-npx circuit-mcp logout     # Clear stored token
+npx circuit-mcp              # Start MCP server (stdio mode)
+npx circuit-mcp setup        # Interactive setup
+npx circuit-mcp auth         # Re-authenticate
+npx circuit-mcp logout       # Clear stored token
+npx circuit-mcp fix          # Troubleshooting guide
 ```
 
-## Troubleshooting
+---
 
-**"Authentication failed" or token expired**
-```bash
-npx circuit-mcp auth
-```
-Tokens last 30 days. Re-auth opens your browser — takes 5 seconds.
+## Troubleshooting
 
-**Cursor not detecting the MCP server**
-1. Confirm `~/.cursor/mcp.json` has the config above
-2. Restart Cursor
-3. Check the MCP panel shows "circuit" as connected
+**"Token expired"** — Run `npx circuit-mcp auth` to re-authenticate.
 
-**Claude Code not finding tools**
-```bash
-claude mcp list              # Verify circuit is registered
-claude mcp remove circuit    # Remove and re-add if needed
-claude mcp add circuit -- npx circuit-mcp
-```
+**"Connection refused"** — Check your internet connection. The MCP connects to Circuit's API.
 
-**"Priority not found" errors**
+**Tool not showing in Cursor/Claude** — Restart your editor after adding the MCP config.
 
-Circuit uses a 3-layer matching strategy, but if you're referencing old IDs, priorities may have been recomputed. Run `circuit.priorities` to get current IDs.
+**Custom API URL** — Set `CIRCUIT_API_URL` environment variable to override the default endpoint.
 
 ---
 
-## How It Works
+## How it works
 
 ```
-Customer feedback
-       ↓
-Circuit (app.withcircuit.com)
-  Feedback → Priorities → Specs
-       ↓
-  Circuit MCP ←── Your AI assistant (Cursor / Claude Code)
-       ↓
-  circuit.priorities  →  What to build
-  circuit.brief       →  How to build it
-  circuit.act         →  Ship it + notify customers
-  circuit.ask         →  Search everything
+Your editor (Cursor / Claude Code)
+    |
+    | JSON-RPC over stdio
+    |
+circuit-mcp (this package)
+    |
+    | HTTPS + Bearer token
+    |
+Circuit API
+    |
+    | PostgreSQL + pgvector
+    |
+Your feedback data
 ```
 
-Auth uses OAuth 2.0 with PKCE. Tokens are SHA-256 hashed with 30-day expiry. All tools are memory-aware — Circuit learns from your corrections and shipping patterns to get smarter over time.
-
-## Links
+The MCP server runs as a local process, communicating with your editor via stdin/stdout. All data stays in your Circuit account, authenticated via OAuth 2.0.
 
-- [Circuit](https://withcircuit.com) — Customer feedback intelligence
-- [MCP Protocol](https://modelcontextprotocol.io) — Model Context Protocol spec
-
-## License
+---
 
-Proprietary — © Circuit ([withcircuit.com](https://withcircuit.com))
+Built by [Circuit](https://withcircuit.com). Feedback in. Specs out.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "circuit-mcp",
-  "version": "2.0.1",
+  "version": "2.3.0",
   "description": "Connect Circuit to Cursor and Claude Code - bring customer priorities and engineering briefs into your AI coding assistant",
   "type": "module",
   "bin": {

package/preview-error.html

@@ -0,0 +1,57 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Circuit - Connection Failed</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: 'Geist', -apple-system, BlinkMacSystemFont, system-ui, 'Segoe UI', Roboto, sans-serif;
+      background: #F5F3F0;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      color: #1C1A18;
+      padding: 24px;
+    }
+    .content {
+      text-align: center;
+      max-width: 400px;
+    }
+    .icon {
+      margin-bottom: 24px;
+    }
+    .icon svg {
+      width: 48px;
+      height: 48px;
+      color: #D64545;
+    }
+    h1 {
+      font-size: 24px;
+      font-weight: 600;
+      color: #1C1A18;
+      margin-bottom: 12px;
+    }
+    p {
+      font-size: 14px;
+      color: rgba(28, 26, 24, 0.6);
+      line-height: 1.6;
+    }
+    .hint {
+      font-size: 12px;
+      color: rgba(28, 26, 24, 0.6);
+      margin-top: 16px;
+    }
+  </style>
+</head>
+<body>
+  <div class="content">
+    <div class="icon">
+      <svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="15" y1="9" x2="9" y2="15"/><line x1="9" y1="9" x2="15" y2="15"/></svg>
+    </div>
+    <h1>Connection Failed</h1>
+    <p>Authentication timed out</p>
+    <p class="hint">Please try connecting again from your AI assistant.</p>
+  </div>
+</body>
+</html>

package/preview-success.html

@@ -0,0 +1,57 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Circuit - Connected</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body {
+      font-family: 'Geist', -apple-system, BlinkMacSystemFont, system-ui, 'Segoe UI', Roboto, sans-serif;
+      background: #F5F3F0;
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      color: #1C1A18;
+      padding: 24px;
+    }
+    .content {
+      text-align: center;
+      max-width: 400px;
+    }
+    .icon {
+      margin-bottom: 24px;
+    }
+    .icon svg {
+      width: 48px;
+      height: 48px;
+      color: #1C1A18;
+    }
+    h1 {
+      font-size: 24px;
+      font-weight: 600;
+      color: #1C1A18;
+      margin-bottom: 12px;
+    }
+    p {
+      font-size: 14px;
+      color: rgba(28, 26, 24, 0.6);
+      line-height: 1.6;
+    }
+    .hint {
+      font-size: 12px;
+      color: rgba(28, 26, 24, 0.6);
+      margin-top: 16px;
+    }
+  </style>
+</head>
+<body>
+  <div class="content">
+    <div class="icon">
+      <svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><polyline points="22 4 12 14.01 9 11.01"/></svg>
+    </div>
+    <h1>Connected.</h1>
+    <p>Your AI coding assistant is now connected to Circuit.</p>
+    <p class="hint">This window will close automatically...</p>
+  </div>
+</body>
+</html>

package/src/auth.js

@@ -8,7 +8,7 @@ import open from 'open';
 import chalk from 'chalk';
 import { showSpinner, showInfo, showPrompt } from './ui.js';
 
-const CIRCUIT_URL = 'https://app.withcircuit.com';
+const CIRCUIT_URL = process.env.CIRCUIT_APP_URL || 'https://app.withcircuit.com';
 const TOKEN_FILE = path.join(os.homedir(), '.circuit', 'token.json');
 
 /**
@@ -136,79 +136,57 @@ function getSuccessPage() {
   return `<!DOCTYPE html>
 <html>
 <head>
-  <title>Circuit - Connected!</title>
+  <title>Circuit - Connected</title>
   <style>
     * { margin: 0; padding: 0; box-sizing: border-box; }
     body {
-      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-      background: #F5F1EA;
+      font-family: 'Geist', -apple-system, BlinkMacSystemFont, system-ui, 'Segoe UI', Roboto, sans-serif;
+      background: #F5F3F0;
       min-height: 100vh;
       display: flex;
       align-items: center;
       justify-content: center;
       color: #1C1A18;
+      padding: 24px;
     }
-    .card {
-      background: white;
-      border-radius: 16px;
-      box-shadow: 0 4px 24px rgba(0,0,0,0.08);
-      padding: 48px 64px;
+    .content {
       text-align: center;
-      max-width: 420px;
+      max-width: 400px;
     }
-    .logo {
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      gap: 8px;
-      margin-bottom: 32px;
-    }
-    .logo-icon {
-      width: 28px;
-      height: 28px;
-      background: #1C1A18;
-      border-radius: 50%;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-    }
-    .logo-icon::after {
-      content: '';
-      width: 12px;
-      height: 12px;
-      border: 2px solid white;
-      border-radius: 50%;
+    .icon {
+      margin-bottom: 24px;
     }
-    .logo-text {
-      font-size: 16px;
-      font-weight: 500;
-    }
-    .woo {
-      font-size: 14px;
-      color: rgba(28,26,24,0.5);
-      margin-bottom: 8px;
+    .icon svg {
+      width: 48px;
+      height: 48px;
+      color: #1C1A18;
     }
     h1 {
-      font-size: 28px;
+      font-size: 24px;
       font-weight: 600;
+      color: #1C1A18;
       margin-bottom: 12px;
     }
     p {
-      font-size: 15px;
-      color: rgba(28,26,24,0.6);
-      line-height: 1.5;
+      font-size: 14px;
+      color: rgba(28, 26, 24, 0.6);
+      line-height: 1.6;
+    }
+    .hint {
+      font-size: 12px;
+      color: rgba(28, 26, 24, 0.6);
+      margin-top: 16px;
     }
   </style>
 </head>
 <body>
-  <div class="card">
-    <div class="logo">
-      <div class="logo-icon"></div>
-      <span class="logo-text">Circuit</span>
+  <div class="content">
+    <div class="icon">
+      <svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><polyline points="22 4 12 14.01 9 11.01"/></svg>
     </div>
-    <p class="woo">Woo hoo!</p>
-    <h1>Connected to Circuit</h1>
-    <p>You can close this window to continue Circuiting.</p>
+    <h1>Connected.</h1>
+    <p>Your AI coding assistant is now connected to Circuit.</p>
+    <p class="hint">This window will close automatically...</p>
   </div>
   <script>setTimeout(() => window.close(), 3000);</script>
 </body>
@@ -216,32 +194,65 @@ function getSuccessPage() {
 }
 
 function getErrorPage(error) {
+  // Sanitize error message to prevent XSS in the static HTML page
+  const safeError = String(error).replace(/[<>&"']/g, c => ({
+    '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&#39;'
+  })[c]);
+
   return `<!DOCTYPE html>
 <html>
 <head>
-  <title>Circuit - Error</title>
+  <title>Circuit - Connection Failed</title>
   <style>
     * { margin: 0; padding: 0; box-sizing: border-box; }
     body {
-      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-      background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+      font-family: 'Geist', -apple-system, BlinkMacSystemFont, system-ui, 'Segoe UI', Roboto, sans-serif;
+      background: #F5F3F0;
       min-height: 100vh;
       display: flex;
       align-items: center;
       justify-content: center;
-      color: white;
+      color: #1C1A18;
+      padding: 24px;
+    }
+    .content {
+      text-align: center;
+      max-width: 400px;
+    }
+    .icon {
+      margin-bottom: 24px;
+    }
+    .icon svg {
+      width: 48px;
+      height: 48px;
+      color: #D64545;
+    }
+    h1 {
+      font-size: 24px;
+      font-weight: 600;
+      color: #1C1A18;
+      margin-bottom: 12px;
+    }
+    p {
+      font-size: 14px;
+      color: rgba(28, 26, 24, 0.6);
+      line-height: 1.6;
+    }
+    .hint {
+      font-size: 12px;
+      color: rgba(28, 26, 24, 0.6);
+      margin-top: 16px;
     }
-    .container { text-align: center; padding: 48px; }
-    .icon { font-size: 64px; margin-bottom: 24px; }
-    h1 { font-size: 32px; color: #ef4444; margin-bottom: 16px; }
-    p { font-size: 18px; color: rgba(255,255,255,0.7); }
   </style>
 </head>
 <body>
-  <div class="container">
-    <div class="icon">⚠️</div>
-    <h1>Authentication Failed</h1>
-    <p>${error}</p>
+  <div class="content">
+    <div class="icon">
+      <svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><line x1="15" y1="9" x2="9" y2="15"/><line x1="9" y1="9" x2="15" y2="15"/></svg>
+    </div>
+    <h1>Connection Failed</h1>
+    <p>${safeError}</p>
+    <p class="hint">Please try connecting again from your AI assistant.</p>
   </div>
 </body>
 </html>`;