@modootoday/datalab-extension-mcp 1.2.5

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+
+/**
+ * The thin stdio adapter — a stdio↔daemon proxy that owns nothing.
+ *
+ * An MCP host spawns this bin; it speaks MCP over stdio to that host and
+ * forwards the two methods it supports (`tools/list`, `tools/call`) to the
+ * background daemon over loopback HTTP. It binds no port and holds no bridge:
+ * the daemon owns 127.0.0.1:8765 and the panel connection, and many adapters
+ * (one per host) share that single daemon. This is why the earlier
+ * one-server-per-host model was replaced — every host raced for the same port
+ * and only one survived.
+ *
+ * Everything with an edge (the readiness probe, the child spawn, the HTTP
+ * fetch) is injectable, so the whole proxy is unit-testable with neither a real
+ * socket nor a real daemon.
+ */
+
+/** The `fetch` shape this module needs — injectable so tests need no real HTTP. */
+type FetchImpl = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    /** Cancels the request once its ceiling passes. Tests may ignore it. */
+    signal?: AbortSignal;
+}) => Promise<{
+    text: () => Promise<string>;
+}>;
+interface EnsureRunningDeps {
+    host?: string;
+    port?: number;
+    /** Probe for an existing daemon. Injected in tests; defaults to `tryConnect`. */
+    connect?: (host: string, port: number, timeoutMs: number) => Promise<{
+        destroy: () => void;
+    } | null>;
+    /** Start the daemon. Injected in tests; defaults to `spawnDaemon`. */
+    spawn?: (daemonEntry: string, args: string[]) => void;
+    /** Injected sleep so the ready-poll never waits real milliseconds in tests. */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Absolute path the spawner runs. Defaults to this bin (`process.argv[1]`):
+     * running THIS file with the `serve` subcommand starts the inlined daemon.
+     */
+    daemonEntry?: string;
+    log?: (message: string) => void;
+    attempts?: number;
+    intervalMs?: number;
+    /**
+     * This adapter's own version. When set, a running daemon OLDER than this is
+     * replaced (it is a stale one still holding the port after an update); a daemon
+     * at this version or newer is left alone, so an older adapter never downgrades
+     * a newer daemon. Unset ⇒ no reconciliation (the daemon is used as-is).
+     */
+    selfVersion?: string;
+    /** Pairing token authorising the shutdown. Defaults to `DATALAB_MCP_TOKEN`. */
+    token?: string;
+    /** Injected in tests; defaults to reading `/bridge/health`. */
+    readVersion?: (base: string) => Promise<string | null>;
+    /** Injected in tests; defaults to `POST /mcp/shutdown`. */
+    shutdown?: (base: string, token: string) => Promise<boolean>;
+}
+/**
+ * Ensure a daemon is up before the adapter starts proxying.
+ *
+ * Fast path first: if a daemon already owns the port, we are done — we only
+ * needed to know it exists, so the probe socket is closed immediately and the
+ * real calls go over HTTP. Otherwise spawn THIS bin as `serve` (which runs the
+ * inlined daemon) and poll until it answers. Racing is fine: whichever daemon
+ * binds first wins and the losers exit 0 on EADDRINUSE.
+ *
+ * If it never comes up inside the budget we log and return rather than throw —
+ * the panel-status card will show disconnected, which is a far better outcome
+ * than crashing the host's whole MCP session over a daemon that is slow to boot.
+ */
+declare function ensureDaemonRunning(deps?: EnsureRunningDeps): Promise<void>;
+interface AdapterServerDeps {
+    host?: string;
+    port?: number;
+    /** Injected in tests; defaults to the global `fetch`. */
+    fetchImpl?: FetchImpl;
+    log?: (message: string) => void;
+    /** MCP handshake identity reported to the host. */
+    name?: string;
+    version?: string;
+}
+/**
+ * Build the low-level MCP `Server` whose two handlers proxy to the daemon.
+ *
+ * The low-level `Server` (not `McpServer`) is the honest fit: we own no tools
+ * and declare no static schema — the catalog is discovered at runtime from the
+ * daemon and changes while running. The request-handler form matches that, and
+ * it is the same shape the daemon it replaced used, so the host sees no
+ * difference across the swap.
+ */
+declare function createAdapterServer(deps?: AdapterServerDeps): Server;
+/**
+ * Read the daemon's `/mcp/notifications` SSE stream, calling `onEvent` with each
+ * `data:` payload. Injectable so the subscription loop is testable without a
+ * real stream. Heartbeat comments (`: hb`) are not data lines, so they are
+ * skipped here and never reach `onEvent`.
+ */
+type SubscribeImpl = (url: string, onEvent: (data: string) => void, signal: AbortSignal) => Promise<void>;
+interface RunAdapterDeps extends AdapterServerDeps {
+    /** Injected in tests; defaults to `ensureDaemonRunning`. */
+    ensure?: (deps: EnsureRunningDeps) => Promise<void>;
+    /** Injected in tests; defaults to a real stdio transport. */
+    transport?: Transport;
+    /** Injected in tests; defaults to the real SSE subscription. */
+    subscribe?: SubscribeImpl;
+}
+/**
+ * Run the adapter: make sure a daemon exists, then serve MCP over stdio.
+ *
+ * The two legs are separate on purpose — `ensureDaemonRunning` deals with the
+ * socket/spawn edges and `createAdapterServer` with the request handlers — so
+ * each is testable alone. This function is the only place that touches the real
+ * stdio transport, which is why it stays a thin composition.
+ */
+declare function runAdapter(deps?: RunAdapterDeps): Promise<void>;
+interface CliHandlers {
+    install: (sub: "install" | "uninstall", argv: readonly string[]) => Promise<void>;
+    serve: () => void;
+    adapter: () => Promise<void>;
+}
+/**
+ * Route the process argv to one of the three subcommand handlers.
+ *
+ * Extracted from `main()` so the routing decision is testable with injected
+ * handlers, without spawning a daemon or connecting a transport. The default
+ * (no recognised subcommand) is the adapter, which is what an MCP host spawns.
+ */
+declare function dispatchCli(argv: readonly string[], handlers: CliHandlers): Promise<void>;
+
+export { type AdapterServerDeps, type CliHandlers, type EnsureRunningDeps, type FetchImpl, type RunAdapterDeps, createAdapterServer, dispatchCli, ensureDaemonRunning, runAdapter };

package/dist/index.js

@@ -0,0 +1,13 @@
+import {
+  createAdapterServer,
+  dispatchCli,
+  ensureDaemonRunning,
+  runAdapter
+} from "./chunk-BF4AMIXC.js";
+import "./chunk-MLKGABMK.js";
+export {
+  createAdapterServer,
+  dispatchCli,
+  ensureDaemonRunning,
+  runAdapter
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@modootoday/datalab-extension-mcp",
+  "version": "1.2.5",
+  "private": false,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "datalab-extension-mcp": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modootoday/datalab-extension-mcp.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://github.com/modootoday/datalab-extension-mcp#readme",
+  "license": "MIT",
+  "description": "Local MCP server that exposes the DataLab Tools browser extension's tools to an MCP host. Read-only lookups run without a prompt; anything that edits a document or costs money is gated by the extension and confirmed by you first. Holds no credentials; every call runs inside your own browser session.",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "chrome-extension",
+    "naver"
+  ]
+}