@spooky-sync/devtools-mcp 0.0.1-canary.32 → 0.0.1-canary.321

package/AGENTS.md

@@ -0,0 +1,64 @@
+# `@spooky-sync/devtools-mcp` (`sp00ky-mcp`) — agent guide
+
+## What this package is
+
+A Model Context Protocol server that gives an AI assistant live, structured access to a running sp00ky app. It bridges to either:
+
+1. **The Sp00ky DevTools browser extension** (via WebSocket on the side channel `bridge.ts` opens), so the assistant sees the *exact* state the user's tab has — local cache, active live queries, event history, auth state.
+2. **A direct SurrealDB connection** (set `SURREAL_URL`, `SURREAL_USER`, `SURREAL_PASS`, `SURREAL_NS`, `SURREAL_DB`) — useful when there's no browser tab attached.
+
+Most tools transparently fall through: extension first, raw DB as a fallback. A handful (auth state, event history clear) require the extension.
+
+## Run it
+
+```bash
+npx @spooky-sync/devtools-mcp
+# or, from inside an app, via the CLI passthrough:
+spky mcp
+```
+
+Wire into Claude / your agent via the MCP server config (`.mcp.json` at the repo root or your client's equivalent).
+
+## Tools exposed
+
+### Connection / state
+
+- **`list_connections`** — which browser tabs are currently bridged.
+- **`get_state` `[tabId]`** — full devtools state: queries, mutations, auth, database tables, versions (extension only).
+- **`get_auth_state` `[tabId]`** — current auth subject + scope (extension only).
+- **`get_active_queries` `[tabId]`** — registered live queries, their last result hashes, and a per-query `timings` breakdown.
+- **`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.
+- **`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).
+- **`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).
+
+### Database (works against extension OR direct DB)
+
+- **`run_query` `query` `[target=local|remote]` `[tabId]`** — execute arbitrary SurQL.
+- **`list_tables` `[tabId]`** — names of tables defined in the running schema.
+- **`get_table_data` `tableName` `[limit]` `[tabId]`** — `SELECT * LIMIT n` shortcut.
+- **`update_table_row` `recordId` `updates` `[tableName] [tabId]`** — `UPDATE recordId MERGE updates`.
+- **`delete_table_row` `recordId` `[tableName] [tabId]`** — `DELETE recordId`.
+
+### Resources
+
+- `sp00ky://state` — full state JSON (extension only).
+- `sp00ky://tables` — table list.
+
+## How an agent should use this
+
+- **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.
+- **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.
+- **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`.
+- **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).
+- **For schema spelunking from outside the browser:** point `SURREAL_URL` at the dev DB and use `run_query` with `INFO FOR DB;`.
+
+## Common gotchas
+
+- **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.
+- **Tab selection matters.** Multi-tab dev: pass `tabId` explicitly or you get whichever tab connected first.
+- **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.
+
+## Pointers
+
+- Sync engine that emits the events this server reads: `node_modules/@spooky-sync/core/AGENTS.md` → `src/modules/devtools/`
+- CLI passthrough: `node_modules/@spooky-sync/cli/AGENTS.md` (`spky mcp`)

package/dist/bridge.js

@@ -15,7 +15,7 @@ export class Bridge {
         return Array.from(this.connectedTabs.values());
     }
     start() {
-        const port = parseInt(process.env.SP00KY_MCP_PORT || '', 10) || BRIDGE_PORT;
+        const port = Number.parseInt(process.env.SP00KY_MCP_PORT || '', 10) || BRIDGE_PORT;
         return new Promise((resolve, reject) => {
             this.wss = new WebSocketServer({ host: '127.0.0.1', port }, () => {
                 process.stderr.write(`[sp00ky-mcp] Bridge listening on ws://127.0.0.1:${port}\n`);
@@ -124,6 +124,7 @@ export class Bridge {
                 reject(new Error(`Request timed out after ${REQUEST_TIMEOUT_MS}ms: ${method}`));
             }, REQUEST_TIMEOUT_MS);
             this.pendingRequests.set(id, { resolve, reject, timer });
+            // oxlint-disable-next-line no-non-null-assertion
             this.extensionSocket.send(JSON.stringify(request));
         });
     }

package/dist/index.js

