mirror of
https://github.com/DayuanJiang/next-ai-draw-io.git
synced 2026-10-13 04:59:51 +08:00
Dayuan Jiang
77be43d996
* feat(mcp-server): list and resume saved diagram sessions start_session accepts an optional session_id to continue a saved diagram under the same preview URL and auto-save file, reporting the restored pages. New read-only tool list_saved_diagrams prints every auto-saved file newest first with its pages. Autosaver gains list() and dataDir(). INSTRUCTIONS and both READMEs mention the new tool. * feat(mcp-server): add restore_version tool for undo and redo from History Add the restore_version write tool so the model can put an earlier version from History back on the canvas (steps_back, default 1). The current canvas is kept in History unless it is the blank page, so a redo is possible. http-server.ts exports restoreHistoryEntry, shared by the HTTP restore endpoint and the tool; history.ts exports HistoryEntry and otherVersions (distinct versions other than the canvas, newest first). The drawing guide tells the model to call restore_version when the user asks to undo, and both READMEs document the tool. * feat(mcp-server): save the diagram History next to the auto-saved file The Autosaver writes each session's History (the XML of its last 20 versions, without thumbnails) to <session-id>.history.json beside the .drawio file, after the same 1 second delay and only when the entries changed. When a saved session is resumed after an idle timeout or a process restart, the saved History is loaded back before the diagram, so the History panel and restore_version keep working. Removing the oldest files also removes their History files. * fix(mcp-server): review fixes for saved sessions, undo tool, history on disk * fix(mcp-server): Codex review fixes for saved sessions, undo and History on disk - start_session resumes every saved file, also a cleared one or one of empty named pages, and decompresses pages draw.io compressed - History kept by a lost user edit or a recovering tab is saved too - A diagram cleared before its first save keeps its History on disk - The History file is written again after the 50-file cap removed it - restore_version compares versions like the edit gate (a bare mxGraphModel from the browser has no page name), checks the restore result, and says "none" when no version is left - The preview closes an open History list when the server state was recreated, since the entries got new ids - start_session's description mentions session_id * fix(mcp-server): compare History versions pairwise and tie restores to the server state Second Codex review of the History fixes: - One bare mxGraphModel in History no longer hides page renames in every comparison: names are left out only when one of the two is bare - A History list asked for before the server recreated the session is dropped, and a restore names the state its list belongs to; the server refuses one from a lost state (History ids change after a restart) * fix(mcp-server): restore from a History list with the state it was taken in Third Codex review: a restore sent the tab's current state, so an old list shown after a failed refresh passed the server's check. The list now keeps the state it came from, and the server refuses a missing (null) state too; only a tab of an older version, which sends none, is let through.
134 lines
4.8 KiB
Markdown
134 lines
4.8 KiB
Markdown
# Next AI Draw.io - Claude Code Plugin
|
|
|
|
AI-powered Draw.io diagram generation with real-time browser preview for Claude Code.
|
|
|
|
## Installation
|
|
|
|
### From Plugin Directory (Coming Soon)
|
|
|
|
Once approved, install via:
|
|
```
|
|
/plugin install next-ai-drawio
|
|
```
|
|
|
|
### Manual Installation
|
|
|
|
```bash
|
|
claude --plugin-dir /path/to/packages/claude-plugin
|
|
```
|
|
|
|
Or add the MCP server directly:
|
|
```bash
|
|
claude mcp add drawio -- npx @next-ai-drawio/mcp-server@latest
|
|
```
|
|
|
|
## Features
|
|
|
|
- **Real-time Preview**: Diagrams appear and update in your browser as Claude creates them
|
|
- **Drawing Rules and Shape Libraries**: Claude gets the web app's layout and style rules and the icon docs for AWS, Azure, GCP, Kubernetes and more
|
|
- **Self-check**: Claude can take a screenshot of the rendered diagram and fix what looks wrong
|
|
- **Draw from Your Files**: ask Claude to draw from a document, image or web page; it reads the source with its own tools and draws. Existing .drawio files open with load_diagram
|
|
- **Version History**: Restore one of the last 20 versions from the **History** button, shown as thumbnails
|
|
- **Natural Language**: Describe diagrams in plain text - flowcharts, architecture diagrams, etc.
|
|
- **Edit Support**: Modify existing diagrams with natural language instructions, including your own edits in the browser
|
|
- **Export**: Save diagrams as `.drawio`, `.png`, `.svg`, or `.drawio.svg` files
|
|
- **Auto-save**: Each diagram is saved to `~/.next-ai-drawio/`, so `claude --resume` can pick it up again
|
|
- **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
|
|
- **Self-contained**: Embedded server, no external dependencies required
|
|
|
|
## Use Case Examples
|
|
|
|
### 1. Create Architecture Diagrams
|
|
|
|
```
|
|
Generate an AWS architecture diagram with Lambda, API Gateway, DynamoDB,
|
|
and S3 for a serverless REST API
|
|
```
|
|
|
|
### 2. Flowchart Generation
|
|
|
|
```
|
|
Create a flowchart showing the CI/CD pipeline: code commit -> build ->
|
|
test -> staging deploy -> production deploy with approval gates
|
|
```
|
|
|
|
### 3. System Design Documentation
|
|
|
|
```
|
|
Design a microservices e-commerce system with user service, product catalog,
|
|
shopping cart, order processing, and payment gateway
|
|
```
|
|
|
|
### 4. Cloud Architecture (AWS/GCP/Azure)
|
|
|
|
```
|
|
Generate a GCP architecture diagram with Cloud Run, Cloud SQL, and
|
|
Cloud Storage for a web application
|
|
```
|
|
|
|
### 5. Sequence Diagrams
|
|
|
|
```
|
|
Create a sequence diagram showing OAuth 2.0 authorization code flow
|
|
between user, client app, auth server, and resource server
|
|
```
|
|
|
|
### 6. Draw From a Document
|
|
|
|
```
|
|
Read docs/architecture.md and draw the system as a diagram
|
|
```
|
|
|
|
### 7. Recreate a Sketch
|
|
|
|
```
|
|
Recreate the whiteboard photo at ~/Desktop/sketch.jpg as a clean draw.io diagram
|
|
```
|
|
|
|
## 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 |
|
|
| `get_shape_library` | Return the shapes and icon styles of a library such as `aws4` |
|
|
| `create_new_diagram` | Create a new diagram from XML |
|
|
| `load_diagram` | Load a `.drawio` file from disk |
|
|
| `edit_diagram` | Edit diagram by ID-based operations; all or nothing |
|
|
| `get_diagram` | Get the current diagram XML |
|
|
| `screenshot_diagram` | Return a PNG of a page so Claude can check the result |
|
|
| `export_diagram` | Save diagram to a `.drawio`, `.png`, `.svg`, or `.drawio.svg` file |
|
|
| `list_pages`, `add_page`, `rename_page`, `delete_page` | Work with multi-page diagrams |
|
|
| `restore_version` | Undo: go back to an earlier version from History (redo is possible too) |
|
|
|
|
## How It Works
|
|
|
|
```
|
|
Claude Code <--stdio--> MCP Server <--http--> Browser (draw.io)
|
|
```
|
|
|
|
1. Ask Claude to create a diagram
|
|
2. Claude calls `start_session` to open a browser window
|
|
3. Claude generates diagram XML and sends it to the browser
|
|
4. You see the diagram update in real-time!
|
|
|
|
## Configuration
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `PORT` | `6002` | Port for the embedded HTTP server |
|
|
| `DRAWIO_BASE_URL` | `https://embed.diagrams.net` | Base URL for draw.io (for self-hosted deployments) |
|
|
| `DRAWIO_DATA_DIR` | `~/.next-ai-drawio` | Folder for auto-saved diagrams and your `instructions.md`; `off` turns auto-save off (`instructions.md` is then read from the default folder) |
|
|
| `DEBUG` | unset | Set to `true` to log debug messages |
|
|
|
|
## Links
|
|
|
|
- [Homepage](https://next-ai-drawio.jiang.jp)
|
|
- [GitHub Repository](https://github.com/DayuanJiang/next-ai-draw-io)
|
|
- [MCP Server Documentation](https://github.com/DayuanJiang/next-ai-draw-io/tree/main/packages/mcp-server)
|
|
|
|
## License
|
|
|
|
Apache-2.0
|