Skip to content

Agent skill that turns natural language, code, Terraform/K8s, SQL, OpenAPI, AsyncAPI, Protobuf and GraphQL sources into editable, tested draw.io architecture diagrams: incremental sync, multi-view projection, drift diff, CI architecture tests, whiteboard derasterize, interactive HTML/PPTX/Mermaid exports.

feat: expose MCP build IR output and tighten workflow tests (#138)

Agents365.ai701e72833273
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8ac7a6a..727cc12 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,14 @@ semantic-ish versioning (the `metadata.version` field in
## [Unreleased]
+### Added
+
+- **MCP server: optional `ir_output` for `build`**: the `build` tool accepts an
+ `ir_output` path and forwards it as `--ir-output`, so a host can save the
+ Diagram IR in the same call and reuse it for `views`, `architecture_test`,
+ `query`, `whatif`, or `story`. The argument stays optional: without it only
+ the `.drawio` is written and the report's `ir` field is `null`.
+
### Fixed
- **MCP server: nonzero tool exits now set `isError`**: `architecture_test`
diff --git a/skills/drawio-skill/SKILL.md b/skills/drawio-skill/SKILL.md
index 72dd568..7916b6b 100644
--- a/skills/drawio-skill/SKILL.md
+++ b/skills/drawio-skill/SKILL.md
@@ -4,7 +4,7 @@ name: drawio-skill
description: Create and edit draw.io/diagrams.net diagrams as editable `.drawio` files. Covers architecture, UML/ERD/sequence, BPMN, network, and swimlane views authored from a description or converted from code, IaC, SQL, and API schemas, plus sync, query, test, review, export, and publish of existing diagrams. Use when the user asks for draw.io/diagrams.net or an editable diagram; prefer Mermaid/PlantUML when diagrams-as-code is enough.
license: MIT
allowed-tools: [Bash, Read, Write, WebFetch]
-metadata: {"openclaw":{"requires":{"anyBins":["python3"]},"emoji":"📐","os":["darwin","linux","win32"],"install":[{"id":"brew-drawio","kind":"brew","formula":"drawio","bins":["drawio"],"label":"Install draw.io for native exports","os":["darwin"],"optional":true},{"id":"brew-graphviz","kind":"brew","formula":"graphviz","bins":["dot"],"label":"Install Graphviz for automatic layout","os":["darwin"],"optional":true}]},"hermes":{"tags":["drawio","diagram","architecture","visualization","uml"],"category":"design","requires_tools":["python3"],"related_skills":["mermaid","excalidraw","plantuml"]},"author":"Agents365-ai","version":"3.4.1","homepage":"https://github.com/Agents365-ai/drawio-skill","compatibility":"Core IR, XML, sync, query, test, review, and Story workflows need Python 3 only; native export needs draw.io; Graphviz is optional.","platforms":["macos","linux","windows"]}
+metadata: {"openclaw":{"requires":{"anyBins":["python3"]},"emoji":"📐","os":["darwin","linux","win32"],"install":[{"id":"brew-drawio","kind":"brew","formula":"drawio","bins":["drawio"],"label":"Install draw.io for native exports","os":["darwin"],"optional":true},{"id":"brew-graphviz","kind":"brew","formula":"graphviz","bins":["dot"],"label":"Install Graphviz for automatic layout","os":["darwin"],"optional":true}]},"hermes":{"tags":["drawio","diagram","architecture","visualization","uml"],"category":"design","requires_tools":["python3"],"related_skills":["mermaid","excalidraw","plantuml"]},"author":"Agents365-ai","version":"3.4.2","homepage":"https://github.com/Agents365-ai/drawio-skill","compatibility":"Core IR, XML, sync, query, test, review, and Story workflows need Python 3 only; native export needs draw.io; Graphviz is optional.","platforms":["macos","linux","windows"]}
---
# Draw.io Architecture Studio
diff --git a/skills/drawio-skill/references/mcp.md b/skills/drawio-skill/references/mcp.md
index 0ae452f..7c1767a 100644
--- a/skills/drawio-skill/references/mcp.md
+++ b/skills/drawio-skill/references/mcp.md
@@ -43,6 +43,27 @@ Outputs are files (`.drawio`, `.html`, `.json`); tool results return the JSON
report or report text plus the written paths, so the host can open or attach
them.
+### Optional IR output
+
+`build` requires only `source` and `output`. Add `ir_output` to save the
+Diagram IR JSON that the other tools consume:
+
+```json
+{
+ "name": "build",
+ "arguments": {
+ "source": "/path/to/terraform",
+ "output": "/path/to/architecture.drawio",
+ "ir_output": "/path/to/architecture.ir.json"
+ }
+}
+```
+
+Without `ir_output`, `build` writes only the `.drawio` and the report's `ir`
+field is `null`; no IR file is created implicitly. With it, the `views`,
+`architecture_test`, `query`, `whatif`, and `story` tools can consume the same
+file.
+
## Behavior and safety
- Offline by default: no tool performs network access; native PNG export is
diff --git a/skills/drawio-skill/scripts/diagramctl_mcp.py b/skills/drawio-skill/scripts/diagramctl_mcp.py
index a845778..ccdf31c 100644
--- a/skills/drawio-skill/scripts/diagramctl_mcp.py
+++ b/skills/drawio-skill/scripts/diagramctl_mcp.py
@@ -64,6 +64,10 @@ TOOLS = [
{
"source": {"type": "string", "description": "Path to source dir/file"},
"output": {"type": "string", "description": "Output .drawio path"},
+ "ir_output": {
+ "type": "string",
+ "description": "Optional Diagram IR JSON output path",
+ },
"source_type": {
"type": "string",
"description": "Override auto-detection "
@@ -83,6 +87,7 @@ TOOLS = [
["source", "output"],
),
"argv": lambda a: ["build", a["source"], "-o", a["output"]]
+ + (["--ir-output", a["ir_output"]] if a.get("ir_output") else [])
+ (["--from", a["source_type"]] if a.get("source_type") else [])
+ (["--group"] if a.get("group") else [])
+ (["--views", a["views"]] if a.get("views") else [])
diff --git a/tests/test_mcp_server.py b/tests/test_mcp_server.py
index e2b13cd..b4e13e6 100644
--- a/tests/test_mcp_server.py
+++ b/tests/test_mcp_server.py
@@ -8,6 +8,7 @@ import sys
import tempfile
import unittest
from pathlib import Path
+from unittest import mock
HERE = Path(__file__).resolve().parent
SCRIPTS = HERE.parent / "skills" / "drawio-skill" / "scripts"
@@ -165,6 +166,14 @@ class TestMcpTools(unittest.TestCase):
self.assertEqual(tool["inputSchema"]["type"], "object")
self.assertIn("description", tool)
+ def test_build_schema_requires_only_source_and_output(self):
+ tools = rpc("tools/list")["result"]["tools"]
+ build = next(t for t in tools if t["name"] == "build")
+ self.assertEqual(["source", "output"], build["inputSchema"]["required"])
+ self.assertEqual(
+ "string", build["inputSchema"]["properties"]["ir_output"]["type"]
+ )
+
def test_doctor_call(self):
resp = rpc("tools/call", {"name": "doctor"})
result = resp["result"]
@@ -185,25 +194,57 @@ class TestMcpTools(unittest.TestCase):
"source": str(graph),
"output": str(out),
"source_type": "graph",
+ "ir_output": str(ir),
},
},
)
self.assertFalse(resp["result"]["isError"], resp["result"]["content"])
- self.assertTrue(out.exists())
- self.assertTrue(ir.exists() is False) # ir-output not requested
report = json.loads(resp["result"]["content"][0]["text"])
- self.assertEqual(report["nodes"], 2)
+ self.assertEqual(2, report["nodes"])
+ self.assertEqual(1, report["edges"])
+ self.assertEqual(str(ir), report["ir"])
+ self.assertTrue(out.exists())
+ self.assertTrue(ir.exists())
+ document = json.loads(ir.read_text(encoding="utf-8"))
+ self.assertEqual("drawio-skill/diagram-ir/v1", document["schema"])
+ self.assertEqual(["web", "db"], [n["id"] for n in document["nodes"]])
+ self.assertEqual(
+ [["web", "db"]],
+ [[e["source"], e["target"]] for e in document["edges"]],
+ )
+ resp = rpc(
+ "tools/call",
+ {"name": "architecture_test", "arguments": {"input": str(ir)}},
+ )
+ result = resp["result"]
+ self.assertFalse(result["isError"], result["content"])
+ findings = json.loads(result["content"][0]["text"])
+ self.assertEqual(0, findings["errors"])
+ self.assertEqual(0, findings["warnings"])
+ self.assertEqual([], findings["findings"])
+
+ def test_build_without_ir_output_writes_only_drawio(self):
+ with tempfile.TemporaryDirectory() as td:
+ graph = Path(td) / "graph.json"
+ graph.write_text(json.dumps(GRAPH))
+ out = Path(td) / "out.drawio"
resp = rpc(
"tools/call",
{
- "name": "architecture_test",
- "arguments": {"input": str(ir if ir.exists() else graph)},
+ "name": "build",
+ "arguments": {
+ "source": str(graph),
+ "output": str(out),
+ "source_type": "graph",
+ },
},
)
- # graph is not IR; the call must fail cleanly with isError, not crash
- if not resp["result"]["isError"]:
- self.assertIn("errors", resp["result"]["content"][0]["text"])
+ self.assertFalse(resp["result"]["isError"], resp["result"]["content"])
+ report = json.loads(resp["result"]["content"][0]["text"])
+ self.assertIsNone(report["ir"])
+ self.assertTrue(out.exists())
+ self.assertEqual([], sorted(Path(td).glob("*.ir.json")))
def test_bad_arguments_is_clean_error(self):
resp = rpc(
@@ -244,6 +285,24 @@ class TestMcpToolArgumentValidation(unittest.TestCase):
self.assertEqual(-32602, resp["error"]["code"])
self.assertIn("probe", resp["error"]["message"])
+ def test_wrong_type_ir_output_is_invalid_params(self):
+ for value in (5, ["out.ir.json"], True):
+ with mock.patch.object(mcp.subprocess, "run") as run:
+ resp = rpc(
+ "tools/call",
+ {
+ "name": "build",
+ "arguments": {
+ "source": "s.json",
+ "output": "o.drawio",
+ "ir_output": value,
+ },
+ },
+ )
+ self.assertEqual(-32602, resp["error"]["code"], value)
+ self.assertIn("ir_output", resp["error"]["message"])
+ run.assert_not_called()
+
def test_unknown_argument_is_invalid_params(self):
resp = rpc(
"tools/call",
@@ -376,10 +435,30 @@ class TestMcpStdioProcess(unittest.TestCase):
text=True,
timeout=60,
)
+ self.assertEqual(0, proc.returncode, proc.stderr)
+ self.assertEqual("", proc.stderr)
lines = [json.loads(line) for line in proc.stdout.splitlines() if line.strip()]
- self.assertEqual(len(lines), 2) # notifications produce no response
- self.assertEqual(lines[0]["result"]["serverInfo"]["name"], "drawio-skill")
- self.assertIn("tools", lines[1]["result"])
+ self.assertEqual(2, len(lines)) # notifications produce no response
+ self.assertEqual([1, 2], [line["id"] for line in lines])
+ self.assertEqual(["2.0", "2.0"], [line["jsonrpc"] for line in lines])
+ for line in lines:
+ self.assertIn("result", line)
+ self.assertEqual("drawio-skill", lines[0]["result"]["serverInfo"]["name"])
+ self.assertEqual("2024-11-05", lines[0]["result"]["protocolVersion"])
+ self.assertEqual(
+ {
+ "doctor",
+ "build",
+ "sync",
+ "views",
+ "architecture_test",
+ "review",
+ "query",
+ "whatif",
+ "story",
+ },
+ {t["name"] for t in lines[1]["result"]["tools"]},
+ )
def test_malformed_requests_do_not_stop_the_server(self):
msgs = [
diff --git a/tests/test_skill_metadata.py b/tests/test_skill_metadata.py
index 5bbbb8b..8bf962c 100644
--- a/tests/test_skill_metadata.py
+++ b/tests/test_skill_metadata.py
@@ -20,7 +20,7 @@ class TestSkillMetadata(unittest.TestCase):
assert metadata_match is not None
metadata = json.loads(metadata_match.group(1))
- self.assertEqual("3.4.1", metadata.get("version"))
+ self.assertEqual("3.4.2", metadata.get("version"))
self.assertEqual(
"https://github.com/Agents365-ai/drawio-skill", metadata.get("homepage")
)