# Plotwork for AI agents

> Page: https://docs.plotwork.dev/agents/overview. Index of every page: https://docs.plotwork.dev/llms.txt

How an AI agent finds, reads, and uses Plotwork: the files it can read without connecting, the ways to call the tools, and the loop that gets a valid diagram.

## TL;DR

| Question | Answer |
|---|---|
| What is Plotwork? | A small text language and renderer for twenty kinds of diagram, from flow, sequence, and database to Gantt, state, mind map, and treemap, written by AI agents and drawn the same way everywhere: in a README, in your editor, and over MCP. |
| How does an agent call it? | Over MCP, locally or hosted, or over HTTP. Every way runs the same 18 tools, which the [tool reference](https://docs.plotwork.dev/mcp/tools.md) lists. |
| Which clients work? | Any MCP client. The [connecting guide](https://docs.plotwork.dev/mcp/connect.md) has the settings for Claude Code, Cursor, VS Code, and Claude Desktop, and the [rules file](https://docs.plotwork.dev/agents/rules.md) says where Codex, GitHub Copilot, and Gemini CLI read their instructions. ChatGPT, Claude, and VS Code show a drawing inline. |
| What does it cost to start? | The local MCP server needs no key and no account. The hosted MCP server and the HTTP API need an API key, and the hosted MCP server also accepts a browser sign-in. |
| Where do I read the docs without a browser? | `https://docs.plotwork.dev/llms.txt` indexes every page. Add `.md` to the address of any page to get it as Markdown. |
| Which tool do I call first? | [`get_diagram_syntax`](https://docs.plotwork.dev/mcp/tools/get-diagram-syntax.md) once to read the language, then [`draw_diagram`](https://docs.plotwork.dev/mcp/tools/draw-diagram.md) with the source. For a common architecture, call [`find_pattern`](https://docs.plotwork.dev/mcp/tools/find-pattern.md) first. |
| What if the source is wrong? | [`draw_diagram`](https://docs.plotwork.dev/mcp/tools/draw-diagram.md) returns every error with its line, column, and hint, and draws nothing until the source is valid. Fix them all and call again. |

## What the server tells your agent

The MCP server sends this guidance to a client when it connects. It is listed here for an agent that reads the docs before it has a connection. The [rules file](https://docs.plotwork.dev/agents/rules.md) holds the same text ready to paste into a project.

1. Draws flow, sequence, database schema, git graph, Gantt chart, class diagram, state, timeline, user journey, mind map, treemap, share chart, quadrant chart, layered architecture, C4 diagram, matrix, Sankey diagram, XY chart, tree, and swimlane diagrams from a small line-oriented text language.
2. Prefer the workflow tools: each does the work of several single tools in one call.
3. When you are unsure which kind of diagram fits, call `suggest_diagram` with the request in plain words and any data: it ranks the kinds and gives a starter that parses; for a whole document, `plan_document_diagrams` returns the sections a picture would help, each with a starter.
4. When the diagram should come from a file the person has (SQL, Prisma, or Drizzle models, an OpenAPI document, Terraform, Bicep, ARM, Pulumi, CloudFormation, or the CDK, docker-compose, Kubernetes manifests, Helm, Kustomize, a Backstage catalog, a Structurizr workspace, AsyncAPI documents, a GitHub Actions workflow, a GitLab CI/CD or Azure Pipelines pipeline, CSV or JSON data, a folder listing, or a git log), call `import_source` with its text and format: it builds the whole diagram from the file in one call, and its diagnostics say what was left out `get_diagram_syntax` with topic import-formats says what each format reads.
5. For a request to draw a common architecture, such as a three-tier network, a serverless API, a container platform, or a queue with workers, call `find_pattern` first with the request in plain words; when a pattern fits, call `draw_from_pattern` with its id, a provider flavour (neutral, aws, azure, or gcp), and slot values that rename its parts, or `get_pattern` to read and edit its source, and when nothing fits, write the diagram from scratch with `draw_diagram`.
6. Call `get_diagram_syntax` once with no kind to read the shared language, and again with kind set to the kind you draw for its statements, limits, and example.
7. Write the source and call `draw_diagram`: it returns every error with line, column, and hint and draws nothing until the source is valid, so fix every error and call again; once valid it returns the warnings, an outline to check the meaning, and the SVG for light and dark.
8. The pictures are most of the answer and you cannot look at them, so pass svg "never" to check a diagram, and draw only when you will save, show, or publish the pictures; when a drawing is too big to read in one answer the SVG is left out, picturesOmitted says so, and svg "always" forces it.
9. To change a diagram that already exists as a Plotwork SVG, a hosted link such as https://cdn.plotwork.dev/d/<22 characters>.svg or an .svg file in the repository, call `read_diagram` first with its url or its text, change the source it returns with `edit_diagram` (rename, set an option, add, remove, or move a statement) or by hand and `draw_diagram`, then write the SVG file again; `compare_diagrams` says what changed, for a review.
10. Set embedSource true on `draw_diagram` whenever you save an SVG into a repository, so the file carries its source and `read_diagram` can give it back next time; the source is then readable by anyone who has the file.
11. To save a valid diagram into the person's repository, run the saveCommand a drawing tool returns in a shell, changing --out to the path you want (add --theme dark for the dark picture): the Plotwork command line reads the diagram from the link on that machine, fetches nothing, and writes the SVG with its source embedded, so you never copy the SVG yourself.
12. With no shell, draw with svg "always" and embedSource true and write the returned svg.
13. Give viewUrl to a person to look at the diagram, and svgUrl or pngUrl to download it in their browser; neither is a file address for curl.
14. An item with no icon= gets the icon its label names when the match is certain, such as the Postgres mark on a node labelled "Postgres", so label items with the product they are; icon=none keeps one item plain and icons=off on the header keeps them all plain.
15. For a finished look, label flow arrows with verbs ("reads", "publishes", "deploys to") so they draw icons, add role= (data, async, identity, private) to the lines that carry those, and give groups a type=; style in `get_diagram_syntax` says more.
16. Use `map_icons` to choose icons for many names at once; it never guesses, so choose from the candidates for an ambiguous name, and never invent an icon.
17. To move Mermaid to Plotwork, call `convert_mermaid` with one diagram, read every diagnostic and its hint, then choose node types and icons; for a whole Markdown file call `sync_markdown` with the document, its path, and convertMermaid true, write the returned markdown and files, then review the diff.
18. When the repository has a plotwork.config.json (or .plotwork/config.json) at its root, read it and pass it as settings to every tool that takes settings: its defaults fill the header options the source leaves out, and broken style rules come back as warnings to fix.
19. Use `validate_diagram`, `outline_diagram`, `render_diagram`, and `search_icons` only for one fine-grained step.
20. Choose node types and tones for meaning; colors are chosen by the theme and cannot be set.

## The tools

11 workflows do a whole job in one call, and 7 single tools do one step. Prefer a workflow.

| Tool | Kind | What it does | A request that leads to it |
|---|---|---|---|
| [`draw_diagram`](https://docs.plotwork.dev/mcp/tools/draw-diagram.md) | Workflow | Checks, describes, and draws a diagram. | Draw a diagram of how a user signs in through an API that checks a database. |
| [`edit_diagram`](https://docs.plotwork.dev/mcp/tools/edit-diagram.md) | Workflow | Changes diagram source with typed operations, on every kind, and checks the result. | Rename the Auth API node to gateway and add a session cache it writes to. |
| [`convert_mermaid`](https://docs.plotwork.dev/mcp/tools/convert-mermaid.md) | Workflow | Converts one Mermaid diagram (flowchart or graph, sequenceDiagram, erDiagram, gitGraph, gantt, classDiagram, stateDiagram, timeline, journey, mindmap, treemap-beta or treemap, pie, quadrantChart, C4Context or C4Container or C4Component or C4Dynamic or C4Deployment, sankey-beta or sankey, xychart-beta or xychart, treeView-beta or treeView) to Plotwork source. | Convert this Mermaid flowchart to Plotwork. |
| [`import_source`](https://docs.plotwork.dev/mcp/tools/import-source.md) | Workflow | Turns a file into a finished diagram in one call. | Draw our database schema from this SQL. |
| [`map_icons`](https://docs.plotwork.dev/mcp/tools/map-icons.md) | Workflow | Finds an icon for each of up to 40 service or product names in one call, such as the services of an architecture. | Which icons should I use for S3, Lambda, Postgres and a queue on AWS? |
| [`sync_markdown`](https://docs.plotwork.dev/mcp/tools/sync-markdown.md) | Workflow | Turns the diagram fences of a Markdown document into pictures, as data. | Replace the Mermaid diagrams in README.md with Plotwork diagrams. |
| [`suggest_diagram`](https://docs.plotwork.dev/mcp/tools/suggest-diagram.md) | Workflow | Picks the kind of diagram for a request in plain words, such as "permission matrix for these endpoints and roles" or "where our cloud spend goes", with optional pasted data (a table, a list, numbers by period). | Which diagram should I use to show who can call which endpoint? |
| [`plan_document_diagrams`](https://docs.plotwork.dev/mcp/tools/plan-document-diagrams.md) | Workflow | Reads a whole document (Markdown, HTML, or plain text pasted from Confluence, Notion, or Google Docs), splits it by its headings, and returns the sections a picture would help. | Which parts of this design doc need a diagram? |
| [`find_pattern`](https://docs.plotwork.dev/mcp/tools/find-pattern.md) | Workflow | Finds a ready-made, checked architecture diagram for a request such as "three tier network", "serverless api", or "two availability zones". | Draw a three-tier network with load balancers. |
| [`get_pattern`](https://docs.plotwork.dev/mcp/tools/get-pattern.md) | Workflow | Returns one pattern filled for a flavour. | Show me the three-tier network pattern for Azure and rename the office network to Branch office. |
| [`draw_from_pattern`](https://docs.plotwork.dev/mcp/tools/draw-from-pattern.md) | Workflow | Fills a pattern and draws it in one call. | Draw a two-zone network on AWS with a replicated database. |
| [`read_diagram`](https://docs.plotwork.dev/mcp/tools/read-diagram.md) | Single tool | Read the source of an existing Plotwork SVG so you can edit the diagram. | One step of a larger job. |
| [`compare_diagrams`](https://docs.plotwork.dev/mcp/tools/compare-diagrams.md) | Single tool | Compare two versions of a diagram by meaning, for a pull request review. | One step of a larger job. |
| [`get_diagram_syntax`](https://docs.plotwork.dev/mcp/tools/get-diagram-syntax.md) | Single tool | Read the diagram language as data. | One step of a larger job. |
| [`validate_diagram`](https://docs.plotwork.dev/mcp/tools/validate-diagram.md) | Single tool | Check diagram source without drawing it: every error in one pass, each with line, column, and a fix hint, plus quality warnings. | One step of a larger job. |
| [`render_diagram`](https://docs.plotwork.dev/mcp/tools/render-diagram.md) | Single tool | Render valid source to a self-contained, accessible SVG in the light or dark theme, with its pixel size and quality warnings. | One step of a larger job. |
| [`outline_diagram`](https://docs.plotwork.dev/mcp/tools/outline-diagram.md) | Single tool | Describe valid diagram source as plain text. | One step of a larger job. |
| [`search_icons`](https://docs.plotwork.dev/mcp/tools/search-icons.md) | Single tool | Find bundled icon names by keyword, idea, product, or abbreviation ("postgres", "token exchange", "s3", "cosmos db"). | One step of a larger job. |

## Ways to call them

| Way | Address | What it needs |
|---|---|---|
| Local MCP server | `npx -y @buun_group/plotwork-mcp@0.1.0-beta.10` | Node 22 or later. No key, no account, and no network unless you opt in to usage sharing. |
| Hosted MCP server, with a key | `https://mcp.plotwork.dev/mcp` | An API key in the `X-API-Key` header or as a bearer value. |
| Hosted MCP server, with a sign-in | `https://mcp.plotwork.dev/mcp-oauth` | A Plotwork account. The client opens a browser and you approve the connection. |
| HTTP API | `https://api.plotwork.dev/v1` | An API key, sent the same way. Each tool has a route, listed in the [rules file](https://docs.plotwork.dev/agents/rules.md#without-mcp). |

The [connecting guide](https://docs.plotwork.dev/mcp/connect.md) has the exact setting for each client.

## See also

| Doc | Why |
|---|---|
| [llms.txt and Markdown pages](https://docs.plotwork.dev/agents/machine-readable.md) | Every file an agent can read without a browser, and when to fetch each |
| [Rules file for your agent](https://docs.plotwork.dev/agents/rules.md) | The guidance above, ready to paste into CLAUDE.md or AGENTS.md |
| [Prompts and recipes](https://docs.plotwork.dev/agents/prompts.md) | Requests that work and the tools an agent calls for each |
| [Connecting an agent](https://docs.plotwork.dev/mcp/connect.md) | Setting up Claude Code, Cursor, VS Code, and other clients |
| [Language reference](https://docs.plotwork.dev/reference/language.md) | Every word the diagram language accepts |