circuit-mcp 2.3.2 → 2.3.4

package/README.md

@@ -1,10 +1,7 @@
 # circuit-mcp
+Feedback in. Specs out. Build it with your AI coding tool.
 
-Customer feedback in. Engineering specs out. Solve it with your AI coding tool.
-
-Connect [Circuit](https://withcircuit.com) to **Cursor** and **Claude Code** via the Model Context Protocol.
-
----
+Connect Circuit to Cursor and Claude Code via the Model Context Protocol.
 
 ## Setup
 
@@ -33,144 +30,73 @@ First run opens your browser to authenticate. Token is cached at `~/.circuit/tok
 
 ---
 
-## 4 Tools
+## 4 tools
 
-### `circuit.priorities`
+### circuit.priorities
 
-What should I work on? Ranked customer priorities with trends, confidence, and pattern matching.
+What should I work on? Ranked customer priorities with revenue impact and trend data.
 
 | 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` |
-
-**Also returns:** Session context (last ship, in-progress builds, suggested next action) and instinct confidence (pattern matching from your shipping history).
-
-**Weekly mode** (`weekly: true`): Returns priority movements (rank changes), new entries, dropped items, and volume spikes compared to last week.
+| weekly | boolean | Weekly digest (movements, new entries, drops, spikes) |
+| lens | string | How to rank: volume, urgency, revenue, retention, delight, feature |
+| segment | string | enterprise, smb, all |
+| limit | number | Default: 5, max: 20 |
+| category | string | Filter: Bug, Feature, Improvement, Praise |
 
-### `circuit.spec`
+### circuit.spec
 
-Full engineering spec for a priority. 5 sections: What to Build, Why It Matters, Customer Voice (verbatim quotes), Files to Touch, Done When.
+Full spec. 5 sections: What to Build, Why It Matters, Customer Voice, Files to Touch, Done When.
 
 | 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) |
+| priority_id | string | From circuit.priorities |
+| batch | boolean | Export multiple specs as markdown |
+| status | string | Filter: ready, building, shipped |
+| limit | number | Default: 10, max: 50 |
 
-**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.
+### circuit.act
 
-**Batch mode** (`batch: true`): Exports multiple specs as formatted markdown for sprint planning or documentation.
-
-### `circuit.act`
-
-Take action. Start building, ship it, share back, assign, correct, submit feedback, or submit a transcript.
+Start building, ship, notify customers, assign, correct, submit feedback or transcript.
 
 | Action | What it does |
 |--------|-------------|
-| `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 |
+| build | Mark as "building" |
+| ship | Mark as shipped, record memory |
+| share | Notify customers (email, widget, or both) |
+| assign | Assign to team member |
+| correct | Fix category classification |
+| submit | Add new feedback |
+| transcript | Submit customer interview/call |
 
-**Share parameters** (when `action: "share"`):
+### circuit.ask
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `spec_id` | string | Spec ID (required) |
-| `channel` | string | `email`, `widget`, `both`, `skip` |
-| `message` | string | Custom message to include in notifications (optional) |
-
-**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` |
-
-### `circuit.ask`
-
-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.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `question` | string | Natural language, e.g. "What are enterprise customers saying about onboarding?" |
+Semantic search across feedback, priorities, specs, help articles and your GitHub repo.
 
 ---
 
 ## Workflow
 
-```
-> 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
-```
-
----
-
-## CLI Commands
-
 ```bash
-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
+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
+circuit.act {action: "ship", ...}       # Ship.
+circuit.act {action: "share", channel: "both"}  # Customers notified.
 ```
 
 ---
 
-## Troubleshooting
-
-**"Token expired"** — Run `npx circuit-mcp auth` to re-authenticate.
-
-**"Connection refused"** — Check your internet connection. The MCP connects to Circuit's API.
+## CLI commands
 
