---
title: "Tools"
description: "Every tool of the dia MCP server, with its description and input parameters."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.dia.rakudeji.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

The dia MCP server has 17 tools. Each description below is the exact text the AI receives, and each table is read from the tool's input schema.

## create_project

**Create a project**

~~~text
Creates a project to group documents. Returns the project id and a URL for humans.
Pass the id as project to create_document, or move existing documents by replacing project via write_document.
The project "default" exists from the start and holds documents created without a project.
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string, 1–20 characters | yes | Human-readable heading, up to 20 characters. |
| `description` | string, non-empty | yes | Human-readable description. Markdown supported (headings, lists, emphasis, code, tables, links). The heading belongs in title; start with body text here. |

## create_document

**Create a document**

~~~text
Creates a document to hold diagrams. Returns the document id, project, kind, and a URL for humans.
Pass the id to write_diagram / read_diagram / render_diagram.
Documents belong to a project; omit project for the default project.
With kind "steps", each diagram builds on the previous one:
existing content keeps its layout, additions appear in place,
a new diagram starts as a copy of the previous diagram (write only the additions),
and edits to an earlier diagram propagate to later diagrams.
Steps also suit before/after comparisons: unchanged elements keep their place.
Use the default "standard" for independent, self-contained diagrams.
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | string, 1–20 characters | yes | Human-readable heading, up to 20 characters. |
| `description` | string, non-empty | yes | Human-readable description. Markdown supported (headings, lists, emphasis, code, tables, links). The heading belongs in title; start with body text here. |
| `kind` | one of `standard`, `steps` | no, default `"standard"` | `"standard"` holds independent diagrams; `"steps"` holds diagrams that each build on the previous one. Default `"standard"`. |
| `project` | string | no, default `"default"` | Project to create the document in. Defaults to the default project. |

## list_projects

**List projects and documents**

~~~text
Lists the caller's projects (title, id, description) and the documents in each
(title, id, kind, diagram count).
Projects and documents are ordered by most recent diagram activity, newest first.
Use to discover project and document ids. Document descriptions and diagram order are returned by read_document.
~~~

No parameters.

## write_project

**Write a project (JSON Patch)**

~~~text
Applies a JSON Patch to a project's title and description.

Project shape (JSON Patch targets this document):
  { "title": "Data platform", "description": "Diagrams of the data platform." }
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project` | string | yes | Project id returned by create_project, or `"default"` for the default project. |
| `patch` | array of `{ op, path }`, at least one item | yes | RFC 6902 JSON Patch applied to `{ title, description }`. A patch with path `""` (whole replacement) is rejected. |

## delete_project

**Delete a project**

~~~text
Deletes a project and every document in it, including their diagrams. Irreversible.
Returns the number of documents and diagrams deleted.
The default project cannot be deleted.
To keep the documents, move them to another project first via write_document.
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project` | string | yes | Project id returned by create_project, or `"default"` for the default project. |

## delete_document

**Delete a document**

~~~text
Deletes a document and every diagram in it. Irreversible.
Returns the number of diagrams deleted.
Deletion proceeds even while someone is viewing the document; verify the target before calling.
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `document` | string | yes | Document id returned by create_document. |

## write_diagram

**Write a diagram (JSON Patch)**

~~~text
Applies a JSON Patch to a diagram, creating it if absent
(then also add title and description; new diagrams start empty in a "standard" document,
copy the previous diagram in a "steps" document).

Diagram shape:
  { "title": "Architecture", "description": "Web calls the DB.",
    "model": { "edges": { "e1": { "from": "web", "to": "db" } } },
    "style": { "web": { "label": "Web", "icon": "i:lucide:globe" }, "e1": { "label": "SQL" } } }

title: max 20 chars; description: Markdown; both required.
Ids: alphanumerics/underscore/hyphen, not digit-first; labels go in style.label.

