@spooky-sync/devtools-mcp 0.0.1-canary.290 → 0.0.1-canary.291
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/AGENTS.md +7 -6
- package/dist/protocol.d.ts +2 -1
- package/dist/protocol.js +2 -1
- package/dist/server.js +69 -39
- package/package.json +1 -1
package/AGENTS.md
CHANGED
|
@@ -24,12 +24,12 @@ Wire into Claude / your agent via the MCP server config (`.mcp.json` at the repo
|
|
|
24
24
|
### Connection / state
|
|
25
25
|
|
|
26
26
|
- **`list_connections`** — which browser tabs are currently bridged.
|
|
27
|
-
- **`get_state` `[tabId]`** — full devtools state:
|
|
27
|
+
- **`get_state` `[tabId]`** — full devtools state: queries, mutations, auth, database tables, versions (extension only).
|
|
28
28
|
- **`get_auth_state` `[tabId]`** — current auth subject + scope (extension only).
|
|
29
29
|
- **`get_active_queries` `[tabId]`** — registered live queries, their last result hashes, and a per-query `timings` breakdown.
|
|
30
30
|
- **`get_query_timings` `[tabId]`** — per-query processing-time breakdown (SSP parse/plan/snapshot + store-apply/circuit-step/transform, local & remote record fetch, frontend reconcile; each as last/p50/p90/p99), sorted slowest-first. For debugging perf.
|
|
31
|
-
- **`
|
|
32
|
-
- **`
|
|
31
|
+
- **`get_mutations` `[status] [includeTray=true] [tabId]`** — the outbox (pending / retrying with attempts), writes that left it since DevTools attached (synced with latency, or rolled back with the server error), debounced updates, tab role + connection, and the failed-writes tray rows with payload and before image (extension only).
|
|
32
|
+
- **`get_logs` `[minLevel] [contains] [after] [limit=100] [captureLevel] [tabId]`** — the client's own log lines (last 500 kept in the page), each with its structured fields. `after` = a previous `head` reads only new lines; `captureLevel: 'debug'` records debug lines without printing them to the console, for the tab's session (extension only).
|
|
33
33
|
|
|
34
34
|
### Database (works against extension OR direct DB)
|
|
35
35
|
|
|
@@ -47,15 +47,16 @@ Wire into Claude / your agent via the MCP server config (`.mcp.json` at the repo
|
|
|
47
47
|
## How an agent should use this
|
|
48
48
|
|
|
49
49
|
- **Before writing a query against a schema you haven't seen:** call `list_tables` and `get_table_data` with `limit: 1` on each table to learn the columns.
|
|
50
|
-
- **After making a mutation through `db.update`:** call `
|
|
51
|
-
- **When
|
|
50
|
+
- **After making a mutation through `db.update`:** call `get_mutations` to confirm it synced (or read why it was rolled back), then `get_active_queries` to confirm subscribed queries refreshed.
|
|
51
|
+
- **When something fails without an obvious error:** `get_logs` with `minLevel: 'warn'`; set `captureLevel: 'debug'`, reproduce, and read again with `after` set to the earlier `head`.
|
|
52
|
+
- **When troubleshooting "why isn't this query updating?":** `get_active_queries` shows the registered SurQL and last result hash; `get_logs` with `captureLevel: 'debug'` then shows each `StreamUpdate` ingest and every statement the stores ran (category `sp00ky-client::local` / `::remote`, the SurrealQL as the message).
|
|
52
53
|
- **For schema spelunking from outside the browser:** point `SURREAL_URL` at the dev DB and use `run_query` with `INFO FOR DB;`.
|
|
53
54
|
|
|
54
55
|
## Common gotchas
|
|
55
56
|
|
|
56
57
|
- **Mutations through this MCP bypass the local mutation queue.** `update_table_row` calls remote SurrealDB directly (or the extension's bridge). The local cache will see the change only when SSP pushes the live update back. For testing in-app, prefer driving mutations through the page itself.
|
|
57
58
|
- **Tab selection matters.** Multi-tab dev: pass `tabId` explicitly or you get whichever tab connected first.
|
|
58
|
-
- **Direct-DB fallback has a smaller capability set.** Anything that reads in-memory devtools state (auth,
|
|
59
|
+
- **Direct-DB fallback has a smaller capability set.** Anything that reads in-memory devtools state (auth, mutations, logs, active queries) only works with the extension.
|
|
59
60
|
|
|
60
61
|
## Pointers
|
|
61
62
|
|
package/dist/protocol.d.ts
CHANGED
|
@@ -27,7 +27,8 @@ export declare const BRIDGE_METHODS: {
|
|
|
27
27
|
readonly GET_QUERY_ROWS: "getQueryRows";
|
|
28
28
|
readonly UPDATE_TABLE_ROW: "updateTableRow";
|
|
29
29
|
readonly DELETE_TABLE_ROW: "deleteTableRow";
|
|
30
|
-
|
|
30
|
+
/** `{ method: 'mutationOp' | 'logOp', op, args }`: the Mutations / Logs dispatchers. */
|
|
31
|
+
readonly PAGE_OP: "pageOp";
|
|
31
32
|
};
|
|
32
33
|
export declare const BRIDGE_PORT = 9315;
|
|
33
34
|
export declare function isBridgeResponse(msg: unknown): msg is BridgeResponse;
|
package/dist/protocol.js
CHANGED
|
@@ -7,7 +7,8 @@ export const BRIDGE_METHODS = {
|
|
|
7
7
|
GET_QUERY_ROWS: 'getQueryRows',
|
|
8
8
|
UPDATE_TABLE_ROW: 'updateTableRow',
|
|
9
9
|
DELETE_TABLE_ROW: 'deleteTableRow',
|
|
10
|
-
|
|
10
|
+
/** `{ method: 'mutationOp' | 'logOp', op, args }`: the Mutations / Logs dispatchers. */
|
|
11
|
+
PAGE_OP: 'pageOp',
|
|
11
12
|
};
|
|
12
13
|
export const BRIDGE_PORT = 9315;
|
|
13
14
|
export function isBridgeResponse(msg) {
|
package/dist/server.js
CHANGED
|
@@ -4,6 +4,21 @@ import { BRIDGE_METHODS } from './protocol.js';
|
|
|
4
4
|
function json(data) {
|
|
5
5
|
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
|
|
6
6
|
}
|
|
7
|
+
const LOG_LEVELS = { trace: 10, debug: 20, info: 30, warn: 40, error: 50, fatal: 60 };
|
|
8
|
+
const LEVEL_NAMES = Object.keys(LOG_LEVELS);
|
|
9
|
+
const levelName = (level) => Object.entries(LOG_LEVELS).reduce((name, [n, v]) => (level >= v ? n : name), 'trace');
|
|
10
|
+
/** A captured line as the agent reads it: the JSON parsed, minus what is already a field. */
|
|
11
|
+
function readableLog(e) {
|
|
12
|
+
let data;
|
|
13
|
+
try {
|
|
14
|
+
const { time: _time, level: _level, msg: _msg, ...rest } = JSON.parse(e.line);
|
|
15
|
+
data = Object.keys(rest).length ? rest : undefined;
|
|
16
|
+
}
|
|
17
|
+
catch {
|
|
18
|
+
data = { truncated: e.line };
|
|
19
|
+
}
|
|
20
|
+
return { seq: e.seq, time: new Date(e.time).toISOString(), level: levelName(e.level), msg: e.msg, data };
|
|
21
|
+
}
|
|
7
22
|
export function createServer(bridge, surreal) {
|
|
8
23
|
const server = new McpServer({
|
|
9
24
|
name: 'sp00ky-devtools',
|
|
@@ -13,7 +28,7 @@ export function createServer(bridge, surreal) {
|
|
|
13
28
|
server.tool('list_connections', 'List browser tabs connected to Sp00ky DevTools', {}, async () => {
|
|
14
29
|
return json({ connected: bridge.isConnected, tabs: bridge.getConnectedTabs() });
|
|
15
30
|
});
|
|
16
|
-
server.tool('get_state', 'Get the full Sp00ky DevTools state (
|
|
31
|
+
server.tool('get_state', 'Get the full Sp00ky DevTools state (queries, mutations, auth, database, versions)', { tabId: z.number().optional().describe('Browser tab ID (uses first connected tab if omitted)') }, async ({ tabId }) => {
|
|
17
32
|
if (!bridge.isConnected) {
|
|
18
33
|
throw new Error('No extension connected. get_state requires the Sp00ky DevTools browser extension.');
|
|
19
34
|
}
|
|
@@ -146,27 +161,61 @@ export function createServer(bridge, surreal) {
|
|
|
146
161
|
}
|
|
147
162
|
throw new Error('No extension connected and no direct database configured.');
|
|
148
163
|
});
|
|
149
|
-
server.tool('
|
|
150
|
-
|
|
151
|
-
|
|
164
|
+
server.tool('get_mutations', "The client's writes: the outbox (pending / retrying with attempt counts), what left it since DevTools " +
|
|
165
|
+
'attached (synced with the server latency, or rolled back with the server error), debounced updates, ' +
|
|
166
|
+
'the tab role and connection (a follower tab never drains), and the rows of the persistent failed-writes ' +
|
|
167
|
+
'tray with their payload and before image. Answers "did my write reach the server?" and "why was it rolled back?".', {
|
|
168
|
+
status: z
|
|
169
|
+
.enum(['pending', 'retrying', 'synced', 'rolled-back', 'dropped'])
|
|
170
|
+
.optional()
|
|
171
|
+
.describe('Only entries with this status'),
|
|
172
|
+
includeTray: z.boolean().optional().default(true).describe('Also read the failed-writes tray rows'),
|
|
152
173
|
tabId: z.number().optional().describe('Browser tab ID'),
|
|
153
|
-
}, async ({
|
|
154
|
-
if (bridge.isConnected) {
|
|
155
|
-
|
|
156
|
-
let events = state?.eventsHistory ?? [];
|
|
157
|
-
if (eventType) {
|
|
158
|
-
events = events.filter((e) => e.eventType === eventType);
|
|
159
|
-
}
|
|
160
|
-
if (limit) {
|
|
161
|
-
events = events.slice(-limit);
|
|
162
|
-
}
|
|
163
|
-
return json(events);
|
|
164
|
-
}
|
|
165
|
-
if (surreal) {
|
|
166
|
-
const result = await surreal.query(`SELECT * FROM _00_events ORDER BY timestamp DESC LIMIT ${limit};`);
|
|
167
|
-
return json(result);
|
|
174
|
+
}, async ({ status, includeTray, tabId }) => {
|
|
175
|
+
if (!bridge.isConnected) {
|
|
176
|
+
throw new Error('No extension connected. get_mutations requires the Sp00ky DevTools browser extension.');
|
|
168
177
|
}
|
|
169
|
-
|
|
178
|
+
const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
|
|
179
|
+
const mutations = state?.mutations;
|
|
180
|
+
if (!mutations) {
|
|
181
|
+
throw new Error('This client does not report its mutations; update @spooky-sync/core.');
|
|
182
|
+
}
|
|
183
|
+
const entries = status
|
|
184
|
+
? (mutations.entries ?? []).filter((e) => e.status === status)
|
|
185
|
+
: mutations.entries;
|
|
186
|
+
const failed = includeTray
|
|
187
|
+
? (await bridge.request(BRIDGE_METHODS.PAGE_OP, { method: 'mutationOp', op: 'listFailed', args: {} }, tabId))?.failed
|
|
188
|
+
: undefined;
|
|
189
|
+
return json({ ...mutations, entries, failed });
|
|
190
|
+
});
|
|
191
|
+
server.tool('get_logs', "Recent lines from the client's own logger (the page keeps its last 500), oldest first, each with its " +
|
|
192
|
+
"structured fields. Pass `after` = a previous call's `head` to read only what is new. `captureLevel` " +
|
|
193
|
+
"changes what the page records (e.g. 'debug') without printing more to the console; it holds for the tab's " +
|
|
194
|
+
'session, so a reload records its boot at that level.', {
|
|
195
|
+
minLevel: z.enum(LEVEL_NAMES).optional().describe('Only lines at or above this level'),
|
|
196
|
+
contains: z.string().optional().describe('Only lines whose JSON contains this text (case-insensitive)'),
|
|
197
|
+
after: z.number().optional().describe('Only lines after this seq (a previous `head`)'),
|
|
198
|
+
limit: z.number().optional().default(100).describe('Max lines, newest kept'),
|
|
199
|
+
captureLevel: z.enum(LEVEL_NAMES).optional().describe('Set what the page records from now on'),
|
|
200
|
+
tabId: z.number().optional().describe('Browser tab ID'),
|
|
201
|
+
}, async ({ minLevel, contains, after, limit, captureLevel, tabId }) => {
|
|
202
|
+
if (!bridge.isConnected) {
|
|
203
|
+
throw new Error('No extension connected. get_logs requires the Sp00ky DevTools browser extension.');
|
|
204
|
+
}
|
|
205
|
+
if (captureLevel) {
|
|
206
|
+
await bridge.request(BRIDGE_METHODS.PAGE_OP, { method: 'logOp', op: 'setCaptureLevel', args: { level: captureLevel } }, tabId);
|
|
207
|
+
}
|
|
208
|
+
const read = (await bridge.request(BRIDGE_METHODS.PAGE_OP, { method: 'logOp', op: 'read', args: { after: after ?? 0 } }, tabId));
|
|
209
|
+
const floor = minLevel ? LOG_LEVELS[minLevel] : 0;
|
|
210
|
+
const term = contains?.toLowerCase();
|
|
211
|
+
const entries = (read?.entries ?? []).filter((e) => e.level >= floor && (!term || String(e.line).toLowerCase().includes(term)));
|
|
212
|
+
return json({
|
|
213
|
+
head: read?.head,
|
|
214
|
+
dropped: read?.dropped,
|
|
215
|
+
consoleLevel: read?.consoleLevel,
|
|
216
|
+
captureLevel: read?.captureLevel,
|
|
217
|
+
entries: entries.slice(Math.max(0, entries.length - (limit ?? 100))).map(readableLog),
|
|
218
|
+
});
|
|
170
219
|
});
|
|
171
220
|
server.tool('get_auth_state', 'Get the current authentication state', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
|
|
172
221
|
if (!bridge.isConnected) {
|
|
@@ -175,13 +224,6 @@ export function createServer(bridge, surreal) {
|
|
|
175
224
|
const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
|
|
176
225
|
return json(state?.auth ?? null);
|
|
177
226
|
});
|
|
178
|
-
server.tool('clear_history', 'Clear the event history', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
|
|
179
|
-
if (!bridge.isConnected) {
|
|
180
|
-
throw new Error('No extension connected. clear_history requires the Sp00ky DevTools browser extension.');
|
|
181
|
-
}
|
|
182
|
-
await bridge.request(BRIDGE_METHODS.CLEAR_HISTORY, {}, tabId);
|
|
183
|
-
return { content: [{ type: 'text', text: 'History cleared.' }] };
|
|
184
|
-
});
|
|
185
227
|
server.tool('describe_schema', 'Describe all tables with columns, types, and sp00ky annotations (@crdt, @parent). Stitches INFO FOR DB with parsed schema metadata. With the browser extension this returns @crdt/@parent semantics; direct-DB mode returns raw column info only.', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
|
|
186
228
|
if (bridge.isConnected) {
|
|
187
229
|
const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
|
|
@@ -314,17 +356,5 @@ export function createServer(bridge, surreal) {
|
|
|
314
356
|
}
|
|
315
357
|
throw new Error('No extension connected and no direct database configured.');
|
|
316
358
|
});
|
|
317
|
-
server.resource('events', 'sp00ky://events', { description: 'Event history' }, async (uri) => {
|
|
318
|
-
if (bridge.isConnected) {
|
|
319
|
-
const state = (await bridge.request(BRIDGE_METHODS.GET_STATE));
|
|
320
|
-
const events = state?.eventsHistory ?? [];
|
|
321
|
-
return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(events, null, 2) }] };
|
|
322
|
-
}
|
|
323
|
-
if (surreal) {
|
|
324
|
-
const result = await surreal.query('SELECT * FROM _00_events ORDER BY timestamp DESC LIMIT 50;');
|
|
325
|
-
return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(result, null, 2) }] };
|
|
326
|
-
}
|
|
327
|
-
throw new Error('No extension connected and no direct database configured.');
|
|
328
|
-
});
|
|
329
359
|
return server;
|
|
330
360
|
}
|