@@ -1,11 +1,24 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { Bridge } from './bridge.js';
+import { SurrealClient } from './surreal.js';
 import { createServer } from './server.js';
 async function main() {
     const bridge = new Bridge();
     await bridge.start();
-    const server = createServer(bridge);
+    const surreal = process.env.SURREAL_URL
+        ? new SurrealClient({
+            url: process.env.SURREAL_URL,
+            namespace: process.env.SURREAL_NS ?? 'main',
+            database: process.env.SURREAL_DB ?? 'main',
+            username: process.env.SURREAL_USER ?? 'root',
+            password: process.env.SURREAL_PASS ?? 'root',
+        })
+        : null;
+    if (surreal) {
+        process.stderr.write(`[sp00ky-mcp] Direct DB mode enabled (${process.env.SURREAL_URL})\n`);
+    }
+    const server = createServer(bridge, surreal);
     const transport = new StdioServerTransport();
     await server.connect(transport);
     process.stderr.write('[sp00ky-mcp] MCP server running on stdio\n');

package/dist/protocol.d.ts

@@ -24,9 +24,11 @@ export declare const BRIDGE_METHODS: {
     readonly GET_STATE: "getState";
     readonly RUN_QUERY: "runQuery";
     readonly GET_TABLE_DATA: "getTableData";
+    readonly GET_QUERY_ROWS: "getQueryRows";
     readonly UPDATE_TABLE_ROW: "updateTableRow";
     readonly DELETE_TABLE_ROW: "deleteTableRow";
-    readonly CLEAR_HISTORY: "clearHistory";
+    /** `{ method: 'mutationOp' | 'logOp', op, args }`: the Mutations / Logs dispatchers. */
+    readonly PAGE_OP: "pageOp";
 };
 export declare const BRIDGE_PORT = 9315;
 export declare function isBridgeResponse(msg: unknown): msg is BridgeResponse;

package/dist/protocol.js

@@ -4,9 +4,11 @@ export const BRIDGE_METHODS = {
     GET_STATE: 'getState',
     RUN_QUERY: 'runQuery',
     GET_TABLE_DATA: 'getTableData',
+    GET_QUERY_ROWS: 'getQueryRows',
     UPDATE_TABLE_ROW: 'updateTableRow',
     DELETE_TABLE_ROW: 'deleteTableRow',
-    CLEAR_HISTORY: 'clearHistory',
+    /** `{ method: 'mutationOp' | 'logOp', op, args }`: the Mutations / Logs dispatchers. */
+    PAGE_OP: 'pageOp',
 };
 export const BRIDGE_PORT = 9315;
 export function isBridgeResponse(msg) {

package/dist/server.d.ts

@@ -1,3 +1,4 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { Bridge } from './bridge.js';
-export declare function createServer(bridge: Bridge): McpServer;
+import type { Bridge } from './bridge.js';
+import type { SurrealClient } from './surreal.js';
+export declare function createServer(bridge: Bridge, surreal?: SurrealClient | null): McpServer;

package/dist/server.js

@@ -1,120 +1,360 @@
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { BRIDGE_METHODS } from './protocol.js';
-export function createServer(bridge) {
+function json(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+const LOG_LEVELS = { trace: 10, debug: 20, info: 30, warn: 40, error: 50, fatal: 60 };
+const LEVEL_NAMES = Object.keys(LOG_LEVELS);
+const levelName = (level) => Object.entries(LOG_LEVELS).reduce((name, [n, v]) => (level >= v ? n : name), 'trace');
+/** A captured line as the agent reads it: the JSON parsed, minus what is already a field. */
+function readableLog(e) {
+    let data;
+    try {
+        const { time: _time, level: _level, msg: _msg, ...rest } = JSON.parse(e.line);
+        data = Object.keys(rest).length ? rest : undefined;
+    }
+    catch {
+        data = { truncated: e.line };
+    }
+    return { seq: e.seq, time: new Date(e.time).toISOString(), level: levelName(e.level), msg: e.msg, data };
+}
+export function createServer(bridge, surreal) {
     const server = new McpServer({
         name: 'sp00ky-devtools',
         version: '0.0.1',
     });
     // --- Tools ---
     server.tool('list_connections', 'List browser tabs connected to Sp00ky DevTools', {}, async () => {
-        const tabs = bridge.getConnectedTabs();
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({
-                        connected: bridge.isConnected,
-                        tabs,
-                    }, null, 2),
-                },
-            ],
-        };
+        return json({ connected: bridge.isConnected, tabs: bridge.getConnectedTabs() });
     });
-    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 }) => {
+    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 }) => {
+        if (!bridge.isConnected) {
+            throw new Error('No extension connected. get_state requires the Sp00ky DevTools browser extension.');
+        }
         const result = await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        return json(result);
     });
     server.tool('run_query', 'Execute a SurrealQL query against the database', {
         query: z.string().describe('SurrealQL query to execute'),
         target: z.enum(['local', 'remote']).optional().default('remote').describe('Query target: local or remote database'),
         tabId: z.number().optional().describe('Browser tab ID'),
     }, async ({ query, target, tabId }) => {
-        const result = await bridge.request(BRIDGE_METHODS.RUN_QUERY, { query, target }, tabId);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        if (bridge.isConnected) {
+            const result = await bridge.request(BRIDGE_METHODS.RUN_QUERY, { query, target }, tabId);
+            return json(result);
+        }
+        if (surreal) {
+            const result = await surreal.query(query);
+            return json(result);
+        }
+        throw new Error('No extension connected and no direct database configured. Set SURREAL_URL or connect the browser extension.');
     });
     server.tool('list_tables', 'List all database tables', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
-        const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
-        const tables = state?.database?.tables ?? [];
-        return { content: [{ type: 'text', text: JSON.stringify(tables, null, 2) }] };
+        if (bridge.isConnected) {
+            const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
+            const tables = state?.database?.tables ?? [];
+            return json(tables);
+        }
+        if (surreal) {
+            const result = await surreal.query('INFO FOR DB;');
+            const info = result;
+            const tables = info?.[0]?.result?.tables ?? info?.[0]?.tables ?? {};
+            return json(Object.keys(tables));
+        }
+        throw new Error('No extension connected and no direct database configured.');
     });
