diff --git a/README.md b/README.md index ba378c38..efa465fe 100644 --- a/README.md +++ b/README.md @@ -92,6 +92,8 @@ Download the Windows, macOS or Linux installer from the [Releases page](https:// ### In your AI agent (MCP) +https://github.com/user-attachments/assets/6f53a67b-ab21-4113-9fee-7fb32f9de678 + Through MCP (Model Context Protocol, the protocol AI agents use to call outside tools), Claude Desktop, Cursor, VS Code and others can draw draw.io diagrams directly. Add this to your client's MCP configuration: ```json diff --git a/docs/cn/README_CN.md b/docs/cn/README_CN.md index 1440c61b..69a256aa 100644 --- a/docs/cn/README_CN.md +++ b/docs/cn/README_CN.md @@ -92,6 +92,8 @@ https://github.com/user-attachments/assets/66b9f12f-219f-4d62-acc0-0725e6850eec ### 在 AI 代理里使用（MCP） +https://github.com/user-attachments/assets/6f53a67b-ab21-4113-9fee-7fb32f9de678 + 通过 MCP（Model Context Protocol，让 AI 代理调用外部工具的协议），Claude Desktop、Cursor、VS Code 等都能直接画 draw.io 图。在客户端的 MCP 配置里加上： ```json diff --git a/docs/ja/README_JA.md b/docs/ja/README_JA.md index fdf2443f..f4f64019 100644 --- a/docs/ja/README_JA.md +++ b/docs/ja/README_JA.md @@ -92,6 +92,8 @@ Web アプリ、Windows / macOS / Linux 向けデスクトップアプリ、そ ### AI エージェントから使う（MCP） +https://github.com/user-attachments/assets/6f53a67b-ab21-4113-9fee-7fb32f9de678 + MCP（Model Context Protocol、AI エージェントが外部ツールを呼び出すためのプロトコル）を通して、Claude Desktop、Cursor、VS Code などから直接 draw.io のダイアグラムを描けます。クライアントの MCP 設定に次を追加します。 ```json diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.md index b9b9d243..b4c77297 100644 --- a/packages/mcp-server/README.md +++ b/packages/mcp-server/README.md @@ -1,272 +1,127 @@ # Next AI Draw.io MCP Server -MCP (Model Context Protocol) server that enables AI agents like Claude Desktop and Cursor to generate and edit draw.io diagrams with **real-time browser preview**. +An MCP server that lets Claude Code, Cursor, VS Code and other AI agents draw draw.io diagrams from your project's files, with a live preview in your browser. The preview is the canvas of the [Next AI Draw.io web app](https://next-ai-drawio.jiang.jp/): the AI's changes are outlined, Ctrl+Z takes them back, and you can edit by hand at any time. -**Self-contained**: the embedded HTTP server and the draw.io editor are in the package, so after install the preview works offline. +https://github.com/user-attachments/assets/6f53a67b-ab21-4113-9fee-7fb32f9de678 -## Quick Start +## Install -```json -{ - "mcpServers": { - "drawio": { - "command": "npx", - "args": ["@next-ai-drawio/mcp-server@latest"] - } - } -} +### Let your AI agent install it + +Paste this into Claude Code, Codex, Cursor, VS Code, Cline or any agent that can edit files and run commands: + +```text +Install the drawio MCP server for the client you are running in, following +https://raw.githubusercontent.com/DayuanJiang/next-ai-draw-io/main/packages/mcp-server/README.md +Name the server "drawio" and keep the servers that are already configured. +Then tell me how to reload so its tools show up. ``` -## Installation +### Install by hand -### Claude Desktop - -Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS): - -```json -{ - "mcpServers": { - "drawio": { - "command": "npx", - "args": ["@next-ai-drawio/mcp-server@latest"] - } - } -} -``` - -### VS Code - -Add to your VS Code settings (`.vscode/mcp.json` in workspace or user settings): - -```json -{ - "mcpServers": { - "drawio": { - "command": "npx", - "args": ["@next-ai-drawio/mcp-server@latest"] - } - } -} -``` - -### Cursor - -Add to Cursor MCP config (`~/.cursor/mcp.json`): - -```json -{ - "mcpServers": { - "drawio": { - "command": "npx", - "args": ["@next-ai-drawio/mcp-server@latest"] - } - } -} -``` - -### Cline (VS Code Extension) - -1. Click the **MCP Servers** icon in Cline's top menu bar -2. Select the **Configure** tab -3. Click **Configure MCP Servers** to edit `cline_mcp_settings.json` -4. Add the drawio server: - -```json -{ - "mcpServers": { - "drawio": { - "command": "npx", - "args": ["@next-ai-drawio/mcp-server@latest"] - } - } -} -``` - -### Claude Code CLI +**Claude Code** ```bash claude mcp add drawio -- npx @next-ai-drawio/mcp-server@latest ``` -### Other MCP Clients +**Codex CLI** -Use the standard MCP configuration with: -- **Command**: `npx` -- **Args**: `["@next-ai-drawio/mcp-server@latest"]` - -## Usage - -1. Restart your MCP client after updating config -2. Ask the AI to create a diagram: - > "Create a flowchart showing user authentication with login, MFA, and session management" - - > "Read docs/architecture.md and draw the system as a diagram" -3. The diagram appears in your browser in real-time! - -## Features - -- **Real-time Preview**: Diagrams appear and update in your browser as the AI creates them. The preview is the web app's canvas: a change the AI makes to the page on screen is outlined, and one Ctrl+Z takes it back -- **Selection**: Select shapes in the preview and say "move these" or "connect this box to that one"; the AI reads what you selected with `get_selection` -- **Drawing Rules**: The AI gets the same layout, edge and style rules as the web app, plus the shape library docs (AWS, Azure, GCP, Kubernetes, Cisco and more), so it uses real icon names instead of guessing -- **Self-check**: The AI can take a screenshot of the rendered diagram (`screenshot: true` on `create_new_diagram` or `edit_diagram`, or `screenshot_diagram`) and fix overlapping shapes or edges that cross shapes -- **Draw from Your Files**: ask the AI to draw from a document, image or web page; it reads the source with the host's own tools and draws. Existing .drawio files open with load_diagram -- **Edit Support**: Modify existing diagrams with natural language instructions. If any change in an edit fails, nothing is written and the AI gets the reason and the current page XML -- **Your Edits Are Kept**: Changes you make in the browser are read before the AI edits again. If the AI overwrites a change you were still making, your version is saved in History -- **Version History**: The last 20 versions appear as cards next to the canvas, with a thumbnail and what changed. Restore one, undo and redo the latest, or compare a version with the canvas; or ask the AI to undo (`restore_version`) -- **Export**: Save as `.drawio`, `.png`, `.svg`, or `.drawio.svg` (an SVG with the diagram embedded, which draw.io and `load_diagram` can open again) through `export_diagram`, or from the download button in the preview's header -- **Multi-page**: List, add, rename, and delete pages, and edit any page -- **Auto-save**: Each session's diagram is saved to `~/.next-ai-drawio/.drawio`, and its last 20 versions to `.history.json`, so the diagram, History and undo survive a restart of the MCP client -- **Custom Instructions**: keep your own drawing rules in `~/.next-ai-drawio/instructions.md` (for example "Always draw in minimal style"); they are appended to the drawing guide on every call -- **Themes and Dark Mode**: Pick a draw.io theme under **Extras > Theme**; the button at the top right switches the page and the editor between light and dark (the system setting until you choose). `DRAWIO_UI`, `DRAWIO_DARK` and `DRAWIO_LANG` fix them -- **Self-contained**: The draw.io editor ships inside the package and is served from the preview's own origin, so after install the preview works offline. `DRAWIO_BASE_URL` points it at another draw.io instead - -## Available Tools - -| Tool | Description | -|------|-------------| -| `start_session` | Opens browser with real-time diagram preview; the result includes the drawing rules. Pass `session_id` to continue a saved diagram | -| `list_saved_diagrams` | List the auto-saved diagrams of earlier sessions, newest first, with their pages | -| `get_drawing_guide` | Return the drawing rules again, for example after a long conversation was compacted, or, with `topic`, a short XML reference for tables, layers or groups | -| `get_shape_library` | Return the shapes and icon styles of a library such as `aws4`, `azure2`, or `kubernetes` | -| `create_new_diagram` | Create a new diagram from XML; a plain list of `mxCell` elements is enough | -| `load_diagram` | Load a `.drawio` or `.drawio.svg` file into the session, from a `path` on disk or from its `xml` content (handles compressed files) | -| `edit_diagram` | Edit diagram by ID-based operations (update/add/delete cells); all or nothing | -| `get_diagram` | Get the current diagram XML, including your edits in the browser | -| `get_selection` | Return the shapes and edges you selected in the preview (ids, labels, positions), so the AI can act on "these" | -| `screenshot_diagram` | Return a PNG of a page so the AI can check the rendered diagram | -| `export_diagram` | Save diagram to a `.drawio`, `.png`, `.svg`, or `.drawio.svg` file | -| `list_pages` | List every page (tab) with id, name, index, and cell count | -| `add_page` | Append a new page without touching existing ones | -| `rename_page` | Rename a page | -| `delete_page` | Delete a page (refuses to delete the last one) | -| `restore_version` | Undo: put an earlier version from History back on the canvas; the current one is kept, so a redo is possible | - -## Continue a Diagram Later - -After every change, the diagram is saved as a normal `.drawio` file in `~/.next-ai-drawio/`, named after the session id (for example `mcp-mgd0a1b2-x7k2p1.drawio`). `start_session` tells the AI both the id and the file path. - -To continue a diagram in a later conversation (for example after `claude --resume`, or in a new chat), the AI calls `start_session` with `session_id` set to that id: the same preview URL opens, the saved diagram is shown, and auto-save keeps writing to the same file. If the id is no longer in the conversation, `list_saved_diagrams` returns every saved diagram, newest first, with the names and cell counts of its pages, so you can ask for "the architecture diagram from yesterday" and let the AI pick it. `load_diagram` with the file path still works too, and you can open the file in draw.io yourself. - -History comes back with the diagram: the last 20 versions are saved next to it in `.history.json` (without thumbnails). When the AI continues the session with `start_session` and its `session_id`, or a preview tab is still open after a restart, the version cards show them again and `restore_version` can undo to them. - -The newest 50 files are kept, each with its History file. Set `DRAWIO_DATA_DIR` to use another folder, or to `off` to turn auto-save off. - -## Custom Instructions - -To give the AI your own drawing rules, write them in `~/.next-ai-drawio/instructions.md` as Markdown, for example "Always draw in minimal style" or "Label every edge". The file is appended to the drawing guide under a `## Custom Instructions` heading each time the guide is returned (`start_session`, `get_drawing_guide` and the `diagram-workflow` prompt), so edits apply without restarting your MCP client. Only the first 5000 characters are used. - -`DRAWIO_DATA_DIR` changes the folder the file is read from; with `DRAWIO_DATA_DIR=off` the default folder is still used, since the file is only read. The text reaches the model as it is, so keep it to drawing rules you trust. - -## How It Works - -``` -┌─────────────────┐ stdio ┌─────────────────┐ -│ Claude Desktop │ <───────────> │ MCP Server │ -│ (AI Agent) │ │ (this package) │ -└─────────────────┘ └────────┬────────┘ - │ - ┌────────▼────────┐ - │ Embedded HTTP │ - │ Server (:6002) │ - └────────┬────────┘ - │ - ┌────────▼────────┐ - │ User's Browser │ - │ (draw.io embed) │ - └─────────────────┘ +```bash +codex mcp add drawio -- npx @next-ai-drawio/mcp-server@latest ``` -1. **MCP Server** receives tool calls from Claude via stdio -2. **Embedded HTTP Server** serves the preview page and the draw.io editor, and handles state -3. **Browser** shows real-time diagram updates via polling - -The server listens on `127.0.0.1` only. Every `/api` request must carry a token that the server generates at start and writes into the preview page, so another website open in the same browser cannot read or change the diagram; the preview page also refuses to be embedded in other pages. Opening the preview URL in another browser on the same machine works, since the page comes with the token. - -## Configuration - -| Variable | Default | Description | -|----------|---------|-------------| -| `PORT` | `6002` | Port for the embedded HTTP server | -| `DRAWIO_BASE_URL` | unset (the bundled draw.io) | An external draw.io for the preview, such as a self-hosted instance (see below). The page cannot reach into an editor from another origin, so with it the AI's changes are not outlined, Ctrl+Z does not take them back and `get_selection` cannot read the selection. The version cards and everything else keep working. | -| `DRAWIO_DATA_DIR` | `~/.next-ai-drawio` | Folder for the auto-saved `.drawio` files and your `instructions.md`. Set to `off` to turn auto-save off (`instructions.md` is then read from the default folder). | -| `DRAWIO_LANG` | unset | Language of the draw.io editor and of the preview's own texts. Unset, the preview's texts follow the browser language, and draw.io chooses: English on the bundled copy until the user picks one under **Extras > Language**, the browser language on `embed.diagrams.net`. A code such as `en`, `zh`, `zh-tw`, `ja` or `de` fixes both and hides that submenu. | -| `DRAWIO_UI` | unset | draw.io theme. Unset, the user picks one under **Extras > Theme** and draw.io remembers it. `kennedy`, `atlas`, `dark`, `min`, `sketch` or `simple` fixes the theme and hides that menu. | -| `DRAWIO_DARK` | `auto` | Dark mode of the preview and the editor until the user switches it with the button at the top right (the browser remembers that choice): `auto` follows the system, `1` starts dark, `0` starts light. | -| `DRAWIO_PREVIEW_UI` | `shell` | The preview page `start_session` opens. `classic` opens the previous preview page (see [Classic preview page](#classic-preview-page)). | -| `DRAWIO_AUTO_SCREENSHOT` | unset | Set to `true` to attach a screenshot to every `create_new_diagram` and `edit_diagram` result, so the AI checks each drawing. Costs 2 to 10 s per call; the preview tab must be open and in front. A call can still pass `screenshot: false`. | -| `BROWSER` | unset | Set to `none` and `start_session` does not open the preview in the system browser (the convention of Vite and Create React App dev servers); the result still names the URL. | -| `DEBUG` | unset | Set to `true` to log debug messages to stderr. | - -### Private Deployment (Self-hosted draw.io) - -For security-sensitive environments that require private deployment of draw.io: +**VS Code** (`.vscode/mcp.json`) ```json { - "mcpServers": { - "drawio": { - "command": "npx", - "args": ["@next-ai-drawio/mcp-server@latest"], - "env": { - "DRAWIO_BASE_URL": "https://drawio.your-company.com" - } - } + "servers": { + "drawio": { "type": "stdio", "command": "npx", "args": ["@next-ai-drawio/mcp-server@latest"] } } } ``` -You can deploy your own draw.io instance using the official Docker image: +**Cursor, Claude Desktop, Cline and most other clients** (`~/.cursor/mcp.json`, `claude_desktop_config.json`, `cline_mcp_settings.json`) + +```json +{ + "mcpServers": { + "drawio": { "command": "npx", "args": ["@next-ai-drawio/mcp-server@latest"] } + } +} +``` + +Restart the client, then ask, for example, "Read this repo and draw its architecture". The preview opens in your browser and the diagram appears as it is drawn. + +## Features + +- **Draws from your project**: the agent reads your code and documents with its own tools. Existing `.drawio` and `.drawio.svg` files open with `load_diagram`. +- **The web app's canvas**: the AI's changes are outlined and one Ctrl+Z takes them back. Select shapes and say "these" (`get_selection`). Your hand edits are read before the AI edits again. +- **Real icons**: the web app's drawing rules and shape libraries (AWS, Azure, GCP, Kubernetes, Cisco and more), so the AI uses real icon names. +- **Self-check**: the AI can look at a screenshot of the rendered diagram and fix overlaps (`screenshot: true`, or `screenshot_diagram`). +- **Versions**: the last 20 versions as cards next to the canvas; restore or compare one, or ask the AI to undo (`restore_version`). +- **Pages and export**: multi-page diagrams; save as `.drawio`, `.png`, `.svg` or `.drawio.svg`. +- **Offline**: the draw.io editor ships inside the package. + +## Saved diagrams + +Every change is saved to `~/.next-ai-drawio/.drawio` with its last 20 versions; the newest 50 diagrams are kept. To continue one in a later conversation, ask the AI for it: it finds it with `list_saved_diagrams` and reopens it with `start_session`. + +## Your own drawing rules + +Write them in `~/.next-ai-drawio/instructions.md`, for example "Always use a minimal style". They are added to the drawing guide on every call, so edits apply without a restart. The first 5000 characters are used. + +## Tools + +| Tool | What it does | +|---|---| +| `start_session` | Open the preview and return the drawing guide; `session_id` continues a saved diagram | +| `create_new_diagram` | Draw a new diagram from `mxCell` XML | +| `edit_diagram` | Add, update or delete cells by id, all or nothing | +| `get_diagram` | The current XML, including your edits in the browser | +| `get_selection` | The shapes you selected in the preview | +| `screenshot_diagram` | A PNG of a page, for the AI to check | +| `load_diagram`, `export_diagram` | Open a `.drawio` or `.drawio.svg` file; save `.drawio`, `.png`, `.svg` or `.drawio.svg` | +| `restore_version` | Go back to an earlier version; a redo stays possible | +| `list_saved_diagrams` | Diagrams saved by earlier sessions, newest first | +| `get_drawing_guide`, `get_shape_library` | The drawing rules again; the icon styles of a library such as `aws4` | +| `list_pages`, `add_page`, `rename_page`, `delete_page` | Pages (tabs) | + +## Configuration + +Environment variables, set in the client's `env` for the server: + +| Variable | Default | What it does | +|---|---|---| +| `PORT` | `6002` | Preview port; when it is taken, the next free one up to 6020 is used | +| `DRAWIO_DATA_DIR` | `~/.next-ai-drawio` | Folder for saved diagrams and `instructions.md`; `off` turns saving off | +| `DRAWIO_AUTO_SCREENSHOT` | unset | `true` attaches a screenshot to every create and edit result (2 to 10 s per call) | +| `DRAWIO_BASE_URL` | the bundled draw.io | Use another draw.io, such as a self-hosted one (see below) | +| `DRAWIO_LANG` | unset | Fix the editor and preview language: `en`, `zh`, `zh-tw`, `ja`, `de` and so on | +| `DRAWIO_UI` | unset | Fix the draw.io theme: `kennedy`, `atlas`, `dark`, `min`, `sketch` or `simple` | +| `DRAWIO_DARK` | `auto` | `1` starts dark, `0` starts light, `auto` follows the system | +| `BROWSER` | unset | `none` does not open the preview by itself; `start_session` still returns the URL | +| `DRAWIO_PREVIEW_UI` | `shell` | `classic` opens the previous preview page, without outlines, Ctrl+Z or `get_selection` | +| `DEBUG` | unset | `true` logs debug messages to stderr | + +### Self-hosted draw.io ```bash docker run -d -p 8080:8080 jgraph/drawio ``` -Then set `DRAWIO_BASE_URL=http://localhost:8080` (or your server's URL). The preview page loads nothing else from the internet, so with a local draw.io it works offline. One exception: shapes from the Material Design library show icons from `fonts.gstatic.com`. - -With an external draw.io the preview cannot reach into the editor (browsers keep pages and frames from other origins apart), so the AI's changes are not outlined on the canvas, Ctrl+Z does not take them back (use the version cards or `restore_version`), and `get_selection` cannot read what you selected. `start_session` tells the AI about this mode. - -Without `DRAWIO_BASE_URL` the preview uses the trimmed draw.io copy bundled with this package. It has the editor, the shape libraries, the templates, PlantUML and Mermaid; features that load more code when used (the org chart layout, for example) are not included. Set `DRAWIO_BASE_URL` to a full draw.io if you need them. - -Like the web app's bundled copy, it has no image proxy (`/drawio/proxy`): images from other websites, including the avatars in the Org Chart and Mind Map templates and the Arista icons in the network templates, show on the canvas only when online and are left out of PNG and SVG exports and version thumbnails. Insert such images from a file instead, or set `DRAWIO_BASE_URL` to a full draw.io (the `jgraph/drawio` Docker image includes the proxy). See [Offline deployment](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/docs/en/offline-deployment.md). - -### Classic preview page - -`DRAWIO_PREVIEW_UI=classic` opens the preview page of the previous releases: draw.io with a **History** dialog and a **Download** button, without the outline of the AI's changes, Ctrl+Z for them, the version cards, Compare and `get_selection`. It stays for one more release and is then removed. +Then set `DRAWIO_BASE_URL=http://localhost:8080`. The preview cannot reach into a draw.io from another origin, so the AI's changes are not outlined, Ctrl+Z does not take them back (use the version cards) and `get_selection` does not work. The bundled copy has no image proxy and leaves out a few features that load code on demand; see [Offline deployment](https://github.com/DayuanJiang/next-ai-draw-io/blob/main/docs/en/offline-deployment.md). ## Troubleshooting -### Port already in use +- **Blank preview in VS Code Simple Browser or Cursor's browser**: the page refuses to be embedded in other pages. Open the URL in a regular browser. +- **Screenshot or PNG/SVG export times out**: the preview tab renders them, and browsers slow down background tabs. Bring the tab to the front and try again. +- **"No active session"**: the AI has to call `start_session` first. +- **The preview does not update**: open the URL that `start_session` returned; its `?mcp=` part connects the page to the session. -If port 6002 is in use, the server will automatically try the next available port (up to 6020). +## How it works -Or set a custom port: -```json -{ - "mcpServers": { - "drawio": { - "command": "npx", - "args": ["@next-ai-drawio/mcp-server@latest"], - "env": { "PORT": "6003" } - } - } -} -``` - -### "No active session" - -Call `start_session` first to open the browser window. - -### Browser not updating - -Check that the browser URL has the `?mcp=` query parameter. The MCP session ID connects the browser to the server. - -### Screenshot or PNG/SVG export times out - -PNG and SVG files are rendered by draw.io in the preview tab. Browsers slow down tabs that stay in the background, so the tab may not answer in time. Bring the preview tab to the front and try again. - -### Preview is blank inside VS Code Simple Browser - -The preview page refuses to be embedded in other pages (it sends `Content-Security-Policy: frame-ancestors 'self'`), so in-editor browsers such as VS Code Simple Browser, Cursor's built-in browser or a port forward's "Preview in Editor" show a blank page. Open the Browser URL from the `start_session` result in a regular browser (Chrome, Edge, Firefox, Safari) instead. +The server talks to the agent over stdio and runs an HTTP server on `127.0.0.1` that serves the preview page and the bundled draw.io; the page polls it for changes. Every `/api` request needs a token that only the preview page has, so other websites cannot read or change your diagram. ## License diff --git a/packages/mcp-server/package-lock.json b/packages/mcp-server/package-lock.json index 08133d1d..19c5f9a5 100644 --- a/packages/mcp-server/package-lock.json +++ b/packages/mcp-server/package-lock.json @@ -1,12 +1,12 @@ { "name": "@next-ai-drawio/mcp-server", - "version": "0.4.0", + "version": "0.4.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@next-ai-drawio/mcp-server", - "version": "0.4.0", + "version": "0.4.1", "license": "Apache-2.0", "dependencies": { "@modelcontextprotocol/sdk": "^1.31.0", diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json index c50c798c..98958f18 100644 --- a/packages/mcp-server/package.json +++ b/packages/mcp-server/package.json @@ -1,6 +1,6 @@ { "name": "@next-ai-drawio/mcp-server", - "version": "0.4.0", + "version": "0.4.1", "description": "MCP server for Next AI Draw.io - AI-powered diagram generation with real-time browser preview", "type": "module", "main": "dist/index.js",