@mermalaid/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+Plain-English summary: You can share and adapt this noncommercially as long as you give credit and share changes under CC BY-NC-SA.
+Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0)
+
+Copyright © 2025–present Dario Novoa (highvoltag3)
+
+This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
+
+You are free to:
+- Share — copy and redistribute the material in any medium or format
+- Adapt — remix, transform, and build upon the material
+
+Under the following terms:
+- Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made.
+- NonCommercial — You may not use the material for commercial purposes.
+- ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license.
+
+Full license text available at:
+https://creativecommons.org/licenses/by-nc-sa/4.0/

package/README.md

@@ -0,0 +1,69 @@
+# @mermalaid/mcp
+
+A local [MCP](https://modelcontextprotocol.io) server that bridges an AI agent to a **live
+Mermalaid editor**. The agent can read the current diagram, replace it (changes appear instantly
+in the user's editor), validate syntax, and render the diagram to an image it can see.
+
+It speaks MCP to the agent over **stdio**, and hosts a **loopback WebSocket** (`127.0.0.1:7337`)
+that the Mermalaid editor connects to. Nothing leaves the machine.
+
+Full guide (install, pairing, tools, security):
+[docs/AGENT_INTEGRATION.md](https://github.com/highvoltag3/mermalaid/blob/main/docs/AGENT_INTEGRATION.md).
+
+## Install / register with an agent
+
+```bash
+claude mcp add mermalaid -- npx -y @mermalaid/mcp
+```
+
+Claude Desktop / Cursor: `"command": "npx", "args": ["-y", "@mermalaid/mcp"]` (see the guide for the full JSON).
+
+The server prints the pairing code and bridge URL to stderr on startup. The agent can also fetch
+them with the `get_pairing_code` tool.
+
+## Develop from this repo
+
+```bash
+npm install
+npm run build      # compiles to dist/
+npm run dev        # tsc --watch
+npm test
+npm run typecheck
+```
+
+Or from the repo root: `npm run mcp:build`.
+
+To point an agent at a local build instead of the published package:
+
+```bash
+claude mcp add mermalaid -- node /absolute/path/to/mermalaid/mcp/dist/index.js
+```
+
+## Tools
+
+`get_connection_status`, `get_pairing_code`, `wait_for_editor`, `get_diagram`, `set_diagram`,
+`append_to_diagram`, `validate_diagram`, `render_diagram`, `get_syntax_reference`.
+
+## Resource
+
+`mermalaid://diagram/current` (`text/vnd.mermaid`) — the live diagram, readable and subscribable
+(`resources/updated` fires on every change).
+
+## Configuration
+
+| Setting | Flag | Env | Default |
+|---|---|---|---|
+| Port | `--port <n>` | `MERMALAID_BRIDGE_PORT` | `7337` (scans → `7340`) |
+| Host | `--host <h>` | `MERMALAID_BRIDGE_HOST` | `127.0.0.1` |
+| Extra origins | `--origins <csv>` | `MERMALAID_BRIDGE_ORIGINS` | (none) |
+| Allow localhost dev origins | `--dev` | `MERMALAID_BRIDGE_DEV` | off |
+
+## Security model
+
+Loopback bind + a fresh per-session pairing code (required before any tool touches the diagram) +
+an Origin allowlist on the WebSocket handshake. Designed for a single local user. See the guide
+for details.
+
+## License
+
+CC-BY-NC-SA-4.0, same as Mermalaid.

package/dist/config.js

@@ -0,0 +1,45 @@
+import { BRIDGE_PORT_FALLBACKS, DEFAULT_BRIDGE_HOST, DEFAULT_HEARTBEAT_INTERVAL_MS, } from './protocol.js';
+function parsePositiveInt(value) {
+    if (!value)
+        return undefined;
+    const n = Number.parseInt(value, 10);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+function readFlag(argv, flag) {
+    const i = argv.indexOf(flag);
+    if (i !== -1 && i + 1 < argv.length)
+        return argv[i + 1];
+    const withEq = argv.find((a) => a.startsWith(`${flag}=`));
+    return withEq ? withEq.slice(flag.length + 1) : undefined;
+}
+/**
+ * Resolve bridge configuration from CLI flags and environment variables.
+ * `--port` / MERMALAID_BRIDGE_PORT pins a single port (no fallback scan).
+ * `--origins` / MERMALAID_BRIDGE_ORIGINS is a comma-separated origin allowlist extension.
+ */
+export function loadConfig(argv = process.argv.slice(2), env = process.env) {
+    const port = parsePositiveInt(readFlag(argv, '--port') ?? env.MERMALAID_BRIDGE_PORT);
+    const host = readFlag(argv, '--host') ?? env.MERMALAID_BRIDGE_HOST ?? DEFAULT_BRIDGE_HOST;
+    const originsRaw = readFlag(argv, '--origins') ?? env.MERMALAID_BRIDGE_ORIGINS ?? '';
+    const extraOrigins = originsRaw
+        .split(',')
+        .map((o) => o.trim())
+        .filter((o) => o.length > 0);
+    const allowDevOrigins = argv.includes('--dev') || Boolean(env.MERMALAID_BRIDGE_DEV);
+    return {
+        host,
+        ports: port ? [port] : [...BRIDGE_PORT_FALLBACKS],
+        extraOrigins,
+        allowDevOrigins,
+        heartbeatIntervalMs: DEFAULT_HEARTBEAT_INTERVAL_MS,
+        maxPayloadBytes: 8 * 1024 * 1024,
+        timeouts: {
+            getDiagramMs: 3_000,
+            setDiagramMs: 8_000,
+            validateMs: 5_000,
+            renderSvgMs: 15_000,
+            renderPngMs: 20_000,
+        },
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,qBAAqB,EACrB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,eAAe,CAAA;AAsBtB,SAAS,gBAAgB,CAAC,KAAyB;IACjD,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAA;IAC5B,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IACpC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AACpD,CAAC;AAED,SAAS,QAAQ,CAAC,IAAc,EAAE,IAAY;IAC5C,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;IACvD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAA;IACzD,OAAO,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CACxB,OAAiB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EACtC,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,IAAI,GAAG,gBAAgB,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,GAAG,CAAC,qBAAqB,CAAC,CAAA;IACpF,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,GAAG,CAAC,qBAAqB,IAAI,mBAAmB,CAAA;IAEzF,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,IAAI,GAAG,CAAC,wBAAwB,IAAI,EAAE,CAAA;IACpF,MAAM,YAAY,GAAG,UAAU;SAC5B,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;IAE9B,MAAM,eAAe,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAA;IAEnF,OAAO;QACL,IAAI;QACJ,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,qBAAqB,CAAC;QACjD,YAAY;QACZ,eAAe;QACf,mBAAmB,EAAE,6BAA6B;QAClD,eAAe,EAAE,CAAC,GAAG,IAAI,GAAG,IAAI;QAChC,QAAQ,EAAE;YACR,YAAY,EAAE,KAAK;YACnB,YAAY,EAAE,KAAK;YACnB,UAAU,EAAE,KAAK;YACjB,WAAW,EAAE,MAAM;YACnB,WAAW,EAAE,MAAM;SACpB;KACF,CAAA;AACH,CAAC"}

package/dist/index.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './config.js';
+import { makeOriginChecker } from './origins.js';
+import { formatPairingCode, generatePairingCode } from './pairing.js';
+import { registerDiagramResource } from './resources.js';
+import { BridgeSession } from './session.js';
+import { registerTools } from './tools.js';
+import { BridgeWsServer } from './wsServer.js';
+const SERVER_NAME = 'mermalaid-mcp';
+function readVersion() {
+    try {
+        const pkgUrl = new URL('../package.json', import.meta.url);
+        const pkg = JSON.parse(readFileSync(fileURLToPath(pkgUrl), 'utf8'));
+        return pkg.version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+// The MCP protocol owns stdout — everything human-facing must go to stderr.
+function logStderr(line) {
+    process.stderr.write(`${line}\n`);
+}
+async function main() {
+    const config = loadConfig();
+    const version = readVersion();
+    const pairingCode = generatePairingCode();
+    const session = new BridgeSession({
+        pairingCode,
+        serverInfo: { name: SERVER_NAME, version },
+        heartbeatIntervalMs: config.heartbeatIntervalMs,
+        timeouts: config.timeouts,
+    });
+    const ws = new BridgeWsServer({
+        host: config.host,
+        ports: config.ports,
+        allowOrigin: makeOriginChecker({
+            extraOrigins: config.extraOrigins,
+            allowDevOrigins: config.allowDevOrigins,
+        }),
+        heartbeatIntervalMs: config.heartbeatIntervalMs,
+        maxPayloadBytes: config.maxPayloadBytes,
+    }, {
+        onMessage: (conn, msg) => session.handleMessage(conn, msg),
+        onClose: (conn) => session.handleClose(conn),
+    });
+    const port = await ws.start();
+    const server = new McpServer({ name: SERVER_NAME, version });
+    registerTools(server, { session, pairingCode, port });
+    registerDiagramResource(server, session);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logStderr('');
+    logStderr(`[${SERVER_NAME}] v${version} ready.`);
+    logStderr(`[${SERVER_NAME}] Bridge listening on ws://${config.host}:${port}`);
+    logStderr(`[${SERVER_NAME}] Pairing code: ${formatPairingCode(pairingCode)}`);
+    logStderr(`[${SERVER_NAME}] In Mermalaid, open the "AI Agent" panel and enter the code to connect.`);
+    logStderr('');
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        session.dispose();
+        await ws.stop();
+        await server.close().catch(() => { });
+        process.exit(0);
+    };
+    process.on('SIGINT', () => void shutdown());
+    process.on('SIGTERM', () => void shutdown());
+}
+main().catch((err) => {
+    logStderr(`[${SERVER_NAME}] Fatal: ${err instanceof Error ? (err.stack ?? err.message) : String(err)}`);
+    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/origins.js

@@ -0,0 +1,36 @@
+// Origin allowlist for the localhost WebSocket bridge.
+//
+// Browsers always send a truthful `Origin` header on a WebSocket handshake and page
+// scripts cannot forge it, so this list blocks any web page not served from a known
+// Mermalaid origin from driving the socket — defense-in-depth on top of the pairing code.
+const PRODUCTION_ORIGINS = [
+    'https://mermalaid.com',
+    'https://www.mermalaid.com',
+    // Tauri desktop webview (macOS/Linux use tauri://localhost; Windows uses http://tauri.localhost)
+    'tauri://localhost',
+    'http://tauri.localhost',
+];
+// Generic Vite dev/preview ports. Off by default (a malicious page on localhost:5173 would
+// otherwise pass the Origin layer); opt in with MERMALAID_BRIDGE_DEV when developing Mermalaid.
+const DEV_ORIGINS = [
+    'http://localhost:5173',
+    'http://127.0.0.1:5173',
+    'http://localhost:4173',
+    'http://127.0.0.1:4173',
+];
+export function makeOriginChecker(options = {}) {
+    const allowed = new Set([
+        ...PRODUCTION_ORIGINS,
+        ...(options.allowDevOrigins ? DEV_ORIGINS : []),
+        ...(options.extraOrigins ?? []),
+    ]);
+    return (origin) => {
+        // Non-browser MCP tooling and some webviews omit Origin entirely. Allow the empty case —
+        // the pairing code still gates binding, and these clients are already local (loopback bind).
+        if (!origin)
+            return true;
+        return allowed.has(origin);
+    };
+}
+export { PRODUCTION_ORIGINS, DEV_ORIGINS };
+//# sourceMappingURL=origins.js.map

package/dist/origins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"origins.js","sourceRoot":"","sources":["../src/origins.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,oFAAoF;AACpF,oFAAoF;AACpF,0FAA0F;AAC1F,MAAM,kBAAkB,GAAG;IACzB,uBAAuB;IACvB,2BAA2B;IAC3B,iGAAiG;IACjG,mBAAmB;IACnB,wBAAwB;CACzB,CAAA;AAED,2FAA2F;AAC3F,gGAAgG;AAChG,MAAM,WAAW,GAAG;IAClB,uBAAuB;IACvB,uBAAuB;IACvB,uBAAuB;IACvB,uBAAuB;CACxB,CAAA;AAOD,MAAM,UAAU,iBAAiB,CAC/B,UAAgC,EAAE;IAElC,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC;QACtB,GAAG,kBAAkB;QACrB,GAAG,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;KAChC,CAAC,CAAA;IACF,OAAO,CAAC,MAAM,EAAE,EAAE;QAChB,yFAAyF;QACzF,6FAA6F;QAC7F,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAA;QACxB,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IAC5B,CAAC,CAAA;AACH,CAAC;AAED,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,CAAA"}

package/dist/pairing.js

@@ -0,0 +1,32 @@
+import { randomInt, timingSafeEqual } from 'node:crypto';
+// Crockford-style base32 without visually ambiguous characters (no 0/1/I/L/O/U).
+// The set is unambiguous by construction, so pairing codes are safe to read aloud/type.
+const ALPHABET = '23456789ABCDEFGHJKMNPQRSTVWXYZ';
+/** Generate a fresh, session-only pairing code (default 8 chars ≈ 40 bits). */
+export function generatePairingCode(length = 8) {
+    let out = '';
+    for (let i = 0; i < length; i++) {
+        out += ALPHABET[randomInt(0, ALPHABET.length)];
+    }
+    return out;
+}
+/** Uppercase and strip anything outside the alphabet (dashes, spaces) for comparison. */
+export function normalizePairingCode(input) {
+    return input.toUpperCase().replace(/[^0-9A-Z]/g, '');
+}
+/** Human-friendly grouping, e.g. `K7RM9QX2` -> `K7RM-9QX2`. */
+export function formatPairingCode(code) {
+    const c = normalizePairingCode(code);
+    if (c.length <= 4)
+        return c;
+    return `${c.slice(0, 4)}-${c.slice(4)}`;
+}
+/** Constant-time comparison of two pairing codes after normalization. */
+export function pairingCodesMatch(a, b) {
+    const na = Buffer.from(normalizePairingCode(a), 'utf8');
+    const nb = Buffer.from(normalizePairingCode(b), 'utf8');
+    if (na.length === 0 || na.length !== nb.length)
+        return false;
+    return timingSafeEqual(na, nb);
+}
+//# sourceMappingURL=pairing.js.map

package/dist/pairing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pairing.js","sourceRoot":"","sources":["../src/pairing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAExD,iFAAiF;AACjF,wFAAwF;AACxF,MAAM,QAAQ,GAAG,gCAAgC,CAAA;AAEjD,+EAA+E;AAC/E,MAAM,UAAU,mBAAmB,CAAC,MAAM,GAAG,CAAC;IAC5C,IAAI,GAAG,GAAG,EAAE,CAAA;IACZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,GAAG,IAAI,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAA;IAChD,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAO,KAAK,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAA;AACtD,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,iBAAiB,CAAC,IAAY;IAC5C,MAAM,CAAC,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAA;IACpC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,CAAC,CAAA;IAC3B,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;AACzC,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,iBAAiB,CAAC,CAAS,EAAE,CAAS;IACpD,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;IACvD,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAA;IACvD,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAC5D,OAAO,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC,CAAA;AAChC,CAAC"}

package/dist/protocol.js

@@ -0,0 +1,53 @@
+// Wire protocol shared between the `mermalaid-mcp` server and the Mermalaid editor.
+//
+// SOURCE OF TRUTH. This file is duplicated verbatim to `src/agentBridge/protocol.ts`
+// so the browser bundle (Vite, bundler resolution) and the Node server (tsc, NodeNext
+// resolution) each get a self-contained copy. A drift test asserts the two stay identical.
+// Keep this file DEPENDENCY-FREE (pure types + consts + guards) — no imports — so it is
+// valid under both module resolution modes.
+export const PROTOCOL_VERSION = 1;
+export const DEFAULT_BRIDGE_HOST = '127.0.0.1';
+export const DEFAULT_BRIDGE_PORT = 7337;
+/** Ports scanned in order when the default is already taken. */
+export const BRIDGE_PORT_FALLBACKS = [7337, 7338, 7339, 7340];
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 15_000;
+/** Discriminator values for every message on the wire. */
+export const MessageType = {
+    // editor -> server
+    Hello: 'hello',
+    State: 'state',
+    SetDiagramResult: 'setDiagramResult',
+    GetDiagramResult: 'getDiagramResult',
+    ValidateResult: 'validateResult',
+    RenderResult: 'renderResult',
+    Pong: 'pong',
+    // server -> editor
+    Welcome: 'welcome',
+    Reject: 'reject',
+    Superseded: 'superseded',
+    SetDiagram: 'setDiagram',
+    GetDiagram: 'getDiagram',
+    Validate: 'validate',
+    Render: 'render',
+    Ping: 'ping',
+};
+/** Parse a raw frame into a BridgeMessage, or null if it is not a well-formed envelope. */
+export function parseBridgeMessage(raw) {
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!obj || typeof obj !== 'object')
+        return null;
+    const m = obj;
+    if (typeof m.type !== 'string' || typeof m.v !== 'number')
+        return null;
+    return m;
+}
+export function serializeBridgeMessage(msg) {
+    return JSON.stringify(msg);
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,EAAE;AACF,qFAAqF;AACrF,sFAAsF;AACtF,2FAA2F;AAC3F,wFAAwF;AACxF,4CAA4C;AAE5C,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAA;AAEjC,MAAM,CAAC,MAAM,mBAAmB,GAAG,WAAW,CAAA;AAC9C,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,CAAA;AACvC,gEAAgE;AAChE,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;AAE7D,MAAM,CAAC,MAAM,6BAA6B,GAAG,MAAM,CAAA;AAEnD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,mBAAmB;IACnB,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,OAAO;IACd,gBAAgB,EAAE,kBAAkB;IACpC,gBAAgB,EAAE,kBAAkB;IACpC,cAAc,EAAE,gBAAgB;IAChC,YAAY,EAAE,cAAc;IAC5B,IAAI,EAAE,MAAM;IACZ,mBAAmB;IACnB,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,QAAQ;IAChB,UAAU,EAAE,YAAY;IACxB,UAAU,EAAE,YAAY;IACxB,UAAU,EAAE,YAAY;IACxB,QAAQ,EAAE,UAAU;IACpB,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,MAAM;CACJ,CAAA;AA6KV,2FAA2F;AAC3F,MAAM,UAAU,kBAAkB,CAAC,GAAW;IAC5C,IAAI,GAAY,CAAA;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IAChD,MAAM,CAAC,GAAG,GAA8B,CAAA;IACxC,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAA;IACtE,OAAO,CAA6B,CAAA;AACtC,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,GAAkB;IACvD,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAA;AAC5B,CAAC"}

package/dist/resources.js

@@ -0,0 +1,40 @@
+import { SubscribeRequestSchema, UnsubscribeRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+export const DIAGRAM_RESOURCE_URI = 'mermalaid://diagram/current';
+const DIAGRAM_MIME = 'text/vnd.mermaid';
+/**
+ * Exposes the live diagram as an MCP resource so users can @-mention / attach it in clients
+ * like Claude Desktop. The high-level McpServer wires resources/read + list but not
+ * subscribe, so this also registers subscribe/unsubscribe and pushes `resources/updated`
+ * whenever the diagram changes.
+ */
+export function registerDiagramResource(server, session) {
+    server.registerResource('current-diagram', DIAGRAM_RESOURCE_URI, {
+        title: 'Current Mermalaid diagram',
+        description: 'The Mermaid source currently open in the connected Mermalaid editor. Reflects live edits from the user and the agent.',
+        mimeType: DIAGRAM_MIME,
+    }, async (uri) => {
+        const cached = session.getCachedDiagram();
+        const text = cached
+            ? cached.code
+            : session.isPaired
+                ? '%% The Mermalaid editor is connected but has not sent its diagram yet.'
+                : '%% No Mermalaid editor is connected. Open Mermalaid and pair the AI Agent panel.';
+        return { contents: [{ uri: uri.toString(), mimeType: DIAGRAM_MIME, text }] };
+    });
+    const subscribers = new Set();
+    server.server.registerCapabilities({ resources: { subscribe: true } });
+    server.server.setRequestHandler(SubscribeRequestSchema, async (request) => {
+        subscribers.add(request.params.uri);
+        return {};
+    });
+    server.server.setRequestHandler(UnsubscribeRequestSchema, async (request) => {
+        subscribers.delete(request.params.uri);
+        return {};
+    });
+    session.onStateChange(() => {
+        if (!subscribers.has(DIAGRAM_RESOURCE_URI))
+            return;
+        void server.server.sendResourceUpdated({ uri: DIAGRAM_RESOURCE_URI }).catch(() => { });
+    });
+}
+//# sourceMappingURL=resources.js.map

package/dist/resources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.js","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,wBAAwB,EAAE,MAAM,oCAAoC,CAAA;AAGrG,MAAM,CAAC,MAAM,oBAAoB,GAAG,6BAA6B,CAAA;AACjE,MAAM,YAAY,GAAG,kBAAkB,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAiB,EAAE,OAAsB;IAC/E,MAAM,CAAC,gBAAgB,CACrB,iBAAiB,EACjB,oBAAoB,EACpB;QACE,KAAK,EAAE,2BAA2B;QAClC,WAAW,EACT,uHAAuH;QACzH,QAAQ,EAAE,YAAY;KACvB,EACD,KAAK,EAAE,GAAG,EAAE,EAAE;QACZ,MAAM,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAA;QACzC,MAAM,IAAI,GAAG,MAAM;YACjB,CAAC,CAAC,MAAM,CAAC,IAAI;YACb,CAAC,CAAC,OAAO,CAAC,QAAQ;gBAChB,CAAC,CAAC,wEAAwE;gBAC1E,CAAC,CAAC,kFAAkF,CAAA;QACxF,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,CAAA;IAC9E,CAAC,CACF,CAAA;IAED,MAAM,WAAW,GAAG,IAAI,GAAG,EAAU,CAAA;IACrC,MAAM,CAAC,MAAM,CAAC,oBAAoB,CAAC,EAAE,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC,CAAA;IACtE,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QACxE,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACnC,OAAO,EAAE,CAAA;IACX,CAAC,CAAC,CAAA;IACF,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,wBAAwB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;QAC1E,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QACtC,OAAO,EAAE,CAAA;IACX,CAAC,CAAC,CAAA;IAEF,OAAO,CAAC,aAAa,CAAC,GAAG,EAAE;QACzB,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,oBAAoB,CAAC;YAAE,OAAM;QAClD,KAAK,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,EAAE,GAAG,EAAE,oBAAoB,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IACvF,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/session.js

@@ -0,0 +1,245 @@
+import { randomUUID } from 'node:crypto';
+import { MessageType, PROTOCOL_VERSION, } from './protocol.js';
+import { pairingCodesMatch } from './pairing.js';
+export class BridgeNotConnectedError extends Error {
+    constructor() {
+        super('No Mermalaid editor is connected');
+        this.name = 'BridgeNotConnectedError';
+    }
+}
+export class BridgeTimeoutError extends Error {
+    constructor(op, timeoutMs) {
+        super(`Editor did not respond to "${op}" within ${timeoutMs}ms`);
+        this.name = 'BridgeTimeoutError';
+    }
+}
+export class BridgeDisconnectedError extends Error {
+    constructor(reason) {
+        super(reason);
+        this.name = 'BridgeDisconnectedError';
+    }
+}
+/**
+ * Owns the single bound-editor relationship: pairing handshake, newest-wins supersede,
+ * the cached editor state, and the request/response correlation used by the MCP tools.
+ */
+export class BridgeSession {
+    opts;
+    editor = null;
+    editorInfo = null;
+    capabilities = null;
+    cached = null;
+    pending = new Map();
+    waiters = [];
+    stateChangeListeners = [];
+    constructor(opts) {
+        this.opts = opts;
+    }
+    get isPaired() {
+        return this.editor !== null;
+    }
+    /** Subscribe to cached-diagram changes (bind, unbind, and each state push). */
+    onStateChange(listener) {
+        this.stateChangeListeners.push(listener);
+    }
+    emitStateChange() {
+        for (const listener of this.stateChangeListeners) {
+            try {
+                listener();
+            }
+            catch {
+                // a listener must not break session handling
+            }
+        }
+    }
+    /** The last known diagram, or null if none has been received yet. */
+    getCachedDiagram() {
+        if (!this.cached)
+            return null;
+        const c = this.cached;
+        return { code: c.code, rev: c.rev, valid: c.valid, error: c.error };
+    }
+    // ---- inbound (called by the WS server) ----
+    handleMessage(conn, msg) {
+        if (msg.type === MessageType.Hello) {
+            this.handleHello(conn, msg);
+            return;
+        }
+        // Only the currently-bound editor may drive session state / resolve requests.
+        if (conn !== this.editor)
+            return;
+        switch (msg.type) {
+            case MessageType.State:
+                this.cacheState(msg);
+                break;
+            case MessageType.SetDiagramResult:
+            case MessageType.GetDiagramResult:
+            case MessageType.ValidateResult:
+            case MessageType.RenderResult:
+            case MessageType.Pong:
+                if (msg.id)
+                    this.resolvePending(msg.id, msg);
+                break;
+            default:
+                break;
+        }
+    }
+    handleClose(conn) {
+        if (conn !== this.editor)
+            return;
+        this.editor = null;
+        this.editorInfo = null;
+        this.capabilities = null;
+        this.cached = null;
+        this.failAllPending(new BridgeDisconnectedError('Editor disconnected'));
+        this.emitStateChange();
+    }
+    handleHello(conn, msg) {
+        if (typeof msg.v !== 'number' || msg.v !== PROTOCOL_VERSION) {
+            this.rejectConn(conn, 'version_mismatch', `Unsupported protocol version ${msg.v}; server speaks ${PROTOCOL_VERSION}.`);
+            return;
+        }
+        if (!msg.pairingCode || !pairingCodesMatch(msg.pairingCode, this.opts.pairingCode)) {
+            this.rejectConn(conn, 'bad_pairing_code', 'Invalid pairing code.');
+            return;
+        }
+        // Newest-wins supersede: an existing editor is bumped in favor of the new one.
+        if (this.editor && this.editor !== conn) {
+            this.editor.send({
+                v: PROTOCOL_VERSION,
+                type: MessageType.Superseded,
+                message: 'Another Mermalaid tab or window took over the agent bridge.',
+            });
+            this.editor.close(4002, 'superseded');
+            this.failAllPending(new BridgeDisconnectedError('Editor superseded by a newer connection'));
+        }
+        this.editor = conn;
+        this.editorInfo = msg.clientInfo ?? null;
+        this.capabilities = msg.capabilities ?? null;
+        this.cached = null; // a fresh `state` push follows welcome
+        this.emitStateChange(); // notify resource subscribers the cached diagram was reset
+        conn.send({
+            v: PROTOCOL_VERSION,
+            type: MessageType.Welcome,
+            sessionId: randomUUID(),
+            serverInfo: this.opts.serverInfo,
+            protocolVersion: PROTOCOL_VERSION,
+            heartbeatIntervalMs: this.opts.heartbeatIntervalMs,
+        });
+        this.resolveWaiters();
+    }
+    rejectConn(conn, reason, message) {
+        conn.send({ v: PROTOCOL_VERSION, type: MessageType.Reject, reason, message });
+        conn.close(4001, reason);
+    }
+    cacheState(msg) {
+        this.cached = {
+            rev: msg.rev,
+            code: msg.code,
+            valid: msg.valid,
+            error: msg.error,
+            source: msg.source,
+            updatedAt: Date.now(),
+        };
+        this.emitStateChange();
+    }
+    // ---- request/response correlation ----
+    request(payload, timeoutMs) {
+        const editor = this.editor;
+        if (!editor)
+            return Promise.reject(new BridgeNotConnectedError());
+        const id = randomUUID();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new BridgeTimeoutError(payload.type, timeoutMs));
+            }, timeoutMs);
+            timer.unref?.();
+            this.pending.set(id, {
+                resolve: resolve,
+                reject,
+                timer,
+            });
+            editor.send({ ...payload, v: PROTOCOL_VERSION, id });
+        });
+    }
+    resolvePending(id, msg) {
+        const p = this.pending.get(id);
+        if (!p)
+            return;
+        clearTimeout(p.timer);
+        this.pending.delete(id);
+        p.resolve(msg);
+    }
+    failAllPending(err) {
+        for (const p of this.pending.values()) {
+            clearTimeout(p.timer);
+            p.reject(err);
+        }
+        this.pending.clear();
+    }
+    // ---- operations used by the MCP tools ----
+    async setDiagram(code, reason) {
+        return this.request({ type: MessageType.SetDiagram, code, mode: 'replace', reason }, this.opts.timeouts.setDiagramMs);
+    }
+    async getDiagram(fresh = false) {
+        const cached = this.getCachedDiagram();
+        if (!fresh && cached)
+            return cached;
+        const res = await this.request({ type: MessageType.GetDiagram }, this.opts.timeouts.getDiagramMs);
+        return { code: res.code, rev: res.rev, valid: res.valid, error: res.error };
+    }
+    async validate(code) {
+        return this.request({ type: MessageType.Validate, code }, this.opts.timeouts.validateMs);
+    }
+    async render(format, opts = {}) {
+        const timeout = format === 'png' ? this.opts.timeouts.renderPngMs : this.opts.timeouts.renderSvgMs;
+        return this.request({ type: MessageType.Render, format, code: opts.code, scale: opts.scale, theme: opts.theme }, timeout);
+    }
+    /** Resolve once an editor is paired, or reject on timeout. */
+    waitForEditor(timeoutMs) {
+        if (this.isPaired)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                resolve,
+                reject,
+                timer: setTimeout(() => {
+                    this.waiters = this.waiters.filter((w) => w !== waiter);
+                    reject(new BridgeTimeoutError('wait_for_editor', timeoutMs));
+                }, timeoutMs),
+            };
+            waiter.timer.unref?.();
+            this.waiters.push(waiter);
+        });
+    }
+    resolveWaiters() {
+        const waiters = this.waiters;
+        this.waiters = [];
+        for (const w of waiters) {
+            clearTimeout(w.timer);
+            w.resolve();
+        }
+    }
+    status() {
+        return {
+            paired: this.isPaired,
+            editorInfo: this.editorInfo,
+            capabilities: this.capabilities,
+            hasCachedState: this.cached !== null,
+            lastRevision: this.cached?.rev ?? null,
+            lastValid: this.cached?.valid ?? null,
+        };
+    }
+    /** Reject outstanding work and drop the editor — used on shutdown. */
+    dispose() {
+        this.failAllPending(new BridgeDisconnectedError('Server shutting down'));
+        for (const w of this.waiters) {
+            clearTimeout(w.timer);
+            w.reject(new BridgeDisconnectedError('Server shutting down'));
+        }
+        this.waiters = [];
+        this.editor = null;
+    }
+}
+//# sourceMappingURL=session.js.map