# zuiku-mcp

> Public release artifact. Not open source. Use is subject to the included `LICENSE.txt`.

![Zuiku workflow demo](https://zuiku.dev/how-zuiku-works-demo-en.gif)

See the full demo on the web: https://zuiku.dev/?locale=en

Zuiku is a diagram editor that turns AI explanations and Markdown into editable diagrams, then lets you bring the refined result back into the same Markdown.
Humans work with the UI, while AI can read and write the same Markdown through MCP.

`zuiku-mcp` is the primary MCP server package for that workflow.

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.

## Licensing and usage terms

- `zuiku-mcp` is distributed as a release 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.
For the default setup, register `zuiku-mcp@latest` so the client picks up the newest published build:

```bash
codex mcp add zuiku \
  --env ZUIKU_MCP_ALLOWED_ROOTS="$(pwd)" \
  -- npx -y zuiku-mcp@latest
```

More setup guides:

- Install: `https://zuiku.dev/install`
- Docs: `https://zuiku.dev/docs`
- X: `https://x.com/kamotami_dev`

## Entry command

```bash
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 package version a fresh `npx` launch would run:

```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
```

After npm publishes a newer build, restart the client or IDE session so it launches the updated package. `zuiku.version` reports the server that is already running, while `npx -y zuiku-mcp --version` shows what a fresh launch resolves to.

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
- VS Code / Cursor: point MCP settings at `npx -y zuiku-mcp`
- IDE extensions: optional helper path that still launches the same MCP server
- Removing the npm package and removing IDE workspace MCP config are separate steps when you have also added `zuiku` to `.vscode/mcp.json` or `.cursor/mcp.json`

## Common use cases

- Turn AI explanations into diagrams for easier understanding
- Adjust diagrams managed in Markdown through the local editor
- Generate ER diagrams from DDL and refine them in the same round-trip workflow
- Keep AI and humans on the same Markdown source instead of splitting UI edits and file edits

## 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
- A temp session is still backed by a temporary `.md` file; it is just not the user's chosen final save location 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
- The first open can take a moment while the local bridge and browser are starting
- After a human edits the diagram in the editor, the AI should call `zuiku.read(path)` again before applying the next update
- If `zuiku.apply` returns `conflict`, that means the file changed after the last `zuiku.read(path)`. Call `zuiku.read(path)` again and retry with the returned hash. Do not treat that conflict as a local editor startup failure.

## Built-in AI guides

- `zuiku://guide/start-here`: read this first when an AI client is unsure how Zuiku opens or saves diagrams
- `zuiku://guide/temp-session-vs-file`: choose between a temporary session and a real `.md` file
- `zuiku://guide/format-guide`: short contract for fast-path sample creation, canonical markdown shape, and read-before-apply updates
- `zuiku://guide/flowchart-example`: minimal canonical Zuiku Markdown example for a small flowchart
- `zuiku://guide/edit-existing-guide`: read-before-apply flow for existing diagrams
- `zuiku://guide/er-from-ddl-guide`: DDL responsibility boundary for ER workflows

When in doubt, start with `zuiku://guide/start-here`, then only pull in the narrower guides you actually need.

## 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 package 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, starting with `zuiku://guide/start-here`
- 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
- 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`
- X: `https://x.com/kamotami_dev`
