@oimdb/mcp 1.0.0

package/README.md

@@ -0,0 +1,131 @@
+# @oimdb/mcp
+
+Connects AI assistants to a live OIMDB store running in the browser. Provides MCP tools for Claude Code and an optional CDP inspector for any AI that can run a shell command.
+
+## For AI Assistants
+
+If you are an AI assistant and this package is present in the project, you can get live OIMDB state from the running browser tab.
+
+**Check if MCP is already configured** — look for `mcpServers.oimdb` in `.claude/settings.json` or `~/.claude/settings.json`. If it is, the tools `oimdb_inspect`, `oimdb_dump`, `oimdb_collection`, and `oimdb_computed` are available. Call `oimdb_inspect` now to see the current state.
+
+**If MCP is not configured yet**, add this to the project's MCP config:
+
+- Claude Code: `.claude/settings.json`
+- Cursor: `.cursor/mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "oimdb": {
+      "command": "npx",
+      "args": ["-y", "@oimdb/mcp"]
+    }
+  }
+}
+```
+
+Then ask the user to:
+1. Reload Claude Code so the MCP server starts
+2. Make sure `debug.ts` calls `registry.connect()` and the app is running in the browser
+
+**If the user just wants a one-shot snapshot** without MCP setup, run this via Bash (requires Chrome launched with `--remote-debugging-port=9222`):
+
+```bash
+npx @oimdb/mcp cdp
+```
+
+## Human Setup
+
+### Standalone DevTools UI (for humans)
+
+```bash
+npx @oimdb/mcp devtools
+```
+
+Opens `http://localhost:7433` automatically. Shows live collections and computeds from the running browser tab. No Chrome extension needed.
+
+```bash
+OIMDB_WS_PORT=7433 OIMDB_UI_PORT=7434 npx @oimdb/mcp devtools   # custom ports
+npx @oimdb/mcp devtools --no-open                                 # don't open browser
+```
+
+### 1. Add MCP config (for AI tools)
+
+Claude Code — `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "oimdb": {
+      "command": "npx",
+      "args": ["-y", "@oimdb/mcp"]
+    }
+  }
+}
+```
+
+Cursor — `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "oimdb": {
+      "command": "npx",
+      "args": ["-y", "@oimdb/mcp"]
+    }
+  }
+}
+```
+
+### 2. Connect the browser
+
+```ts
+// src/debug.ts
+import './store/users.debug';
+import './store/tasks.debug';
+import { registry } from '@oimdb/devtools';
+
+if (typeof window !== 'undefined') {
+    (window as Record<string, unknown>).__OIMDB_DEV__ = registry;
+    registry.connect(); // connects to ws://localhost:7432
+}
+```
+
+### 3. Use from Claude
+
+```
+Call oimdb_inspect to see what's in the store.
+```
+
+## Available MCP Tools
+
+| Tool | Description |
+|---|---|
+| `oimdb_inspect` | Full structured state — all collections, computeds, dep graph |
+| `oimdb_dump` | Human-readable text summary (same as `registry.dump()`) |
+| `oimdb_collection` | Details of one collection by name |
+| `oimdb_computed` | Status + deps of one computed by name |
+
+## CDP Inspector (no browser-side code needed)
+
+Launch Chrome with `--remote-debugging-port=9222`, then:
+
+```bash
+npx @oimdb/mcp cdp
+npx @oimdb/mcp cdp | jq .collections
+OIMDB_CDP_URL=http://localhost:9222 npx @oimdb/mcp cdp
+```
+
+## Port
+
+The MCP bridge WebSocket runs on port `7432` by default. Change it:
+
+```bash
+OIMDB_WS_PORT=7433 npx @oimdb/mcp
+```
+
+Update `registry.connect()` accordingly:
+
+```ts
+registry.connect('ws://localhost:7433');
+```