-    server.tool('get_table_data', 'Fetch all records from a database table', {
+    server.tool('get_query_rows', 'Fetch the rows (data, localArray, remoteArray) of ONE active query by its queryHash. ' +
+        'The state from get_active_queries carries counts and capped ids only.', {
+        queryHash: z.number().describe('queryHash from get_active_queries'),
+        tabId: z.number().optional().describe('Browser tab ID'),
+    }, async ({ queryHash, tabId }) => {
+        if (!bridge.isConnected)
+            throw new Error('No extension connected.');
+        const result = await bridge.request(BRIDGE_METHODS.GET_QUERY_ROWS, { queryHash }, tabId);
+        return json(result);
+    });
+    server.tool('get_table_data', 'Fetch records from a database table', {
         tableName: z.string().describe('Name of the table'),
+        limit: z.number().optional().default(100).describe('Max number of records to return'),
         tabId: z.number().optional().describe('Browser tab ID'),
-    }, async ({ tableName, tabId }) => {
-        const result = await bridge.request(BRIDGE_METHODS.GET_TABLE_DATA, { tableName }, tabId);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    }, async ({ tableName, limit, tabId }) => {
+        if (bridge.isConnected) {
+            const result = await bridge.request(BRIDGE_METHODS.GET_TABLE_DATA, { tableName }, tabId);
+            return json(result);
+        }
+        if (surreal) {
+            const result = await surreal.query(`SELECT * FROM \`${tableName}\` LIMIT ${limit};`);
+            return json(result);
+        }
+        throw new Error('No extension connected and no direct database configured.');
     });
     server.tool('update_table_row', 'Update a record in a database table', {
-        tableName: z.string().describe('Name of the table'),
-        recordId: z.string().describe('Record ID to update'),
+        tableName: z.string().optional().describe('Name of the table (used when browser extension is connected)'),
+        recordId: z.string().describe('Record ID to update (e.g. "users:abc123")'),
         updates: z.record(z.unknown()).describe('Fields to update'),
         tabId: z.number().optional().describe('Browser tab ID'),
     }, async ({ tableName, recordId, updates, tabId }) => {
-        const result = await bridge.request(BRIDGE_METHODS.UPDATE_TABLE_ROW, { tableName, recordId, updates }, tabId);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        if (bridge.isConnected) {
+            const result = await bridge.request(BRIDGE_METHODS.UPDATE_TABLE_ROW, { tableName, recordId, updates }, tabId);
+            return json(result);
+        }
+        if (surreal) {
+            const result = await surreal.query(`UPDATE ${recordId} MERGE ${JSON.stringify(updates)};`);
+            return json(result);
+        }
+        throw new Error('No extension connected and no direct database configured.');
     });
     server.tool('delete_table_row', 'Delete a record from a database table', {
-        tableName: z.string().describe('Name of the table'),
-        recordId: z.string().describe('Record ID to delete'),
+        tableName: z.string().optional().describe('Name of the table (used when browser extension is connected)'),
+        recordId: z.string().describe('Record ID to delete (e.g. "users:abc123")'),
         tabId: z.number().optional().describe('Browser tab ID'),
     }, async ({ tableName, recordId, tabId }) => {
-        const result = await bridge.request(BRIDGE_METHODS.DELETE_TABLE_ROW, { tableName, recordId }, tabId);
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+        if (bridge.isConnected) {
+            const result = await bridge.request(BRIDGE_METHODS.DELETE_TABLE_ROW, { tableName, recordId }, tabId);
+            return json(result);
+        }
+        if (surreal) {
+            const result = await surreal.query(`DELETE ${recordId};`);
+            return json(result);
+        }
+        throw new Error('No extension connected and no direct database configured.');
     });
-    server.tool('get_active_queries', 'Get all active live queries and their data', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
-        const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
-        const queries = state?.activeQueries ?? [];
-        return { content: [{ type: 'text', text: JSON.stringify(queries, null, 2) }] };
+    server.tool('get_active_queries', 'Get all active live queries: surql, params, counts, capped membership ids and timings ' +
+        '(rows are not included; use get_query_rows for one query)', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
+        if (bridge.isConnected) {
+            const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
+            return json(state?.activeQueries ?? []);
+        }
+        if (surreal) {
+            const result = await surreal.query('SELECT * FROM _00_query;');
+            return json(result);
+        }
+        throw new Error('No extension connected and no direct database configured.');
+    });
+    server.tool('get_query_timings', 'Per-query processing-time breakdown for debugging: SSP phases (parse/plan/snapshot at registration; store-apply/circuit-step/transform per ingest, plus whole-ingest `ssp` wall time), local & remote record-fetch, and frontend reconcile — each as { lastMs, p50, p90, p99, count } — sorted slowest-first. Requires the Sp00ky DevTools browser extension. The SurrealDB fallback only exposes persisted materialization percentiles (the per-phase samples are in-memory).', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
+        if (bridge.isConnected) {
+            const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
+            const queries = state?.activeQueries
+                ? Object.values(state.activeQueries)
+                : [];
+            // Rank by the dominant phases' p90 (fall back to last) so the slowest
+            // query/phase surfaces first.
+            const scoreOf = (t) => ['ssp', 'localFetch', 'remoteFetch', 'frontend'].reduce((s, k) => s + (t?.[k]?.p90 ?? t?.[k]?.lastMs ?? 0), 0);
+            const rows = queries
+                .map((q) => ({
+                queryHash: q.queryHash,
+                query: q.query,
+                updateCount: q.timings?.updateCount ?? q.updateCount,
+                errorCount: q.timings?.errorCount,
+                timings: q.timings ?? null,
+                _score: scoreOf(q.timings),
+            }))
+                .sort((a, b) => b._score - a._score)
+                // oxlint-disable-next-line no-unused-vars -- strip the internal sort key
+                .map(({ _score, ...rest }) => rest);
+            return json(rows);
+        }
+        if (surreal) {
+            const result = await surreal.query('SELECT * FROM _00_query;');
+            return json(result);
+        }
+        throw new Error('No extension connected and no direct database configured.');
     });
-    server.tool('get_events', 'Get event history, optionally filtered by type', {
-        eventType: z.string().optional().describe('Filter by event type'),
-        limit: z.number().optional().describe('Max number of events to return'),
+    server.tool('get_mutations', "The client's writes: the outbox (pending / retrying with attempt counts), what left it since DevTools " +
+        'attached (synced with the server latency, or rolled back with the server error), debounced updates, ' +
+        'the tab role and connection (a follower tab never drains), and the rows of the persistent failed-writes ' +
+        'tray with their payload and before image. Answers "did my write reach the server?" and "why was it rolled back?".', {
+        status: z
+            .enum(['pending', 'retrying', 'synced', 'rolled-back', 'dropped'])
+            .optional()
+            .describe('Only entries with this status'),
+        includeTray: z.boolean().optional().default(true).describe('Also read the failed-writes tray rows'),
         tabId: z.number().optional().describe('Browser tab ID'),
-    }, async ({ eventType, limit, tabId }) => {
+    }, async ({ status, includeTray, tabId }) => {
+        if (!bridge.isConnected) {
+            throw new Error('No extension connected. get_mutations requires the Sp00ky DevTools browser extension.');
+        }
         const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
-        let events = state?.eventsHistory ?? [];
-        if (eventType) {
-            events = events.filter((e) => e.eventType === eventType);
+        const mutations = state?.mutations;
+        if (!mutations) {
+            throw new Error('This client does not report its mutations; update @spooky-sync/core.');
+        }
+        const entries = status
+            ? (mutations.entries ?? []).filter((e) => e.status === status)
+            : mutations.entries;
+        const failed = includeTray
+            ? (await bridge.request(BRIDGE_METHODS.PAGE_OP, { method: 'mutationOp', op: 'listFailed', args: {} }, tabId))?.failed
+            : undefined;
+        return json({ ...mutations, entries, failed });
+    });
+    server.tool('get_logs', "Recent lines from the client's own logger (the page keeps its last 500), oldest first, each with its " +
+        "structured fields. Pass `after` = a previous call's `head` to read only what is new. `captureLevel` " +
+        "changes what the page records (e.g. 'debug') without printing more to the console; it holds for the tab's " +
+        'session, so a reload records its boot at that level.', {
+        minLevel: z.enum(LEVEL_NAMES).optional().describe('Only lines at or above this level'),
+        contains: z.string().optional().describe('Only lines whose JSON contains this text (case-insensitive)'),
+        after: z.number().optional().describe('Only lines after this seq (a previous `head`)'),
+        limit: z.number().optional().default(100).describe('Max lines, newest kept'),
+        captureLevel: z.enum(LEVEL_NAMES).optional().describe('Set what the page records from now on'),
+        tabId: z.number().optional().describe('Browser tab ID'),
+    }, async ({ minLevel, contains, after, limit, captureLevel, tabId }) => {
+        if (!bridge.isConnected) {
+            throw new Error('No extension connected. get_logs requires the Sp00ky DevTools browser extension.');
         }
-        if (limit) {
-            events = events.slice(-limit);
+        if (captureLevel) {
+            await bridge.request(BRIDGE_METHODS.PAGE_OP, { method: 'logOp', op: 'setCaptureLevel', args: { level: captureLevel } }, tabId);
         }
-        return { content: [{ type: 'text', text: JSON.stringify(events, null, 2) }] };
+        const read = (await bridge.request(BRIDGE_METHODS.PAGE_OP, { method: 'logOp', op: 'read', args: { after: after ?? 0 } }, tabId));
+        const floor = minLevel ? LOG_LEVELS[minLevel] : 0;
+        const term = contains?.toLowerCase();
+        const entries = (read?.entries ?? []).filter((e) => e.level >= floor && (!term || String(e.line).toLowerCase().includes(term)));
+        return json({
+            head: read?.head,
+            dropped: read?.dropped,
+            consoleLevel: read?.consoleLevel,
+            captureLevel: read?.captureLevel,
+            entries: entries.slice(Math.max(0, entries.length - (limit ?? 100))).map(readableLog),
+        });
     });
     server.tool('get_auth_state', 'Get the current authentication state', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
+        if (!bridge.isConnected) {
+            throw new Error('No extension connected. get_auth_state requires the Sp00ky DevTools browser extension.');
+        }
         const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
-        const auth = state?.auth ?? null;
-        return { content: [{ type: 'text', text: JSON.stringify(auth, null, 2) }] };
+        return json(state?.auth ?? null);
     });
-    server.tool('clear_history', 'Clear the event history', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
-        await bridge.request(BRIDGE_METHODS.CLEAR_HISTORY, {}, tabId);
-        return { content: [{ type: 'text', text: 'History cleared.' }] };
+    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 }) => {
+        if (bridge.isConnected) {
+            const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
+            const dbState = state?.database ?? {};
+            return json({
+                source: 'extension',
+                tables: dbState.tables ?? [],
+                relationships: dbState.relationships ?? [],
+            });
+        }
+        if (surreal) {
+            const dbInfo = (await surreal.query('INFO FOR DB;'));
+            const tablesObj = dbInfo?.[0]?.result?.tables ?? dbInfo?.[0]?.tables ?? {};
+            const tableNames = Object.keys(tablesObj);
+            const tables = await Promise.all(tableNames.map(async (name) => {
+                try {
+                    const info = (await surreal.query(`INFO FOR TABLE \`${name}\`;`));
+                    const fieldsObj = info?.[0]?.result?.fields ?? info?.[0]?.fields ?? {};
+                    const columns = Object.entries(fieldsObj).map(([fname, def]) => ({
+                        name: fname,
+                        definition: typeof def === 'string' ? def : JSON.stringify(def),
+                    }));
+                    return { name, columns };
+                }
+                catch (e) {
+                    return { name, columns: [], error: e instanceof Error ? e.message : String(e) };
+                }
+            }));
+            return json({
+                source: 'direct-db',
+                note: '@crdt / @parent annotations are not visible in direct-DB mode; connect the browser extension to see them.',
+                tables,
+            });
+        }
+        throw new Error('No extension connected and no direct database configured.');
+    });
+    server.tool('lint_query', 'Validate a SurrealQL query without running it. Sends EXPLAIN <query> through the connected channel; returns parse / plan errors with location when SurrealDB provides them.', {
+        query: z.string().describe('SurrealQL query to validate'),
+        target: z
+            .enum(['local', 'remote'])
+            .optional()
+            .default('remote')
+            .describe('When using the extension: lint against local (cache) or remote DB'),
+        tabId: z.number().optional().describe('Browser tab ID'),
+    }, async ({ query, target, tabId }) => {
+        const trimmed = query.trim().replace(/;\s*$/, '');
+        const explainQuery = /^\s*EXPLAIN\b/i.test(trimmed) ? trimmed : `EXPLAIN ${trimmed};`;
+        const parseError = (msg) => {
+            const m = msg.match(/line\s+(\d+)(?:[,\s]+col(?:umn)?\s+(\d+))?/i);
+            return {
+                ok: false,
+                errors: [
+                    {
+                        message: msg,
+                        line: m ? Number(m[1]) : undefined,
+                        column: m && m[2] ? Number(m[2]) : undefined,
+                    },
+                ],
+            };
+        };
+        const inspectResult = (raw) => {
+            const arr = Array.isArray(raw) ? raw : [raw];
+            const errors = arr
+                .map((r) => (r && r.status === 'ERR' ? r.result ?? r.message : null))
+                .filter(Boolean);
+            if (errors.length > 0) {
+                return { ok: false, errors: errors.map((m) => parseError(m).errors[0]) };
+            }
+            return { ok: true, plan: arr };
+        };
+        try {
+            if (bridge.isConnected) {
+                const result = await bridge.request(BRIDGE_METHODS.RUN_QUERY, { query: explainQuery, target }, tabId);
+                return json(inspectResult(result));
+            }
+            if (surreal) {
+                const result = await surreal.query(explainQuery);
+                return json(inspectResult(result));
+            }
+            throw new Error('No extension connected and no direct database configured.');
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return json(parseError(msg));
+        }
     });
     // --- Resources ---
     server.resource('state', 'sp00ky://state', { description: 'Full Sp00ky DevTools state' }, async (uri) => {
+        if (!bridge.isConnected) {
+            throw new Error('No extension connected. State resource requires the browser extension.');
+        }
         const state = await bridge.request(BRIDGE_METHODS.GET_STATE);
         return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(state, null, 2) }] };
     });
     server.resource('tables', 'sp00ky://tables', { description: 'List of database tables' }, async (uri) => {
-        const state = (await bridge.request(BRIDGE_METHODS.GET_STATE));
-        const tables = state?.database?.tables ?? [];
-        return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(tables, null, 2) }] };
+        if (bridge.isConnected) {
+            const state = (await bridge.request(BRIDGE_METHODS.GET_STATE));
+            const tables = state?.database?.tables ?? [];
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(tables, null, 2) }] };
+        }
+        if (surreal) {
+            const result = await surreal.query('INFO FOR DB;');
+            const info = result;
+            const tables = info?.[0]?.result?.tables ?? info?.[0]?.tables ?? {};
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(Object.keys(tables), null, 2) }] };
+        }
+        throw new Error('No extension connected and no direct database configured.');
     });
     server.resource('table-data', new ResourceTemplate('sp00ky://tables/{tableName}', { list: undefined }), { description: 'Contents of a specific database table' }, async (uri, variables) => {
         const tableName = variables.tableName;
-        const result = await bridge.request(BRIDGE_METHODS.GET_TABLE_DATA, { tableName });
-        return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(result, null, 2) }] };
+        if (bridge.isConnected) {
+            const result = await bridge.request(BRIDGE_METHODS.GET_TABLE_DATA, { tableName });
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(result, null, 2) }] };
+        }
+        if (surreal) {
+            const result = await surreal.query(`SELECT * FROM \`${tableName}\` LIMIT 100;`);
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(result, null, 2) }] };
+        }
+        throw new Error('No extension connected and no direct database configured.');
     });
     server.resource('queries', 'sp00ky://queries', { description: 'Active live queries' }, async (uri) => {
-        const state = (await bridge.request(BRIDGE_METHODS.GET_STATE));
-        const queries = state?.activeQueries ?? [];
-        return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(queries, null, 2) }] };
-    });
-    server.resource('events', 'sp00ky://events', { description: 'Event history' }, async (uri) => {
-        const state = (await bridge.request(BRIDGE_METHODS.GET_STATE));
-        const events = state?.eventsHistory ?? [];
-        return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(events, null, 2) }] };
+        if (bridge.isConnected) {
+            const state = (await bridge.request(BRIDGE_METHODS.GET_STATE));
+            const queries = state?.activeQueries ?? [];
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(queries, null, 2) }] };
+        }
+        if (surreal) {
+            const result = await surreal.query('SELECT * FROM _00_query;');
+            return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(result, null, 2) }] };
+        }
+        throw new Error('No extension connected and no direct database configured.');
     });
     return server;
 }

