@reddb-io/ui-mcp 0.1.1

package/dist/index.js

@@ -0,0 +1,599 @@
+#!/usr/bin/env node
+import { registerAppResource, registerAppTool, RESOURCE_MIME_TYPE, } from "@modelcontextprotocol/ext-apps/server";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod/v4";
+import { classifyTarget } from "./target-mode.js";
+import { resolveLocalFilePath, spawnLocalServer, stopAllLocalServers, } from "./local-server.js";
+import { startEmbedServer, stopAllEmbedServers, } from "./embed-server.js";
+import { registerDataTools } from "./data-tools.js";
+// Single source of truth for "what version am I": the package.json version
+// (changeset-managed, version-locked with @reddb-io/ui + ui-kit), overridable by
+// the RED_BUILD_VERSION env the release CI sets from the git tag. From the
+// compiled dist/index.js, ../package.json is the package root manifest (shipped
+// because `files` always includes it). Mirrors the ../red-skills build-info
+// pattern; replaces the previously hardcoded "0.1.0".
+function resolveVersion() {
+    const fromEnv = process.env.RED_BUILD_VERSION;
+    if (fromEnv)
+        return fromEnv.replace(/^v/, "");
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+        if (pkg.version)
+            return pkg.version;
+    }
+    catch {
+        // fall through
+    }
+    return "0.0.0-dev";
+}
+const RED_UI_MCP_VERSION = resolveVersion();
+const APP_RESOURCE_URI = "ui://red-ui/app.html";
+const MCP_APPS_CDN = "https://esm.sh/@modelcontextprotocol/ext-apps@1.7.2/app-with-deps";
+const DEFAULT_APP_URL = "https://ui.reddb.io";
+function parseList(value) {
+    if (!value)
+        return [];
+    return value
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function normalizeHttpUrl(value, fallback) {
+    const raw = value?.trim() || fallback;
+    const url = new URL(raw);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`RED_UI_APP_URL must be an http(s) URL, got ${raw}`);
+    }
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+}
+function getOrigin(url) {
+    return new URL(url).origin;
+}
+// Local mode (#51, ADR-0006) serves the embeddable bundle from an ephemeral
+// `http://127.0.0.1:<port>` the MCP picks at runtime, so the CSP cannot name the
+// exact origin ahead of time. Allow loopback on any port for framing, scripts,
+// and connections; the hosted origin stays explicit. Port-wildcard host-sources
+// are valid CSP (`http://127.0.0.1:*`).
+const LOCALHOST_CSP = ["http://localhost:*", "http://127.0.0.1:*"];
+function appCsp(config) {
+    const appOrigin = getOrigin(config.appUrl);
+    return {
+        connectDomains: [...config.connectDomains, ...LOCALHOST_CSP],
+        frameDomains: [appOrigin, ...LOCALHOST_CSP],
+        resourceDomains: [appOrigin, "https://esm.sh", ...LOCALHOST_CSP],
+    };
+}
+function loadConfig() {
+    const appUrl = normalizeHttpUrl(process.env.RED_UI_APP_URL, DEFAULT_APP_URL);
+    const defaultConnectDomains = [
+        getOrigin(appUrl),
+        "http://localhost:5055",
+        "http://127.0.0.1:5055",
+        "http://localhost:15055",
+        "http://127.0.0.1:15055",
+        "http://localhost:25055",
+        "http://127.0.0.1:25055",
+    ];
+    // Auth for the server-side data tools: a bearer token (RED_UI_CONNECTION_TOKEN)
+    // or a raw Authorization header (RED_UI_CONNECTION_AUTH). Read from env only —
+    // never echoed into tool output or logs.
+    const token = process.env.RED_UI_CONNECTION_TOKEN?.trim();
+    const rawAuth = process.env.RED_UI_CONNECTION_AUTH?.trim();
+    const connectionAuthHeader = rawAuth || (token ? `Bearer ${token}` : undefined);
+    return {
+        appUrl,
+        connectDomains: [
+            ...new Set([
+                ...defaultConnectDomains,
+                ...parseList(process.env.RED_UI_CONNECT_DOMAINS),
+            ]),
+        ],
+        connectionUrl: process.env.RED_UI_CONNECTION_URL?.trim() || undefined,
+        connectionAuthHeader,
+    };
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+function jsonForInlineScript(value) {
+    return JSON.stringify(value).replaceAll("<", "\\u003c");
+}
+function renderRedUiAppHtml(config) {
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>red-ui</title>
+    <style>
+      :root {
+        color-scheme: light dark;
+        font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+        background: #101214;
+        color: #f5f7f8;
+      }
+      * { box-sizing: border-box; }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        background: #101214;
+      }
+      .shell {
+        display: grid;
+        grid-template-rows: auto 1fr;
+        min-height: 100vh;
+      }
+      header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 16px;
+        padding: 10px 12px;
+        border-bottom: 1px solid rgba(255, 255, 255, 0.1);
+        background: #171a1d;
+      }
+      .brand {
+        display: flex;
+        align-items: center;
+        gap: 10px;
+        min-width: 0;
+      }
+      .mark {
+        display: grid;
+        place-items: center;
+        width: 28px;
+        height: 28px;
+        border: 1px solid rgba(255, 255, 255, 0.18);
+        border-radius: 6px;
+        color: #ff5a4d;
+        font-weight: 720;
+      }
+      .title {
+        display: grid;
+        gap: 1px;
+        min-width: 0;
+      }
+      .title strong {
+        font-size: 14px;
+        font-weight: 680;
+      }
+      .title span {
+        overflow: hidden;
+        max-width: min(60vw, 720px);
+        color: #a9b0b6;
+        font-family: "JetBrains Mono", ui-monospace, SFMono-Regular, monospace;
+        font-size: 11px;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+      .actions {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        flex: 0 0 auto;
+      }
+      button, a.button {
+        appearance: none;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        min-height: 30px;
+        padding: 0 10px;
+        border: 1px solid rgba(255, 255, 255, 0.14);
+        border-radius: 6px;
+        background: #22272b;
+        color: #f5f7f8;
+        font: inherit;
+        font-size: 12px;
+        text-decoration: none;
+        cursor: pointer;
+      }
+      button:hover, a.button:hover {
+        background: #2a3035;
+      }
+      main {
+        min-height: 0;
+        background: #0d0f11;
+      }
+      iframe {
+        display: block;
+        width: 100%;
+        height: 100%;
+        min-height: 620px;
+        border: 0;
+        background: white;
+      }
+      .empty {
+        display: none;
+        padding: 28px;
+        color: #c7cdd2;
+      }
+      .empty code {
+        padding: 2px 5px;
+        border-radius: 4px;
+        background: rgba(255, 255, 255, 0.08);
+        color: #fff;
+      }
+      body[data-error="true"] iframe { display: none; }
+      body[data-error="true"] .empty { display: block; }
+      @media (max-width: 720px) {
+        header {
+          align-items: stretch;
+          flex-direction: column;
+        }
+        .actions {
+          justify-content: flex-end;
+        }
+        .title span {
+          max-width: 100%;
+        }
+      }
+    </style>
+  </head>
+  <body>
+    <div class="shell">
+      <header>
+        <div class="brand">
+          <div class="mark">r</div>
+          <div class="title">
+            <strong>red-ui MCP App</strong>
+            <span id="target">${escapeHtml(config.appUrl)}</span>
+          </div>
+        </div>
+        <div class="actions">
+          <button id="fullscreen" type="button">Fullscreen</button>
+          <button id="open" type="button">Open</button>
+        </div>
+      </header>
+      <main>
+        <iframe id="red-ui-frame" title="red-ui"></iframe>
+        <section class="empty">
+          <h1>red-ui is not reachable</h1>
+          <p>Start the web app with <code>pnpm dev</code>, or set <code>RED_UI_APP_URL</code> before starting this MCP server.</p>
+        </section>
+      </main>
+    </div>
+    <script type="module">
+      const DEFAULT_APP_URL = ${jsonForInlineScript(config.appUrl)};
+      const MCP_APPS_CDN = ${jsonForInlineScript(MCP_APPS_CDN)};
+      const frame = document.getElementById('red-ui-frame');
+      const target = document.getElementById('target');
+      const openButton = document.getElementById('open');
+      const fullscreenButton = document.getElementById('fullscreen');
+      const state = {
+        appUrl: DEFAULT_APP_URL,
+        view: 'query',
+        connectionUrl: ''
+      };
+
+      let app;
+
+      function applyPatch(patch) {
+        if (!patch || typeof patch !== 'object') return;
+        if (typeof patch.appUrl === 'string' && patch.appUrl) state.appUrl = patch.appUrl;
+        if (typeof patch.view === 'string') state.view = patch.view;
+        if (typeof patch.connectionUrl === 'string') state.connectionUrl = patch.connectionUrl;
+        render();
+      }
+
+      function buildFrameUrl() {
+        const url = new URL(state.appUrl || DEFAULT_APP_URL);
+        url.searchParams.set('mcp', '1');
+        // Open Contract pre-configuration: seed non-secret endpoint + route.
+        // Never seed a token here — secrets are reserved for a later
+        // postMessage channel.
+        if (state.connectionUrl) url.searchParams.set('cs', state.connectionUrl);
+        if (state.view) url.searchParams.set('to', '/' + state.view.replace(/^\\//, ''));
+        return url.toString();
+      }
+
+      function render() {
+        const nextUrl = buildFrameUrl();
+        target.textContent = nextUrl;
+        openButton.dataset.url = nextUrl;
+        if (frame.src !== nextUrl) frame.src = nextUrl;
+      }
+
+      openButton.addEventListener('click', async () => {
+        const url = openButton.dataset.url || buildFrameUrl();
+        if (app?.openLink) {
+          await app.openLink({ url }).catch(() => window.open(url, '_blank', 'noopener,noreferrer'));
+          return;
+        }
+        window.open(url, '_blank', 'noopener,noreferrer');
+      });
+
+      fullscreenButton.addEventListener('click', async () => {
+        if (app?.requestDisplayMode) {
+          await app.requestDisplayMode({ mode: 'fullscreen' }).catch(() => {});
+        }
+      });
+
+      frame.addEventListener('error', () => {
+        document.body.dataset.error = 'true';
+      });
+
+      render();
+
+      try {
+        const { App } = await import(MCP_APPS_CDN);
+        app = new App(
+          { name: 'red-ui', version: ${JSON.stringify(RED_UI_MCP_VERSION)} },
+          {},
+          { autoResize: true }
+        );
+        app.ontoolinput = (params) => applyPatch(params.arguments);
+        app.ontoolresult = (params) => applyPatch(params.structuredContent);
+        await app.connect();
+      } catch (error) {
+        console.warn('MCP Apps bridge unavailable; rendering red-ui with static defaults.', error);
+      }
+    </script>
+  </body>
+</html>`;
+}
+function createServer(config) {
+    const server = new McpServer({
+        name: "red-ui",
+        version: RED_UI_MCP_VERSION,
+    });
+    // One `red server` per local file (its flock is single-writer — ADR-0006).
+    // Keyed by the resolved absolute path so a repeated open reuses the child.
+    const localServers = new Map();
+    async function openLocalServer(target) {
+        const key = resolveLocalFilePath(target);
+        const existing = localServers.get(key);
+        if (existing) {
+            try {
+                const handle = await existing;
+                if (handle.child.exitCode === null &&
+                    handle.child.signalCode === null) {
+                    return handle;
+                }
+            }
+            catch {
+                // Previous attempt failed; fall through and respawn.
+            }
+        }
+        const pending = spawnLocalServer({ target });
+        localServers.set(key, pending);
+        try {
+            return await pending;
+        }
+        catch (error) {
+            localServers.delete(key);
+            throw error;
+        }
+    }
+    // One embed server per MCP process serves the Embeddable Lib bundle (#37) over
+    // `http://127.0.0.1:<port>` for local mode (#51, ADR-0006). The bundle is the
+    // same regardless of which file is open, so it is a singleton; it is torn down
+    // with the local servers on disconnect/exit.
+    let embedServer = null;
+    async function openEmbedServer() {
+        if (embedServer) {
+            try {
+                const handle = await embedServer;
+                if (handle.server.listening)
+                    return handle;
+            }
+            catch {
+                // Previous attempt failed; fall through and respawn.
+            }
+        }
+        const pending = startEmbedServer();
+        embedServer = pending;
+        try {
+            return await pending;
+        }
+        catch (error) {
+            embedServer = null;
+            throw error;
+        }
+    }
+    registerAppResource(server, "red-ui app", APP_RESOURCE_URI, {
+        description: "Interactive red-ui database workspace embedded as an MCP App.",
+        _meta: {
+            ui: {
+                csp: appCsp(config),
+                prefersBorder: false,
+            },
+        },
+    }, async () => ({
+        contents: [
+            {
+                uri: APP_RESOURCE_URI,
+                mimeType: RESOURCE_MIME_TYPE,
+                text: renderRedUiAppHtml(config),
+                _meta: {
+                    ui: {
+                        csp: appCsp(config),
+                        prefersBorder: false,
+                    },
+                },
+            },
+        ],
+    }));
+    registerAppTool(server, "open_red_ui", {
+        title: "Open red-ui",
+        description: "Display the red-ui database workspace as an embedded MCP App.",
+        inputSchema: {
+            connectionUrl: z
+                .string()
+                .optional()
+                .describe("Optional red/http connection URL to preselect in red-ui, for example http://localhost:5055."),
+            view: z
+                .enum(["home", "query", "collections", "cluster", "security"])
+                .optional()
+                .describe("Initial red-ui view to display. Defaults to query."),
+        },
+        _meta: {
+            ui: {
+                resourceUri: APP_RESOURCE_URI,
+                visibility: ["model", "app"],
+            },
+        },
+    }, async ({ connectionUrl, view }) => {
+        const selectedView = view ?? "query";
+        const mode = classifyTarget(connectionUrl);
+        // Local-file targets (#48, ADR-0006): the browser Surface cannot reach a
+        // filesystem path, so the MCP process spawns one `red server` that owns
+        // the file, health-checks it via `/stats`, and points the UI at the
+        // ephemeral `http://127.0.0.1:<port>` it exposes. The child is torn down
+        // on MCP exit/disconnect.
+        if (mode === "local") {
+            const target = connectionUrl ?? "";
+            try {
+                const local = await openLocalServer(target);
+                const readOnlyNote = local.readOnly
+                    ? " (read-only: the file is already held by another writer)"
+                    : "";
+                // Serve the UI same-origin over http://localhost so the iframe and
+                // the spawned red server share an http:// scheme — no HTTPS→localhost
+                // mixed-content block (Firefox/Safari), fully offline (#51, ADR-0006).
+                // If the embeddable bundle can't be found we still hand back a working
+                // local API, falling back to the hosted UI with a note.
+                let uiUrl = config.appUrl;
+                let uiNote = "";
+                try {
+                    const embed = await openEmbedServer();
+                    uiUrl = embed.baseUrl;
+                }
+                catch (embedError) {
+                    const detail = embedError instanceof Error
+                        ? embedError.message
+                        : String(embedError);
+                    uiNote = ` (local UI bundle unavailable, falling back to ${config.appUrl}: ${detail})`;
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Serving local file ${local.filePath} via a red server at ${local.baseUrl}${readOnlyNote}; opening red-ui ${selectedView} view from ${uiUrl}.${uiNote}`,
+                        },
+                    ],
+                    structuredContent: {
+                        appUrl: uiUrl,
+                        connectionUrl: local.baseUrl,
+                        view: selectedView,
+                        mode,
+                        localServer: {
+                            filePath: local.filePath,
+                            port: local.port,
+                            readOnly: local.readOnly,
+                        },
+                    },
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Could not open the local file "${target}": ${message}`,
+                        },
+                    ],
+                    isError: true,
+                    structuredContent: {
+                        appUrl: config.appUrl,
+                        connectionUrl: "",
+                        view: selectedView,
+                        mode,
+                    },
+                };
+            }
+        }
+        // Remote target: hand the URL to the browser via the Open Contract; no
+        // process is spawned.
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Opening red-ui ${selectedView} view from ${config.appUrl}.`,
+                },
+            ],
+            structuredContent: {
+                appUrl: config.appUrl,
+                connectionUrl: connectionUrl ?? "",
+                view: selectedView,
+                mode,
+            },
+        };
+    });
+    // Server-side data tools (#49, ADR-0006): run a RedClient in this process and
+    // return reddb reads to the model as structuredContent, without driving the
+    // visual iframe. Honour the configured default connection + auth (env-only).
+    registerDataTools(server, {
+        defaultUrl: config.connectionUrl,
+        authHeader: config.connectionAuthHeader,
+    });
+    return server;
+}
+function printHelp() {
+    process.stdout.write(`red-ui MCP server
+
+Usage:
+  ui-mcp --stdio
+
+Environment:
+  RED_UI_APP_URL             URL of the hosted or running red-ui web app. Default: ${DEFAULT_APP_URL}
+  RED_UI_CONNECT_DOMAINS     Comma-separated extra connect-src domains for the embedded app.
+  RED_BINARY                 Path to the reddb \`red\` binary used to serve local .rdb files.
+                             Defaults to the @reddb-io/sdk binary, else \`red\` on PATH.
+  RED_UI_EMBED_DIR           Directory holding the embeddable bundle (\`index.js\`) served over
+                             http://localhost in local mode. Defaults to the installed @reddb-io/ui.
+  RED_UI_CONNECTION_URL      Default reddb endpoint for the data tools (query/list/get), e.g. http://localhost:5055.
+  RED_UI_CONNECTION_TOKEN    Bearer token for the data tools' RedClient (sent as Authorization: Bearer …; never logged).
+  RED_UI_CONNECTION_AUTH     Raw Authorization header for the data tools (overrides RED_UI_CONNECTION_TOKEN).
+
+Example client config:
+  {
+    "mcpServers": {
+      "red-ui": {
+        "command": "npx",
+        "args": ["-y", "@reddb-io/ui@latest", "mcp", "--stdio"],
+        "env": { "RED_UI_APP_URL": "${DEFAULT_APP_URL}" }
+      }
+    }
+  }
+`);
+}
+async function main() {
+    const args = new Set(process.argv.slice(2));
+    if (args.has("--help") || args.has("-h")) {
+        printHelp();
+        return;
+    }
+    if (!args.has("--stdio")) {
+        throw new Error("Only --stdio transport is supported for now.");
+    }
+    const server = createServer(loadConfig());
+    const transport = new StdioServerTransport();
+    // Tear down any spawned local `red server` children when the MCP client
+    // disconnects (stdin closes) — no orphan servers (ADR-0006). The process
+    // exit hooks in local-server.ts are the synchronous backstop.
+    const previousOnClose = transport.onclose?.bind(transport);
+    transport.onclose = () => {
+        previousOnClose?.();
+        void stopAllLocalServers();
+        void stopAllEmbedServers();
+    };
+    await server.connect(transport);
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.stack : String(error)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/local-server.d.ts

@@ -0,0 +1,62 @@
+import { type ChildProcess } from "node:child_process";
+export interface RedBinary {
+    binaryPath: string;
+    /** Where we found it: an SDK package name, "path", or "env". */
+    source: string;
+}
+export interface LocalServerHandle {
+    baseUrl: string;
+    port: number;
+    filePath: string;
+    readOnly: boolean;
+    child: ChildProcess;
+    /** Idempotent teardown — SIGTERM then SIGKILL, resolves once the child exits. */
+    stop(): Promise<void>;
+}
+export interface SpawnLocalServerOptions {
+    /** Connection target as received by the tool (path / file:// / ~/… / *.rdb). */
+    target: string;
+    readOnly?: boolean;
+    /** Override binary resolution (tests, explicit config). */
+    binaryPath?: string;
+    /** Override the ephemeral port (tests). */
+    port?: number;
+    /** Max time to wait for `/stats` to report healthy. Default 10s. */
+    healthTimeoutMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Resolve a fuzzy local target into an absolute filesystem path the `red`
+ * binary can `--path`. Handles `file://` URLs, `~`/`~/…` home expansion, and
+ * relative paths (resolved against the MCP process cwd).
+ */
+export declare function resolveLocalFilePath(target: string): string;
+/**
+ * Resolve the `red` binary: explicit `RED_BINARY` env → `@reddb-io/sdk`'s
+ * subprocess binary (or `reddb-cli`'s) → a PATH `red`. Throws an actionable
+ * error when none is found.
+ */
+export declare function resolveRedBinary(): Promise<RedBinary>;
+/**
+ * Raised when `red server` dies trying to acquire the single-writer `flock` on
+ * the target — the signal to retry the open with `--read-only` (#50).
+ */
+export declare class LockContentionError extends Error {
+    readonly detail: string;
+    constructor(detail: string);
+}
+/** True when `text` (a `red server` stderr) looks like single-writer lock
+ *  contention — used to decide whether to retry the open as `--read-only`. */
+export declare function looksLikeLockContention(text: string): boolean;
+/**
+ * Spawn one `red server` that owns `target`, wait for `/stats` to report
+ * healthy, and return a handle whose `stop()` tears the child down.
+ *
+ * Open mode (#50): an explicit `readOnly` is honoured verbatim. When it is
+ * unspecified, the file opens read-write but transparently falls back to
+ * `--read-only` if reddb dies acquiring the single-writer `flock` — the trigger
+ * case being a second viewer of a live agent memory `.rdb` (ADR-0006).
+ */
+export declare function spawnLocalServer(options: SpawnLocalServerOptions): Promise<LocalServerHandle>;
+/** Stop every tracked local server (MCP transport close / shutdown). */
+export declare function stopAllLocalServers(): Promise<void>;