zuiku-mcp 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.3.3
+
+- change the default editor URL from the dev-local `http://localhost:5173/editor` to `https://zuiku.dev/editor`
+- clarify that `zuiku.open` should use the returned exact `editorUrl`, not a bare `/editor`
+- refresh npm-facing metadata so the npm homepage points to the install guide and the package page explains the GitHub links it shows
+- replace `UNLICENSED` package metadata with package-local public preview terms via `LICENSE.txt` and README notice
+
+## 0.3.2
+
+- initial public `zuiku-mcp` npm package release

package/LICENSE.txt

@@ -0,0 +1,49 @@
+Zuiku MCP Preview License
+
+Copyright (c) 2026 Kamotami. All rights reserved.
+
+1. Limited License Grant
+
+Subject to the terms of this License, you may install, run, copy, and internally modify this package for:
+
+- personal use;
+- evaluation, testing, and internal review;
+- internal business workflows, including IDE, MCP, CI, automation, and documentation workflows; and
+- use by your employees, contractors, and agents acting on your behalf for the same internal purposes.
+
+No ownership rights are transferred to you.
+
+2. Restrictions
+
+You may not:
+
+- redistribute this package;
+- distribute modified versions or derivative works of this package;
+- provide this package, or its functionality, to third parties as a hosted service, SaaS offering, managed service, API, or similar external service;
+- sell, sublicense, resell, rent, lease, or otherwise commercialize this package as a standalone product or service;
+- use the Zuiku, Kamotami, or related names, logos, or marks without prior written permission; or
+- remove or obscure copyright, trademark, or license notices.
+
+3. Public Preview / Not Open Source
+
+This package is provided as a public preview release. It is source-available, but it is not open source. No rights are granted except as expressly stated in this License.
+
+4. Third-Party Components
+
+This package may include or depend on third-party components that are licensed under their own terms. Those terms continue to apply to the relevant third-party components.
+
+5. Termination
+
+Your rights under this License terminate automatically if you violate it. Upon termination, you must stop using the package and delete copies under your control, except where retention is required by law or internal recordkeeping policy.
+
+6. Disclaimer of Warranty
+
+THIS PACKAGE IS PROVIDED "AS IS" WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, WHETHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT.
+
+7. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, KAMOTAMI WILL NOT BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR PUNITIVE DAMAGES, OR FOR ANY LOSS OF DATA, PROFITS, GOODWILL, OR BUSINESS INTERRUPTION, ARISING OUT OF OR RELATED TO THIS PACKAGE OR THIS LICENSE.
+
+8. Future Versions
+
+Future versions of this package may be provided under different terms. This License applies only to the version distributed with it.

package/README.md

@@ -1,17 +1,36 @@
 # zuiku-mcp
 
+> Public preview release. Not open source. Use is subject to the included `LICENSE.txt`.
+
 `zuiku-mcp` is the primary MCP server package for Zuiku.
 
+Use it when you want an AI client such as Codex CLI, Claude Code, Gemini CLI, VS Code, or Cursor to read and write Zuiku Markdown, Mermaid diagrams, and exports through MCP.
+
 `npx -y zuiku-mcp` is the shared entrypoint that CLI clients, IDE MCP settings, and optional IDE extensions call behind the scenes. It is usually configured once and then launched automatically by the client.
 
-## What it exposes
+## Preview and licensing
 
-- `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
-- `zuiku.export`: export Markdown, PNG, or SVG
-- `zuiku.ddl_to_er`: turn an upstream-acquired DDL string into ER diagram payloads
+- `zuiku-mcp` is distributed as a public preview package for evaluation and internal workflow use
+- It is not open source, and no rights are granted except as stated in the included `LICENSE.txt`
+- Personal use, evaluation use, and internal business workflow use are allowed, including use by employees, contractors, and agents acting on your behalf for those internal purposes
+- Redistribution, distribution of modified versions, hosted-service use, resale, and unauthorized trademark use are prohibited
+- Future versions may be provided under different terms; the included `LICENSE.txt` applies to the version you received
+
+## Quick start
+
+Run this in the directory you want Zuiku to edit:
+
+```bash
+codex mcp add zuiku \
+  --env ZUIKU_MCP_ALLOWED_ROOTS=$(pwd) \
+  --env ZUIKU_MCP_OPEN_BROWSER=0 \
+  -- npx -y zuiku-mcp
+```
+
+More setup guides:
+
+- Install: `https://zuiku.dev/install`
+- Docs: `https://zuiku.dev/docs`
 
 ## Entry command
 
@@ -19,6 +38,15 @@
 npx -y zuiku-mcp
 ```
 
+## 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 in the Zuiku web editor backed by a localhost session host
+- `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
+- `zuiku.export`: export Markdown, PNG, or SVG
+- `zuiku.ddl_to_er`: turn an upstream-acquired DDL string into ER diagram payloads
+
 ## Version and update
 
 Check the currently installed package version:
