@drawio/mcp 1.0.3 → 1.0.5

package/README.md

@@ -10,27 +10,7 @@ The official [draw.io](https://www.draw.io) MCP (Model Context Protocol) server
 - **URL support**: Fetch content from URLs automatically
 - **Customizable display**: Lightbox mode, dark mode, and more
 
-## Two Ways to Use
-
-### Option 1: MCP Server (Claude Desktop)
-
-Install and configure the MCP server for Claude Desktop. The server runs locally and can automatically open diagrams in your browser.
-
-### Option 2: Project Instructions (No MCP)
-
-Use draw.io diagram generation with custom project instructions - works in both Claude.ai and Claude Desktop without installing the MCP server. See [Using Project Instructions](#using-project-instructions-no-mcp) below.
-
-| Feature | MCP Server | Project Instructions |
-|---------|------------|----------------------|
-| Platform | Claude Desktop | Claude.ai & Claude Desktop |
-| Installation | Required | None |
-| System access | Opens browser automatically | No system access |
-| Link verification | Automatic | User can inspect link before clicking |
-| Complexity | More setup | Just paste instructions |
-
----
-
-## MCP Server Installation
+## Installation
 
 ### Using npx (recommended)
 
@@ -287,57 +267,69 @@ Product Database,database,
 4. The URL is returned to the LLM, which can present it to the user
 5. Opening the URL loads draw.io with the diagram ready to view/edit
 
-## Development
+## Alternative: Project Instructions (No MCP Required)
 
-```bash
-# Install dependencies
-npm install
+An alternative approach is available that works **without installing the MCP server**. Instead of using MCP tools, you add instructions to a Claude Project that teach Claude to generate draw.io URLs using Python code execution.
 
-# Run the server
-npm start
-```
+### Advantages
 
----
+- **No installation required** - works immediately in Claude.ai
+- **No desktop app needed** - works entirely in the browser
+- **Easy to use** - just add instructions to your Claude Project
+- **Privacy-friendly** - the generated URL uses a hash fragment (`#create=...`), which stays in the browser and is never sent to any server
 
-## Using Project Instructions (No MCP)
+### How to Install
 
-You can use draw.io diagram generation without installing the MCP server by using custom project instructions. This works in both Claude.ai (web) and Claude Desktop.
+1. Open your Claude Project settings
+2. Add the contents of [`src/claude-project-instructions.txt`](src/claude-project-instructions.txt) to your project instructions
+3. Ask Claude to create diagrams - it will generate clickable draw.io URLs
 
-**Advantages:**
+### How It Works
 
-- **No installation** - Just paste instructions into a project
-- **Works everywhere** - Claude.ai and Claude Desktop
-- **No system access** - Claude generates a link without accessing your computer
-- **Transparent** - You can inspect the generated URL before clicking
-- **Verifiable** - The link visibly points to `app.diagrams.net`
+The instructions teach Claude to:
+1. Generate diagram code (Mermaid, XML, or CSV)
+2. Execute Python code to compress and encode the diagram
+3. Output a clickable URL that opens draw.io with your diagram
 
-### Setup
+### Token Usage Note
 
-1. Create a new Project in Claude.ai or Claude Desktop
-2. In Project Settings, paste the contents of [`claude-project-instructions.txt`](./claude-project-instructions.txt) into the custom instructions
-3. Start a conversation and ask Claude to create diagrams
+The current instructions tell Claude to output the URL as a clickable link for user convenience. This has two considerations:
 
-### How It Works
+1. **Token count**: The URL can be long (especially for complex diagrams), which consumes output tokens
+2. **Character accuracy**: The URL contains base64-encoded data where even a single character change breaks the diagram. The instructions emphasize character-perfect accuracy, but if you experience issues with broken links, you can use the alternative ending below.
+
+### Alternative: Reference Script Output Only
 
-Claude creates an **HTML artifact** that:
-1. Generates Mermaid/CSV/XML diagram code based on your request
-2. Compresses the diagram data using pako.js (loaded from CDN)
-3. Shows a button to open draw.io with the diagram in lightbox mode
-4. In draw.io, hover to see the "Edit" button to open the full editor
+If you prefer not to have Claude re-type the URL (to save tokens or avoid potential character substitution issues), replace the last section of the instructions with:
+
+```
+## CRITICAL: URL Output Rules
 
-**Note:** The artifact uses draw.io's lightbox mode (`lightbox=1&dark=auto&border=10&edit=_blank`).
+**NEVER re-type, repeat, or copy the generated URL in your response.**
+
+After the Python script executes, simply tell the user:
+> "Click the URL in the code output above to open your diagram."
+
+Why: The URL contains base64-encoded data that can be corrupted when reproduced. The ONLY safe URL is the one printed directly by Python in the execution output.
+```
 
-### Example
+This approach requires users to click the URL in the code execution output rather than in Claude's response, but guarantees the URL is always correct.
 
-**You:** Create a flowchart for a user login process
+## Development
 
-**Claude:** *Creates an HTML artifact with an "Open in draw.io" button*
+```bash
+# Install dependencies
+npm install
 
----
+# Run the server
+npm start
+```
 
 ## Related Resources
 
 - [draw.io](https://www.draw.io) - Free online diagram editor
 - [draw.io Desktop](https://github.com/jgraph/drawio-desktop) - Desktop application
+- [@drawio/mcp on npm](https://www.npmjs.com/package/@drawio/mcp) - This package on npm
+- [drawio-mcp on GitHub](https://github.com/jgraph/drawio-mcp) - Source code repository
 - [Mermaid.js Documentation](https://mermaid.js.org/intro/)
 - [MCP Specification](https://modelcontextprotocol.io/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawio/mcp",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Official draw.io MCP server for LLMs - Open diagrams in draw.io editor",
   "type": "module",
   "main": "src/index.js",

package/src/claude-project-instructions.txt

@@ -0,0 +1,104 @@
+# Draw.io Diagram Generation
+
+When the user requests any visual diagram, use draw.io to create it.
+
+## Supported Diagrams
+
+Draw.io supports virtually any diagram type:
+- **Standard**: Flowcharts, org charts, mind maps, timelines, Venn diagrams
+- **Software**: UML (class, sequence, activity, use case), ERD, architecture diagrams
+- **Cloud/Infrastructure**: AWS, Azure, GCP, Kubernetes, network topology
+- **Engineering**: Electrical circuits, digital logic, P&ID, floor plans
+- **Business**: BPMN, value streams, customer journeys, SWOT
+- **UI/UX**: Wireframes, mockups, sitemaps
+- **And more**: Infographics, data flows, decision trees, etc.
+
+## Format Selection
+
+Choose the optimal format for the task:
+
+| Format | Best For |
+|--------|----------|
+| **Mermaid** | Flowcharts, sequences, ERD, Gantt, state diagrams, class diagrams |
+| **CSV** | Hierarchical data (org charts), bulk import from spreadsheets |
+| **XML** | Complex layouts, precise positioning, custom styling, icons, shapes |
+
+## URL Generation
+
+Execute this Python code to generate the draw.io URL:
+
+```python
+import json, zlib, base64
+from urllib.parse import quote
+
+# Set these variables:
+diagram_type = "mermaid"  # "mermaid", "xml", or "csv"
+diagram_code = """graph TD
+    A[Start] --> B[End]"""
+
+# Generate compressed URL (raw deflate with 4KB window for memory efficiency)
+encoded = quote(diagram_code, safe='')
+c = zlib.compressobj(9, zlib.DEFLATED, -15)  # -15 = raw deflate with 32KB window
+raw_deflate = c.compress(encoded.encode('utf-8')) + c.flush()
+data = base64.b64encode(raw_deflate).decode()
+
+payload = json.dumps({"type": diagram_type, "compressed": True, "data": data})
+url = f"https://app.diagrams.net/#create={quote(payload, safe='')}"
+print(url)
+```
+
+## Format Examples
+
+### Mermaid
+```
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action]
+    B -->|No| D[End]
+```
+
+### XML (draw.io native)
+```xml
+<mxGraphModel>
+  <root>
+    <mxCell id="0"/>
+    <mxCell id="1" parent="0"/>
+    <mxCell id="2" value="Box" style="rounded=1;fillColor=#d5e8d4;" vertex="1" parent="1">
+      <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
+    </mxCell>
+  </root>
+</mxGraphModel>
+```
+
+### CSV (hierarchical data)
+```
+# label: %name%
+# style: rounded=1;whiteSpace=wrap;html=1;
+# connect: {"from":"manager","to":"name","invert":true}
+# layout: auto
+name,manager
+CEO,
+CTO,CEO
+CFO,CEO
+```
+
+## Instructions
+
+1. When a diagram is requested, determine the best format
+2. Generate the diagram code
+3. Execute the Python code to create the URL
+4. Return the clickable URL to the user
+
+## CRITICAL: URL Output Rules
+
+**ABSOLUTELY ZERO TOLERANCE: When outputting the URL, you MUST reproduce it with 100% character-perfect accuracy.**
+
+- The URL is a cryptographic hash - changing even ONE character destroys it completely
+- DO NOT "fix" or "correct" anything - if it looks wrong, it is still correct
+- DO NOT substitute any characters: no `i`↔`I`, no `k`↔`u`, no `0`↔`O`, no `l`↔`1`, NOTHING
+- Copy the URL byte-for-byte, character-for-character, exactly as printed by Python
+- If you are uncertain about any character, output it EXACTLY as shown - never guess
+
+**THE LINK WILL BE COMPLETELY BROKEN AND USELESS IF YOU CHANGE EVEN A SINGLE CHARACTER.**
+
+After executing the script, output the URL exactly as a clickable link for the user.