read_diagram
Read the source of an existing Plotwork SVG so you can edit the diagram. It is a single tool of the MCP server and the HTTP API, with the title "Read diagram".
TL;DR
| Question | Answer |
|---|---|
| What is it? | A single tool: it does one thing. |
| What does it do? | Read the source of an existing Plotwork SVG so you can edit the diagram. |
| How do I call it over HTTP? | POST /v1/diagrams/read |
| Does it change anything? | No. It is read-only and idempotent. It saves no file and returns its answer as data. |
| Which bounds apply? | None beyond the limits of each argument, which are in the schema below. |
| Where do I read its schema as data? | An MCP client gets the name, description, and JSON Schema of every tool from tools/list. |
What it does
Read the source of an existing Plotwork SVG so you can edit the diagram. Send the text of an .svg file as svg, or a hosted link (https://cdn.plotwork.dev/d/ (opens in a new tab)<22 characters>.svg) as url. Returns the exact source, its kind, the stored diagram id if it was published, and a parse check. Call it first when asked to change a diagram that already exists, then edit the source and call draw_diagram (or edit_diagram); next says how to save or publish it again. Only a picture saved with embedSource true (or by sync_markdown) carries its source; otherwise status is no-source, with the title, outline, and labels to rebuild it from. A text that is not an SVG and a refused or unreachable link come back as data. Only cdn.plotwork.dev and cdn-preview.plotwork.dev are fetched (https, no redirects, 5 seconds, 1 MB); svg reads nothing from the network.
Arguments
| Field | Type | Required | Description |
|---|---|---|---|
svg | string | no | The text of a Plotwork SVG: the content of an .svg file in the repository. Send this or url, not both. at least 1 character; at most 1000000 characters. |
url | string | no | The link of a hosted Plotwork picture, https://cdn.plotwork.dev/d/ (opens in a new tab)<22 characters>.svg. Only Plotwork's own picture hosts are fetched. Send this or svg, not both. at least 1 character; at most 200 characters. |
Result
| Field | Type | Required | Description |
|---|---|---|---|
status | "read" | "no-source" | "damaged" | "not-a-picture" | "refused" | "unreachable" | yes | read: the source was found. no-source: the picture carries none. damaged: it carries one that cannot be read back. not-a-picture: the text is not an SVG. refused: the link is not one this tool fetches. unreachable: the link could not be fetched. |
hasSource | boolean | yes | True when source is set. |
source | string | null | yes | The exact source the picture was drawn from, ready to edit and send to draw_diagram; null when there is none. |
kind | string | null | yes | The diagram kind of the source, or null. |
id | string | null | yes | The id of the stored diagram when the picture was published (data-plotwork-id), or null. |
from | "text" | "url" | yes | Where the picture came from: the text that was sent, or the link that was fetched. |
validation | object | null | yes | The check of the source, or null when there is none. It parses the source; draw_diagram also lays it out and returns warnings. |
picture | object | null | yes | What the picture says about itself, or null when the text is not an SVG. |
message | string | yes | What happened, in one sentence. |
next | string | yes | The next step in one sentence. |
Behavior hints
| Hint | Value |
|---|---|
readOnlyHint | true |
destructiveHint | false |
idempotentHint | true |
openWorldHint | true |
See also
| Doc | Why |
|---|---|
| Tool reference | Every tool, with the workflows first |
POST /v1/diagrams/read | The same operation over HTTP |
| Language reference | What the diagram source may contain |
| Writing diagrams with an agent | The loop in practice |