@spooky-sync/devtools-mcp 0.0.1-canary.97 → 1.0.0-beta.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.
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: events, queries, auth, database tables (extension only).
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
- - **`get_events` `[eventType] [limit]`** — recent event log, optionally filtered.
32
- - **`clear_history` `[tabId]`** — wipe the in-tab event log (extension only).
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 `get_active_queries` or `get_events` to confirm the mutation drained and any subscribed queries refreshed.
51
- - **When troubleshooting "why isn't this query updating?":** `get_active_queries` shows the registered SurQL and last result hash; `get_events` shows whether new records ingested.
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, events, active queries) only works with the extension.
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
 
@@ -24,9 +24,11 @@ export declare const BRIDGE_METHODS: {
24
24
  readonly GET_STATE: "getState";
25
25
  readonly RUN_QUERY: "runQuery";
26
26
  readonly GET_TABLE_DATA: "getTableData";
27
+ readonly GET_QUERY_ROWS: "getQueryRows";
27
28
  readonly UPDATE_TABLE_ROW: "updateTableRow";
28
29
  readonly DELETE_TABLE_ROW: "deleteTableRow";
29
- readonly CLEAR_HISTORY: "clearHistory";
30
+ /** `{ method: 'mutationOp' | 'logOp', op, args }`: the Mutations / Logs dispatchers. */
31
+ readonly PAGE_OP: "pageOp";
30
32
  };
31
33
  export declare const BRIDGE_PORT = 9315;
32
34
  export declare function isBridgeResponse(msg: unknown): msg is BridgeResponse;
package/dist/protocol.js CHANGED
@@ -4,9 +4,11 @@ export const BRIDGE_METHODS = {
4
4
  GET_STATE: 'getState',
5
5
  RUN_QUERY: 'runQuery',
6
6
  GET_TABLE_DATA: 'getTableData',
7
+ GET_QUERY_ROWS: 'getQueryRows',
7
8
  UPDATE_TABLE_ROW: 'updateTableRow',
8
9
  DELETE_TABLE_ROW: 'deleteTableRow',
9
- CLEAR_HISTORY: 'clearHistory',
10
+ /** `{ method: 'mutationOp' | 'logOp', op, args }`: the Mutations / Logs dispatchers. */
11
+ PAGE_OP: 'pageOp',
10
12
  };
11
13
  export const BRIDGE_PORT = 9315;
12
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 (events, queries, auth, database)', { tabId: z.number().optional().describe('Browser tab ID (uses first connected tab if omitted)') }, async ({ tabId }) => {
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
  }
@@ -49,6 +64,16 @@ export function createServer(bridge, surreal) {
49
64
  }
50
65
  throw new Error('No extension connected and no direct database configured.');
51
66
  });
67
+ server.tool('get_query_rows', 'Fetch the rows (data, localArray, remoteArray) of ONE active query by its queryHash. ' +
68
+ 'The state from get_active_queries carries counts and capped ids only.', {
69
+ queryHash: z.number().describe('queryHash from get_active_queries'),
70
+ tabId: z.number().optional().describe('Browser tab ID'),
71
+ }, async ({ queryHash, tabId }) => {
72
+ if (!bridge.isConnected)
73
+ throw new Error('No extension connected.');
74
+ const result = await bridge.request(BRIDGE_METHODS.GET_QUERY_ROWS, { queryHash }, tabId);
75
+ return json(result);
76
+ });
52
77
  server.tool('get_table_data', 'Fetch records from a database table', {
53
78
  tableName: z.string().describe('Name of the table'),
54
79
  limit: z.number().optional().default(100).describe('Max number of records to return'),
@@ -95,7 +120,8 @@ export function createServer(bridge, surreal) {
95
120
  }
96
121
  throw new Error('No extension connected and no direct database configured.');
97
122
  });
98
- server.tool('get_active_queries', 'Get all active live queries and their data', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
123
+ server.tool('get_active_queries', 'Get all active live queries: surql, params, counts, capped membership ids and timings ' +
124
+ '(rows are not included; use get_query_rows for one query)', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
99
125
  if (bridge.isConnected) {
100
126
  const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
101
127
  return json(state?.activeQueries ?? []);
@@ -135,27 +161,61 @@ export function createServer(bridge, surreal) {
135
161
  }
136
162
  throw new Error('No extension connected and no direct database configured.');
137
163
  });
138
- server.tool('get_events', 'Get event history, optionally filtered by type', {
139
- eventType: z.string().optional().describe('Filter by event type'),
140
- limit: z.number().optional().default(50).describe('Max number of events to return'),
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'),
141
173
  tabId: z.number().optional().describe('Browser tab ID'),
142
- }, async ({ eventType, limit, tabId }) => {
143
- if (bridge.isConnected) {
144
- const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
145
- let events = state?.eventsHistory ?? [];
146
- if (eventType) {
147
- events = events.filter((e) => e.eventType === eventType);
148
- }
149
- if (limit) {
150
- events = events.slice(-limit);
151
- }
152
- return json(events);
153
- }
154
- if (surreal) {
155
- const result = await surreal.query(`SELECT * FROM _00_events ORDER BY timestamp DESC LIMIT ${limit};`);
156
- 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.');
157
177
  }
158
- throw new Error('No extension connected and no direct database configured.');
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
+ });
159
219
  });
160
220
  server.tool('get_auth_state', 'Get the current authentication state', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
161
221
  if (!bridge.isConnected) {
@@ -164,13 +224,6 @@ export function createServer(bridge, surreal) {
164
224
  const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
165
225
  return json(state?.auth ?? null);
166
226
  });
167
- server.tool('clear_history', 'Clear the event history', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
168
- if (!bridge.isConnected) {
169
- throw new Error('No extension connected. clear_history requires the Sp00ky DevTools browser extension.');
170
- }
171
- await bridge.request(BRIDGE_METHODS.CLEAR_HISTORY, {}, tabId);
172
- return { content: [{ type: 'text', text: 'History cleared.' }] };
173
- });
174
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 }) => {
175
228
  if (bridge.isConnected) {
176
229
  const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
@@ -303,17 +356,5 @@ export function createServer(bridge, surreal) {
303
356
  }
304
357
  throw new Error('No extension connected and no direct database configured.');
305
358
  });
306
- server.resource('events', 'sp00ky://events', { description: 'Event history' }, async (uri) => {
307
- if (bridge.isConnected) {
308
- const state = (await bridge.request(BRIDGE_METHODS.GET_STATE));
309
- const events = state?.eventsHistory ?? [];
310
- return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(events, null, 2) }] };
311
- }
312
- if (surreal) {
313
- const result = await surreal.query('SELECT * FROM _00_events ORDER BY timestamp DESC LIMIT 50;');
314
- return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(result, null, 2) }] };
315
- }
316
- throw new Error('No extension connected and no direct database configured.');
317
- });
318
359
  return server;
319
360
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@spooky-sync/devtools-mcp",
3
- "version": "0.0.1-canary.97",
3
+ "version": "1.0.0-beta.1",
4
4
  "description": "MCP server for Sp00ky Sync devtools",
5
5
  "license": "MIT",
6
6
  "type": "module",