package/bin/cdp.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+/**
+ * One-shot CDP inspector: connects to Chrome, evaluates __OIMDB_DEV__.inspect(),
+ * prints JSON to stdout. Pipe to jq or paste into an AI prompt.
+ *
+ * Requirements:
+ *   Launch Chrome with: --remote-debugging-port=9222
+ *   (or set CDP_URL env var to point to a different address)
+ *
+ * Usage:
+ *   npx @oimdb/mcp cdp
+ *   OIMDB_CDP_URL=http://localhost:9222 npx @oimdb/mcp cdp
+ *   npx @oimdb/mcp cdp | jq .collections
+ */
+
+const cdpBase = process.env.OIMDB_CDP_URL || 'http://localhost:9222';
+
+async function run() {
+    // 1. List open tabs
+    let tabs;
+    try {
+        const res = await fetch(`${cdpBase}/json/list`);
+        tabs = await res.json();
+    } catch {
+        process.stderr.write(
+            `[OIMDB CDP] Cannot reach Chrome at ${cdpBase}\n` +
+            `Launch Chrome with: --remote-debugging-port=9222\n`
+        );
+        process.exit(1);
+    }
+
+    // Find first tab that has a debugger URL
+    const tab = tabs.find((t) => t.webSocketDebuggerUrl);
+    if (!tab) {
+        process.stderr.write('[OIMDB CDP] No debuggable tabs found.\n');
+        process.exit(1);
+    }
+
+    process.stderr.write(`[OIMDB CDP] Connected to: ${tab.title} (${tab.url})\n`);
+
+    // 2. Open CDP WebSocket
+    const { WebSocket } = await import('ws');
+    const ws = new WebSocket(tab.webSocketDebuggerUrl);
+
+    await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            ws.close();
+            reject(new Error('CDP timeout (5s)'));
+        }, 5000);
+
+        ws.once('open', () => {
+            ws.send(JSON.stringify({
+                id: 1,
+                method: 'Runtime.evaluate',
+                params: {
+                    expression: [
+                        '(function(){',
+                        '  if(!window.__OIMDB_DEV__) return null;',
+                        '  return JSON.parse(JSON.stringify(window.__OIMDB_DEV__.inspect()));',
+                        '})()',
+                    ].join(''),
+                    returnByValue: true,
+                    awaitPromise: false,
+                },
+            }));
+        });
+
+        ws.on('message', (raw) => {
+            const msg = JSON.parse(raw.toString());
+            if (msg.id !== 1) return;
+            clearTimeout(timeout);
+            ws.close();
+
+            const val = msg.result?.result?.value;
+            if (val === null || val === undefined) {
+                process.stderr.write(
+                    '[OIMDB CDP] __OIMDB_DEV__ not found on this page.\n' +
+                    'Make sure debug.ts sets: window.__OIMDB_DEV__ = registry\n'
+                );
+                process.exit(1);
+            }
+            process.stdout.write(JSON.stringify(val, null, 2) + '\n');
+            resolve(undefined);
+        });
+
+        ws.once('error', (err) => {
+            clearTimeout(timeout);
+            reject(err);
+        });
+    });
+}
+
+run().catch((err) => {
+    process.stderr.write('[OIMDB CDP] Error: ' + err.message + '\n');
+    process.exit(1);
+});

package/bin/devtools.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+const path = require('path');
+const { OIMDevUIServer } = require('../dist/index.cjs');
+
+const wsPort = process.env.OIMDB_WS_PORT ? Number(process.env.OIMDB_WS_PORT) : 7432;
+const uiPort = process.env.OIMDB_UI_PORT ? Number(process.env.OIMDB_UI_PORT) : 7433;
+const noOpen = process.argv.includes('--no-open');
+const uiDir  = path.join(__dirname, '../ui');
+
+const server = new OIMDevUIServer({ wsPort, uiPort, uiDir, open: !noOpen });
+server.start();

package/bin/server.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+const { OIMDevMcpServer } = require('../dist/index.cjs');
+
+const wsPort = process.env.OIMDB_WS_PORT ? Number(process.env.OIMDB_WS_PORT) : 7432;
+const server = new OIMDevMcpServer({ wsPort });
+server.start().catch((err) => {
+    process.stderr.write('[OIMDB MCP] Fatal: ' + err.message + '\n');
+    process.exit(1);
+});

package/dist/index.cjs

