@spooky-sync/devtools-mcp 0.0.1-canary.20

package/dist/bridge.d.ts

@@ -0,0 +1,23 @@
+interface ConnectedTab {
+    tabId: number;
+    url?: string;
+    title?: string;
+}
+export declare class Bridge {
+    private wss;
+    private extensionSocket;
+    private connectedTabs;
+    private pendingRequests;
+    private requestCounter;
+    private pingInterval;
+    get isConnected(): boolean;
+    getConnectedTabs(): ConnectedTab[];
+    start(): Promise<void>;
+    private startPing;
+    private stopPing;
+    private handleMessage;
+    request(method: string, params?: Record<string, unknown>, tabId?: number): Promise<unknown>;
+    private getDefaultTabId;
+    stop(): Promise<void>;
+}
+export {};

package/dist/bridge.js

@@ -0,0 +1,154 @@
+import { WebSocketServer, WebSocket } from 'ws';
+import { isBridgeResponse, isBridgeNotification, BRIDGE_PORT, } from './protocol.js';
+const REQUEST_TIMEOUT_MS = 10_000;
+export class Bridge {
+    wss = null;
+    extensionSocket = null;
+    connectedTabs = new Map();
+    pendingRequests = new Map();
+    requestCounter = 0;
+    pingInterval = null;
+    get isConnected() {
+        return this.extensionSocket?.readyState === WebSocket.OPEN;
+    }
+    getConnectedTabs() {
+        return Array.from(this.connectedTabs.values());
+    }
+    start() {
+        const port = parseInt(process.env.SPOOKY_MCP_PORT || '', 10) || BRIDGE_PORT;
+        return new Promise((resolve, reject) => {
+            this.wss = new WebSocketServer({ host: '127.0.0.1', port }, () => {
+                process.stderr.write(`[spooky-mcp] Bridge listening on ws://127.0.0.1:${port}\n`);
+                resolve();
+            });
+            this.wss.on('error', (err) => {
+                process.stderr.write(`[spooky-mcp] Bridge error: ${err.message}\n`);
+                reject(err);
+            });
+            this.wss.on('connection', (ws) => {
+                process.stderr.write('[spooky-mcp] Extension connected\n');
+                // Only allow one extension connection at a time
+                if (this.extensionSocket) {
+                    this.extensionSocket.close();
+                }
+                this.extensionSocket = ws;
+                // Start keepalive pings
+                this.startPing(ws);
+                ws.on('message', (data) => {
+                    try {
+                        const msg = JSON.parse(data.toString());
+                        this.handleMessage(msg);
+                    }
+                    catch (err) {
+                        process.stderr.write(`[spooky-mcp] Bad message: ${err}\n`);
+                    }
+                });
+                ws.on('close', () => {
+                    process.stderr.write('[spooky-mcp] Extension disconnected\n');
+                    if (this.extensionSocket === ws) {
+                        this.extensionSocket = null;
+                        this.connectedTabs.clear();
+                        this.stopPing();
+                        // Reject all pending requests
+                        for (const [id, pending] of this.pendingRequests) {
+                            pending.reject(new Error('Extension disconnected'));
+                            clearTimeout(pending.timer);
+                            this.pendingRequests.delete(id);
+                        }
+                    }
+                });
+                ws.on('error', (err) => {
+                    process.stderr.write(`[spooky-mcp] Socket error: ${err.message}\n`);
+                });
+            });
+        });
+    }
+    startPing(ws) {
+        this.stopPing();
+        this.pingInterval = setInterval(() => {
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.ping();
+            }
+        }, 20_000);
+    }
+    stopPing() {
+        if (this.pingInterval) {
+            clearInterval(this.pingInterval);
+            this.pingInterval = null;
+        }
+    }
+    handleMessage(msg) {
+        // Handle response to a pending request
+        if (isBridgeResponse(msg)) {
+            const pending = this.pendingRequests.get(msg.id);
+            if (pending) {
+                clearTimeout(pending.timer);
+                this.pendingRequests.delete(msg.id);
+                if (msg.error) {
+                    pending.reject(new Error(msg.error.message));
+                }
+                else {
+                    pending.resolve(msg.result);
+                }
+            }
+            return;
+        }
+        // Handle notifications from extension
+        if (isBridgeNotification(msg)) {
+            if (msg.method === 'tabsChanged') {
+                this.connectedTabs.clear();
+                const tabs = msg.params.tabs;
+                for (const tab of tabs) {
+                    this.connectedTabs.set(tab.tabId, tab);
+                }
+            }
+            return;
+        }
+    }
+    async request(method, params = {}, tabId) {
+        if (!this.extensionSocket || this.extensionSocket.readyState !== WebSocket.OPEN) {
+            throw new Error('No extension connected. Make sure the Spooky DevTools extension is running and has a page with Spooky open.');
+        }
+        const id = `mcp-${++this.requestCounter}`;
+        const resolvedTabId = tabId ?? this.getDefaultTabId();
+        const request = {
+            jsonrpc: '2.0',
+            id,
+            method,
+            params,
+            ...(resolvedTabId !== undefined ? { tabId: resolvedTabId } : {}),
+        };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`Request timed out after ${REQUEST_TIMEOUT_MS}ms: ${method}`));
+            }, REQUEST_TIMEOUT_MS);
+            this.pendingRequests.set(id, { resolve, reject, timer });
+            this.extensionSocket.send(JSON.stringify(request));
+        });
+    }
+    getDefaultTabId() {
+        const tabs = this.getConnectedTabs();
+        return tabs.length > 0 ? tabs[0].tabId : undefined;
+    }
+    async stop() {
+        this.stopPing();
+        for (const [id, pending] of this.pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error('Bridge shutting down'));
+            this.pendingRequests.delete(id);
+        }
+        if (this.extensionSocket) {
+            this.extensionSocket.close();
+            this.extensionSocket = null;
+        }
+        return new Promise((resolve) => {
+            if (this.wss) {
+                this.wss.close(() => resolve());
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Bridge } from './bridge.js';
+import { createServer } from './server.js';
+async function main() {
+    const bridge = new Bridge();
+    await bridge.start();
+    const server = createServer(bridge);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write('[spooky-mcp] MCP server running on stdio\n');
+    // Graceful shutdown
+    const cleanup = async () => {
+        process.stderr.write('[spooky-mcp] Shutting down...\n');
+        await bridge.stop();
+        process.exit(0);
+    };
+    process.on('SIGINT', cleanup);
+    process.on('SIGTERM', cleanup);
+}
+main().catch((err) => {
+    process.stderr.write(`[spooky-mcp] Fatal error: ${err.message}\n`);
+    process.exit(1);
+});

package/dist/protocol.d.ts

@@ -0,0 +1,34 @@
+export interface BridgeRequest {
+    jsonrpc: '2.0';
+    id: string;
+    method: string;
+    params: Record<string, unknown>;
+    tabId?: number;
+}
+export interface BridgeResponse {
+    jsonrpc: '2.0';
+    id: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+    };
+}
+export interface BridgeNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params: Record<string, unknown>;
+}
+export type BridgeMessage = BridgeRequest | BridgeResponse | BridgeNotification;
+export declare const BRIDGE_METHODS: {
+    readonly GET_STATE: "getState";
+    readonly RUN_QUERY: "runQuery";
+    readonly GET_TABLE_DATA: "getTableData";
+    readonly UPDATE_TABLE_ROW: "updateTableRow";
+    readonly DELETE_TABLE_ROW: "deleteTableRow";
+    readonly CLEAR_HISTORY: "clearHistory";
+};
+export declare const BRIDGE_PORT = 9315;
+export declare function isBridgeResponse(msg: unknown): msg is BridgeResponse;
+export declare function isBridgeRequest(msg: unknown): msg is BridgeRequest;
+export declare function isBridgeNotification(msg: unknown): msg is BridgeNotification;

