agentic-mermaid 0.1.1 → 0.1.2

package/docs/mcp-code-mode-rationale.md

@@ -1,101 +0,0 @@
-# MCP Code Mode rationale
-
-Local `agentic-mermaid-mcp` is intentionally Code Mode first. Its primary tool is `execute(code)`, which runs synchronous JavaScript against the typed `mermaid.*` SDK in a local `node:vm` sandbox. This is a local implementation inspired by Code Mode as a product shape; it is not Cloudflare Codemode, not backed by `@cloudflare/codemode`, and not an OS/container security boundary. The local helper tools (`render_png` and `describe`) are narrow conveniences, not a second full authoring API.
-
-There is now also a **hosted** MCP at `https://agentic-mermaid.dev/mcp` (stateless Streamable HTTP; see [`docs/project/hosted-mcp-cloudflare-plan.md`](./project/hosted-mcp-cloudflare-plan.md)). It keeps `execute` but runs agent code in a per-request Cloudflare Dynamic Worker isolate (`globalOutbound: null`, empty env, `cpuMs` budget) instead of a local `node:vm` — there the isolate configuration *is* the security boundary — and adds direct `render_svg`/`render_ascii`/`render_png`/`verify`/`describe` tools so the common render/verify paths avoid a billable isolate, plus the declarative `mutate`/`build` tools (see below). Both share the same hardened `mermaid.*` facade; their semantics are pinned against each other by a differential test suite.
-
-## Why the MCP server exists
-
-Agents often need a multi-step diagram transaction:
-
-1. parse source;
-2. narrow to a mutable family;
-3. apply one or more typed mutations;
-4. verify and inspect the result;
-5. serialize only after verify passes.
-
-As separate MCP tools, that workflow becomes many tool calls and loses useful in-call state. In Code Mode it is one call: the agent writes the small algorithm and the server preserves lineage/tracing inside the execution.
-
-## Code Mode first, plus a narrow declarative edit surface
-
-Code Mode stays the primary tool for multi-step logic. But `execute` asks the
-model to write correct sandboxed JavaScript, and a weaker model drives that
-poorly (serialization pitfalls, provenance rules, sync-only constraints) when
-all it wanted was to apply a few structured edits. So the hosted surface adds
-exactly **two** declarative tools — `mutate` (edit a `source`) and `build`
-(author from a `family`) — that take a JSON op list and return one canonical
-`{ ok, family, source, verify }` envelope. They run verify internally and only
-emit source when it passes, so the verify-before-commit contract holds without
-the model writing it. Both funnel through the same validated `mutateChecked`
-core as Code Mode's `mermaid.mutate`, so an op is rejected identically either
-way — there is no second implementation to drift.
-
-We still do **not** explode the surface into `parse`/`narrow`/`serialize`/… as
-separate tools: those are the composable steps `execute` exists to sequence in
-one call, and a full per-operation MCP API would multiply round trips, weaken
-in-call lineage, and be another public contract to keep in lockstep. `mutate`
-and `build` are the deliberate exception because a *structured edit* is the one
-workflow that (a) is common, (b) needs no arbitrary logic, and (c) a weak model
-gets wrong through `execute`. For everything richer, use `execute`, the CLI
-(`am mutate --ops`, `am verify`, `am render`), or a library import.
-
-## What the non-Code-Mode MCP tools are for
-
-Local MCP keeps only two helpers:
-
-- `render_png(source)` exists because PNG is binary output and returning base64 from a dedicated MCP tool is simpler than putting binary handling into Code Mode snippets. For clients that cannot comfortably carry large base64 payloads, `render_png({source, output:"file"})` writes a managed local artifact and `output:"url"` returns an HTTP-served artifact when the server runs with HTTP/SSE transport.
-- `describe(source)` exists because one-shot natural-language summaries are common for screen readers, docs, and context compaction.
-
-The hosted endpoint adds direct pure tools (`render_svg`, `render_ascii`, `render_png`, `verify`, `describe`) because every hosted `execute` spins a Dynamic Worker isolate; common render/verify calls should be ordinary Worker invocations and edge-cacheable. Hosted `mutate` and `build` are the only declarative authoring tools, and they exist to apply typed op lists with the verify-before-emit contract without asking a weaker model to write JavaScript. They do not introduce a separate mutation engine.
-
-Local managed artifacts are generated under the server artifact directory with safe names, size limits, TTL cleanup, MIME type, byte count, and SHA-256 metadata; they are not arbitrary user-chosen file writes. Hosted `render_png` returns base64 only.
-
-## Equivalence example
-
-`examples/mcp-vs-cli-complex-diagrams.ts` builds the same complicated diagrams two ways: an Auth Flow flowchart with feedback loops and an Order Domain ER diagram.
-
-- MCP Code Mode: `tools/call execute` runs parse → narrow → mutate[] → verify → serialize.
-- CLI: `am mutate <diagram>.mmd --ops ops.json --json` runs the same typed mutation batch and verify-before-emit contract.
-
-The example asserts that both channels produce byte-identical Mermaid source for every case. This is the supported equivalence story: **MCP Code Mode and CLI/library can produce the same diagrams**. Hosted `mutate`/`build` are a bounded shortcut for the same typed op-list workflows, not a replacement for Code Mode when custom control flow is needed.
-
-## Transports
-
-The default transport is stdio for local MCP clients:
-
-```sh
-agentic-mermaid-mcp
-```
-
-HTTP/SSE reachability is available when a client needs a network endpoint. See [`mcp-http-transport.md`](./mcp-http-transport.md) for the full quickstart, JSON-RPC examples, option table, and security defaults:
-
-```sh
-agentic-mermaid-mcp --transport http --host 127.0.0.1 --port 3000 \
-  --artifact-dir .agentic-mermaid-artifacts
-```
-
-The HTTP transport exposes `/sse` for MCP SSE sessions, `/message?sessionId=...` for session messages, `/rpc` for direct JSON-RPC tests/integrations, `/health`, and `/artifacts/<name>` for managed outputs. It binds to loopback by default; non-loopback binding requires `--auth-token`, and `/rpc`/`/message` require `content-type: application/json` so browser-simple CSRF posts are rejected. Use an explicit host only when you have reviewed the sandbox and artifact exposure boundary.
-
-Example stdio `.mcp.json` entry:
-
-```json
-{
-  "mcpServers": {
-    "agentic-mermaid": {
-      "command": "npx",
-      "args": ["-y", "agentic-mermaid-mcp"]
-    }
-  }
-}
-```
-
-Example HTTP launch command for clients that manage MCP SSE URLs separately:
-
-```sh
-npx -y agentic-mermaid-mcp --transport http --host 127.0.0.1 --port 3000
-# non-loopback requires --auth-token <token>
-```
-
-## When to add more MCP tools
-
-Add another non-Code-Mode MCP tool only with evidence that a real client cannot use `execute`, hosted `mutate`/`build`, or the CLI/library path. Until then, keep the surface small: one compositional tool, direct pure render/verify/describe tools where they avoid hosted isolate cost, and the two declarative structured-edit tools.