-**Tool not showing in Cursor/Claude** — Restart your editor after adding the MCP config.
-
-**Custom API URL** — Set `CIRCUIT_API_URL` environment variable to override the default endpoint.
-
----
-
-## How it works
-
-```
-Your editor (Cursor / Claude Code)
-    |
-    | JSON-RPC over stdio
-    |
-circuit-mcp (this package)
-    |
-    | HTTPS + Bearer token
-    |
-Circuit API
-    |
-    | PostgreSQL + pgvector
-    |
-Your feedback data
+```bash
+npx circuit-mcp         # Start MCP server
+npx circuit-mcp auth    # Re-authenticate
+npx circuit-mcp logout  # Clear stored token
+npx circuit-mcp fix     # Troubleshooting guide
 ```
 
-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.
-
 ---
 
-Built by [Circuit](https://withcircuit.com). Feedback in. Specs out.
+Built by Circuit. Feedback in. Specs out.

package/package.json

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

package/src/auth.js

@@ -137,6 +137,7 @@ function getSuccessPage() {
 <html>
 <head>
   <title>Circuit - Connected</title>
+  <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg width='32' height='32' viewBox='0 0 32 32' fill='none' xmlns='http://www.w3.org/2000/svg'><defs><mask id='m'><circle cx='16' cy='16' r='13' fill='white'/><circle cx='16' cy='16' r='6.9' fill='black'/></mask></defs><ellipse cx='16' cy='17.73' rx='13' ry='11.27' fill='rgba(168,102,122,0.2)'/><circle cx='16' cy='16' r='13' fill='%23A8667A' mask='url(%23m)'/></svg>">
   <style>
     * { margin: 0; padding: 0; box-sizing: border-box; }
     body {
@@ -186,7 +187,7 @@ function getSuccessPage() {
     </div>
     <h1>Connected.</h1>
     <p>Your AI coding assistant is now connected to Circuit.</p>
-    <p class="hint">This window will close automatically...</p>
+    <p class="hint">You can close this tab and return to your editor.</p>
   </div>
   <script>setTimeout(() => window.close(), 3000);</script>
 </body>
@@ -203,6 +204,7 @@ function getErrorPage(error) {
 <html>
 <head>
   <title>Circuit - Connection Failed</title>
+  <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg width='32' height='32' viewBox='0 0 32 32' fill='none' xmlns='http://www.w3.org/2000/svg'><defs><mask id='m'><circle cx='16' cy='16' r='13' fill='white'/><circle cx='16' cy='16' r='6.9' fill='black'/></mask></defs><ellipse cx='16' cy='17.73' rx='13' ry='11.27' fill='rgba(168,102,122,0.2)'/><circle cx='16' cy='16' r='13' fill='%23A8667A' mask='url(%23m)'/></svg>">
   <style>
     * { margin: 0; padding: 0; box-sizing: border-box; }
     body {

package/src/index.js

@@ -132,15 +132,28 @@ function prompt(question) {
 function showUsageGuide() {
   console.log(chalk.dim('  ─────────────────────────────────────────\n'));
   console.log(chalk.white.bold('  How to use Circuit\n'));
-  console.log(chalk.dim('  Open Claude Code or Cursor and ask:\n'));
-  console.log(chalk.white('  "What are my top priorities?"'));
-  console.log(chalk.white('  "Show me the brief for priority #1"'));
-  console.log(chalk.white('  "What feedback mentions dark mode?"'));
-  console.log(chalk.white('  "What are my most urgent issues?"'));
-  console.log(chalk.white('  "Show priorities by revenue impact"'));
-  console.log();
-  console.log(chalk.dim('  Circuit will fetch your real customer data.'));
-  console.log(chalk.dim('  Just ask naturally and your AI will handle the rest.\n'));
+  console.log(chalk.dim('  Open Claude Code or Cursor and try:\n'));
+
+  console.log(chalk.cyan('  circuit.priorities') + chalk.dim(' — What should I work on?'));
+  console.log(chalk.dim('  "What are my top priorities?"'));
+  console.log(chalk.dim('  "Show priorities by revenue impact"'));
+  console.log(chalk.dim('  "What\'s changed this week?"\n'));
+
+  console.log(chalk.cyan('  circuit.spec') + chalk.dim(' — Full engineering spec for a priority'));
+  console.log(chalk.dim('  "Show me the spec for priority #1"'));
+  console.log(chalk.dim('  "Get the brief for <priority_id>"\n'));
+
+  console.log(chalk.cyan('  circuit.act') + chalk.dim(' — Take action on a spec'));
+  console.log(chalk.dim('  "Start building <spec_id>"'));
+  console.log(chalk.dim('  "Mark <spec_id> as shipped"'));
+  console.log(chalk.dim('  "Tell customers we shipped <spec_id>"\n'));
+
+  console.log(chalk.cyan('  circuit.ask') + chalk.dim(' — Search across all your feedback'));
+  console.log(chalk.dim('  "What feedback mentions dark mode?"'));
+  console.log(chalk.dim('  "What are enterprise customers asking for?"\n'));
+
+  console.log(chalk.dim('  Circuit fetches your real customer data.'));
+  console.log(chalk.dim('  Just ask naturally — your AI handles the rest.\n'));
 }
 
 // Configure Cursor by writing to ~/.cursor/mcp.json

package/src/server.js

@@ -85,7 +85,13 @@ async function handleMessage(message, token) {
         result: {
           protocolVersion: '2024-11-05',
           serverInfo: { name: 'circuit-mcp', version: '2.2.0' },
-          capabilities: { tools: {}, resources: {} }
+          capabilities: { tools: {}, resources: {} },
+          instructions: `Circuit is connected. 4 tools available:
+• circuit.priorities — what to work on next
+• circuit.spec — engineering spec for any priority
+• circuit.act — ship and close the loop with customers
+• circuit.ask — search across all your feedback
+Run circuit.help for examples.`
         }
       };
 
@@ -290,6 +296,14 @@ const TOOLS = [
       },
       required: ['question']
     }
+  },
+  {
+    name: 'circuit.help',
+    description: 'Show what Circuit can do — all available tools, example prompts, and how to use them.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
   }
 ];
 
@@ -524,6 +538,43 @@ function formatBatchExport(data) {
   return output;
 }
 
+function formatHelp() {
+  return `# Circuit — What I can do
+
+## circuit.priorities — What should I work on?
+Ranked customer priorities with revenue impact and trend data.
+
+* "What are my top priorities?"
+* "Show priorities by revenue impact"
+* "Show urgent bugs only"
+* "What's changed this week?"
+* "Show enterprise priorities"
+
+## circuit.spec — Engineering spec for a priority
+5 sections: What to Build, Why It Matters, Customer Voice, Files to Touch, Done When.
+* "Show me the spec for priority #1"
+* "Get the brief for <priority_id>"
+* "Export all ready specs for sprint planning"
+
+## circuit.act — Ship it and close the loop
+Start building, mark as shipped, notify customers, assign to a team member, or submit new feedback.
+* "Start building <spec_id>"
+* "Mark <spec_id> as shipped"
+* "Tell customers we shipped <spec_id>"
+* "Assign <spec_id> to Catherine"
+* "Submit feedback: users want dark mode"
+* "Submit transcript: <transcript text>"
+
+## circuit.ask — Search across all your feedback
+Ask anything about your customers, feedback or priorities.
+* "What feedback mentions dark mode?"
+* "What are enterprise customers asking for?"
+* "Have we shipped anything related to CSV exports?"
+* "What's our most common bug type?"
+
+Ask naturally — Circuit picks the right tool.`;
+}
+
 // ─────────────────────────────────────────────────────────────
 // Tool Call Handler
 // ─────────────────────────────────────────────────────────────
@@ -539,6 +590,7 @@ async function handleToolCall(id, params, token) {
       'circuit.spec': formatSpec,
       'circuit.act': formatAct,
       'circuit.ask': formatAsk,
+      'circuit.help': () => formatHelp(),
     };
 
     const formatter = formatters[name] || ((d) => JSON.stringify(d, null, 2));