@oimdb/mcp 1.0.3 → 1.1.0

package/README.md

@@ -108,6 +108,49 @@ Call oimdb_inspect to see what's in the store.
 | `oimdb_collection` | Details of one collection by name |
 | `oimdb_computed` | Status + deps of one computed by name |
 
+## Offline / static mode (no browser)
+
+By default the tools read a **live browser tab**. You can instead point the
+server at an **in-process model** so it answers offline — ideal for "what's the
+data model?" questions without running the app.
+
+**CLI — a model module.** Set `OIMDB_MODEL_MODULE` to a module that builds the
+model in Node and exports a `registry` (or a default export, or a zero-arg
+factory returning one):
+
+```ts
+// oimdb-model.js  (built JS, or run the server under a TS loader)
+import { OIMEventQueue, OIMReactiveCollection } from '@oimdb/core';
+import { OIMDevRegistry } from '@oimdb/devtools';
+
+const queue = new OIMEventQueue();
+const users = new OIMReactiveCollection(queue, { selectPk: u => u.id });
+
+export const registry = new OIMDevRegistry();
+registry.collection('users', users, { indexes: { /* ... */ } });
+```
+
+```bash
+OIMDB_MODEL_MODULE=./oimdb-model.js npx @oimdb/mcp
+```
+
+No WebSocket port is opened in this mode — no browser required.
+
+**Embedded — inject a registry.** When running the server from your own Node
+process, pass the registry directly:
+
+```ts
+import { createOIMDevMcpServer } from '@oimdb/mcp';
+import { registry } from './oimdb-model';
+
+await createOIMDevMcpServer({ registry }).start();
+```
+
+> **Fields offline:** structure (collections, indexes, relations) is available
+> as soon as the model is constructed. Entity **field names** appear only when
+> the model holds at least one sample entity (TypeScript types are erased at
+> runtime) — seed a representative row in the model module if you want them.
+
 ## CDP Inspector (no browser-side code needed)
 
 Launch Chrome with `--remote-debugging-port=9222`, then:

package/bin/server.cjs

@@ -2,7 +2,9 @@
 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 });