package/dist/protocol.js

@@ -0,0 +1,37 @@
+// Shared message types for MCP Server <-> Chrome Extension bridge (JSON-RPC 2.0 style)
+// Methods the MCP server can call on the extension
+export const BRIDGE_METHODS = {
+    GET_STATE: 'getState',
+    RUN_QUERY: 'runQuery',
+    GET_TABLE_DATA: 'getTableData',
+    UPDATE_TABLE_ROW: 'updateTableRow',
+    DELETE_TABLE_ROW: 'deleteTableRow',
+    CLEAR_HISTORY: 'clearHistory',
+};
+export const BRIDGE_PORT = 9315;
+export function isBridgeResponse(msg) {
+    return (typeof msg === 'object' &&
+        msg !== null &&
+        'jsonrpc' in msg &&
+        msg.jsonrpc === '2.0' &&
+        'id' in msg &&
+        ('result' in msg || 'error' in msg));
+}
+export function isBridgeRequest(msg) {
+    return (typeof msg === 'object' &&
+        msg !== null &&
+        'jsonrpc' in msg &&
+        msg.jsonrpc === '2.0' &&
+        'method' in msg &&
+        'id' in msg &&
+        !('result' in msg) &&
+        !('error' in msg));
+}
+export function isBridgeNotification(msg) {
+    return (typeof msg === 'object' &&
+        msg !== null &&
+        'jsonrpc' in msg &&
+        msg.jsonrpc === '2.0' &&
+        'method' in msg &&
+        !('id' in msg));
+}

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Bridge } from './bridge.js';
+export declare function createServer(bridge: Bridge): McpServer;