package/dist/surreal.d.ts

@@ -0,0 +1,13 @@
+export interface SurrealConfig {
+    url: string;
+    namespace: string;
+    database: string;
+    username: string;
+    password: string;
+}
+export declare class SurrealClient {
+    private config;
+    private authHeader;
+    constructor(config: SurrealConfig);
+    query(surql: string): Promise<unknown[]>;
+}

package/dist/surreal.js

@@ -0,0 +1,27 @@
+export class SurrealClient {
+    config;
+    authHeader;
+    constructor(config) {
+        this.config = config;
+        this.authHeader =
+            'Basic ' + Buffer.from(`${config.username}:${config.password}`).toString('base64');
+    }
+    async query(surql) {
+        const res = await fetch(`${this.config.url}/sql`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: this.authHeader,
+                'surreal-ns': this.config.namespace,
+                'surreal-db': this.config.database,
+                Accept: 'application/json',
+            },
+            body: surql,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`SurrealDB query failed (${res.status}): ${text}`);
+        }
+        return res.json();
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/devtools-mcp",
-  "version": "0.0.1-canary.32",
+  "version": "0.0.1-canary.321",
   "description": "MCP server for Sp00ky Sync devtools",
   "license": "MIT",
   "type": "module",
@@ -8,11 +8,13 @@
     "sp00ky-mcp": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "tsc",
-    "dev": "tsc --watch"
+    "dev": "tsc --watch",
+    "test": "vitest run"
   },
   "repository": {
     "type": "git",
@@ -29,6 +31,7 @@
   },
   "devDependencies": {
     "@types/ws": "^8.18.0",
-    "typescript": "^5.6.2"
+    "typescript": "^5.6.2",
+    "vitest": "^1.0.0"
   }
 }