agentic-mermaid 0.3.2 → 0.4.1

package/skills/agentic-mermaid-diagram-workflow/SKILL.md

@@ -12,7 +12,40 @@ An agent-agnostic typed editing surface for Mermaid. New diagrams can be authore
 - `agentic-mermaid-mcp` connected → **Code Mode** (`references/code-mode.md`). Multi-step edits in one round-trip.
 - Can run JS/TS with imports → **library** (`agentic-mermaid/agent`). Same SDK.
 - Shell only → **CLI** (`references/cli.md`).
-- No local install, network only → **hosted MCP** at `https://agentic-mermaid.dev/mcp` (stateless streamable HTTP JSON-RPC; `execute` Code Mode, `describe_sdk` for one family's mutation schema on demand, `render_svg`/`render_ascii`/`render_png`/`verify`/`describe`, and the declarative `mutate` (edit a `source`) / `build` (author from a `family`) tools — prefer `mutate`/`build` for structured edits; 64KB input caps).
+- No local install, network only → **hosted MCP** at `https://agentic-mermaid.dev/mcp` (stateless Streamable HTTP JSON-RPC; `execute`, `describe_sdk`, `render_svg`, `render_ascii`, `render_png`, `verify`, `describe`, `mutate`, and `build` tools — 64 KB input cap). Read `references/hosted-mcp.md` before composing a hosted request. Use the named direct tool and its exact argument object; do not substitute library APIs or local Code Mode for a hosted direct-tool task.
+
+For hosted MCP, choose the least-powerful tool that completes the task:
+
+| Need | Tool | Required arguments |
+|---|---|---|
+| Structural validity, family, warnings, layout counts | `verify` | `{ source }` |
+| Prose, AX tree, or semantic fact inventory | `describe` | `{ source, format?: 'text' \| 'json' \| 'facts' }` |
+| Edit an existing diagram with known ops | `mutate` | `{ source, ops: [{ kind, ...fields }] }` |
+| Author a new modeled diagram with known ops | `build` | `{ family, ops: [{ kind, ...fields }] }` |
+| Discover one family's exact op fields | `describe_sdk` | `{ family, detail: 'fields' }` |
+| Custom synchronous control flow | `execute` | `{ code, timeoutMs? }` |
+
+Use `render_svg`, `render_ascii`, or `render_png` for a requested output; do not route a one-shot render, verify, describe, mutate, or build through `execute`.
+Mutation vocabularies are family-specific and are never interchangeable. In
+particular, a state diagram uses `add_state` and `add_transition`; never reuse
+the flowchart-only `add_node` or `add_edge` kinds for a state diagram. If the
+exact family op is not already known, call `describe_sdk` instead of borrowing
+an op name from another family. State `add_state` accepts `id`, optional
+`label`, `parent`, and `region`; it has no `terminal` field. Model an
+unsuccessful terminal state as an ordinary state reached by the requested
+labeled transition rather than inventing a convenience flag. For a class
+association, use `{ kind: 'add_relation', from, to, relKind: 'association' }`;
+there is no `add_relationship` op or `relation` field.
+The request envelope's `tool` is always one of the bare hosted names above.
+Never invent a provider-qualified name such as `hosted_agentic_mermaid_mcp.*`
+or a diagram-specific tool such as `update_state_diagram`.
+For a hosted task that asks for one final fenced JSON request, use this exact
+response order: (1) finish all explanation as prose or inline code, (2) emit
+the request in the answer's only fenced block, and (3) stop immediately after
+the closing fence. Never print a fenced request before the explanation, even as
+an example or draft, and never repeat it. Before emitting, count exactly one
+fenced block and recheck every op `kind` and field against this skill or
+`describe_sdk`; do not substitute a plausible synonym.
 
 ## Capability discovery
 
@@ -23,6 +56,10 @@ source example; the generated Section A matrix supplies explicit native,
 source-preserved, diagnosed, and absent states. This skill intentionally does
 not maintain a second family or operation table.
 
+On hosted MCP, inspect the connected server's `tools/list` for its tool surface
+and call `describe_sdk({ family, detail: 'fields' })` for mutation fields. There
+is no hosted tool named `capabilities`.
+
 Any diagram with constructs we don't model falls back to an **opaque** body: it still parses, renders, verifies, and round-trips losslessly — it just isn't offered for structured mutation (the narrower returns null). The parser never silently drops anything.
 
 State diagrams own a dedicated body: `asState` models states/transitions, `[*]`, composites, stereotypes/history, concurrency regions, notes, bare declarations, and class/inline paint. `asFlowchart` returns null on a state diagram.
@@ -45,6 +82,32 @@ For new diagrams, author Mermaid source directly, then `parseRegisteredMermaid`
 
 Do not regenerate or concatenate source to edit an existing structured diagram when a typed op exists. Direct source authoring is fine for new diagrams. Mutation ops use the discriminator field `kind` (not `type`). Edge removal uses ids such as `{ kind: 'remove_edge', id: 'API->DB' }`; verify before serializing.
 
+For `mutate` or `build`, treat the returned envelope as the commit boundary:
+accept `source` only when both top-level `ok` and `verify.ok` are true, and
+inspect `verify.warnings`. If an op fails, use its `opIndex` and `error`, call
+`describe_sdk` with `detail: 'fields'`, then retry with only the returned
+`kind` and fields. Never guess a hosted op name or fall back to source
+concatenation.
+
+When the user asks which embedded verification fields must pass, name the
+response paths exactly: require top-level `ok`, confirm top-level `family`,
+require `verify.ok`, and inspect `verify.warnings`. Do not replace those field
+paths with a paraphrase.
+
+In a hosted `mutate` request, `source` is the exact pre-edit input; do not apply
+the requested change to that string yourself. Express every change only in
+`ops`, and include no convenience fields that `describe_sdk` did not advertise.
+For file-backed input, inspect the bytes rather than relying on terminal display:
+preserve line endings and whether the file has a final newline. If the file ends
+in LF, the JSON `source` string must end in `\n` after its last visible line.
+Never trim or normalize the source; compare the JSON-decoded `source` bytes to
+the attachment before emitting the request.
+
+If a request such as “make this better” has no concrete quality goal, ask for
+the audience, output medium, and intended improvement before mutating. A
+read-only `verify`, `describe`, or render inspection is safe to offer, but do
+not invent an edit objective.
+
 Minimal existing-flowchart pattern:
 
 ```ts

package/skills/agentic-mermaid-diagram-workflow/references/hosted-mcp.md

@@ -0,0 +1,110 @@
+# Hosted MCP
+
+Use `https://agentic-mermaid.dev/mcp` through an MCP client. It is a stateless,
+tools-only Streamable HTTP server. Each diagram source or Code Mode program is
+sent to the hosted service. Use the local library, CLI, or stdio MCP instead
+for sensitive data, offline work, inputs over 64 KB, arbitrary local file I/O,
+or file/URL PNG artifacts.
+
+## Direct request contract
+
+An MCP client selects the tool separately from its arguments. When showing a
+request, name both explicitly:
+
+```json
+{"tool":"verify","arguments":{"source":"flowchart TD\n  API --> DB"}}
+```
+
+For raw JSON-RPC, the method remains `tools/call`:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "verify",
+    "arguments": { "source": "flowchart TD\n  API --> DB" }
+  }
+}
+```
+
+Do not use `"method":"verify"`, put arguments directly under `params`, or
+show an anonymous argument object without naming the selected tool.
+The envelope's `tool` value is a bare server tool name. Never prefix it with a
+provider or server name and never invent a diagram-specific tool such as
+`update_state_diagram`.
+
+If the answer calls for one final fenced JSON request, finish all prose first,
+emit the request in the answer's only fenced block, then stop after its closing
+fence. Never show a fenced request before the explanation, even as an example
+or draft, and never repeat it. As a final preflight, count one fenced block
+total and verify each op name and field against the family schema; a plausible
+synonym is still an invalid call.
+
+## Direct tools
+
+- `verify({ source })` returns structural `ok`, detected `family`, `summary`,
+  `warnings`, and layout counts. Confirm the family as well as `ok`.
+- `describe({ source, format })` uses `text` for prose, `json` for an AX tree,
+  and `facts` for compact deterministic semantic fact lines.
+- `render_svg({ source, options? })`, `render_ascii({ source, useAscii?,
+  targetWidth?, options? })`, and `render_png({ source, ...portableOptions,
+  options? })` handle one-shot output.
+- `mutate({ source, ops })` edits an existing modeled diagram.
+- `build({ family, ops })` creates a new modeled diagram from an empty family.
+- `describe_sdk({ family, detail: 'fields' })` returns exact version-matched op
+  names, fields, enums, defaults, and constraints. Use `detail: 'signatures'`
+  only for a compact menu.
+- `execute({ code, timeoutMs? })` runs synchronous JavaScript with the injected
+  `mermaid.*` global. Reserve it for custom control flow that a direct tool or
+  op list cannot express.
+
+There is no hosted `capabilities` tool. Use the MCP client's `tools/list` for
+tool discovery and `describe_sdk` for one family's mutation schema.
+
+## Declarative edit and recovery
+
+Before unfamiliar `mutate` or `build` ops, call:
+
+```json
+{"tool":"describe_sdk","arguments":{"family":"class","detail":"fields"}}
+```
+
+Then use exactly the returned `kind` and fields. Ops are ordered,
+all-or-nothing, and use `kind`, never `type`. A successful edit returns
+`{ ok, family, source, verify }`; accept the source only when `ok` and
+`verify.ok` are true, after inspecting `verify.warnings`.
+Op kinds are not portable across families: state diagrams use `add_state` and
+`add_transition`, never the flowchart-only `add_node` or `add_edge` kinds.
+If the answer must identify the commit checks, spell out the exact response
+paths: top-level `ok`, top-level `family`, `verify.ok`, and
+`verify.warnings`. Do not paraphrase away those names.
+
+Two common exact-schema patterns are:
+
+```json
+{"tool":"mutate","arguments":{"source":"stateDiagram-v2\n  [*] --> Idle\n  Idle --> Processing: start\n  Processing --> Complete: done","ops":[{"kind":"add_state","id":"Failed"},{"kind":"add_transition","from":"Processing","to":"Failed","label":"fail"}]}}
+```
+
+```json
+{"tool":"build","arguments":{"family":"class","ops":[{"kind":"add_class","id":"Customer"},{"kind":"add_class","id":"Account"},{"kind":"add_relation","from":"Customer","to":"Account","relKind":"association"}]}}
+```
+
+For `mutate`, copy the original pre-edit source byte-for-byte into `source` and
+put the desired change only in `ops`; do not pre-apply it to the source string.
+For an attached or file-backed source, use a byte-aware read to determine its
+line endings and final-newline state. A terminal LF is part of the source: the
+JSON string must end in `\n` after the final visible line. Terminal output that
+only displays the lines is not sufficient evidence that the file lacks one.
+State `add_state` accepts `id`, optional `label`, `parent`, and `region`—there is
+no `terminal` field. Model a terminal path explicitly with an `add_transition`
+to `[*]` when the requested outcome requires one.
+
+For class diagrams the family is `class`, not `classDiagram`; class identity is
+`id`, and an association is `add_relation` with `relKind: "association"`.
+
+On failure, read `opIndex` and `error`, refresh that family's field schema with
+`describe_sdk`, and retry only the failed request with corrected documented
+fields. Do not invent an op, switch to source concatenation, or split one
+oversized diagram across hosted calls.

package/dist/mcp-cli-XGZP6CMW.js

@@ -1,17 +0,0 @@
-import {
-  MCP_CLI_HELP,
-  MCP_FLAG_SPECS,
-  parseMcpCliOptions,
-  runMcpCli
-} from "./chunk-NE6JBHSE.js";
-import "./chunk-IVN6KP3W.js";
-import "./chunk-YWKCUBQN.js";
-import "./chunk-GX7UT56Q.js";
-import "./chunk-3D4EHVQ4.js";
-export {
-  MCP_CLI_HELP,
-  MCP_FLAG_SPECS,
-  parseMcpCliOptions,
-  runMcpCli
-};
-//# sourceMappingURL=mcp-cli-XGZP6CMW.js.map