circuit-mcp 1.0.0

package/README.md

@@ -0,0 +1,82 @@
+# Circuit MCP
+
+Connect [Circuit](https://withcircuit.com) to Cursor and Claude Code via MCP (Model Context Protocol).
+
+## Quick Start
+
+### Cursor
+
+Add to your Cursor settings (`Cmd+Shift+P` → "Cursor Settings: Open User Settings"):
+
+```json
+{
+  "mcpServers": {
+    "circuit": {
+      "command": "npx",
+      "args": ["circuit-mcp"]
+    }
+  }
+}
+```
+
+### 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`.
+
+```
+  ╭──────────────────────────────────╮
+  │  ⚡ Circuit MCP                  │
+  ╰──────────────────────────────────╯
+
+  First time setup - let's connect your account.
+
+  Opening browser to authenticate...
+
+  ✓ Connected!
+```
+
+## Commands
+
+```bash
+# Start MCP server (used by Cursor/Claude)
+npx circuit-mcp
+
+# Show setup instructions
+npx circuit-mcp setup
+
+# Re-authenticate
+npx circuit-mcp auth
+
+# Log out (clear stored token)
+npx circuit-mcp logout
+```
+
+## Available Tools
+
+Once connected, your AI coding assistant can use these tools:
+
+| 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 |
+
+### Example Usage in Cursor/Claude
+
+> "What are the top 5 customer priorities?"
+
+> "Get the brief for priority #1 and help me implement it"
+
+> "Show me recent feedback about authentication issues"
+
+## License
+
+MIT

package/bin/circuit-mcp.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { main } from '../src/index.js';
+
+main().catch(err => {
+  console.error('Fatal error:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "circuit-mcp",
+  "version": "1.0.0",
+  "description": "Circuit MCP server for Cursor and Claude Code",
+  "type": "module",
+  "bin": {
+    "circuit-mcp": "./bin/circuit-mcp.js"
+  },
+  "main": "./src/index.js",
+  "scripts": {
+    "start": "node bin/circuit-mcp.js"
+  },
+  "keywords": [
+    "circuit",
+    "mcp",
+    "cursor",
+    "claude",
+    "ai",
+    "feedback"
+  ],
+  "author": "Circuit",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "open": "^10.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/auth.js

@@ -0,0 +1,217 @@
+import http from 'http';
+import { URL } from 'url';
+import { randomBytes } from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import open from 'open';
+import chalk from 'chalk';
+import { showSpinner, showInfo, showPrompt } from './ui.js';
+
+const CIRCUIT_URL = 'https://app.withcircuit.com';
+const TOKEN_FILE = path.join(os.homedir(), '.circuit', 'token.json');
+
+/**
+ * Get stored token from disk
+ */
+export async function getStoredToken() {
+  try {
+    const data = await fs.readFile(TOKEN_FILE, 'utf-8');
+    const { token, expiresAt } = JSON.parse(data);
+
+    // Check if expired
+    if (expiresAt && new Date(expiresAt) < new Date()) {
+      await clearToken();
+      return null;
+    }
+
+    return token;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store token to disk
+ */
+async function storeToken(token, expiresIn = 86400 * 30) {
+  const dir = path.dirname(TOKEN_FILE);
+  await fs.mkdir(dir, { recursive: true });
+
+  const expiresAt = new Date(Date.now() + expiresIn * 1000).toISOString();
+  await fs.writeFile(TOKEN_FILE, JSON.stringify({ token, expiresAt }, null, 2));
+}
+
+/**
+ * Clear stored token
+ */
+export async function clearToken() {
+  try {
+    await fs.unlink(TOKEN_FILE);
+  } catch {
+    // Ignore if file doesn't exist
+  }
+}
+
+/**
+ * Authenticate with Circuit via OAuth
+ */
+export async function authenticate() {
+  return new Promise((resolve, reject) => {
+    // Find available port
+    const server = http.createServer();
+
+    server.listen(0, '127.0.0.1', async () => {
+      const { port } = server.address();
+      const callbackUrl = `http://127.0.0.1:${port}/callback`;
+      const state = randomBytes(16).toString('hex');
+
+      // Build auth URL
+      const authUrl = new URL(`${CIRCUIT_URL}/mcp/auth`);
+      authUrl.searchParams.set('redirect_uri', callbackUrl);
+      authUrl.searchParams.set('state', state);
+      authUrl.searchParams.set('response_type', 'code');
+
+      // Handle callback
+      server.on('request', async (req, res) => {
+        const url = new URL(req.url, `http://127.0.0.1:${port}`);
+
+        if (url.pathname === '/callback') {
+          const token = url.searchParams.get('access_token');
+          const error = url.searchParams.get('error');
+          const returnedState = url.searchParams.get('state');
+
+          if (error) {
+            res.writeHead(400, { 'Content-Type': 'text/html' });
+            res.end(getErrorPage(error));
+            server.close();
+            reject(new Error(error));
+            return;
+          }
+
+          if (!token) {
+            res.writeHead(400, { 'Content-Type': 'text/html' });
+            res.end(getErrorPage('No token received'));
+            server.close();
+            reject(new Error('No token received'));
+            return;
+          }
+
+          // Store token
+          await storeToken(token);
+
+          // Send success page
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end(getSuccessPage());
+
+          server.close();
+          resolve(token);
+        }
+      });
+
+      // Open browser
+      console.log(chalk.dim('  Opening browser to authenticate...\n'));
+      showInfo(`If browser doesn't open, visit:\n     ${chalk.cyan(authUrl.toString())}\n`);
+
+      try {
+        await open(authUrl.toString());
+      } catch {
+        // Browser failed to open, user will need to click link
+      }
+
+      // Timeout after 5 minutes
+      setTimeout(() => {
+        server.close();
+        reject(new Error('Authentication timed out'));
+      }, 5 * 60 * 1000);
+    });
+
+    server.on('error', reject);
+  });
+}
+
+function getSuccessPage() {
+  return `<!DOCTYPE html>
+<html>
+<head>
+  <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: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      color: white;
+    }
+    .container {
+      text-align: center;
+      padding: 48px;
+    }
+    .icon {
+      font-size: 64px;
+      margin-bottom: 24px;
+    }
+    h1 {
+      font-size: 32px;
+      font-weight: 600;
+      margin-bottom: 16px;
+      color: #6366F1;
+    }
+    p {
+      font-size: 18px;
+      color: rgba(255,255,255,0.7);
+      margin-bottom: 8px;
+    }
+    .hint {
+      margin-top: 32px;
+      font-size: 14px;
+      color: rgba(255,255,255,0.5);
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div class="icon">⚡</div>
+    <h1>Connected to Circuit!</h1>
+    <p>You can close this window and return to your terminal.</p>
+    <p class="hint">Circuit is now ready to use in Cursor or Claude Code.</p>
+  </div>
+  <script>setTimeout(() => window.close(), 3000);</script>
+</body>
+</html>`;
+}
+
+function getErrorPage(error) {
+  return `<!DOCTYPE html>
+<html>
+<head>
+  <title>Circuit - Error</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%);
+      min-height: 100vh;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      color: white;
+    }
+    .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>
+</body>
+</html>`;
+}

package/src/index.js

@@ -0,0 +1,108 @@
+import chalk from 'chalk';
+import { authenticate, getStoredToken } from './auth.js';
+import { startMcpServer } from './server.js';
+import { showBanner, showSuccess, showError, showSpinner } from './ui.js';
+
+const CIRCUIT_URL = 'https://app.withcircuit.com';
+
+export async function main() {
+  const args = process.argv.slice(2);
+
+  // Handle setup command
+  if (args[0] === 'setup') {
+    await runSetup();
+    return;
+  }
+
+  // Handle auth command
+  if (args[0] === 'auth') {
+    await runAuth();
+    return;
+  }
+
+  // Handle logout command
+  if (args[0] === 'logout') {
+    await runLogout();
+    return;
+  }
+
+  // Default: start MCP server
+  await runServer();
+}
+
+async function runSetup() {
+  showBanner();
+
+  console.log(chalk.dim('  Choose your AI coding tool:\n'));
+  console.log(`  ${chalk.bold('1.')} Cursor`);
+  console.log(`  ${chalk.bold('2.')} Claude Code`);
+  console.log(`  ${chalk.bold('3.')} Both\n`);
+
+  // For now, show instructions for both
+  console.log(chalk.cyan.bold('  Cursor Setup\n'));
+  console.log(chalk.dim('  Add to your Cursor settings (Cmd+Shift+P → "Cursor Settings: Open User Settings"):\n'));
+  console.log(chalk.white(`  {
+    "mcpServers": {
+      "circuit": {
+        "command": "npx",
+        "args": ["circuit-mcp"]
+      }
+    }
+  }\n`));
+
+  console.log(chalk.cyan.bold('  Claude Code Setup\n'));
+  console.log(chalk.dim('  Run this command in your terminal:\n'));
+  console.log(chalk.white(`  claude mcp add circuit -- npx circuit-mcp\n`));
+
+  console.log(chalk.dim('  ─────────────────────────────────────────\n'));
+  console.log(chalk.dim('  After setup, Circuit will prompt you to'));
+  console.log(chalk.dim('  authenticate on first use.\n'));
+}
+
+async function runAuth() {
+  showBanner();
+
+  const spinner = showSpinner('Authenticating...');
+
+  try {
+    const token = await authenticate();
+    spinner.stop();
+    showSuccess('Authenticated successfully!');
+    console.log(chalk.dim('\n  Your token is stored locally.\n'));
+  } catch (err) {
+    spinner.stop();
+    showError(`Authentication failed: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+async function runLogout() {
+  showBanner();
+
+  const { clearToken } = await import('./auth.js');
+  await clearToken();
+  showSuccess('Logged out successfully.');
+}
+
+async function runServer() {
+  // Check for existing token
+  let token = await getStoredToken();
+
+  if (!token) {
+    // First run - show banner and auth
+    showBanner();
+    console.log(chalk.dim('  First time setup - let\'s connect your account.\n'));
+
+    try {
+      token = await authenticate();
+      showSuccess('Connected!');
+      console.log();
+    } catch (err) {
+      showError(`Authentication failed: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  // Start MCP server (stdio mode for Cursor/Claude)
+  await startMcpServer(token);
+}

package/src/server.js

@@ -0,0 +1,286 @@
+import { createInterface } from 'readline';
+
+const CIRCUIT_API = 'https://app.withcircuit.com';
+
+/**
+ * Start MCP server in stdio mode
+ * Communicates with Cursor/Claude via JSON-RPC over stdin/stdout
+ */
+export async function startMcpServer(token) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false
+  });
+
+  // Handle incoming JSON-RPC messages
+  rl.on('line', async (line) => {
+    try {
+      const message = JSON.parse(line);
+      const response = await handleMessage(message, token);
+      if (response) {
+        console.log(JSON.stringify(response));
+      }
+    } catch (err) {
+      // Send error response
+      console.log(JSON.stringify({
+        jsonrpc: '2.0',
+        error: { code: -32700, message: 'Parse error' },
+        id: null
+      }));
+    }
+  });
+
+  // Keep process alive
+  process.stdin.resume();
+}
+
+/**
+ * Handle incoming MCP message
+ */
+async function handleMessage(message, token) {
+  const { id, method, params } = message;
+
+  switch (method) {
+    case 'initialize':
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          protocolVersion: '2024-11-05',
+          serverInfo: {
+            name: 'circuit-mcp',
+            version: '1.0.0'
+          },
+          capabilities: {
+            tools: {},
+            resources: {}
+          }
+        }
+      };
+
+    case 'initialized':
+      // No response needed for notification
+      return null;
+
+    case 'tools/list':
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {
+          tools: [
+            {
+              name: 'get_priorities',
+              description: 'Get the top customer feedback priorities from Circuit',
+              inputSchema: {
+                type: 'object',
+                properties: {
+                  limit: {
+                    type: 'number',
+                    description: 'Maximum number of priorities to return (default: 10)'
+                  },
+                  focus: {
+                    type: 'string',
+                    description: 'Focus type: volume, revenue, urgency, negative, positive, feature',
+                    enum: ['volume', 'revenue', 'urgency', 'negative', 'positive', 'feature']
+                  }
+                }
+              }
+            },
+            {
+              name: 'get_brief',
+              description: 'Get the engineering brief for a specific priority',
+              inputSchema: {
+                type: 'object',
+                properties: {
+                  priority_id: {
+                    type: 'string',
+                    description: 'The ID of the priority to get the brief for'
+                  }
+                },
+                required: ['priority_id']
+              }
+            },
+            {
+              name: 'get_feedback',
+              description: 'Get raw customer feedback items',
+              inputSchema: {
+                type: 'object',
+                properties: {
+                  limit: {
+                    type: 'number',
+                    description: 'Maximum number of feedback items to return (default: 20)'
+                  }
+                }
+              }
+            }
+          ]
+        }
+      };
+
+    case 'tools/call':
+      return await handleToolCall(id, params, token);
+
+    case 'resources/list':
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: { resources: [] }
+      };
+
+    case 'ping':
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: {}
+      };
+
+    default:
+      return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32601, message: `Method not found: ${method}` }
+      };
+  }
+}
+
+/**
+ * Handle tool calls
+ */
+async function handleToolCall(id, params, token) {
+  const { name, arguments: args } = params;
+
+  try {
+    let result;
+
+    switch (name) {
+      case 'get_priorities':
+        result = await fetchPriorities(token, args);
+        break;
+
+      case 'get_brief':
+        result = await fetchBrief(token, args);
+        break;
+
+      case 'get_feedback':
+        result = await fetchFeedback(token, args);
+        break;
+
+      default:
+        return {
+          jsonrpc: '2.0',
+          id,
+          error: { code: -32602, message: `Unknown tool: ${name}` }
+        };
+    }
+
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+      }
+    };
+
+  } catch (err) {
+    return {
+      jsonrpc: '2.0',
+      id,
+      error: { code: -32000, message: err.message }
+    };
+  }
+}
+
+/**
+ * Fetch priorities from Circuit API
+ */
+async function fetchPriorities(token, args = {}) {
+  const limit = args.limit || 10;
+  const focus = args.focus || 'volume';
+
+  const url = `${CIRCUIT_API}/api/focus?limit=${limit}&focus_type=${focus}`;
+
+  const response = await fetch(url, {
+    headers: { 'Authorization': `Bearer ${token}` }
+  });
+
+  if (!response.ok) {
+    throw new Error(`API error: ${response.status}`);
+  }
+
+  const data = await response.json();
+
+  // Format for readability
+  return (data.priorities || data.clusters || []).map((p, i) => ({
+    rank: i + 1,
+    id: p.cluster_id || p.id,
+    title: p.summary || p.theme,
+    category: p.category,
+    mentions: p.volume || p.count,
+    urgency: p.urgency_score,
+    trend: p.trend
+  }));
+}
+
+/**
+ * Fetch a specific brief from Circuit API
+ */
+async function fetchBrief(token, args) {
+  if (!args.priority_id) {
+    throw new Error('priority_id is required');
+  }
+
+  const url = `${CIRCUIT_API}/api/builds?cluster_id=${args.priority_id}`;
+
+  const response = await fetch(url, {
+    headers: { 'Authorization': `Bearer ${token}` }
+  });
+
+  if (!response.ok) {
+    throw new Error(`API error: ${response.status}`);
+  }
+
+  const data = await response.json();
+  const build = (data.builds || []).find(b =>
+    b.cluster_id === args.priority_id || b.clusterId === args.priority_id
+  );
+
+  if (!build) {
+    throw new Error('Brief not found for this priority');
+  }
+
+  return {
+    id: build.id,
+    title: build.title,
+    status: build.status,
+    content: build.build || build.spec_content
+  };
+}
+
+/**
+ * Fetch raw feedback from Circuit API
+ */
+async function fetchFeedback(token, args = {}) {
+  const limit = args.limit || 20;
+
+  const url = `${CIRCUIT_API}/api/feedback/all?limit=${limit}`;
+
+  const response = await fetch(url, {
+    headers: { 'Authorization': `Bearer ${token}` }
+  });
+
+  if (!response.ok) {
+    throw new Error(`API error: ${response.status}`);
+  }
+
+  const data = await response.json();
+
+  return (data.feedback || []).map(f => ({
+    id: f.id,
+    text: f.text,
+    source: f.source,
+    sentiment: f.analysis?.sentiment,
+    intent: f.analysis?.intent,
+    created_at: f.created_at
+  }));
+}