package/docs/mcp-http-transport.md

@@ -1,223 +0,0 @@
-# MCP HTTP/SSE transport quickstart
-
-`agentic-mermaid-mcp` defaults to stdio for local MCP clients. Use HTTP/SSE only when a client needs a reachable endpoint or when PNG artifacts should be fetched by file/URL instead of returned as large base64 strings.
-
-> Looking for a zero-setup endpoint? A **hosted** MCP already runs at `https://agentic-mermaid.dev/mcp` (`claude mcp add --transport http agentic-mermaid https://agentic-mermaid.dev/mcp`). It is a different implementation — stateless Streamable HTTP, Cloudflare-backed, tools `execute`/`render_svg`/`render_ascii`/`render_png`/`verify`/`describe`/`mutate`/`build`, inputs capped at 64KB, and no file/URL PNG artifacts (base64 only). See [`docs/project/hosted-mcp-cloudflare-plan.md`](./project/hosted-mcp-cloudflare-plan.md). Run the local server below when you need file/URL artifacts, larger inputs, offline use, or your own auth.
->
-> **Privacy:** every hosted call (`execute`, `render_*`, `verify`, `describe`, `mutate`, `build`) sends your diagram source or code to the agentic-mermaid.dev server, and successful responses are edge-cached for up to a day. For diagrams that must not leave your machine, use the library, the CLI, or the local stdio/HTTP server on this page — the pipeline is fully local and needs no network.
-
-## Which endpoint returns plain JSON?
-
-Two transports, two framings — pick by what your client expects:
-
-| You are… | Use | Response framing |
-|---|---|---|
-| An MCP client (Claude Code, MCP SDKs) | hosted `/mcp`, or local `/sse` + `/message` | Handled by the client. |
-| A script POSTing JSON-RPC yourself | hosted `POST /mcp`, or local `POST /rpc` | Plain `application/json` — `json.loads` the body directly. |
-
-The local `/sse` + `/message` pair is the MCP SSE session transport: `POST /message` returns only `202 {"ok":true}`, and the actual JSON-RPC response arrives on the open `/sse` stream framed as SSE events (`event: message` / `data: {...}` lines). If you find yourself stripping `data:` prefixes before parsing, switch to `POST /rpc` (local) or `POST /mcp` (hosted) — both reply with an unframed JSON body.
-
-## Start the server
-
-Loopback/local development:
-
-```sh
-npx -y agentic-mermaid-mcp --transport http --host 127.0.0.1 --port 3000 \
-  --artifact-dir .agentic-mermaid-artifacts
-```
-
-Remote binding requires a bearer token:
-
-```sh
-npx -y agentic-mermaid-mcp --transport http --host 0.0.0.0 --port 3000 \
-  --artifact-dir .agentic-mermaid-artifacts \
-  --auth-token "$AGENTIC_MERMAID_MCP_TOKEN"
-```
-
-HTTP endpoints:
-
-| Endpoint | Purpose |
-|---|---|
-| `GET /health` | Readiness probe, returns `{ "ok": true }`. |
-| `GET /sse` | MCP SSE session endpoint. First event contains the `/message?sessionId=...` URL. |
-| `POST /message?sessionId=...` | JSON-RPC requests for an SSE session. The HTTP response is just `202 {"ok":true}`; the JSON-RPC response is emitted on the SSE stream as `event: message` / `data:` frames. |
-| `POST /rpc` | Direct JSON-RPC endpoint for tests/scripts/simple integrations. Replies with plain `application/json` (no SSE framing). |
-| `GET /artifacts/<name>` | Fetch managed artifacts returned by `render_png` `output: "url"`. |
-
-`/rpc` and `/message` require `content-type: application/json`; browser-simple `text/plain` form posts are rejected. Non-loopback hosts require `Authorization: Bearer <token>`.
-
-## Direct JSON-RPC examples: `render_png`
-
-### Base64 output (default)
-
-Request:
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "method": "tools/call",
-  "params": {
-    "name": "render_png",
-    "arguments": {
-      "source": "flowchart TD\n  A --> B"
-    }
-  }
-}
-```
-
-`curl`:
-
-```sh
-curl -sS http://127.0.0.1:3000/rpc \
-  -H 'content-type: application/json' \
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"render_png","arguments":{"source":"flowchart TD\n  A --> B"}}}'
-```
-
-Response shape:
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 1,
-  "result": {
-    "content": [
-      {
-        "type": "text",
-        "text": "{\"ok\":true,\"png_base64\":\"iVBORw0KGgo...\"}"
-      }
-    ],
-    "isError": false
-  }
-}
-```
-
-### File output
-
-Request:
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 2,
-  "method": "tools/call",
-  "params": {
-    "name": "render_png",
-    "arguments": {
-      "source": "flowchart TD\n  A --> B",
-      "output": "file"
-    }
-  }
-}
-```
-
-Response shape (`content[0].text` is JSON):
-
-```json
-{
-  "ok": true,
-  "artifact": {
-    "path": "/absolute/path/.agentic-mermaid-artifacts/<name>.png",
-    "mimeType": "image/png",
-    "bytes": 12345,
-    "sha256": "64 lowercase hex characters"
-  }
-}
-```
-
-Use `output: "file"` when the MCP host and consumer share a filesystem or when a local orchestrator will move the artifact elsewhere.
-
-### URL output
-
-Request:
-
-```json
-{
-  "jsonrpc": "2.0",
-  "id": 3,
-  "method": "tools/call",
-  "params": {
-    "name": "render_png",
-    "arguments": {
-      "source": "flowchart TD\n  A --> B",
-      "output": "url"
-    }
-  }
-}
-```
-
-Response shape (`content[0].text` is JSON):
-
-```json
-{
-  "ok": true,
-  "artifact": {
-    "url": "http://127.0.0.1:3000/artifacts/<name>.png",
-    "mimeType": "image/png",
-    "bytes": 12345,
-    "sha256": "64 lowercase hex characters"
-  }
-}
-```
-
-Fetch the artifact:
-
-```sh
-curl -L -o diagram.png 'http://127.0.0.1:3000/artifacts/<name>.png'
-```
-
-If the server is behind a reverse proxy, set `--public-url https://example.com/artifacts` so returned URLs are externally reachable.
-
-## Sample SSE flow
-
-Open the SSE stream and capture the first event:
-
-```sh
-curl -N http://127.0.0.1:3000/sse
-```
-
-The server immediately sends an endpoint event:
-
-```text
-event: endpoint
-data: http://127.0.0.1:3000/message?sessionId=<session-id>
-```
-
-Post JSON-RPC to that message URL:
-
-```sh
-curl -sS 'http://127.0.0.1:3000/message?sessionId=<session-id>' \
-  -H 'content-type: application/json' \
-  -d '{"jsonrpc":"2.0","id":4,"method":"ping"}'
-```
-
-The response is delivered on the open SSE stream:
-
-```text
-event: message
-data: {"jsonrpc":"2.0","id":4,"result":{}}
-```
-
-## Options
-
-| Option | Default | Purpose |
-|---|---:|---|
-| `--transport stdio\|http` | `stdio` | Select stdio or HTTP/SSE transport. `--http` is an alias for `--transport http`. |
-| `--host <host>` | `127.0.0.1` | HTTP bind host. Non-loopback hosts require `--auth-token`. |
-| `--port <port>` | `3000` | HTTP bind port. Use `0` for an ephemeral test port. |
-| `--artifact-dir <dir>` | OS temp dir | Directory for managed file/URL artifacts. Files use generated safe names. |
-| `--public-url <url>` | `http://<host>:<port>/artifacts` | URL prefix returned by `output: "url"`; useful behind reverse proxies. |
-| `--auth-token <token>` | unset | Bearer token required for `/rpc` and `/message` when binding non-loopback. Optional on loopback. |
-| `--max-artifact-bytes <n>` | `20971520` | Maximum bytes for a single managed artifact. |
-| `--artifact-ttl-ms <n>` | `3600000` | How long managed artifacts remain fetchable by this server process. |
-| `--max-rpc-body-bytes <n>` | `1048576` | Maximum HTTP JSON-RPC request body size. |
-| `--max-sandbox-timeout-ms <n>` | `30000` | Maximum `execute` timeout accepted over any transport. |
-
-## Security defaults
-
-- HTTP binds to loopback by default.
-- Non-loopback binding requires `--auth-token`.
-- `/rpc` and `/message` reject non-JSON content types and cross-origin browser posts.
-- Request bodies and artifact sizes are bounded.
-- URL/file artifacts are generated under a managed store, served only if the current process created and still tracks them, and checked against TTL on read.
-- `execute(code)` still runs in local `node:vm`, not an OS/container security boundary. Do not expose HTTP/SSE to hostile users without an outer isolation layer.