circuit-mcp 1.0.13 → 1.0.15

package/README.md

@@ -2,11 +2,13 @@
 
 Connect [Circuit](https://withcircuit.com) to Cursor and Claude Code via MCP (Model Context Protocol).
 
+**Circuit** transforms customer feedback into engineering specs. The MCP brings your priorities and briefs directly into your AI coding assistant.
+
 ## Quick Start
 
 ### Cursor
 
-Add to your Cursor settings (`Cmd+Shift+P` → "Cursor Settings: Open User Settings"):
+Add to `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -21,62 +23,75 @@ Add to your Cursor settings (`Cmd+Shift+P` → "Cursor Settings: Open User Setti
 
 ### Claude Code
 
-Run this command:
-
 ```bash
 claude mcp add circuit -- npx circuit-mcp
 ```
 
 ## First Run
 
-On first use, Circuit will open your browser to authenticate. After signing in, your token is cached locally at `~/.circuit/token.json`.
+On first use, Circuit opens your browser to authenticate. Your token is cached at `~/.circuit/token.json`.
 
 ```
-  ╭──────────────────────────────────╮
-  │  ⚡ Circuit MCP                  │
-  ╰──────────────────────────────────╯
+  Circuit MCP
 
   First time setup - let's connect your account.
-
   Opening browser to authenticate...
 
-  ✓ Connected!
+  Connected!
 ```
 
-## Commands
+## Available Tools
 
-```bash
-# Start MCP server (used by Cursor/Claude)
-npx circuit-mcp
+| Tool | Description |
+|------|-------------|
+| `get_priorities` | Get top customer priorities ranked by volume, urgency, or sentiment |
+| `get_brief` | Get the engineering spec for a priority (what to build, why, done criteria) |
+| `search_feedback` | Search raw customer feedback by keyword |
+| `start_building` | Mark a brief as "building" - you're working on it |
+| `mark_done` | Mark a brief as "done" - it shipped! |
 
-# Show setup instructions
-npx circuit-mcp setup
+## Example Usage
 
-# Re-authenticate
-npx circuit-mcp auth
+Ask your AI assistant:
 
-# Log out (clear stored token)
-npx circuit-mcp logout
-```
+> "What are my top 5 priorities?"
 
-## Available Tools
+> "Get the brief for priority #1"
 
-Once connected, your AI coding assistant can use these tools:
+> "Search feedback about login issues"
 
-| Tool | Description |
-|------|-------------|
-| `get_priorities` | Get top customer feedback priorities |
-| `get_brief` | Get the engineering brief for a priority |
-| `get_feedback` | Get raw customer feedback items |
+> "Mark that brief as done"
 
-### Example Usage in Cursor/Claude
+## Commands
 
-> "What are the top 5 customer priorities?"
+```bash
+npx circuit-mcp          # Start MCP server (used by Cursor/Claude)
+npx circuit-mcp setup    # Show setup instructions
+npx circuit-mcp auth     # Re-authenticate
+npx circuit-mcp logout   # Clear stored token
+```
+
+## How It Works
+
+```
+Circuit (app.withcircuit.com)
+         │
+         │ Feedback → Priorities → Briefs
+         │
+         ▼
+    Circuit MCP ◄─── Cursor / Claude Code
+         │
+         │ get_priorities, get_brief, etc.
+         │
+         ▼
+    Your AI assistant has context
+```
 
-> "Get the brief for priority #1 and help me implement it"
+## Links
 
-> "Show me recent feedback about authentication issues"
+- [Circuit](https://withcircuit.com) - Customer feedback intelligence
+- [MCP Protocol](https://modelcontextprotocol.io) - Model Context Protocol spec
 
 ## License
 
-MIT
+Proprietary - © Circuit (withcircuit.com)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "circuit-mcp",
-  "version": "1.0.13",
-  "description": "Circuit MCP server for Cursor and Claude Code",
+  "version": "1.0.15",
+  "description": "Connect Circuit to Cursor and Claude Code - bring customer priorities and engineering briefs into your AI coding assistant",
   "type": "module",
   "bin": {
     "circuit-mcp": "./bin/circuit-mcp.js"
@@ -13,13 +13,28 @@
   "keywords": [
     "circuit",
     "mcp",
+    "model-context-protocol",
     "cursor",
     "claude",
+    "claude-code",
     "ai",
-    "feedback"
+    "feedback",
+    "priorities",
+    "engineering",
+    "specs",
+    "customer-feedback"
   ],
-  "author": "Circuit",
-  "license": "MIT",
+  "author": "Circuit <hello@withcircuit.com>",
+  "license": "UNLICENSED",
+  "homepage": "https://withcircuit.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CatherineWilliamsTreloar/Circuit.git",
+    "directory": "circuit-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/CatherineWilliamsTreloar/Circuit/issues"
+  },
   "dependencies": {
     "chalk": "^5.3.0",
     "open": "^10.1.0"

package/src/server.js

@@ -173,6 +173,19 @@ async function handleMessage(message, token) {
                 },
                 required: ['query']
               }
+            },
+            {
+              name: 'get_insights',
+              description: 'Get high-level insights and patterns across your priorities. Identifies themes, trends, and strategic recommendations.',
+              inputSchema: {
+                type: 'object',
+                properties: {
+                  limit: {
+                    type: 'number',
+                    description: 'Number of priorities to analyze (default: 10)'
+                  }
+                }
+              }
             }
           ]
         }
@@ -204,6 +217,233 @@ async function handleMessage(message, token) {
   }
 }
 
+/**
+ * Format priorities for display (matches Circuit UI exactly)
+ */
+function formatPriorities(data) {
+  if (data.message) {
+    return data.message;
+  }
+
+  if (!data.priorities || data.priorities.length === 0) {
+    return 'No priorities found. Upload feedback to Circuit to get started.';
+  }
+
+  const lines = [];
+
+  for (const p of data.priorities) {
+    // Format trend indicator like Circuit UI
+    let trendText = '';
+    if (p.trend === 'up') {
+      trendText = ' ↑';
+    } else if (p.trend === 'down') {
+      trendText = ' ↓';
+    }
+
+    // Format: #Rank. Title
+    lines.push(`**#${p.rank}. ${p.theme}**`);
+
+    // Badges row: Category | X users | Trend | Status
+    const badges = [];
+    badges.push(p.category || 'Other');
+    badges.push(`${p.volume} users`);
+    if (trendText) badges.push(trendText.trim());
+    if (p.brief_status && p.brief_status !== 'no_brief') {
+      const statusLabel = { ready: 'Ready', building: 'Building', done: 'Done' }[p.brief_status];
+      if (statusLabel) badges.push(statusLabel);
+    }
+
+    lines.push(badges.join(' · '));
+
+    // Key quote (customer voice)
+    if (p.key_quote) {
+      lines.push(`> "${p.key_quote}"`);
+    }
+
+    lines.push(`priority_id: \`${p.id}\``);
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push('Use `get_brief` with a priority_id to see the full engineering spec.');
+
+  return lines.join('\n');
+}
+
+/**
+ * Format brief for display (matches Circuit UI format for Cursor/Claude)
+ */
+function formatBrief(data) {
+  if (data.error) {
+    if (data.error === 'no_brief' && data.priority) {
+      const p = data.priority;
+      let output = `# ${p.theme || 'Priority'}\n\n`;
+      output += `${p.category || 'Other'} · ${p.volume || 0} users\n\n`;
+      output += `**No brief generated yet**\n\n`;
+
+      if (p.summary) {
+        output += `${p.summary}\n\n`;
+      }
+
+      if (p.key_quote) {
+        output += `> "${p.key_quote}"\n\n`;
+      }
+
+      output += `---\n\n`;
+
+      // Include deep link to Circuit
+      if (data.circuit_url) {
+        output += `**Generate brief:** ${data.circuit_url}\n\n`;
+      }
+
+      output += `Or I can help you draft implementation notes based on the customer feedback above.`;
+      return output;
+    }
+    return `Error: ${data.message || data.error}`;
+  }
+
+  const spec = data.spec_content || '';
+
+  // Build header like Circuit UI exports
+  // Format: # Title
+  // Priority: #X | Mentions: Y | Type: Z
+  // ---
+  // {spec content}
+
+  let output = '';
+
+  // Status line
+  const statusText = {
+    'ready': 'Ready',
+    'building': 'Building',
+    'done': 'Done'
+  }[data.status] || data.status;
+
+  output += `Status: ${statusText}\n\n`;
+
+  // The spec_content should already be formatted markdown
+  // Clean up any XML-style tags to proper headers
+  let cleanSpec = spec
+    .replace(/<what_to_build>/gi, '## WHAT TO BUILD\n')
+    .replace(/<\/what_to_build>/gi, '\n')
+    .replace(/<why_it_matters>/gi, '## WHY IT MATTERS\n')
+    .replace(/<\/why_it_matters>/gi, '\n')
+    .replace(/<customer_voice>/gi, '## CUSTOMER VOICE\n')
+    .replace(/<\/customer_voice>/gi, '\n')
+    .replace(/<files_to_touch>/gi, '## FILES TO TOUCH\n')
+    .replace(/<\/files_to_touch>/gi, '\n')
+    .replace(/<done_when>/gi, '## DONE WHEN\n')
+    .replace(/<\/done_when>/gi, '\n');
+
+  output += cleanSpec;
+
+  output += `\n---\n`;
+  output += `build_id: \`${data.build_id}\``;
+
+  return output;
+}
+
+/**
+ * Format search results for display
+ */
+function formatSearchResults(data) {
+  if (data.message) {
+    return data.message;
+  }
+
+  if (!data.results || data.results.length === 0) {
+    return 'No feedback found matching your search.';
+  }
+
+  const lines = [`**${data.total} results found**\n`];
+
+  for (const f of data.results) {
+    lines.push(`**${f.source}** · Urgency: ${f.urgency}/5`);
+    lines.push(`> "${f.text}"`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format status change response
+ */
+function formatStatusChange(data) {
+  if (data.error) {
+    return `Error: ${data.error}`;
+  }
+
+  if (data.success) {
+    return data.message;
+  }
+
+  return JSON.stringify(data, null, 2);
+}
+
+/**
+ * Format insights for display
+ */
+function formatInsights(data) {
+  if (data.message) {
+    return data.message;
+  }
+
+  const lines = [];
+
+  lines.push(`## Insights from ${data.analyzed} priorities\n`);
+  lines.push(`**Total feedback volume:** ${data.total_feedback_volume} mentions\n`);
+
+  // Category breakdown
+  if (data.category_breakdown) {
+    lines.push('**Category breakdown:**');
+    for (const [cat, count] of Object.entries(data.category_breakdown)) {
+      lines.push(`- ${cat}: ${count}`);
+    }
+    lines.push('');
+  }
+
+  // Top 3 by volume
+  if (data.top_3_by_volume && data.top_3_by_volume.length > 0) {
+    lines.push('**Top priorities by volume:**');
+    for (const p of data.top_3_by_volume) {
+      lines.push(`- ${p.theme} (${p.volume} users, ${p.category})`);
+    }
+    lines.push('');
+  }
+
+  // Trends
+  if (data.trending_up && data.trending_up.length > 0) {
+    lines.push(`**Trending up:** ${data.trending_up.join(', ')}`);
+  }
+  if (data.trending_down && data.trending_down.length > 0) {
+    lines.push(`**Trending down:** ${data.trending_down.join(', ')}`);
+  }
+
+  // High urgency
+  if (data.high_urgency && data.high_urgency.length > 0) {
+    lines.push('\n**High urgency items:**');
+    for (const h of data.high_urgency) {
+      lines.push(`- ${h.theme} (urgency: ${h.urgency})`);
+    }
+  }
+
+  // Recommendations
+  if (data.recommendations && data.recommendations.length > 0) {
+    lines.push('\n**Recommendations:**');
+    for (const r of data.recommendations) {
+      lines.push(`- ${r}`);
+    }
+  }
+
+  lines.push('\n---');
+  if (data.circuit_url) {
+    lines.push(`View full details: ${data.circuit_url}`);
+  }
+
+  return lines.join('\n');
+}
+
 /**
  * Handle tool calls
  */
@@ -214,11 +454,35 @@ async function handleToolCall(id, params, token) {
     // Call the Circuit MCP backend
     const result = await callMcpApi(token, name, args || {});
 
+    // Format response based on tool type
+    let formattedText;
+
+    switch (name) {
+      case 'get_priorities':
+        formattedText = formatPriorities(result);
+        break;
+      case 'get_brief':
+        formattedText = formatBrief(result);
+        break;
+      case 'search_feedback':
+        formattedText = formatSearchResults(result);
+        break;
+      case 'start_building':
+      case 'mark_done':
+        formattedText = formatStatusChange(result);
+        break;
+      case 'get_insights':
+        formattedText = formatInsights(result);
+        break;
+      default:
+        formattedText = JSON.stringify(result, null, 2);
+    }
+
     return {
       jsonrpc: '2.0',
       id,
       result: {
-        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+        content: [{ type: 'text', text: formattedText }]
       }
     };