Canopy

1# Canopy
2 
3Renders diagram source files to PNG/SVG using [Kroki](https://kroki.io). No runtime dependencies — uses only Node.js built-ins.
4 
5![Architecture overview](diagrams/public/architecture/overview.png)
6 
7Two usage modes:
8 
9- **CLI** — drop source files into `src/`, run `make render`, get images in `diagrams/`
10- **MCP server** — AI tools (`render_diagram`, `render_file`) render on demand and return a one-click preview URL
11 
12---
13 
14## Quick start
15 
16```bash
17make up        # start local Kroki (Docker)
18make render    # render all files in src/ → diagrams/
19```
20 
21Output lands in `diagrams/`.
22 
23---
24 
25## CLI usage
26 
27```bash
28make render                                  # render everything in src/
29make render FILE=public/flow.puml            # single file
30make render DIR=src/public                   # subdirectory → diagrams/public/
31make render DIR=src/public OUT=out/pub       # custom output directory
32```
33 
34---
35 
36## Supported formats
37 
38Format is detected from the file extension. Unsupported extensions are skipped.
39 
40| Extension(s)                    | Kroki type   |
41|---------------------------------|--------------|
42| `.puml`, `.plantuml`            | plantuml     |
43| `.c4puml`                       | c4plantuml   |
44| `.mmd`, `.mermaid`              | mermaid      |
45| `.dot`, `.gv`                   | graphviz     |
46| `.d2`                           | d2           |
47| `.dbml`                         | dbml         |
48| `.ditaa`                        | ditaa        |
49| `.erd`                          | erd          |
50| `.excalidraw`                   | excalidraw   |
51| `.blockdiag`                    | blockdiag    |
52| `.seqdiag`                      | seqdiag      |
53| `.actdiag`                      | actdiag      |
54| `.nwdiag`                       | nwdiag       |
55| `.packetdiag`                   | packetdiag   |
56| `.rackdiag`                     | rackdiag     |
57| `.bpmn`                         | bpmn         |
58| `.bytefield`                    | bytefield    |
59| `.nomnoml`                      | nomnoml      |
60| `.pikchr`                       | pikchr       |
61| `.dsl`                          | structurizr  |
62| `.bob`                          | svgbob       |
63| `.symbolator`                   | symbolator   |
64| `.tikz`                         | tikz         |
65| `.vega`                         | vega         |
66| `.vegalite`                     | vegalite     |
67| `.wavedrom`                     | wavedrom     |
68| `.wireviz`                      | wireviz      |
69 
70To add a format, edit the `KROKI_TYPE` map in `generate.cjs`. Full list: https://kroki.io/#support
71 
72---
73 
74## Markdown files
75 
76Embed diagrams as fenced code blocks using the diagram type as the language name. Each block is rendered individually and saved to a sub-directory named after the `.md` file.
77 
78### Title syntax
79 
80Add a title after the language name on the opening fence line:
81 
82````md
83```plantuml "User Registration Flow"
84@startuml
85Alice -> Bob: hello
86@enduml
87```
88````
89→ `diagrams/architecture/User Registration Flow.png`
90 
91````md
92```plantuml user-flow
93```
94````
95→ `diagrams/architecture/user-flow.png`
96 
97Without a title, files are named by type and sequence number: `plantuml-01.png`, `mermaid-01.png`, etc.
98 
99### Example
100 
101````md
102```plantuml "Sequence Overview"
103@startuml
104...
105@enduml
106```
107 
108```mermaid data-flow
109graph TD
110    A --> B
111```
112````
113 
114Render a markdown file:
115 
116```bash
117make render FILE=src/architecture.md
118```
119 
120Output for `src/architecture.md`:
121 
122```
123diagrams/
124└── architecture/
125    ├── Sequence Overview.png
126    └── data-flow.png
127```
128 
129---
130 
131## Project structure
132 
133```
134canopy/
135├── generate.cjs        # CLI renderer
136├── mcp.cjs             # MCP server + HTTP preview server
137├── lib/renderer.cjs    # shared rendering logic
138├── Makefile
139├── docker-compose.yml
140├── src/
141│   ├── public/         # committed — shared diagrams
142│   └── private/        # gitignored — sensitive diagrams
143└── diagrams/
144    ├── public/         # committed
145    └── private/        # gitignored
146```
147 
148Sub-directory structure is mirrored from `src/` to `diagrams/` automatically:
149 
150```
151src/public/flow.puml     →  diagrams/public/flow.png
152src/public/arch.md       →  diagrams/public/arch/sequence.png
153```
154 
155---
156 
157## Local Kroki server
158 
159Run your own Kroki instance via Docker to avoid sending diagrams to the public server.
160 
161```bash
162make up        # start all containers (detached)
163make down      # stop and remove containers
164make restart   # restart containers
165make status    # show container status
166```
167 
168The script checks `http://localhost:8000` automatically on every run:
169 
170```
171Kroki: checking http://localhost:8000 ... ok
172```
173 
174If unavailable, it asks before falling back to `https://kroki.io`.
175 
176Containers started by `docker-compose.yml`:
177 
178| Service      | Image                       | Covers                                                     |
179|--------------|-----------------------------|------------------------------------------------------------|
180| `kroki`      | yuzutech/kroki              | Core (PlantUML, C4, GraphViz, D2, Mermaid, etc.)           |
181| `mermaid`    | yuzutech/kroki-mermaid      | Mermaid                                                    |
182| `blockdiag`  | yuzutech/kroki-blockdiag    | BlockDiag, SeqDiag, ActDiag, NwDiag, PacketDiag, RackDiag  |
183| `bpmn`       | yuzutech/kroki-bpmn         | BPMN                                                       |
184| `excalidraw` | yuzutech/kroki-excalidraw   | Excalidraw                                                 |
185| `wireviz`    | yuzutech/kroki-wireviz      | WireViz                                                    |
186 
187---
188 
189## MCP server
190 
191The MCP server exposes diagram rendering as AI tools. It starts an HTTP file server on port 17432 (auto-increments if taken) alongside the MCP stdio transport.
192 
193![MCP tool call flow](diagrams/public/architecture/mcp-flow.png?v=2)
194 
195**Available tools:**
196 
197| Tool | Description |
198|------|-------------|
199| `render_diagram` | Render diagram source text → returns a preview URL |
200| `render_file` | Render a source file from disk → returns preview URL(s) |
201| `list_supported_types` | List all supported Kroki types and extensions |
202 
203The preview URL (e.g. `http://127.0.0.1:17432/a1b2c3`) opens directly in your browser.
204 
205### Claude Code
206 
207Add globally so it's available in every project:
208 
209```bash
210claude mcp add canopy -s user node /path/to/canopy/mcp.cjs
211```
212 
213Or let Claude Code auto-discover it when you open this repo — `.mcp.json` is already included.
214 
215### Claude Desktop
216 
217Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
218 
219```json
220{
221  "mcpServers": {
222    "canopy": {
223      "command": "node",
224      "args": ["/path/to/canopy/mcp.cjs"]
225    }
226  }
227}
228```
229 
230Restart Claude Desktop after editing. The MCP server starts automatically when the app launches.
231 
232---
233 
234## Notes
235 
236- `diagrams/private/` and `src/private/` are gitignored — use them for sensitive diagrams.
237- Non-diagram code blocks in `.md` files are silently skipped.
238- Rendered images are saved to `~/.canopy/output/` and persist across reboots. The registry is persisted to `~/.canopy/registry.json` and reloaded on each server start, so preview URLs remain valid indefinitely as long as the image file exists on disk.
239