model.edges values: from, to, optional type ("connect" arrow, default;
"contains" nests `to` in `from`). from/to nodes exist implicitly.
model.nodes: only edge-less nodes; values {}.

Layout: arrows decide placement. flow "down" puts sources above targets, "right" left of them.
Elements with no arrow between them line up across the flow, in the order they are written:
side by side in "down", stacked in "right".
So to stack a container's children vertically, give the container flow "right"; to put them side by side, leave it "down".
Each container lays out its children with its own flow.
When arrows form a loop, the arrows written first keep their direction and later ones are drawn as returns.
Labels stay on one line: long labels widen the diagram, and each edge label adds a row of space.

style keys are node/edge ids; "root" is the whole diagram.
Node keys:
  flow: "down"|"right"; containers/root; default "down"
  label: node text
  icon: "i:<set>:<name>" (built-in; search_icons) or "u:<set>:<name>" (custom; upload_icon); required on leaves
  borderColor: #rrggbb
  textColor: #rrggbb; also tints monochrome icons
  padding: px; default 12, containers 24
  paddingY: vertical override of padding
  minHeight: px; default 40
  gap: px between children; containers only; default 20
  borderWidth: px; 0 removes; default 1.5, containers 2.5
  iconSize: icon height px; default 16
  preset: name in presets; written values win
Edge keys:
  label: edge text
  color: stroke and arrowhead #rrggbb

presets holds style values shared between nodes, applied via style.<id>.preset:
  "presets": { "quiet": { "borderColor": "#9ca3af" } }

views holds named highlights that dim the rest; unknown ids ignored:
  "views": { "ingest": { "title": "流れ", "ids": [...] } }

Violations save nothing and return reasons:
nodes and edges share a namespace; one parent per node; acyclic containment;
contained nodes not also connected; style keys and style.icon must exist;
node and edge keys unmixed; presets referenced and defined in pairs;
leaf nodes need an icon; the unpicturable belongs in prose.
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `document` | string | yes | Document id returned by create_document. |
| `diagram` | string, matches `^[A-Za-z_][A-Za-z0-9_-]*$` | yes | Diagram id, unique within the document. Alphanumerics, underscores, and hyphens; must not start with a digit. Created if it does not exist. |
| `patch` | array of `{ op, path }`, at least one item | yes | RFC 6902 JSON Patch applied to the JSON returned by read_diagram. Send only the changes, not the whole diagram. Supported ops: add, remove, replace, move, copy, test, edit. `"add"` and `"replace"` require value; `"move"` and `"copy"` require from. `"add"` overwrites existing keys; `"replace"` fails on missing keys, so prefer `"add"` when unsure whether the key exists. `"edit"` rewrites part of a string in place: `{ op: "edit", path, find, replace }` replaces the one occurrence of find in the string at path, and fails unless the match is unique. Use it to touch long descriptions without resending them. A patch with path `""` (whole replacement) is rejected. |

## read_document

**Read a document**

~~~text
Returns a document's title, description, and diagram order as JSON.
Modify with write_document by sending a patch against this JSON.
Read individual diagrams with read_diagram.

Document shape (JSON Patch targets this JSON):
  {
    "title": "Data platform",
    "description": "Internal architecture overview.",
    "project": "default",
    "diagrams": ["overview", "ingest", "serving"]
  }

diagrams lists diagram ids in reading order. Order is the array itself; there are no indexes.
project is the id of the project the document belongs to; replace it to move the document.
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `document` | string | yes | Document id returned by create_document. |

## write_document

**Write a document (JSON Patch)**

~~~text
Applies a JSON Patch to a document's title, description, and diagram order.

Document shape (JSON Patch targets this JSON):
  {
    "title": "Data platform",
    "description": "Internal architecture overview.",
    "project": "default",
    "diagrams": ["overview", "ingest", "serving"]
  }

diagrams lists diagram ids in reading order. Order is the array itself; there are no indexes.
project is the id of the project the document belongs to; replace it to move the document.