@@ -54,18 +82,36 @@ npm install -g zuiku-mcp@latest
 ## Common environment variables
 
 - `ZUIKU_MCP_ALLOWED_ROOTS`: allowed file roots (`:` separated)
-- `ZUIKU_MCP_ENABLE_EDITOR_HOST`: `1` to enable the localhost editor host (default: `1`)
+- `ZUIKU_MCP_ENABLE_EDITOR_HOST`: `1` to enable the localhost session host that bridges the web editor to local files (default: `1`)
 - `ZUIKU_MCP_OPEN_BROWSER`: `1` to open the browser on `zuiku.open`
 - `ZUIKU_MCP_EDITOR_HOST` / `ZUIKU_MCP_EDITOR_PORT`: host bind settings
-- `ZUIKU_EDITOR_URL`: editor URL (default: `http://localhost:5173/editor`)
+- `ZUIKU_EDITOR_URL`: editor URL (default: `https://zuiku.dev/editor`)
+
+## Open behavior
+
+- `zuiku.open` returns an exact `editorUrl`
+- If your client does not open it automatically, open that exact `editorUrl`
+- Do not open bare `/editor`; it can show unrelated local state
+- The default editor target is `https://zuiku.dev/editor`
+- The editor UI is web-based, but reads and writes the local markdown file through a localhost session host
+- After a human edits the diagram in the editor, the AI should call `zuiku.read(path)` again before applying the next update
+
+## Why the npm page shows GitHub links
+
+- `homepage` points to Zuiku's install guide because npm users usually need setup first
+- `repository` points to the source repository, so npm can show a `Code` link
+- `bugs` points to GitHub Issues, so npm can show an issue/report link
+- The published npm package ships the runnable artifact (`bin/`, `dist/`) plus npm-facing docs files
+- Public npm distribution and public source-repository visibility are related but not the same decision; the current package intentionally links to the public source repo for preview visibility, transparency, and issue reporting
 
 ## 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
+- `zuiku.apply(openAfterApply=true)` can request opening or reusing the web editor session after save
 - Discovery guides are exposed over MCP resources/prompts so AI clients can avoid external lookup