package/dist/server.js

@@ -0,0 +1,120 @@
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { BRIDGE_METHODS } from './protocol.js';
+export function createServer(bridge) {
+    const server = new McpServer({
+        name: 'spooky-devtools',
+        version: '0.0.1',
+    });
+    // --- Tools ---
+    server.tool('list_connections', 'List browser tabs connected to Spooky DevTools', {}, async () => {
+        const tabs = bridge.getConnectedTabs();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        connected: bridge.isConnected,
+                        tabs,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.tool('get_state', 'Get the full Spooky DevTools state (events, queries, auth, database)', { tabId: z.number().optional().describe('Browser tab ID (uses first connected tab if omitted)') }, async ({ tabId }) => {
+        const result = await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId);
+        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    });
+    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) }] };
+    });
+    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) }] };
+    });
+    server.tool('get_table_data', 'Fetch all records from a database table', {
+        tableName: z.string().describe('Name of the table'),
+        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) }] };
+    });
+    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'),
+        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) }] };
+    });
+    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'),
+        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) }] };
+    });
+    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_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'),
+        tabId: z.number().optional().describe('Browser tab ID'),
+    }, async ({ eventType, limit, tabId }) => {
+        const state = (await bridge.request(BRIDGE_METHODS.GET_STATE, {}, tabId));
+        let events = state?.eventsHistory ?? [];
+        if (eventType) {
+            events = events.filter((e) => e.eventType === eventType);
+        }
+        if (limit) {
+            events = events.slice(-limit);
+        }
+        return { content: [{ type: 'text', text: JSON.stringify(events, null, 2) }] };
+    });
+    server.tool('get_auth_state', 'Get the current authentication state', { tabId: z.number().optional().describe('Browser tab ID') }, async ({ tabId }) => {
+        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) }] };
+    });
+    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.' }] };
+    });
+    // --- Resources ---
+    server.resource('state', 'spooky://state', { description: 'Full Spooky DevTools state' }, async (uri) => {
+        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', 'spooky://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) }] };
+    });
+    server.resource('table-data', new ResourceTemplate('spooky://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) }] };
+    });
+    server.resource('queries', 'spooky://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', 'spooky://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) }] };
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@spooky-sync/devtools-mcp",
+  "version": "0.0.1-canary.20",
+  "description": "MCP server for Spooky Sync devtools",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "spooky-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mono424/spooky.git",
+    "directory": "apps/devtools-mcp"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "ws": "^8.18.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.0",
+    "typescript": "^5.6.2"
+  }
+}