Plotwork for AI agents

TL;DR

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 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/ (opens in a new tab)<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.

Ways to call them

The connecting guide has the exact setting for each client.

See also