Example: move the third diagram to the front
  [{ "op": "move", "from": "/diagrams/2", "path": "/diagrams/0" }]
Example: rewrite the description
  [{ "op": "replace", "path": "/description", "value": "…" }]

Ids cannot be added to or removed from diagrams: create with write_diagram, delete with delete_diagram.
In a steps document, reordering keeps every diagram as it looks; later edits build on the new order.
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `document` | string | yes | Document id returned by create_document. |
| `patch` | array of `{ op, path }`, at least one item | yes | RFC 6902 JSON Patch applied to the JSON returned by read_document. A patch with path `""` (whole replacement) is rejected. |

## copy_diagram

**Copy a diagram**

~~~text
Copies a whole diagram, including model and style.
The copy follows the diagram whose id is in after; by default the source within
a document, or the last diagram in another document.

Use to move a diagram to another document or to branch an alternative from it.
Not needed for the next diagram of a steps document: new diagrams inherit the previous one automatically.

Example: copy to another document under the same id
  { "document": "…", "diagram": "overview", "into": "…" }
Example: copy within the document, placed after another diagram
  { "document": "…", "diagram": "overview", "as": "overview-alt", "after": "ingest" }
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `document` | string | yes | Document id returned by create_document. |
| `diagram` | string, matches `^[A-Za-z_][A-Za-z0-9_-]*$` | yes | Id of an existing diagram in the document. Alphanumerics, underscores, and hyphens; must not start with a digit. Errors if absent. |
| `into` | string | no | Destination document id. Defaults to the source document. |
| `as` | string, matches `^[A-Za-z_][A-Za-z0-9_-]*$` | no | Id for the copy. Alphanumerics, underscores, and hyphens; must not start with a digit. Defaults to the source id. Errors if it already exists. |
| `after` | string, matches `^[A-Za-z_][A-Za-z0-9_-]*$` | no | Id of the diagram in the destination document that the copy should follow. Defaults to the source diagram within a document, or the last diagram in another document. |
| `title` | string, 1–20 characters | no | Title for the copy. Defaults to the source title. |
| `description` | string, non-empty | no | Description for the copy. Defaults to the source description. |

## delete_diagram

**Delete a diagram**

~~~text
Deletes one diagram from a document. Returns the remaining diagram order.
To delete the whole document, use delete_document.

In a steps document, content added on the deleted diagram also disappears from later diagrams.
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `document` | string | yes | Document id returned by create_document. |
| `diagram` | string, matches `^[A-Za-z_][A-Za-z0-9_-]*$` | yes | Id of an existing diagram in the document. Alphanumerics, underscores, and hyphens; must not start with a digit. Errors if absent. |

## read_diagram

**Read a diagram**

~~~text
Returns one diagram as JSON: title, description, model, and style.
Use to check current content before writing a JSON Patch.
Modify with write_diagram by sending a patch against this JSON;
that tool documents the diagram shape and the available style keys.
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `document` | string | yes | Document id returned by create_document. |
| `diagram` | string, matches `^[A-Za-z_][A-Za-z0-9_-]*$` | yes | Id of an existing diagram in the document. Alphanumerics, underscores, and hyphens; must not start with a digit. Errors if absent. |

## list_versions

**List diagram versions**

~~~text
Returns a diagram's versions, newest first; the first entry is the current version.
Every write appends a version; versions are never deleted and are addressed by hash.
Returns the newest 20 by default; raise limit for more. total counts them all.
Restore an old version with restore_diagram.
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `document` | string | yes | Document id returned by create_document. |
| `diagram` | string, matches `^[A-Za-z_][A-Za-z0-9_-]*$` | yes | Id of an existing diagram in the document. Alphanumerics, underscores, and hyphens; must not start with a digit. Errors if absent. |
| `limit` | number, 1–100 | no, default `20` | Maximum number of versions to return. Default 20. |

## restore_diagram

**Restore a version**