+- For ER workflows, Zuiku converts the DDL string you give it; acquiring DDL itself belongs to the upstream AI environment or another tool
 - 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`

package/dist/zuiku-mcp-server.mjs

@@ -17,7 +17,7 @@ var MCP_TOOL_DEFINITIONS = [
   },
   {
     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.",
+    description: "Open a markdown file, canonical Zuiku Markdown, or Mermaid-only text in a web editor session backed by a localhost bridge. Mermaid-only input is normalized on save, and the result includes editorUrl.",
     inputSchema: {
       type: "object",
       properties: {
@@ -44,7 +44,7 @@ var MCP_TOOL_DEFINITIONS = [
   },
   {
     name: "zuiku.apply",
-    description: "Apply Mermaid-only or canonical Zuiku Markdown with hash conflict protection. The saved file is normalized to canonical Zuiku Markdown, and openAfterApply can open or reuse the local editor session.",
+    description: "Apply Mermaid-only or canonical Zuiku Markdown with hash conflict protection. The saved file is normalized to canonical Zuiku Markdown, and openAfterApply can open or reuse the web editor session backed by a localhost bridge.",
     inputSchema: {
       type: "object",
       properties: {
@@ -361,10 +361,11 @@ var GUIDE_TEXT_BY_TOPIC = {
     "",
     "- \u5165\u529B\u306F `Zuiku Markdown` \u307E\u305F\u306F `Mermaid\u5358\u4F53` \u3092\u53D7\u3051\u3089\u308C\u308B\u3002",
     "- \u4FDD\u5B58\u3068\u5171\u6709\u306E\u6B63\u898F\u5F62\u306F `H1 -> mermaid -> layout-json` \u306E Markdown 1\u30D5\u30A1\u30A4\u30EB\u3002",
-    "- `zuiku.open` \u306F editor session \u3092\u4F5C\u308A\u3001`editorUrl` \u3092\u8FD4\u3059\u3002",
+    "- `zuiku.open` \u306F Web editor \u3068 localhost session host \u3092\u3064\u306A\u3050 editor session \u3092\u4F5C\u308A\u3001`editorUrl` \u3092\u8FD4\u3059\u3002",
     "- `zuiku.apply` \u306F\u4FDD\u5B58\u6642\u306B\u6B63\u898F\u5F62\u3078\u5BC4\u305B\u308B\u3002",
     "- \u65E2\u5B58\u66F4\u65B0\u306F `zuiku.read -> zuiku.apply(expectedHash=...)`\u3002",
     "- `openAfterApply=true` \u3067 editor session \u306E\u518D\u5229\u7528\u307E\u305F\u306F\u65B0\u898F open \u3092\u8981\u6C42\u3067\u304D\u308B\u3002",
+    "- \u4EBA\u9593\u304C editor \u3067\u4FEE\u6B63\u3057\u305F\u5185\u5BB9\u3092 AI \u304C\u4F7F\u3046\u306B\u306F\u3001\u6B21\u306E\u66F4\u65B0\u524D\u306B `zuiku.read(path)` \u3067\u518D\u53D6\u5F97\u3059\u308B\u3002",
     "- DDL \u53D6\u5F97\u3084 DB \u63A5\u7D9A\u306F Zuiku \u306E\u8CAC\u52D9\u3067\u306F\u306A\u3044\u3002"
   ].join("\n"),
   "flowchart-example": [
@@ -410,6 +411,7 @@ var GUIDE_TEXT_BY_TOPIC = {
     "- Zuiku \u306F DB \u3078\u63A5\u7D9A\u3057\u306A\u3044\u3002`zuiku.ddl_to_er(ddl, ...)` \u3060\u3051\u3092\u62C5\u5F53\u3059\u308B\u3002",
     "- \u65B0\u898F\u306A\u3089 `zuiku.open(markdown, openInBrowser=true)`\u3002",
     "- \u65E2\u5B58\u66F4\u65B0\u306A\u3089 `zuiku.read -> zuiku.apply(mode, expectedHash, openAfterApply=true)`\u3002",
+    "- \u4EBA\u9593\u304C editor \u3067\u76F4\u3057\u305F\u3042\u3068\u306E\u518D\u7DE8\u96C6\u3082\u3001AI \u306F\u307E\u305A `zuiku.read(path)` \u3067\u6700\u65B0\u3092\u8AAD\u3080\u3002",
     "- `current-page` \u306F `targetDiagramId` \u5FC5\u9808\u3002",
     "- \u4FDD\u5B58\u7D50\u679C\u306F Zuiku Markdown \u6B63\u898F\u5F62\u3078\u5BC4\u308B\u3002"
   ].join("\n"),
@@ -421,6 +423,7 @@ var GUIDE_TEXT_BY_TOPIC = {
     "- \u5165\u529B\u306F Zuiku Markdown \u3067\u3082 Mermaid\u5358\u4F53\u3067\u3082\u3088\u3044\u3002",
     "- `zuiku.apply(path, markdown, expectedHash, mode, targetDiagramId?, openAfterApply=true)` \u3092\u4F7F\u3046\u3002",
     "- `replace` \u306F file \u5168\u4F53\u66F4\u65B0\u3001`current-page` \u306F diagram \u5358\u4F4D\u66F4\u65B0\u3002",
+    "- \u4EBA\u9593\u304C editor \u3067\u4FEE\u6B63\u3057\u305F\u3042\u3068\u306F\u3001AI \u304C\u6B21\u306B `zuiku.read(path)` \u3067\u6700\u65B0\u3092\u518D\u53D6\u5F97\u3057\u3066\u304B\u3089\u7D9A\u3051\u308B\u3002",
     "- \u4FDD\u5B58\u6642\u306F\u6B63\u898F Zuiku Markdown \u306B\u6B63\u898F\u5316\u3055\u308C\u308B\u3002"
   ].join("\n")
 };
@@ -3678,7 +3681,7 @@ function normalizeToZuikuMarkdown(markdown, options = {}) {
 }
 function resolveProjectTitleForExport(projectName) {
   const trimmed = projectName.trim();
-  if (trimmed.length === 0 || trimmed === "\u56F3\u80B2 MVP \u30B9\u30B1\u30EB\u30C8\u30F3") {
+  if (trimmed.length === 0 || trimmed === "\u56F3\u80B2 MVP \u30B9\u30B1\u30EB\u30C8\u30F3" || trimmed === "Zuiku MVP \u30B9\u30B1\u30EB\u30C8\u30F3") {
     return "Zuiku";
   }
   return trimmed;
@@ -5714,11 +5717,11 @@ function parseBearerToken(value) {
 // package.json
 var package_default = {
   name: "zuiku-mcp",
-  version: "0.3.2",
-  description: "Round-trip Diagram Editor MCP server for Zuiku",
+  version: "0.3.3",
+  description: "Public preview MCP server for Zuiku round-trip diagram editing",
   type: "module",
-  license: "UNLICENSED",
-  homepage: "https://zuiku.dev/docs",
+  license: "SEE LICENSE IN LICENSE.txt",
+  homepage: "https://zuiku.dev/install",
   bugs: {
     url: "https://github.com/kamotami/zuiku/issues"
   },
@@ -5748,7 +5751,9 @@ var package_default = {
   files: [
     "bin",
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE.txt"
   ],
   publishConfig: {
     access: "public"
@@ -6281,15 +6286,15 @@ function isMcpErrorCode(value) {
 }
 function buildEditorSessionMessage(opened) {
   if (opened.openedInEditor && opened.reusedSession) {
-    return "Reused the existing Zuiku editor session and requested it to open.";
+    return "Reused the existing Zuiku editor session and requested it to open. If the wrong page appeared, open the exact editorUrl instead of bare /editor.";
   }
   if (opened.openedInEditor) {
-    return "Requested the Zuiku editor session to open.";
+    return "Requested the Zuiku editor session to open. If the wrong page appeared, open the exact editorUrl instead of bare /editor.";
   }
   if (opened.reusedSession) {
-    return "Reused the existing Zuiku editor session. If your client did not open it automatically, use the editorUrl.";
+    return "Reused the existing Zuiku editor session. If your client did not open it automatically, use the exact editorUrl. Opening bare /editor may show unrelated local state.";
   }
-  return "Zuiku editor session is ready. 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 exact editorUrl. Opening bare /editor may show unrelated local state.";
 }
 function buildApplyResultMessage(options) {
   if (!options.openAfterApply) {
@@ -6578,14 +6583,14 @@ function asNonEmptyString3(value) {
 // ../../scripts/zuiku-local-editor-host.ts
 import { createHash as createHash2, randomUUID } from "node:crypto";
 import { createServer } from "node:http";
-import { mkdir as mkdir2, mkdtemp, readFile as readFile2, readdir, rm, stat as stat2, writeFile as writeFile2 } from "node:fs/promises";
+import { chmod, mkdir as mkdir2, mkdtemp, readFile as readFile2, readdir, rm, stat as stat2, writeFile as writeFile2 } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import path3 from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_PORT = 17731;
-var DEFAULT_EDITOR_URL = "http://localhost:5173/editor";
+var DEFAULT_EDITOR_URL = "https://zuiku.dev/editor";
 var MAX_BODY_BYTES = 5 * 1024 * 1024;
 var DEFAULT_SESSION_IDLE_TIMEOUT_MS = 60 * 60 * 1e3;
 var DEFAULT_TEMP_FILE_TTL_MS = 24 * 60 * 60 * 1e3;
@@ -6850,10 +6855,11 @@ var LocalEditorHostImpl = class {
     return true;
   }
   async openSessionViaAttachedHost(request) {
-    const response = await fetch(`${this.getBaseUrl()}/sessions?mcpToken=${encodeURIComponent(this.sessionToken)}`, {
+    const response = await fetch(`${this.getBaseUrl()}/sessions`, {
       method: "POST",
       headers: {
-        "Content-Type": "application/json"
+        "Content-Type": "application/json",
+        "X-Zuiku-Mcp-Token": this.sessionToken
       },
       body: JSON.stringify({
         ...request.path ? { path: request.path } : {},
@@ -6916,7 +6922,13 @@ var LocalEditorHostImpl = class {
       editorUrl: this.editorUrl,
       ownerPid: process.pid
     };
-    await writeFile2(this.registryFilePath, JSON.stringify(payload), "utf8");
+    await writeFile2(this.registryFilePath, JSON.stringify(payload), {
+      encoding: "utf8",
+      mode: 384
+    });
+    if (process.platform !== "win32") {
+      await chmod(this.registryFilePath, 384).catch(() => void 0);
+    }
   }
   async removeRegistryFileIfOwned() {
     const registry = await this.readRegistryFile();
@@ -7293,9 +7305,11 @@ function ensureMarkdownExtension(filePath) {
 }
 function buildEditorUrl(editorUrl, hostUrl, sessionId, sessionToken) {
   const target = new URL(editorUrl);
-  target.searchParams.set("mcpSession", sessionId);
-  target.searchParams.set("mcpHost", hostUrl);
-  target.searchParams.set("mcpToken", sessionToken);
+  const params = new URLSearchParams();
+  params.set("mcpSession", sessionId);
+  params.set("mcpHost", hostUrl);
+  params.set("mcpToken", sessionToken);
+  target.hash = params.toString();
   return target.toString();
 }
 function openBrowser(url) {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "zuiku-mcp",
-  "version": "0.3.2",
-  "description": "Round-trip Diagram Editor MCP server for Zuiku",
+  "version": "0.3.3",
+  "description": "Public preview MCP server for Zuiku round-trip diagram editing",
   "type": "module",
-  "license": "UNLICENSED",
-  "homepage": "https://zuiku.dev/docs",
+  "license": "SEE LICENSE IN LICENSE.txt",
+  "homepage": "https://zuiku.dev/install",
   "bugs": {
     "url": "https://github.com/kamotami/zuiku/issues"
   },
@@ -34,7 +34,9 @@
   "files": [
     "bin",
     "dist",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE.txt"
   ],
   "publishConfig": {
     "access": "public"