@kelceyp/chrome-control-mcp 0.2.1 → 0.4.0

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.
package/bun.lock ADDED
@@ -0,0 +1,40 @@
1
+ {
2
+ "lockfileVersion": 1,
3
+ "workspaces": {
4
+ "": {
5
+ "name": "@kelceyp/chrome-control-mcp",
6
+ "dependencies": {
7
+ "@modelcontextprotocol/sdk": "^0.6.0",
8
+ },
9
+ },
10
+ },
11
+ "packages": {
12
+ "@modelcontextprotocol/sdk": ["@modelcontextprotocol/sdk@0.6.1", "", { "dependencies": { "content-type": "^1.0.5", "raw-body": "^3.0.0", "zod": "^3.23.8" } }, "sha512-OkVXMix3EIbB5Z6yife2XTrSlOnVvCLR1Kg91I4pYFEsV9RbnoyQVScXCuVhGaZHOnTZgso8lMQN1Po2TadGKQ=="],
13
+
14
+ "bytes": ["bytes@3.1.2", "", {}, "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg=="],
15
+
16
+ "content-type": ["content-type@1.0.5", "", {}, "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA=="],
17
+
18
+ "depd": ["depd@2.0.0", "", {}, "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw=="],
19
+
20
+ "http-errors": ["http-errors@2.0.0", "", { "dependencies": { "depd": "2.0.0", "inherits": "2.0.4", "setprototypeof": "1.2.0", "statuses": "2.0.1", "toidentifier": "1.0.1" } }, "sha512-FtwrG/euBzaEjYeRqOgly7G0qviiXoJWnvEH2Z1plBdXgbyjv34pHTSb9zoeHMyDy33+DWy5Wt9Wo+TURtOYSQ=="],
21
+
22
+ "iconv-lite": ["iconv-lite@0.6.3", "", { "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" } }, "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw=="],
23
+
24
+ "inherits": ["inherits@2.0.4", "", {}, "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ=="],
25
+
26
+ "raw-body": ["raw-body@3.0.0", "", { "dependencies": { "bytes": "3.1.2", "http-errors": "2.0.0", "iconv-lite": "0.6.3", "unpipe": "1.0.0" } }, "sha512-RmkhL8CAyCRPXCE28MMH0z2PNWQBNk2Q09ZdxM9IOOXwxwZbN+qbWaatPkdkWIKL2ZVDImrN/pK5HTRz2PcS4g=="],
27
+
28
+ "safer-buffer": ["safer-buffer@2.1.2", "", {}, "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg=="],
29
+
30
+ "setprototypeof": ["setprototypeof@1.2.0", "", {}, "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw=="],
31
+
32
+ "statuses": ["statuses@2.0.1", "", {}, "sha512-RwNA9Z/7PrK06rYLIzFMlaF+l73iwpzsqRIFgbMLbTcLD6cOao82TaWefPXQvB2fOC4AjuYSEndS7N/mTCbkdQ=="],
33
+
34
+ "toidentifier": ["toidentifier@1.0.1", "", {}, "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA=="],
35
+
36
+ "unpipe": ["unpipe@1.0.0", "", {}, "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ=="],
37
+
38
+ "zod": ["zod@3.25.76", "", {}, "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ=="],
39
+ }
40
+ }
package/handover.md ADDED
@@ -0,0 +1,302 @@
1
+ # Chrome Control MCP - ChatGPT Adapter Handover
2
+
3
+ **Date:** 2025-10-25
4
+ **Status:** In progress - adapter bug fix needed
5
+ **Current Version:** 0.3.0 (published)
6
+
7
+ ---
8
+
9
+ ## Overview
10
+
11
+ This MCP server provides Chrome automation via AppleScript. It includes a specialized `gpt_chat` tool for conversing with ChatGPT programmatically.
12
+
13
+ **Problem:** The `gpt_chat` tool currently has a bug where it returns `{ok: true, text: "", ms: ~1200}` - empty text despite ChatGPT responding successfully.
14
+
15
+ ---
16
+
17
+ ## What Works
18
+
19
+ 1. ✅ **execute_javascript** - Sync JS execution
20
+ 2. ✅ **execute_javascript_async** - Async JS with polling (v0.2.0)
21
+ 3. ⚠️ **gpt_chat** - Auto-injects ChatGPT adapter, but has empty text bug (v0.3.0)
22
+
23
+ ---
24
+
25
+ ## The Bug
26
+
27
+ ### Symptoms
28
+ ```json
29
+ // gpt_chat returns:
30
+ {"ok": true, "text": "", "ms": 1244}
31
+ // ChatGPT DID respond, but text is empty
32
+ ```
33
+
34
+ ### Root Cause (Diagnosed with ChatGPT)
35
+
36
+ **Node Replacement Issue:**
37
+ 1. Adapter captures `const node = lastAssistantNode()` once
38
+ 2. During streaming, ChatGPT replaces DOM nodes (stream container → final wrapper)
39
+ 3. MutationObserver watches the **old/detached node**
40
+ 4. Detached node stops mutating → idle detected after 1.2s
41
+ 5. Reads `node.innerText` from detached node → returns ""
42
+
43
+ **Evidence:**
44
+ - Timing is exactly 1.2s (the idle threshold)
45
+ - Manual DOM queries show text IS there
46
+ - Happens consistently
47
+
48
+ ---
49
+
50
+ ## The Solution (Designed with ChatGPT)
51
+
52
+ ### Hybrid Approach: Text-Length Primary + Button Confirmation
53
+
54
+ **Why this approach:**
55
+ - Text-length polling is robust (no DOM structure assumptions)
56
+ - Longer idle period handles "Thinking..." pauses
57
+ - Button presence confirms rendering is complete
58
+ - Falls back gracefully if buttons don't appear
59
+
60
+ ### Implementation Details
61
+
62
+ **Key Parameters:**
63
+ ```javascript
64
+ idlePrimaryMs: 1200 // Normal streaming pause
65
+ idleConfirmMs: 3300 // Thinking pause threshold
66
+ finalButtonGraceMs: 2000 // Grace period for buttons
67
+ ```
68
+
69
+ **Logic Flow:**
70
+ 1. Poll text length every 100ms
71
+ 2. Track when length changes (resets idle timer)
72
+ 3. After 1.2s idle + input enabled: eligible for checking
73
+ 4. After 3.3s idle: check for turn-action buttons
74
+ 5. If buttons found: return text (confirmed complete)
75
+ 6. If no buttons after 2s grace: return text anyway (with note)
76
+
77
+ **Key Fixes:**
78
+ - Always fetch `lastAssistantNode()` fresh (no capturing)
79
+ - Look for buttons in turn container, not content node
80
+ - Proper async with `await sleep(100)` (prevents page freeze)
81
+
82
+ ---
83
+
84
+ ## Implementation Code
85
+
86
+ ChatGPT provided complete implementation in conversation. See their latest response for:
87
+
88
+ ```javascript
89
+ const waitForResponseWithBaseline = async (baseline, {
90
+ timeoutMs = 120000,
91
+ idlePrimaryMs = 1200,
92
+ idleConfirmMs = 3300,
93
+ finalButtonGraceMs = 2000
94
+ } = {}) => {
95
+ // Full implementation in ChatGPT response
96
+ // Uses text-length polling + button confirmation
97
+ // Returns: {ok, text, ms, note?}
98
+ }
99
+ ```
100
+
101
+ ---
102
+
103
+ ## Testing Plan
104
+
105
+ ### Step 1: Test via execute_javascript_async
106
+
107
+ **Do NOT update gpt_chat tool yet.** Test manually first.
108
+
109
+ 1. **Inject v1.0.2 adapter** with hybrid approach
110
+ 2. **Send test message:** `"[CC] Test 1/5: Hybrid approach - reply HYBRID-OK-1"`
111
+ 3. **Verify result:** `{ok: true, text: "HYBRID-OK-1", ms: ...}`
112
+ 4. **Run 5 consecutive tests** to verify consistency
113
+ 5. **Check for page freezes** (previous attempts froze the page)
114
+
115
+ ### Step 2: Update gpt_chat tool
116
+
117
+ Once validated:
118
+ 1. Update embedded adapter in `server/index.js` (case 'gpt_chat')
119
+ 2. Bump `ADAPTER_VERSION` to `'1.0.2'`
120
+ 3. Update `package.json` to `0.4.0`
121
+ 4. Publish to npm
122
+ 5. Restart Claude Code
123
+ 6. Test `gpt_chat` tool directly
124
+
125
+ ---
126
+
127
+ ## ChatGPT Collaboration Context
128
+
129
+ **ChatGPT Session:** https://chatgpt.com/c/68fc1d3b-286c-8323-9488-82949cd69331
130
+ **Tab:** "Conversation setup explanation"
131
+
132
+ **Message Prefixes:**
133
+ - `[PK]` - Paul (user)
134
+ - `[CC]` - Claude Code (this agent)
135
+
136
+ **What ChatGPT Knows:**
137
+ - The complete adapter evolution (experiments, bugs, fixes)
138
+ - The node replacement issue diagnosis
139
+ - Text-length vs button detection trade-offs
140
+ - The hybrid approach design
141
+ - Implementation details and edge cases
142
+
143
+ **You can continue the conversation** by sending messages with `[CC]` prefix to ask questions or clarify implementation details.
144
+
145
+ ---
146
+
147
+ ## File Locations
148
+
149
+ ### Source Code
150
+ - **MCP Server:** `/Users/paulkelcey/Dev/gh/kelceyp-mcp-servers/chrome-control/server/index.js`
151
+ - **Package:** `/Users/paulkelcey/Dev/gh/kelceyp-mcp-servers/chrome-control/package.json`
152
+
153
+ ### Backup
154
+ - **Backup (pre-async):** `/Users/paulkelcey/Dev/gh/kelceyp-mcp-servers/chrome-control-bak/`
155
+
156
+ ### Related Files (in clibuilder project)
157
+ - **Original Adapter:** `/Users/paulkelcey/Dev/gh/kelceyp-mcp-servers/clibuilder/docs/cartridges/runbooks/chatgpt-adapter.js`
158
+ - **Handover Notes:** `/Users/paulkelcey/Dev/gh/kelceyp-mcp-servers/clibuilder/docs/cartridges/runbooks/chatgpt-collaboration-handover.md`
159
+
160
+ ---
161
+
162
+ ## Current gpt_chat Implementation (Broken)
163
+
164
+ Located in `server/index.js` starting at line ~570:
165
+
166
+ ```javascript
167
+ case 'gpt_chat': {
168
+ const { message, idle_ms = 1200, timeout_ms = 120000, tab_id } = args;
169
+
170
+ const ADAPTER_VERSION = '1.0.0';
171
+
172
+ // Embeds ChatBridge adapter
173
+ // Problem: Uses old node-capturing approach
174
+ // Line ~656: const node = lastAssistantNode();
175
+ // This node can become detached during streaming
176
+
177
+ // Needs update to v1.0.2 with hybrid approach
178
+ }
179
+ ```
180
+
181
+ ---
182
+
183
+ ## Button Detection Notes
184
+
185
+ **Initial Idea:** Poll for action buttons (Copy/Regenerate) to detect completion
186
+
187
+ **Problem Found:**
188
+ - Buttons are NOT children of `[data-message-author-role="assistant"]`
189
+ - They're in a separate toolbar within the turn container
190
+ - Need to search `[data-testid*="conversation-turn"]` → find toolbar → check buttons
191
+
192
+ **Filter Issue:**
193
+ ```javascript
194
+ // This was too aggressive:
195
+ candidates.filter(btn => !btn.closest('pre, code'))
196
+
197
+ // Excluded ALL buttons because markdown container has code blocks
198
+ ```
199
+
200
+ **ChatGPT's Fix:**
201
+ - Find the turn container first
202
+ - Find toolbar within turn: `[data-testid*="turn-actions"]` or `[role="toolbar"]`
203
+ - Check for buttons only in toolbar (naturally excludes code-copy buttons)
204
+
205
+ **Why Hybrid is Better:**
206
+ - Button detection is fragile (A/B testing, DOM changes)
207
+ - Text-length is robust
208
+ - Buttons confirm, but text-length drives the decision
209
+
210
+ ---
211
+
212
+ ## Edge Cases Handled
213
+
214
+ 1. **Thinking pauses:** 3.3s idle threshold
215
+ 2. **Toolbar A/B variants:** Falls back to text if no buttons
216
+ 3. **Code-heavy replies:** Text length jumps handled by longer idle
217
+ 4. **Images-only replies:** May need special handling (not critical for v1)
218
+ 5. **Node replacement:** Always fetch fresh node
219
+ 6. **Page freezing:** Proper async with `await sleep(100)`
220
+
221
+ ---
222
+
223
+ ## Known Issues
224
+
225
+ 1. **Page freeze** - Previous test script froze the page
226
+ - Cause: Tight polling loop without proper async
227
+ - Fix: Use `await sleep(100)` between polls
228
+
229
+ 2. **Empty text response** - Current gpt_chat bug
230
+ - Cause: Node replacement during streaming
231
+ - Fix: Implement v1.0.2 hybrid approach
232
+
233
+ 3. **AppleScript "missing value"** - Some DOM queries return this error
234
+ - Cause: AppleScript can't serialize complex objects
235
+ - Workaround: Return simple strings or use JSON.stringify carefully
236
+
237
+ ---
238
+
239
+ ## Next Steps
240
+
241
+ 1. **Read ChatGPT's latest response** in the conversation
242
+ 2. **Copy the complete `waitForResponseWithBaseline` implementation**
243
+ 3. **Create test payload** for execute_javascript_async
244
+ 4. **Run 5 tests** to verify consistency
245
+ 5. **Check for page freezes**
246
+ 6. **If successful:** Update gpt_chat tool
247
+ 7. **Publish v0.4.0**
248
+
249
+ ---
250
+
251
+ ## Collaboration Principles (from Paul)
252
+
253
+ When working on this project, follow these:
254
+ 1. **Don't be helpful** - Don't do more than asked
255
+ 2. **Be brutal with scope** - No gold plating
256
+ 3. **Measure twice, cut once** - Test before implementing
257
+ 4. **RTFM** - Research before implementing
258
+ 5. **No backwards compatibility** - Breaking changes OK
259
+ 6. **No fallbacks or defaults** - Fail fast
260
+ 7. **Shift left** - Ask questions, do designs
261
+ 8. **Don't run ahead** - Work with the user
262
+
263
+ ---
264
+
265
+ ## Questions for ChatGPT
266
+
267
+ If you need clarification:
268
+
269
+ 1. Ask about specific edge cases
270
+ 2. Request code snippets for tricky parts
271
+ 3. Confirm implementation details
272
+ 4. Discuss trade-offs
273
+
274
+ Use `[CC]` prefix in messages.
275
+
276
+ ---
277
+
278
+ ## Success Criteria
279
+
280
+ **For v1.0.2 adapter:**
281
+ - [ ] 5/5 consecutive tests return `{ok: true, text: "<response>", ms: ...}`
282
+ - [ ] No empty text responses
283
+ - [ ] No page freezes
284
+ - [ ] Latency roughly stable (within expected range)
285
+
286
+ **For gpt_chat tool:**
287
+ - [ ] Same success criteria as adapter
288
+ - [ ] Works without manual injection
289
+ - [ ] Version auto-detection works
290
+
291
+ ---
292
+
293
+ ## Version History
294
+
295
+ - **v0.1.0** - Initial chrome-control (execute_javascript only)
296
+ - **v0.2.0** - Added execute_javascript_async
297
+ - **v0.3.0** - Added gpt_chat (has empty text bug)
298
+ - **v0.4.0** - (Pending) gpt_chat with v1.0.2 hybrid adapter
299
+
300
+ ---
301
+
302
+ **End of handover**
package/package.json CHANGED
@@ -1,24 +1,16 @@
1
1
  {
2
2
  "name": "@kelceyp/chrome-control-mcp",
3
- "version": "0.2.1",
4
- "description": "MCP server for controlling Google Chrome on macOS via AppleScript",
3
+ "version": "0.4.0",
4
+ "description": "MCP server for controlling Google Chrome on macOS via AppleScript with async JavaScript support",
5
+ "main": "server/index.js",
5
6
  "type": "module",
6
- "main": "dist/index.js",
7
7
  "bin": {
8
- "chrome-control-mcp": "dist/index.js"
8
+ "chrome-control-mcp": "server/index.js"
9
9
  },
10
10
  "scripts": {
11
- "clean": "rm -rf dist",
12
- "build": "bun run clean && bun build server/index.js --outdir dist --minify --sourcemap=none --target=node --format=esm --banner:js='#!/usr/bin/env node'",
13
- "prepare": "bun run build",
14
- "release": "bash scripts/publish.sh"
11
+ "start": "node server/index.js",
12
+ "test": "echo \"Error: no test specified\" && exit 1"
15
13
  },
16
- "files": [
17
- "dist",
18
- "README.md",
19
- "LICENSE",
20
- "package.json"
21
- ],
22
14
  "keywords": [
23
15
  "mcp",
24
16
  "modelcontextprotocol",
@@ -28,26 +20,24 @@
28
20
  "applescript",
29
21
  "macos",
30
22
  "claude",
31
- "ai",
32
- "server"
23
+ "ai"
33
24
  ],
34
25
  "author": "Paul Kelcey",
35
26
  "license": "MIT",
36
27
  "repository": {
37
28
  "type": "git",
38
- "url": "git+https://github.com/kelceyp/chrome-control-mcp.git"
29
+ "url": "https://github.com/kelceyp/chrome-control-mcp"
39
30
  },
40
31
  "dependencies": {
41
32
  "@modelcontextprotocol/sdk": "^0.6.0"
42
33
  },
43
34
  "engines": {
44
- "node": ">=18"
35
+ "node": ">=16.0.0"
45
36
  },
46
37
  "os": [
47
38
  "darwin"
48
39
  ],
49
40
  "publishConfig": {
50
41
  "access": "restricted"
51
- },
52
- "private": false
53
- }
42
+ }
43
+ }