+// Offline/static mode: point at a module that builds the model in-process.
+const modelModulePath = process.env.OIMDB_MODEL_MODULE || undefined;
+const server = new OIMDevMcpServer({ wsPort, modelModulePath });
 server.start().catch((err) => {
     process.stderr.write('[OIMDB MCP] Fatal: ' + err.message + '\n');
     process.exit(1);

package/dist/index.cjs

@@ -31,36 +31,86 @@ module.exports = __toCommonJS(index_exports);
 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_node_url = require("url");
+var import_node_path = require("path");
 var import_zod = require("zod");
+async function loadRegistryFromModule(path) {
+  const url = (0, import_node_url.pathToFileURL)((0, import_node_path.resolve)(path)).href;
+  const mod = await import(url);
+  let candidate = mod.registry ?? mod.default ?? mod;
+  if (typeof candidate === "function") {
+    candidate = await candidate();
+  }
+  if (!candidate || typeof candidate.inspect !== "function" || typeof candidate.dumpString !== "function") {
+    throw new Error(
+      `[OIMDB MCP] Module "${path}" must export a registry exposing inspect() and dumpString() (as a "registry" or default export, or a zero-arg factory returning one).`
+    );
+  }
+  return candidate;
+}
 var OIMDevMcpServer = class {
   constructor(options = {}) {
     this.wss = null;
     this.latestBrowser = null;
     this.pending = /* @__PURE__ */ new Map();
+    this.modelModuleLoaded = false;
     this.wsPort = options.wsPort ?? 7432;
-    this.mcpServer = new import_mcp.McpServer({ name: "oimdb", version: "1.0.0" });
+    this.inProcessRegistry = options.registry ?? null;
+    this.modelModulePath = options.modelModulePath;
+    this.mcpServer = new import_mcp.McpServer(
+      { name: "oimdb", version: "1.0.0" },
+      {
+        instructions: "Before using these tools, read the OIMDB API reference so you know how to write correct code: node_modules/@oimdb/core/llms.txt. Then use oimdb_inspect to see the data model (collections, indexes, computeds). The source is either a live browser tab (WebSocket bridge) or an in-process model (when a registry / model module is provided) for offline/static introspection."
+      }
+    );
     this.registerTools();
   }
+  /**
+   * Resolves the in-process registry, loading the model module on first use.
+   * Returns null when no in-process source is configured (browser-bridge mode).
+   */
+  async getInProcessRegistry() {
+    if (this.inProcessRegistry) return this.inProcessRegistry;
+    if (this.modelModulePath && !this.modelModuleLoaded) {
+      this.modelModuleLoaded = true;
+      this.inProcessRegistry = await loadRegistryFromModule(
+        this.modelModulePath
+      );
+    }
+    return this.inProcessRegistry;
+  }
+  /** Reads the inspect snapshot from the in-process model or the browser. */
+  async readInspect() {
+    const registry = await this.getInProcessRegistry();
+    if (registry) return registry.inspect();
+    return this.queryBrowser("inspect");
+  }
+  /** Reads the human-readable dump from the in-process model or the browser. */
+  async readDump() {
+    const registry = await this.getInProcessRegistry();
+    if (registry) return registry.dumpString();
+    return await this.queryBrowser("dump");
+  }
   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."
+      description: "Get full state of all registered OIMDB collections and computeds. Returns structured JSON with entity counts, field names, index keys, relations, and computed statuses. Source is the connected browser tab, or an in-process model when one is configured (offline/static \u2014 field names appear only if the model holds sample entities)."
     }, async () => {
-      const data = await this.queryBrowser("inspect");
+      const data = await this.readInspect();
       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."
+      description: "Get a human-readable text summary of OIMDB state. Same output as registry.dump(). Reads the connected browser tab or an in-process model when configured."
     }, async () => {
-      const text = await this.queryBrowser("dump");
+      const text = await this.readDump();
       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 data = await this.readInspect();
       const info = data.collections[name];
       if (!info) {
         const available = Object.keys(data.collections).join(", ") || "(none registered)";
@@ -72,7 +122,7 @@ var OIMDevMcpServer = class {
       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 data = await this.readInspect();
       const info = data.computeds[name];
       if (!info) {
         const available = Object.keys(data.computeds).join(", ") || "(none registered)";
@@ -86,11 +136,14 @@ var OIMDevMcpServer = class {
       throw new Error(
         `No browser tab connected to the OIMDB MCP bridge.
 
-Add to your debug entry point:
+Live mode \u2014 add to your debug entry point:
   import { registry } from '@oimdb/devtools';
   registry.connect(); // connects to ws://localhost:${this.wsPort}
+Then reload the page.
 
-Then reload the page.`
+Offline mode \u2014 point the server at a model module instead:
+  OIMDB_MODEL_MODULE=./path/to/model.js npx @oimdb/mcp
+(the module exports a "registry" with inspect()/dumpString()).`
       );
     }
     return new Promise((resolve, reject) => {
@@ -150,7 +203,14 @@ Set a different port: OIMDB_WS_PORT=7433 npx @oimdb/mcp
 `);
   }
   async start() {
-    this.setupWebSocketServer();
+    const registry = await this.getInProcessRegistry();
+    if (registry) {
+      process.stderr.write(
+        "[OIMDB MCP] In-process model loaded \u2014 serving offline (no browser bridge).\n"
+      );
+    } else {
+      this.setupWebSocketServer();
+    }
     const transport = new import_stdio.StdioServerTransport();
     await this.mcpServer.connect(transport);
   }

package/dist/index.d.cts

@@ -1,6 +1,29 @@
+/**
+ * The readable shape the MCP tools need from a registry — `OIMDevRegistry` from
+ * `@oimdb/devtools` already satisfies it. Declared structurally (following the
+ * existing `IOIMDev*Like` convention) so `@oimdb/mcp` need not depend on
+ * `@oimdb/devtools`; it is not a separate registry implementation.
+ */
+interface IOIMDevRegistryLike {
+    inspect(): unknown;
+    dumpString(): string;
+}
 type TOIMDevMcpOptions = {
     /** Port for the WebSocket bridge that browser tabs connect to. Default: 7432 */
     wsPort?: number;
+    /**
+     * An in-process registry to read directly (your `OIMDevRegistry`). When
+     * provided, the tools answer from it without a browser/WebSocket bridge
+     * (no `wsPort` server started).
+     */
+    registry?: IOIMDevRegistryLike;
+    /**
+     * Path to a module that builds the model in this process for offline
+     * introspection. The module must export a `registry` (or a default export,
+     * or a zero-arg factory) exposing `inspect()` and `dumpString()`.
+     * Also settable via the `OIMDB_MODEL_MODULE` env var for the CLI.
+     */
+    modelModulePath?: string;
 };
 
 declare class OIMDevMcpServer {
@@ -9,7 +32,19 @@ declare class OIMDevMcpServer {
     private wss;
     private latestBrowser;
     private readonly pending;
+    private inProcessRegistry;
+    private readonly modelModulePath?;
+    private modelModuleLoaded;
     constructor(options?: TOIMDevMcpOptions);
+    /**
+     * Resolves the in-process registry, loading the model module on first use.
+     * Returns null when no in-process source is configured (browser-bridge mode).
+     */
+    private getInProcessRegistry;
+    /** Reads the inspect snapshot from the in-process model or the browser. */
+    private readInspect;
+    /** Reads the human-readable dump from the in-process model or the browser. */
+    private readDump;
     private registerTools;
     private queryBrowser;
     private setupWebSocketServer;
@@ -41,4 +76,4 @@ declare class OIMDevUIServer {
 declare function createOIMDevMcpServer(options?: TOIMDevMcpOptions): OIMDevMcpServer;
 declare function createOIMDevUIServer(options: TOIMDevUIServerOptions): OIMDevUIServer;
 
-export { OIMDevMcpServer, OIMDevUIServer, type TOIMDevMcpOptions, type TOIMDevUIServerOptions, createOIMDevMcpServer, createOIMDevUIServer };
+export { type IOIMDevRegistryLike, OIMDevMcpServer, OIMDevUIServer, type TOIMDevMcpOptions, type TOIMDevUIServerOptions, createOIMDevMcpServer, createOIMDevUIServer };

package/dist/index.d.ts

@@ -1,6 +1,29 @@
+/**
+ * The readable shape the MCP tools need from a registry — `OIMDevRegistry` from
+ * `@oimdb/devtools` already satisfies it. Declared structurally (following the
+ * existing `IOIMDev*Like` convention) so `@oimdb/mcp` need not depend on
+ * `@oimdb/devtools`; it is not a separate registry implementation.
+ */
+interface IOIMDevRegistryLike {
+    inspect(): unknown;
+    dumpString(): string;
+}
 type TOIMDevMcpOptions = {
     /** Port for the WebSocket bridge that browser tabs connect to. Default: 7432 */
     wsPort?: number;
+    /**
+     * An in-process registry to read directly (your `OIMDevRegistry`). When
+     * provided, the tools answer from it without a browser/WebSocket bridge
+     * (no `wsPort` server started).
+     */
+    registry?: IOIMDevRegistryLike;
+    /**
+     * Path to a module that builds the model in this process for offline
+     * introspection. The module must export a `registry` (or a default export,
+     * or a zero-arg factory) exposing `inspect()` and `dumpString()`.
+     * Also settable via the `OIMDB_MODEL_MODULE` env var for the CLI.
+     */
+    modelModulePath?: string;
 };
 
 declare class OIMDevMcpServer {
@@ -9,7 +32,19 @@ declare class OIMDevMcpServer {
     private wss;
     private latestBrowser;
     private readonly pending;
+    private inProcessRegistry;
+    private readonly modelModulePath?;
+    private modelModuleLoaded;
     constructor(options?: TOIMDevMcpOptions);
+    /**
+     * Resolves the in-process registry, loading the model module on first use.
+     * Returns null when no in-process source is configured (browser-bridge mode).
+     */
+    private getInProcessRegistry;
+    /** Reads the inspect snapshot from the in-process model or the browser. */
+    private readInspect;
+    /** Reads the human-readable dump from the in-process model or the browser. */
+    private readDump;
     private registerTools;
     private queryBrowser;
     private setupWebSocketServer;
@@ -41,4 +76,4 @@ declare class OIMDevUIServer {
 declare function createOIMDevMcpServer(options?: TOIMDevMcpOptions): OIMDevMcpServer;
 declare function createOIMDevUIServer(options: TOIMDevUIServerOptions): OIMDevUIServer;
 
-export { OIMDevMcpServer, OIMDevUIServer, type TOIMDevMcpOptions, type TOIMDevUIServerOptions, createOIMDevMcpServer, createOIMDevUIServer };
+export { type IOIMDevRegistryLike, OIMDevMcpServer, OIMDevUIServer, type TOIMDevMcpOptions, type TOIMDevUIServerOptions, createOIMDevMcpServer, createOIMDevUIServer };

package/dist/index.js

@@ -2,36 +2,86 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { WebSocketServer } from "ws";
+import { pathToFileURL } from "url";
+import { resolve as resolvePath } from "path";
 import { z } from "zod";
+async function loadRegistryFromModule(path) {
+  const url = pathToFileURL(resolvePath(path)).href;
+  const mod = await import(url);
+  let candidate = mod.registry ?? mod.default ?? mod;
+  if (typeof candidate === "function") {
+    candidate = await candidate();
+  }
+  if (!candidate || typeof candidate.inspect !== "function" || typeof candidate.dumpString !== "function") {
+    throw new Error(
+      `[OIMDB MCP] Module "${path}" must export a registry exposing inspect() and dumpString() (as a "registry" or default export, or a zero-arg factory returning one).`
+    );
+  }
+  return candidate;
+}
 var OIMDevMcpServer = class {
   constructor(options = {}) {
     this.wss = null;
     this.latestBrowser = null;
     this.pending = /* @__PURE__ */ new Map();
+    this.modelModuleLoaded = false;
     this.wsPort = options.wsPort ?? 7432;
-    this.mcpServer = new McpServer({ name: "oimdb", version: "1.0.0" });
+    this.inProcessRegistry = options.registry ?? null;
+    this.modelModulePath = options.modelModulePath;
+    this.mcpServer = new McpServer(
+      { name: "oimdb", version: "1.0.0" },
+      {
+        instructions: "Before using these tools, read the OIMDB API reference so you know how to write correct code: node_modules/@oimdb/core/llms.txt. Then use oimdb_inspect to see the data model (collections, indexes, computeds). The source is either a live browser tab (WebSocket bridge) or an in-process model (when a registry / model module is provided) for offline/static introspection."
+      }
+    );
     this.registerTools();
   }
+  /**
+   * Resolves the in-process registry, loading the model module on first use.
+   * Returns null when no in-process source is configured (browser-bridge mode).
+   */
+  async getInProcessRegistry() {
+    if (this.inProcessRegistry) return this.inProcessRegistry;
+    if (this.modelModulePath && !this.modelModuleLoaded) {
+      this.modelModuleLoaded = true;
+      this.inProcessRegistry = await loadRegistryFromModule(
+        this.modelModulePath
+      );
+    }
+    return this.inProcessRegistry;
+  }
+  /** Reads the inspect snapshot from the in-process model or the browser. */
+  async readInspect() {
+    const registry = await this.getInProcessRegistry();
+    if (registry) return registry.inspect();
+    return this.queryBrowser("inspect");
+  }
+  /** Reads the human-readable dump from the in-process model or the browser. */
+  async readDump() {
+    const registry = await this.getInProcessRegistry();
+    if (registry) return registry.dumpString();
+    return await this.queryBrowser("dump");
+  }
   registerTools() {
     const server = this.mcpServer;
     const nameSchema = { name: 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."
+      description: "Get full state of all registered OIMDB collections and computeds. Returns structured JSON with entity counts, field names, index keys, relations, and computed statuses. Source is the connected browser tab, or an in-process model when one is configured (offline/static \u2014 field names appear only if the model holds sample entities)."
     }, async () => {
-      const data = await this.queryBrowser("inspect");
+      const data = await this.readInspect();
       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."
+      description: "Get a human-readable text summary of OIMDB state. Same output as registry.dump(). Reads the connected browser tab or an in-process model when configured."
     }, async () => {
-      const text = await this.queryBrowser("dump");
+      const text = await this.readDump();
       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 data = await this.readInspect();
       const info = data.collections[name];
       if (!info) {
         const available = Object.keys(data.collections).join(", ") || "(none registered)";
@@ -43,7 +93,7 @@ var OIMDevMcpServer = class {
       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 data = await this.readInspect();
       const info = data.computeds[name];
       if (!info) {
         const available = Object.keys(data.computeds).join(", ") || "(none registered)";
@@ -57,11 +107,14 @@ var OIMDevMcpServer = class {
       throw new Error(
         `No browser tab connected to the OIMDB MCP bridge.
 
-Add to your debug entry point:
+Live mode \u2014 add to your debug entry point:
   import { registry } from '@oimdb/devtools';
   registry.connect(); // connects to ws://localhost:${this.wsPort}
+Then reload the page.
 
-Then reload the page.`
+Offline mode \u2014 point the server at a model module instead:
+  OIMDB_MODEL_MODULE=./path/to/model.js npx @oimdb/mcp
+(the module exports a "registry" with inspect()/dumpString()).`
       );
     }
     return new Promise((resolve, reject) => {
@@ -121,7 +174,14 @@ Set a different port: OIMDB_WS_PORT=7433 npx @oimdb/mcp
 `);
   }
   async start() {
-    this.setupWebSocketServer();
+    const registry = await this.getInProcessRegistry();
+    if (registry) {
+      process.stderr.write(
+        "[OIMDB MCP] In-process model loaded \u2014 serving offline (no browser bridge).\n"
+      );
+    } else {
+      this.setupWebSocketServer();
+    }
     const transport = new StdioServerTransport();
     await this.mcpServer.connect(transport);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oimdb/mcp",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "MCP server and CDP inspector for OIMDB — connects AI assistants to live browser state",
   "type": "module",
   "main": "./dist/index.cjs",