zuiku-mcp 0.3.1 → 0.3.2

package/README.md

@@ -6,6 +6,7 @@
 
 ## What it exposes
 
+- `zuiku.version`: report the running package/server version and update hints
 - `zuiku.open`: open a markdown file, canonical Zuiku Markdown, or Mermaid-only content as a localhost editor session
 - `zuiku.read`: read current Markdown and hash before updating
 - `zuiku.apply`: write Mermaid-only or canonical Markdown back as normalized Zuiku Markdown with hash-based conflict protection
@@ -18,6 +19,32 @@
 npx -y zuiku-mcp
 ```
 
+## Version and update
+
+Check the currently installed package version:
+
+```bash
+npx -y zuiku-mcp --version
+```
+
+Check the latest published npm version:
+
+```bash
+npm view zuiku-mcp version
+```
+
+Run the latest package one-shot:
+
+```bash
+npx -y zuiku-mcp@latest
+```
+
+Update a global install:
+
+```bash
+npm install -g zuiku-mcp@latest
+```
+
 ## Typical usage
 
 - Codex CLI / Claude Code / Gemini CLI: register it as an MCP server command
@@ -35,9 +62,11 @@ npx -y zuiku-mcp
 ## Notes
 
 - Requires Node.js 20+
+- `zuiku.version` can be called from MCP clients to confirm the running build and show update hints
 - For chat clients, `ZUIKU_MCP_OPEN_BROWSER=0` is usually the better default
 - `zuiku.apply(openAfterApply=true)` can request opening or reusing the local editor session after save
 - Discovery guides are exposed over MCP resources/prompts so AI clients can avoid external lookup
+- After updating, restart the MCP client or IDE session so the new package is launched
 - During preview, CLI and manual MCP setup are the source of truth; optional IDE extension listings can be added on top later
 - Install guide: `https://zuiku.dev/install`
 - Docs: `https://zuiku.dev/docs`

package/bin/zuiku-mcp.mjs