~~~text
Restores a diagram to the content of a given version.
The restored content is appended as a new version, so no history is lost.
Find version hashes with list_versions.
Old versions that violate current invariants (e.g. leaf nodes without icons) are rejected.
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `document` | string | yes | Document id returned by create_document. |
| `diagram` | string, matches `^[A-Za-z_][A-Za-z0-9_-]*$` | yes | Id of the diagram to restore. |
| `version` | string | yes | Version hash returned by list_versions. |

## render_diagram

**Render a diagram (PNG)**

~~~text
Renders a diagram to a PNG image, alongside the diagram's title and description.
The background is transparent by default; set background to "white" for dark surfaces.
Rendered to fit 1400px on the long edge, which is the resolution a model can read;
the diagram URL serves the full-size image for humans.
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `document` | string | yes | Document id returned by create_document. |
| `diagram` | string, matches `^[A-Za-z_][A-Za-z0-9_-]*$` | yes | Id of an existing diagram in the document. Alphanumerics, underscores, and hyphens; must not start with a digit. Errors if absent. |
| `background` | one of `white`, `transparent` | no, default `"transparent"` | `"white"` fills the background; `"transparent"` leaves it unfilled so the surface behind shows through. Default `"transparent"`. |

## upload_icon

**Upload an icon**

~~~text
Uploads a custom icon for use in diagrams. Pass either raw SVG or base64-encoded PNG/JPEG.
Once stored under a set and name, reference it as "u:<set>:<name>" in style.icon, across documents.
Sets are created on demand. Re-uploading the same set and name replaces the icon.

SVG is sanitized to drawable content only; scripts, animation, and external references are removed.
If nothing drawable remains after sanitizing, the upload is rejected.

Text inside SVG is dropped in PNG export; convert text to paths first.

To use the icon on a node, set style.icon:
On leaf nodes it renders at 40px with the label below.
  "style": { "store": { "icon": "u:aws-icons:s3", "label": "S3" } }
Adjust with iconSize (px).
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `set` | string, matches `^[a-z0-9]+(-[a-z0-9]+)*$` | yes | Custom icon set name; created if it does not exist (e.g. aws-icons, company). Referenced in diagrams as `"u:<set>:<name>"`. |
| `name` | string, matches `^[a-z0-9]+(-[a-z0-9]+)*$` | yes | Name within the set. |
| `svg` | string, non-empty | no | Raw SVG source. Mutually exclusive with image. |
| `image` | string, non-empty | no | Base64-encoded PNG or JPEG, up to 512KB. |

## search_icons

**Search icons**

~~~text
Searches icon names usable in style.icon, over built-in icons and custom icons
(custom first). Matches names only, not descriptions or categories.
Separators are ignored, so "loadbalancer" and "load-balancer" match alike,
and product names match directly (postgresql, kubernetes, s3, ec2, …).
The response returns matching names plus the sets they came from, with hit counts;
pass one back as set to keep a diagram visually consistent.
Set color to "color" for brand logos with intrinsic colors (this excludes custom icons).

Write found names into style. Leaf nodes require one, rendered at 40px;
containers take only an icon, rendered at 16px left of the heading.
  "style": { "db": { "icon": "i:logos:postgresql", "label": "PostgreSQL" } }
~~~

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string, non-empty | yes | Search terms, in English (e.g. database, kubernetes, user). |
| `set` | string | no, default `""` | Restrict results to one set (e.g. lucide, logos, mdi). Use to keep icons visually consistent within a diagram. The middle segment of a returned name is its set. |
| `color` | one of `color`, `mono` | no | `"color"` selects icons with intrinsic colors (brand logos); style.textColor has no effect on them. `"mono"` selects monochrome icons that take the style color. Omit to search both. |
| `limit` | number, 1–50 | no, default `20` | Maximum number of results. Default 20. |

Source: https://docs.dia.rakudeji.com/en/ai/tools/index.mdx