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.

Preview and licensing

• 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:

codex mcp add zuiku \
  --env ZUIKU_MCP_ALLOWED_ROOTS=$(pwd) \
  -- npx -y zuiku-mcp

More setup guides:

• Install: https://zuiku.dev/install
• Docs: https://zuiku.dev/docs

Entry command

npx -y zuiku-mcp

What it exposes

• zuiku.version: report the running package/server version and update hints
• zuiku.open: open an existing Zuiku markdown file, create a new file when path + markdown are both given, or open Mermaid-only / canonical Markdown in a temp session 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:

npx -y zuiku-mcp --version

Check the latest published npm version:

npm view zuiku-mcp version

Run the latest package one-shot:

npx -y zuiku-mcp@latest

Update a global install:

npm install -g zuiku-mcp@latest

Typical usage

• Codex CLI / Claude Code / Gemini CLI: register it as an MCP server command
• VS Code / Cursor: point MCP settings at npx -y zuiku-mcp
• IDE extensions: optional helper path that still launches the same MCP server

Common environment variables

• ZUIKU_MCP_ALLOWED_ROOTS: allowed file roots (: separated)
• 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: optional. Defaults to 1, which opens the web editor after zuiku.open and after zuiku.apply saves. Set 0 only when you want a quieter setup that relies on editorUrl
• ZUIKU_MCP_EDITOR_HOST / ZUIKU_MCP_EDITOR_PORT: host bind settings
• ZUIKU_EDITOR_URL: override only. By default, Zuiku uses the local-origin editor at http://127.0.0.1:<port>/editor
• ZUIKU_MCP_EDITOR_APP_DIR: advanced override for the bundled local editor assets directory

Open behavior

• zuiku.open returns an exact editorUrl
• The default editorUrl target is the local-origin editor at http://127.0.0.1:<port>/editor
• ZUIKU_EDITOR_URL is only for intentionally overriding that target, for example to https://zuiku.dev/editor
• If your client does not open it automatically, open that exact editorUrl
• Do not open bare /editor; it can show unrelated local state
• zuiku.open(path, markdown, openInBrowser=true) can create a new real file when the save path is already decided
• zuiku.open(markdown, openInBrowser=true) can start a temp session when the save path is not decided yet
• The result also includes healthUrl, which is the first place to check if loading fails
• The editor UI is served locally by default, and reads and writes the local markdown file through the 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/, editor-app/) 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
• The default setup opens the web editor automatically; set ZUIKU_MCP_OPEN_BROWSER=0 only when you want a quieter chat or CI flow
• When browser auto-open is enabled, zuiku.apply opens or reuses the web editor session after save by default
• In a quieter setup, zuiku.apply(openAfterApply=true) can still request opening or reusing the web editor session after save
• The published package includes the bundled local editor app used for the default local-origin /editor flow
• 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
• Docs: https://zuiku.dev/docs