@spooky-sync/devtools-mcp 0.0.1-canary.64 → 0.0.1-canary.65

package/AGENTS.md

@@ -0,0 +1,62 @@
+# `@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: events, queries, auth, database tables (extension only).
+- **`get_auth_state` `[tabId]`** — current auth subject + scope (extension only).
+- **`get_active_queries` `[tabId]`** — registered live queries and their last result hashes.
+- **`get_events` `[eventType] [limit]`** — recent event log, optionally filtered.
+- **`clear_history` `[tabId]`** — wipe the in-tab event log (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_active_queries` or `get_events` to confirm the mutation drained and any subscribed queries refreshed.
+- **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.
+- **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, events, 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/server.js

@@ -142,6 +142,92 @@ export function createServer(bridge, surreal) {
         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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/devtools-mcp",
-  "version": "0.0.1-canary.64",
+  "version": "0.0.1-canary.65",
   "description": "MCP server for Sp00ky Sync devtools",
   "license": "MIT",
   "type": "module",
@@ -8,7 +8,8 @@
     "sp00ky-mcp": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "AGENTS.md"
   ],
   "scripts": {
     "build": "tsc",