package/src/ui.js

@@ -0,0 +1,58 @@
+import chalk from 'chalk';
+
+const CIRCUIT_PURPLE = '#6366F1';
+
+export function showBanner() {
+  console.log();
+  console.log(chalk.hex(CIRCUIT_PURPLE).bold('  ╭──────────────────────────────────╮'));
+  console.log(chalk.hex(CIRCUIT_PURPLE).bold('  │') + chalk.white.bold('  ⚡ Circuit MCP                  ') + chalk.hex(CIRCUIT_PURPLE).bold('│'));
+  console.log(chalk.hex(CIRCUIT_PURPLE).bold('  ╰──────────────────────────────────╯'));
+  console.log();
+}
+
+export function showSuccess(message) {
+  console.log(chalk.green('  ✓ ') + chalk.white(message));
+}
+
+export function showError(message) {
+  console.log(chalk.red('  ✗ ') + chalk.white(message));
+}
+
+export function showInfo(message) {
+  console.log(chalk.blue('  ℹ ') + chalk.dim(message));
+}
+
+export function showStep(step, message) {
+  console.log(chalk.dim(`  ${step}. `) + chalk.white(message));
+}
+
+export function showSpinner(message) {
+  const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+  let i = 0;
+  let stopped = false;
+
+  const interval = setInterval(() => {
+    if (stopped) return;
+    process.stderr.write(`\r  ${chalk.hex(CIRCUIT_PURPLE)(frames[i])} ${chalk.dim(message)}`);
+    i = (i + 1) % frames.length;
+  }, 80);
+
+  return {
+    stop: () => {
+      stopped = true;
+      clearInterval(interval);
+      process.stderr.write('\r' + ' '.repeat(message.length + 10) + '\r');
+    },
+    update: (newMessage) => {
+      message = newMessage;
+    }
+  };
+}
+
+export function showPrompt(message) {
+  process.stdout.write(chalk.cyan('  → ') + chalk.white(message));
+}
+
+export function clearLine() {
+  process.stdout.write('\r\x1b[K');
+}