@drawio/mcp 1.0.4 → 1.0.5

package/README.md

@@ -267,9 +267,53 @@ 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
 
-## Alternative: Project Instructions (Experimental)
+## Alternative: Project Instructions (No MCP Required)
 
-For an alternative approach that works without installing the MCP server, see the [Project Instructions discussion](https://github.com/jgraph/drawio-mcp/discussions/1). This approach uses Claude's Python sandbox to generate draw.io URLs, but has limitations due to a zlib compression bug.
+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.
+
+### 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
+
+### How to Install
+
+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
+
+### How It Works
+
+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
+
+### Token Usage Note
+
+The current instructions tell Claude to output the URL as a clickable link for user convenience. This has two considerations:
+
+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
+
+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
+
+**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.
+```
+
+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.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawio/mcp",
-  "version": "1.0.4",
+  "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.