circuit-mcp 2.0.0 → 2.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +126 -37
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Connect [Circuit](https://withcircuit.com) to Cursor and Claude Code via MCP (Model Context Protocol).
4
4
 
5
- **Circuit** transforms customer feedback into engineering specs. The MCP brings your priorities and briefs directly into your AI coding assistant.
5
+ 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.
6
6
 
7
7
  ## Quick Start
8
8
 
@@ -27,71 +27,160 @@ Add to `~/.cursor/mcp.json`:
27
27
  claude mcp add circuit -- npx circuit-mcp
28
28
  ```
29
29
 
30
- ## First Run
30
+ ### First Run
31
31
 
32
32
  On first use, Circuit opens your browser to authenticate. Your token is cached at `~/.circuit/token.json`.
33
33
 
34
34
  ```
35
- Circuit MCP
35
+ Circuit MCP
36
36
 
37
- First time setup - let's connect your account.
38
- Opening browser to authenticate...
37
+ First time setup — let's connect your account.
38
+ Opening browser to authenticate...
39
39
 
40
- Connected!
40
+ ✓ Connected!
41
41
  ```
42
42
 
43
- ## Available Tools
43
+ ---
44
44
 
45
- | Tool | Description |
46
- |------|-------------|
47
- | `get_priorities` | Get top customer priorities ranked by volume, urgency, or sentiment |
48
- | `get_brief` | Get the engineering spec for a priority (what to build, why, done criteria) |
49
- | `search_feedback` | Search raw customer feedback by keyword |
50
- | `start_building` | Mark a brief as "building" - you're working on it |
51
- | `mark_done` | Mark a brief as "done" - it shipped! |
45
+ ## Tools
52
46
 
53
- ## Example Usage
47
+ Four tools. Everything you need to go from "what should I build?" to "shipped."
54
48
 
55
- Ask your AI assistant:
49
+ ### `circuit.priorities` — What should I work on?
56
50
 
57
- > "What are my top 5 priorities?"
51
+ Returns ranked priorities with trend data, confidence scores, and pattern matching from your shipping history.
58
52
 
59
- > "Get the brief for priority #1"
53
+ | Parameter | Description |
54
+ |-----------|-------------|
55
+ | `lens` | How to rank: `volume`, `urgency`, `revenue`, `retention`, `delight`, `feature` |
56
+ | `segment` | Filter by customer segment: `enterprise`, `smb`, `all` |
57
+ | `limit` | Number of priorities to return (default: 5, max: 20) |
58
+ | `category` | Filter: `Bug`, `Feature`, `Friction`, `Complaint`, `Praise` |
60
59
 
61
- > "Search feedback about login issues"
60
+ Each priority includes a `matches_pattern` flag — Circuit learns what you tend to ship and surfaces priorities that fit your instincts.
62
61
 
63
- > "Mark that brief as done"
62
+ **Try it:** *"What are my top priorities by revenue impact for enterprise customers?"*
63
+
64
+ ### `circuit.brief` — The full engineering spec
65
+
66
+ 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.
67
+
68
+ | Parameter | Description |
69
+ |-----------|-------------|
70
+ | `priority_id` or `build_id` | Which priority to get the brief for |
71
+ | `include_history` | Include version history and related ship memory (default: true) |
72
+
73
+ Uses a 3-layer matching strategy to find the right brief, even with partial or ambiguous IDs.
74
+
75
+ **Try it:** *"Get the brief for priority #1"*
76
+
77
+ ### `circuit.act` — Take action
78
+
79
+ One tool, four actions. Move work forward without leaving your editor.
80
+
81
+ | Action | What it does |
82
+ |--------|-------------|
83
+ | `build` | Mark a brief as "building" — you're working on it |
84
+ | `ship` | Mark shipped. Auto-notifies customers who submitted feedback via the widget. Creates a ship memory so Circuit learns your patterns. |
85
+ | `correct` | Fix an AI classification that got it wrong. Writes a correction memory and recomputes pattern matching. |
86
+ | `submit` | Add new feedback directly via MCP |
87
+
88
+ **Try it:** *"Mark the login brief as building"* → build it → *"Ship it"*
89
+
90
+ ### `circuit.ask` — Search across everything
91
+
92
+ 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.
93
+
94
+ **Try it:** *"Search for feedback about onboarding friction"*
95
+
96
+ ---
97
+
98
+ ## Example Workflow
99
+
100
+ A typical session looks like this:
101
+
102
+ ```
103
+ You: "What should I work on?"
104
+ Circuit: → circuit.priorities (lens: urgency)
105
+ Returns top 5, #1 is "Login timeout on slow connections"
106
+
107
+ You: "Get me the brief for that"
108
+ Circuit: → circuit.brief (priority_id: ...)
109
+ Returns spec: what to build, affected files, done criteria
110
+
111
+ You: "I'm on it"
112
+ Circuit: → circuit.act (action: build)
113
+ Marked as building
114
+
115
+ ... you write the code ...
116
+
117
+ You: "Done, ship it"
118
+ Circuit: → circuit.act (action: ship)
119
+ Marked as shipped. 12 customers notified.
120
+ ```
121
+
122
+ Feedback in. Spec out. Code shipped. Customers notified. That's the circuit.
123
+
124
+ ---
64
125
 
65
126
  ## Commands
66
127
 
67
128
  ```bash
68
- npx circuit-mcp # Start MCP server (used by Cursor/Claude)
69
- npx circuit-mcp setup # Show setup instructions
70
- npx circuit-mcp auth # Re-authenticate
71
- npx circuit-mcp logout # Clear stored token
129
+ npx circuit-mcp # Start MCP server (used by Cursor/Claude Code)
130
+ npx circuit-mcp setup # Show setup instructions
131
+ npx circuit-mcp auth # Re-authenticate
132
+ npx circuit-mcp logout # Clear stored token
133
+ ```
134
+
135
+ ## Troubleshooting
136
+
137
+ **"Authentication failed" or token expired**
138
+ ```bash
139
+ npx circuit-mcp auth
72
140
  ```
141
+ Tokens last 30 days. Re-auth opens your browser — takes 5 seconds.
142
+
143
+ **Cursor not detecting the MCP server**
144
+ 1. Confirm `~/.cursor/mcp.json` has the config above
145
+ 2. Restart Cursor
146
+ 3. Check the MCP panel shows "circuit" as connected
147
+
148
+ **Claude Code not finding tools**
149
+ ```bash
150
+ claude mcp list # Verify circuit is registered
151
+ claude mcp remove circuit # Remove and re-add if needed
152
+ claude mcp add circuit -- npx circuit-mcp
153
+ ```
154
+
155
+ **"Priority not found" errors**
156
+
157
+ 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.
158
+
159
+ ---
73
160
 
74
161
  ## How It Works
75
162
 
76
163
  ```
164
+ Customer feedback
165
+ ↓
77
166
  Circuit (app.withcircuit.com)
78
- │
79
- │ Feedback → Priorities → Briefs
80
- │
81
- ▼
82
- Circuit MCP ◄─── Cursor / Claude Code
83
- │
84
- │ get_priorities, get_brief, etc.
85
- │
86
- ▼
87
- Your AI assistant has context
167
+ Feedback → Priorities → Specs
168
+ ↓
169
+ Circuit MCP ←── Your AI assistant (Cursor / Claude Code)
170
+ ↓
171
+ circuit.priorities → What to build
172
+ circuit.brief → How to build it
173
+ circuit.act → Ship it + notify customers
174
+ circuit.ask → Search everything
88
175
  ```
89
176
 
177
+ 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.
178
+
90
179
  ## Links
91
180
 
92
- - [Circuit](https://withcircuit.com) - Customer feedback intelligence
93
- - [MCP Protocol](https://modelcontextprotocol.io) - Model Context Protocol spec
181
+ - [Circuit](https://withcircuit.com) — Customer feedback intelligence
182
+ - [MCP Protocol](https://modelcontextprotocol.io) — Model Context Protocol spec
94
183
 
95
184
  ## License
96
185
 
97
- Proprietary - © Circuit (withcircuit.com)
186
+ Proprietary — © Circuit ([withcircuit.com](https://withcircuit.com))
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "circuit-mcp",
3
- "version": "2.0.0",
3
+ "version": "2.0.1",
4
4
  "description": "Connect Circuit to Cursor and Claude Code - bring customer priorities and engineering briefs into your AI coding assistant",
5
5
  "type": "module",
6
6
  "bin": {