@@ -0,0 +1,310 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  OIMDevMcpServer: () => OIMDevMcpServer,
+  OIMDevUIServer: () => OIMDevUIServer,
+  createOIMDevMcpServer: () => createOIMDevMcpServer,
+  createOIMDevUIServer: () => createOIMDevUIServer
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/OIMDevMcpServer.ts
+var import_mcp = require("@modelcontextprotocol/sdk/server/mcp.js");
+var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
+var import_ws = require("ws");
+var import_zod = require("zod");
+var OIMDevMcpServer = class {
+  constructor(options = {}) {
+    this.wss = null;
+    this.latestBrowser = null;
+    this.pending = /* @__PURE__ */ new Map();
+    this.wsPort = options.wsPort ?? 7432;
+    this.mcpServer = new import_mcp.McpServer({ name: "oimdb", version: "1.0.0" });
+    this.registerTools();
+  }
+  registerTools() {
+    const server = this.mcpServer;
+    const nameSchema = { name: import_zod.z.string().describe("Registered name") };
+    server.registerTool("oimdb_inspect", {
+      description: "Get full state of all registered OIMDB collections and computeds from the connected browser tab. Returns structured JSON with entity counts, field names, index keys, relations, and computed statuses."
+    }, async () => {
+      const data = await this.queryBrowser("inspect");
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    });
+    server.registerTool("oimdb_dump", {
+      description: "Get a human-readable text summary of OIMDB state. Same output as registry.dump() in the browser."
+    }, async () => {
+      const text = await this.queryBrowser("dump");
+      return { content: [{ type: "text", text }] };
+    });
+    server.registerTool("oimdb_collection", {
+      description: "Get details of a specific registered collection: entity count, field names, index keys, and relations.",
+      inputSchema: nameSchema
+    }, async ({ name }) => {
+      const data = await this.queryBrowser("inspect");
+      const info = data.collections[name];
+      if (!info) {
+        const available = Object.keys(data.collections).join(", ") || "(none registered)";
+        return { content: [{ type: "text", text: `Collection '${name}' not found. Registered: ${available}` }] };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(info, null, 2) }] };
+    });
+    server.registerTool("oimdb_computed", {
+      description: "Get status and resolved dependency names of a specific registered computed value. Shows fresh/stale/pending status, current value, and which registered sources it depends on.",
+      inputSchema: nameSchema
+    }, async ({ name }) => {
+      const data = await this.queryBrowser("inspect");
+      const info = data.computeds[name];
+      if (!info) {
+        const available = Object.keys(data.computeds).join(", ") || "(none registered)";
+        return { content: [{ type: "text", text: `Computed '${name}' not found. Registered: ${available}` }] };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(info, null, 2) }] };
+    });
+  }
+  async queryBrowser(action) {
+    if (!this.latestBrowser) {
+      throw new Error(
+        `No browser tab connected to the OIMDB MCP bridge.
+
+Add to your debug entry point:
+  import { registry } from '@oimdb/devtools';
+  registry.connect(); // connects to ws://localhost:${this.wsPort}
+
+Then reload the page.`
+      );
+    }
+    return new Promise((resolve, reject) => {
+      const id = Math.random().toString(36).slice(2);
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error("Browser response timeout (5s). Is the page active?"));
+      }, 5e3);
+      this.pending.set(id, { resolve, reject, timer });
+      this.latestBrowser.ws.send(JSON.stringify({ type: "request", id, action }));
+    });
+  }
+  setupWebSocketServer() {
+    this.wss = new import_ws.WebSocketServer({ port: this.wsPort });
+    this.wss.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        process.stderr.write(
+          `[OIMDB MCP] Port ${this.wsPort} is already in use.
+Set a different port: OIMDB_WS_PORT=7433 npx @oimdb/mcp
+`
+        );
+        process.exit(1);
+      }
+      process.stderr.write(`[OIMDB MCP] WebSocket server error: ${err.message}
+`);
+      process.exit(1);
+    });
+    this.wss.on("connection", (ws) => {
+      ws.on("message", (raw) => {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === "hello") {
+          this.latestBrowser = { ws, url: msg.url, title: msg.title };
+          process.stderr.write(`[OIMDB MCP] Browser connected: ${msg.title} (${msg.url})
+`);
+          return;
+        }
+        if (msg.type === "response") {
+          const pending = this.pending.get(msg.id);
+          if (!pending) return;
+          this.pending.delete(msg.id);
+          clearTimeout(pending.timer);
+          if (msg.error) {
+            pending.reject(new Error(msg.error));
+          } else {
+            pending.resolve(msg.data);
+          }
+        }
+      });
+      ws.on("close", () => {
+        if (this.latestBrowser?.ws === ws) {
+          this.latestBrowser = null;
+          process.stderr.write("[OIMDB MCP] Browser disconnected\n");
+        }
+      });
+    });
+    process.stderr.write(`[OIMDB MCP] Bridge ready on ws://localhost:${this.wsPort}
+`);
+  }
+  async start() {
+    this.setupWebSocketServer();
+    const transport = new import_stdio.StdioServerTransport();
+    await this.mcpServer.connect(transport);
+  }
+};
+
+// src/core/OIMDevUIServer.ts
+var import_http = require("http");
+var import_fs = require("fs");
+var import_path = require("path");
+var import_child_process = require("child_process");
+var import_ws2 = require("ws");
+var MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8"
+};
+var OIMDevUIServer = class {
+  constructor(options) {
+    this.wss = null;
+    this.latestBrowser = null;
+    this.pending = /* @__PURE__ */ new Map();
+    this.wsPort = options.wsPort ?? 7432;
+    this.uiPort = options.uiPort ?? 7433;
+    this.uiDir = options.uiDir;
+    this.shouldOpen = options.open ?? true;
+  }
+  async queryBrowser(action) {
+    if (!this.latestBrowser) return null;
+    return new Promise((resolve, reject) => {
+      const id = Math.random().toString(36).slice(2);
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error("timeout"));
+      }, 5e3);
+      this.pending.set(id, { resolve, reject, timer });
+      this.latestBrowser.ws.send(JSON.stringify({ type: "request", id, action }));
+    });
+  }
+  setupBridge() {
+    this.wss = new import_ws2.WebSocketServer({ port: this.wsPort });
+    this.wss.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        process.stderr.write(
+          `[OIMDB DevTools] Port ${this.wsPort} is already in use.
+Set a different port: OIMDB_WS_PORT=7433 npx @oimdb/mcp devtools
+`
+        );
+        process.exit(1);
+      }
+      process.stderr.write(`[OIMDB DevTools] Bridge error: ${err.message}
+`);
+      process.exit(1);
+    });
+    this.wss.on("connection", (ws) => {
+      ws.on("message", (raw) => {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === "hello") {
+          this.latestBrowser = { ws, url: msg.url, title: msg.title };
+          process.stderr.write(`[OIMDB DevTools] Browser connected: ${msg.title} (${msg.url})
+`);
+          return;
+        }
+        if (msg.type === "response") {
+          const req = this.pending.get(msg.id);
+          if (!req) return;
+          this.pending.delete(msg.id);
+          clearTimeout(req.timer);
+          if (msg.error) req.reject(new Error(msg.error));
+          else req.resolve(msg.data);
+        }
+      });
+      ws.on("close", () => {
+        if (this.latestBrowser?.ws === ws) {
+          this.latestBrowser = null;
+          process.stderr.write("[OIMDB DevTools] Browser disconnected\n");
+        }
+      });
+    });
+    process.stderr.write(`[OIMDB DevTools] Bridge on ws://localhost:${this.wsPort}
+`);
+  }
+  setupHTTP() {
+    const server = (0, import_http.createServer)((req, res) => {
+      const url = req.url ?? "/";
+      res.setHeader("Access-Control-Allow-Origin", "*");
+      if (url === "/api/inspect") {
+        this.queryBrowser("inspect").then((data) => {
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({
+            connected: !!this.latestBrowser,
+            tab: this.latestBrowser ? { url: this.latestBrowser.url, title: this.latestBrowser.title } : null,
+            data
+          }));
+        }).catch(() => {
+          res.writeHead(200, { "Content-Type": "application/json" });
+          res.end(JSON.stringify({ connected: false, tab: null, data: null }));
+        });
+        return;
+      }
+      const filePath = (0, import_path.join)(this.uiDir, url === "/" ? "index.html" : url);
+      try {
+        const content = (0, import_fs.readFileSync)(filePath);
+        res.writeHead(200, { "Content-Type": MIME[(0, import_path.extname)(filePath)] ?? "text/plain" });
+        res.end(content);
+      } catch {
+        res.writeHead(404);
+        res.end("Not found");
+      }
+    });
+    server.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        process.stderr.write(
+          `[OIMDB DevTools] UI port ${this.uiPort} is already in use.
+Set a different port: OIMDB_UI_PORT=7434 npx @oimdb/mcp devtools
+`
+        );
+        process.exit(1);
+      }
+    });
+    server.listen(this.uiPort, () => {
+      const uiUrl = `http://localhost:${this.uiPort}`;
+      process.stderr.write(`[OIMDB DevTools] UI ready \u2192 ${uiUrl}
+`);
+      if (this.shouldOpen) this.openURL(uiUrl);
+    });
+  }
+  openURL(url) {
+    const cmd = process.platform === "win32" ? `start "" "${url}"` : process.platform === "darwin" ? `open "${url}"` : `xdg-open "${url}"`;
+    (0, import_child_process.exec)(cmd, (err) => {
+      if (err) process.stderr.write(`[OIMDB DevTools] Could not open browser: ${err.message}
+`);
+    });
+  }
+  start() {
+    this.setupBridge();
+    this.setupHTTP();
+    process.stderr.write(
+      `[OIMDB DevTools] Add to debug.ts: registry.connect();
+`
+    );
+  }
+};
+
+// src/index.ts
+function createOIMDevMcpServer(options) {
+  return new OIMDevMcpServer(options);
+}
+function createOIMDevUIServer(options) {
+  return new OIMDevUIServer(options);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OIMDevMcpServer,
+  OIMDevUIServer,
+  createOIMDevMcpServer,
+  createOIMDevUIServer
+});

