circuit-mcp 1.0.14 → 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.14",
-  "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)'
+                  }
+                }
+              }
             }
           ]
         }
@@ -230,11 +243,15 @@ function formatPriorities(data) {
     // Format: #Rank. Title
     lines.push(`**#${p.rank}. ${p.theme}**`);
 
-    // Badges row: Category | X users | Trend
+    // 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(' · '));
 
@@ -272,8 +289,14 @@ function formatBrief(data) {
         output += `> "${p.key_quote}"\n\n`;
       }
 
-      output += `---\n`;
-      output += data.suggestion;
+      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}`;
@@ -358,6 +381,69 @@ function formatStatusChange(data) {
   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
  */
@@ -385,6 +471,9 @@ async function handleToolCall(id, params, token) {
       case 'mark_done':
         formattedText = formatStatusChange(result);
         break;
+      case 'get_insights':
+        formattedText = formatInsights(result);
+        break;
       default:
         formattedText = JSON.stringify(result, null, 2);
     }