@@ -1,4 +1,14 @@
 #!/usr/bin/env node
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const packageJson = require("../package.json");
+
+if (process.argv.includes("--version") || process.argv.includes("-v") || process.argv[2] === "version") {
+  process.stdout.write(`${packageJson.version}\n`);
+  process.exit(0);
+}
+
 const entryPath = new URL("../dist/zuiku-mcp-server.mjs", import.meta.url);
 
 try {

package/dist/zuiku-mcp-server.mjs

@@ -5,6 +5,16 @@ import path4 from "node:path";
 
 // ../../apps/web/src/lib/mcpContract.ts
 var MCP_TOOL_DEFINITIONS = [
+  {
+    name: "zuiku.version",
+    description: "Return the current zuiku-mcp package/server version and update hints. Use this to confirm which MCP build is currently running.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      required: [],
+      additionalProperties: false
+    }
+  },
   {
     name: "zuiku.open",
     description: "Open a markdown file, canonical Zuiku Markdown, or Mermaid-only text in a local editor session. Mermaid-only input is normalized on save, and the result includes editorUrl.",
@@ -99,6 +109,18 @@ function validateMcpToolRequest(input) {
     return invalidRequest("args must be an object");
   }
   const args = input.args;
+  if (tool === "zuiku.version") {
+    if (!hasOnlyKeys(args, [])) {
+      return invalidRequest("zuiku.version.args contains unknown keys");
+    }
+    return {
+      ok: true,
+      value: {
+        tool,
+        args: {}
+      }
+    };
+  }
   if (tool === "zuiku.open") {
     if (!hasOnlyKeys(args, ["path", "markdown", "title", "openInBrowser"])) {
       return invalidRequest("zuiku.open.args contains unknown keys");
@@ -5689,6 +5711,56 @@ function parseBearerToken(value) {
   return match?.[1]?.trim();
 }
 
+// package.json
+var package_default = {
+  name: "zuiku-mcp",
+  version: "0.3.2",
+  description: "Round-trip Diagram Editor MCP server for Zuiku",
+  type: "module",
+  license: "UNLICENSED",
+  homepage: "https://zuiku.dev/docs",
+  bugs: {
+    url: "https://github.com/kamotami/zuiku/issues"
+  },
+  repository: {
+    type: "git",
+    url: "git+https://github.com/kamotami/zuiku.git",
+    directory: "packages/zuiku-mcp"
+  },
+  keywords: [
+    "zuiku",
+    "mcp",
+    "diagram",
+    "mermaid",
+    "markdown",
+    "round-trip"
+  ],
+  engines: {
+    node: ">=20.0.0"
+  },
+  bin: {
+    "zuiku-mcp": "bin/zuiku-mcp.mjs"
+  },
+  scripts: {
+    build: "node ./scripts/build.mjs",
+    prepack: "npm run build"
+  },
+  files: [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  publishConfig: {
+    access: "public"
+  }
+};
+
+// ../../apps/web/src/lib/mcpServerMeta.ts
+var ZUIKU_MCP_PACKAGE_NAME = package_default.name;
+var ZUIKU_MCP_PACKAGE_VERSION = package_default.version;
+var ZUIKU_MCP_SERVER_NAME = "zuiku-mcp-min";
+var ZUIKU_MCP_PROTOCOL_VERSION = "2024-11-05";
+
 // ../../apps/web/src/lib/mcpStdioRuntime.ts
 var McpToolExecutionError = class extends Error {
   code;
@@ -5800,6 +5872,26 @@ function warnHookFailure(tool, hookName, error) {
 }
 async function executeValidatedToolCall(request, ownerId, context) {
   switch (request.tool) {
+    case "zuiku.version": {
+      return {
+        packageName: ZUIKU_MCP_PACKAGE_NAME,
+        packageVersion: ZUIKU_MCP_PACKAGE_VERSION,
+        serverName: ZUIKU_MCP_SERVER_NAME,
+        serverVersion: ZUIKU_MCP_PACKAGE_VERSION,
+        protocolVersion: ZUIKU_MCP_PROTOCOL_VERSION,
+        entryCommand: "npx -y zuiku-mcp",
+        versionCommands: {
+          cli: "npx -y zuiku-mcp --version",
+          npm: "npm view zuiku-mcp version"
+        },
+        updateCommands: {
+          oneShotLatest: "npx -y zuiku-mcp@latest",
+          globalInstallLatest: "npm install -g zuiku-mcp@latest"
+        },
+        restartRequiredAfterUpdate: true,
+        message: "Restart your MCP client or IDE session after updating so the new package is launched."
+      };
+    }
     case "zuiku.open": {
       const source = request.args.path ? "path" : "markdown";
       if (source === "path") {
@@ -5813,13 +5905,18 @@ async function executeValidatedToolCall(request, ownerId, context) {
         }
         const markdown2 = await readFile(filePath, "utf8");
         if (context.localEditorHost) {
-          const opened = await context.localEditorHost.openSession({
-            path: filePath,
-            openInBrowser: request.args.openInBrowser ?? context.defaultOpenInBrowser
-          });
+          const opened = await openLocalEditorSessionOrThrow(
+            context.localEditorHost,
+            {
+              path: filePath,
+              openInBrowser: request.args.openInBrowser ?? context.defaultOpenInBrowser
+            },
+            "failed to open Zuiku editor session"
+          );
           return {
             ...opened,
-            modifiedAt: fileStat.mtime.toISOString()
+            modifiedAt: fileStat.mtime.toISOString(),
+            message: buildEditorSessionMessage(opened)
           };
         }
         return {
@@ -5844,12 +5941,19 @@ async function executeValidatedToolCall(request, ownerId, context) {
         throw new McpToolExecutionError("limit_exceeded", shapeError);
       }
       if (context.localEditorHost) {
-        const opened = await context.localEditorHost.openSession({
-          markdown: normalizedMarkdown,
-          title: request.args.title,
-          openInBrowser: request.args.openInBrowser ?? context.defaultOpenInBrowser
-        });
-        return opened;
+        const opened = await openLocalEditorSessionOrThrow(
+          context.localEditorHost,
+          {
+            markdown: normalizedMarkdown,
+            title: request.args.title,
+            openInBrowser: request.args.openInBrowser ?? context.defaultOpenInBrowser
+          },
+          "failed to open Zuiku editor session"
+        );
+        return {
+          ...opened,
+          message: buildEditorSessionMessage(opened)
+        };
       }
       return {
         source,
@@ -5972,10 +6076,14 @@ async function handleApply(request, ownerId, context) {
   let sessionId;
   let editorUrl;
   if (request.args.openAfterApply && context.localEditorHost) {
-    const opened = await context.localEditorHost.openSession({
-      path: filePath,
-      openInBrowser: true
-    });
+    const opened = await openLocalEditorSessionOrThrow(
+      context.localEditorHost,
+      {
+        path: filePath,
+        openInBrowser: true
+      },
+      "saved markdown but failed to open the Zuiku editor session"
+    );
     sessionId = opened.sessionId;
     editorUrl = opened.editorUrl;
     openedInEditor = opened.openedInEditor;
@@ -5990,7 +6098,13 @@ async function handleApply(request, ownerId, context) {
     ...sessionId ? { sessionId } : {},
     ...editorUrl ? { editorUrl } : {},
     openedInEditor,
-    reusedSession
+    reusedSession,
+    message: buildApplyResultMessage({
+      openAfterApply: request.args.openAfterApply ?? false,
+      editorUrl,
+      openedInEditor,
+      reusedSession
+    })
   };
 }
 async function buildMarkdownForApplyMode(request, filePath) {
@@ -6138,6 +6252,58 @@ async function resolvePathWithinAllowedRootsOrThrow(rawPath, allowedRoots2, opti
   }
   return resolved;
 }
+function openLocalEditorSessionOrThrow(host, request, fallbackMessage) {
+  return host.openSession(request).catch((error) => {
+    throw normalizeLocalEditorHostError(error, fallbackMessage);
+  });
+}
+function normalizeLocalEditorHostError(error, fallbackMessage) {
+  if (error instanceof McpToolExecutionError) {
+    return error;
+  }
+  if (isStructuredToolError(error)) {
+    return new McpToolExecutionError(error.code, error.message, error.data);
+  }
+  if (error instanceof Error) {
+    return new McpToolExecutionError("invalid_request", error.message);
+  }
+  return new McpToolExecutionError("invalid_request", fallbackMessage);
+}
+function isStructuredToolError(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.message === "string" && isMcpErrorCode(candidate.code) && (candidate.data === void 0 || typeof candidate.data === "object" && candidate.data !== null && !Array.isArray(candidate.data));
+}
+function isMcpErrorCode(value) {
+  return value === "invalid_request" || value === "parse_error" || value === "conflict" || value === "limit_exceeded" || value === "not_found";
+}
+function buildEditorSessionMessage(opened) {
+  if (opened.openedInEditor && opened.reusedSession) {
+    return "Reused the existing Zuiku editor session and requested it to open.";
+  }
+  if (opened.openedInEditor) {
+    return "Requested the Zuiku editor session to open.";
+  }
+  if (opened.reusedSession) {
+    return "Reused the existing Zuiku editor session. If your client did not open it automatically, use the editorUrl.";
+  }
+  return "Zuiku editor session is ready. If your client did not open it automatically, use the editorUrl.";
+}
+function buildApplyResultMessage(options) {
+  if (!options.openAfterApply) {
+    return "Saved canonical Zuiku Markdown.";
+  }
+  if (!options.editorUrl) {
+    return "Saved canonical Zuiku Markdown. The editor session was not opened.";
+  }
+  return `Saved canonical Zuiku Markdown. ${buildEditorSessionMessage({
+    editorUrl: options.editorUrl,
+    openedInEditor: options.openedInEditor,
+    reusedSession: options.reusedSession
+  })}`;
+}
 function hashText(value) {
   return `sha256:${createHash("sha256").update(value).digest("hex")}`;
 }
@@ -6311,7 +6477,7 @@ function createMcpJsonRpcDispatcher(options) {
             jsonrpc: "2.0",
             id,
             result: {
-              content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+              content: [{ type: "text", text: formatToolSuccessText(toolName, payload) }],
               structuredContent: payload
             }
           };
@@ -6348,7 +6514,7 @@ function createMcpJsonRpcDispatcher(options) {
 function toolError(code, message, data) {
   return {
     isError: true,
-    content: [{ type: "text", text: `${code}: ${message}` }],
+    content: [{ type: "text", text: formatToolErrorText(code, message, data) }],
     structuredContent: {
       code,
       message,
@@ -6356,6 +6522,44 @@ function toolError(code, message, data) {
     }
   };
 }
+function formatToolSuccessText(toolName, payload) {
+  if (toolName === "zuiku.version" && isObjectRecord(payload)) {
+    const packageVersion = asString4(payload.packageVersion);
+    const cliCommand = asString4(asObject(payload.versionCommands)?.cli);
+    if (packageVersion && cliCommand) {
+      return `zuiku-mcp ${packageVersion}
+check: ${cliCommand}`;
+    }
+  }
+  if ((toolName === "zuiku.open" || toolName === "zuiku.apply") && isObjectRecord(payload)) {
+    const message = asString4(payload.message);
+    const editorUrl = asString4(payload.editorUrl);
+    const lines = [
+      ...message ? [message] : [],
+      ...editorUrl ? ["Open this URL if needed:", editorUrl] : []
+    ];
+    if (lines.length > 0) {
+      return lines.join("\n");
+    }
+  }
+  return JSON.stringify(payload, null, 2);
+}
+function formatToolErrorText(code, message, data) {
+  const lines = [`${code}: ${message}`];
+  const suggestion = asString4(data?.suggestion);
+  const editorUrl = asString4(data?.editorUrl);
+  if (suggestion) {
+    lines.push(`hint: ${suggestion}`);
+  }
+  if (editorUrl) {
+    lines.push("Open this URL if needed:");
+    lines.push(editorUrl);
+  }
+  return lines.join("\n");
+}
+function isObjectRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function asObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
 }
@@ -6401,12 +6605,14 @@ var LocalEditorHostImpl = class {
   sessionIdleTimeoutMs;
   tempFileTtlMs;
   cleanupIntervalMs;
+  registryFilePath;
   sessions = /* @__PURE__ */ new Map();
   pathSessionIds = /* @__PURE__ */ new Map();
   server;
   listeningPort;
   tempDir;
   cleanupTimer;
+  attachedBaseUrl;
   constructor(options) {
     this.host = options.host?.trim() || DEFAULT_HOST;
     this.port = options.port ?? DEFAULT_PORT;
@@ -6426,12 +6632,13 @@ var LocalEditorHostImpl = class {
       options.cleanupIntervalMs,
       DEFAULT_CLEANUP_INTERVAL_MS
     );
+    this.registryFilePath = path3.join(tmpdir(), `zuiku-mcp-host-${slug2(`${this.host}-${this.port}`)}.json`);
   }
   getBaseUrl() {
-    return `http://${this.host}:${this.listeningPort}`;
+    return this.attachedBaseUrl ?? `http://${this.host}:${this.listeningPort}`;
   }
   async ensureStarted() {
-    if (this.server?.listening) {
+    if (this.server?.listening || this.attachedBaseUrl) {
       return;
     }
     const server = createServer((request, response) => {
@@ -6443,21 +6650,37 @@ var LocalEditorHostImpl = class {
         });
       });
     });
-    await new Promise((resolve, reject) => {
-      server.once("error", reject);
-      server.listen(this.port, this.host, () => {
-        server.off("error", reject);
-        resolve();
+    try {
+      await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(this.port, this.host, () => {
+          server.off("error", reject);
+          resolve();
+        });
       });
-    });
+    } catch (error) {
+      if (await this.tryAttachToRunningHost(error)) {
+        return;
+      }
+      if (isAddressInUseError(error)) {
+        throw buildPortInUseJsonError(this.host, this.port, this.editorUrl);
+      }
+      throw error;
+    }
     const address = server.address();
     if (address && typeof address === "object") {
       this.listeningPort = address.port;
     }
     this.server = server;
+    this.attachedBaseUrl = void 0;
+    await this.writeRegistryFile();
     this.startCleanupTimer();
   }
   async stop() {
+    if (this.attachedBaseUrl && !this.server) {
+      this.attachedBaseUrl = void 0;
+      return;
+    }
     this.stopCleanupTimer();
     if (this.server) {
       await new Promise((resolve, reject) => {
@@ -6471,6 +6694,8 @@ var LocalEditorHostImpl = class {
       }).catch(() => void 0);
       this.server = void 0;
     }
+    this.attachedBaseUrl = void 0;
+    await this.removeRegistryFileIfOwned().catch(() => void 0);
     const tempDir = this.tempDir;
     const records = [...this.sessions.values()];
     this.sessions.clear();
@@ -6487,6 +6712,9 @@ var LocalEditorHostImpl = class {
   }
   async openSession(request) {
     await this.ensureStarted();
+    if (this.attachedBaseUrl && !this.server) {
+      return this.openSessionViaAttachedHost(request);
+    }
     const nowIso = (/* @__PURE__ */ new Date()).toISOString();
     const nowMs = Date.now();
     if (request.path && request.markdown) {
@@ -6595,6 +6823,108 @@ var LocalEditorHostImpl = class {
       reusedSession
     };
   }
+  async tryAttachToRunningHost(error) {
+    if (!isAddressInUseError(error)) {
+      return false;
+    }
+    const registry = await this.readRegistryFile();
+    if (!registry) {
+      return false;
+    }
+    if (registry.baseUrl !== `http://${this.host}:${this.port}`) {
+      return false;
+    }
+    const response = await fetch(`${registry.baseUrl}/health`).catch(() => void 0);
+    if (!response?.ok) {
+      await rm(this.registryFilePath, { force: true }).catch(() => void 0);
+      return false;
+    }
+    const health = await response.json().catch(() => void 0);
+    if (!health || health.ok !== true || health.host !== registry.baseUrl) {
+      await rm(this.registryFilePath, { force: true }).catch(() => void 0);
+      return false;
+    }
+    this.attachedBaseUrl = registry.baseUrl;
+    this.sessionToken = registry.sessionToken;
+    this.listeningPort = this.port;
+    return true;
+  }
+  async openSessionViaAttachedHost(request) {
+    const response = await fetch(`${this.getBaseUrl()}/sessions?mcpToken=${encodeURIComponent(this.sessionToken)}`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        ...request.path ? { path: request.path } : {},
+        ...typeof request.markdown === "string" ? { markdown: request.markdown } : {},
+        ...request.title ? { title: request.title } : {},
+        ...typeof request.openInBrowser === "boolean" ? { openInBrowser: request.openInBrowser } : {}
+      })
+    }).catch((error) => {
+      const message = error instanceof Error ? error.message : "failed to reach running editor host";
+      throw jsonError(503, "invalid_request", message);
+    });
+    const payload = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      throw jsonError(
+        response.status,
+        payload.code ?? "invalid_request",
+        payload.message ?? "failed to open session through running editor host"
+      );
+    }
+    if (typeof payload.sessionId !== "string" || typeof payload.path !== "string" || typeof payload.hash !== "string" || typeof payload.bytes !== "number" || typeof payload.createdAt !== "string" || typeof payload.updatedAt !== "string" || typeof payload.editorUrl !== "string" || typeof payload.openedInEditor !== "boolean" || typeof payload.reusedSession !== "boolean" || payload.source !== "path" && payload.source !== "markdown") {
+      throw jsonError(502, "invalid_request", "running editor host returned invalid session payload");
+    }
+    return {
+      sessionId: payload.sessionId,
+      source: payload.source,
+      path: payload.path,
+      hash: payload.hash,
+      bytes: payload.bytes,
+      createdAt: payload.createdAt,
+      updatedAt: payload.updatedAt,
+      editorUrl: payload.editorUrl,
+      openedInEditor: payload.openedInEditor,
+      reusedSession: payload.reusedSession
+    };
+  }
+  async readRegistryFile() {
+    const raw = await readFile2(this.registryFilePath, "utf8").catch(() => void 0);
+    if (!raw) {
+      return void 0;
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed.baseUrl !== "string" || typeof parsed.sessionToken !== "string" || typeof parsed.editorUrl !== "string" || typeof parsed.ownerPid !== "number") {
+        return void 0;
+      }
+      return {
+        baseUrl: parsed.baseUrl,
+        sessionToken: parsed.sessionToken,
+        editorUrl: parsed.editorUrl,
+        ownerPid: parsed.ownerPid
+      };
+    } catch {
+      return void 0;
+    }
+  }
+  async writeRegistryFile() {
+    const payload = {
+      baseUrl: this.getBaseUrl(),
+      sessionToken: this.sessionToken,
+      editorUrl: this.editorUrl,
+      ownerPid: process.pid
+    };
+    await writeFile2(this.registryFilePath, JSON.stringify(payload), "utf8");
+  }
+  async removeRegistryFileIfOwned() {
+    const registry = await this.readRegistryFile();
+    if (!registry || registry.ownerPid !== process.pid) {
+      return;
+    }
+    await rm(this.registryFilePath, { force: true }).catch(() => void 0);
+  }
   async handleRequest(request, response) {
     try {
       this.ensureLoopbackClient(request);
@@ -7021,6 +7351,22 @@ function asString5(value) {
 function asBoolean2(value) {
   return typeof value === "boolean" ? value : void 0;
 }
+function isAddressInUseError(error) {
+  return typeof error === "object" && error !== null && "code" in error && error.code === "EADDRINUSE";
+}
+function buildPortInUseJsonError(host, port, editorUrl) {
+  return jsonError(
+    409,
+    "conflict",
+    `editor host port ${host}:${port} is already in use by another process`,
+    {
+      host,
+      port,
+      editorUrl,
+      suggestion: "Stop the other process or set ZUIKU_MCP_EDITOR_PORT to a different free port."
+    }
+  );
+}
 function isJsonError(value) {
   return typeof value === "object" && value !== null && "status" in value && "code" in value;
 }
@@ -7102,9 +7448,9 @@ function isMainModule(currentModuleUrl) {
 }
 
 // ../../scripts/zuiku-mcp-server.ts
-var SERVER_NAME = "zuiku-mcp-min";
-var SERVER_VERSION = "0.3.0";
-var PROTOCOL_VERSION = "2024-11-05";
+var SERVER_NAME = ZUIKU_MCP_SERVER_NAME;
+var SERVER_VERSION = ZUIKU_MCP_PACKAGE_VERSION;
+var PROTOCOL_VERSION = ZUIKU_MCP_PROTOCOL_VERSION;
 var allowedRoots = resolveAllowedRoots();
 var editorHostEnabled = parseBooleanEnv2(process.env.ZUIKU_MCP_ENABLE_EDITOR_HOST, true);
 var localEditorHost = editorHostEnabled ? createLocalEditorHost({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zuiku-mcp",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Round-trip Diagram Editor MCP server for Zuiku",
   "type": "module",
   "license": "UNLICENSED",