package/dist/index.d.cts

@@ -0,0 +1,44 @@
+type TOIMDevMcpOptions = {
+    /** Port for the WebSocket bridge that browser tabs connect to. Default: 7432 */
+    wsPort?: number;
+};
+
+declare class OIMDevMcpServer {
+    private readonly mcpServer;
+    private readonly wsPort;
+    private wss;
+    private latestBrowser;
+    private readonly pending;
+    constructor(options?: TOIMDevMcpOptions);
+    private registerTools;
+    private queryBrowser;
+    private setupWebSocketServer;
+    start(): Promise<void>;
+}
+
+type TOIMDevUIServerOptions = {
+    wsPort?: number;
+    uiPort?: number;
+    uiDir: string;
+    open?: boolean;
+};
+declare class OIMDevUIServer {
+    private readonly wsPort;
+    private readonly uiPort;
+    private readonly uiDir;
+    private readonly shouldOpen;
+    private wss;
+    private latestBrowser;
+    private readonly pending;
+    constructor(options: TOIMDevUIServerOptions);
+    private queryBrowser;
+    private setupBridge;
+    private setupHTTP;
+    private openURL;
+    start(): void;
+}
+
+declare function createOIMDevMcpServer(options?: TOIMDevMcpOptions): OIMDevMcpServer;
+declare function createOIMDevUIServer(options: TOIMDevUIServerOptions): OIMDevUIServer;
+
+export { OIMDevMcpServer, OIMDevUIServer, type TOIMDevMcpOptions, type TOIMDevUIServerOptions, createOIMDevMcpServer, createOIMDevUIServer };

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+type TOIMDevMcpOptions = {
+    /** Port for the WebSocket bridge that browser tabs connect to. Default: 7432 */
+    wsPort?: number;
+};
+
+declare class OIMDevMcpServer {
+    private readonly mcpServer;
+    private readonly wsPort;
+    private wss;
+    private latestBrowser;
+    private readonly pending;
+    constructor(options?: TOIMDevMcpOptions);
+    private registerTools;
+    private queryBrowser;
+    private setupWebSocketServer;
+    start(): Promise<void>;
+}
+
+type TOIMDevUIServerOptions = {
+    wsPort?: number;
+    uiPort?: number;
+    uiDir: string;
+    open?: boolean;
+};
+declare class OIMDevUIServer {
+    private readonly wsPort;
+    private readonly uiPort;
+    private readonly uiDir;
+    private readonly shouldOpen;
+    private wss;
+    private latestBrowser;
+    private readonly pending;
+    constructor(options: TOIMDevUIServerOptions);
+    private queryBrowser;
+    private setupBridge;
+    private setupHTTP;
+    private openURL;
+    start(): void;
+}
+
+declare function createOIMDevMcpServer(options?: TOIMDevMcpOptions): OIMDevMcpServer;
+declare function createOIMDevUIServer(options: TOIMDevUIServerOptions): OIMDevUIServer;
+
+export { OIMDevMcpServer, OIMDevUIServer, type TOIMDevMcpOptions, type TOIMDevUIServerOptions, createOIMDevMcpServer, createOIMDevUIServer };