graphite-art-mcp

Overview Schema Source Related Servers Discussions Admin

Graphite: insert SVG as editable artwork

graphite_insert_svg

Insert SVG markup or a local SVG file into a Graphite document as editable vector layers, converting text to outlines for native hand-editing.

Instructions

Insert SVG markup into the active Graphite document as an editable group layer (each SVG element becomes its own vector layer; the user can keep editing it by hand). This is the main way to create artwork: generate the SVG yourself, then call this with either svg (inline markup) or svg_path (a local file; preferred for anything large). Returns the new layer_id. The operation is one undo step. is converted to outlined paths automatically (Graphite cannot render text from SVG); pass outline_text=false to skip that. Large artwork is slow to build (roughly 40 ms per element); the wait scales with the element count. Fails with NO_ACTIVE_DOCUMENT if no document is open (call graphite_new_document first), INVALID_SVG if the markup does not parse, and BRIDGE_TIMEOUT if Graphite has not reported the layer in time even after a grace period — in that case call graphite_get_document and look for the returned layer_id before retrying, because the layer may still appear and a retry would duplicate it.

Input Schema

TableJSON Schema

Name	Required	Description
`x`	No	Horizontal position in document units (pixels). With center=false this is the left edge of the SVG viewBox.
`y`	No	Vertical position in document units; y grows downward. With center=false this is the top edge of the SVG viewBox.
`svg`	No	Complete SVG markup starting with <svg …>. Give it a viewBox and explicit width/height; gradients, groups, paths, basic shapes and text are supported (<text> is converted to outlined paths by the connector, see outline_text). Provide either svg or svg_path.
`name`	No	Optional layer name shown in the Layers panel.
`center`	No	When true, (x, y) becomes the visual centre of the artwork instead of its top-left corner.
`svg_path`	No	Absolute path of a local SVG file to insert instead of inline markup. Prefer this for large artwork (hundreds of elements): the file is read by the connector, so the markup is not re-sent on every call.
`parent_id`	No	Optional layer_id of a group or artboard to insert into. Omit to insert at the document root.
`outline_text`	No	Convert <text> elements to outlined paths before inserting (default). Graphite's web build cannot render text itself. Uses the bundled Liberation Sans/Serif/Mono faces, or fonts from GRAPHITE_MCP_FONT_DIR matched by family name; italic is synthesised.

Output Schema

TableJSON Schema

Name	Required	Description
`elements`	Yes	Number of SVG elements sent; each becomes a layer.
`layer_id`	Yes	Node id of the new group layer, as a decimal string. Refer to it in later edits.
`document_id`	Yes	Active document the layer was inserted into, when known.
`text_outlined`	Yes	Number of <text> elements converted to paths before inserting.
`confirmed_late`	Yes	True when the bridge's wait expired but graphite_get_document then showed the layer, so nothing needs to be retried.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Sep 28, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only supply the safety flags; the description adds substantial non-obvious behavior: one undo step, ~40 ms per element build cost, automatic <text> outlining (and the outline_text=false escape hatch), and three named failure modes with remediation. The duplicate-layer warning on retry is a real behavioral hazard disclosed only here.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then usage, then errors; nearly every sentence carries new information. It is on the long side and a few clauses (e.g. re-explaining that <text> becomes paths) overlap with the schema, costing a point but not readability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 8-parameter mutation tool with an output schema, the description covers what the schema cannot: cost model, undo semantics, error taxonomy and retry safety. Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, but the description still adds decision-relevant meaning: which of svg/svg_path to prefer and why (file read by connector, markup not re-sent), and why outline_text defaults to true (Graphite cannot render text). These are trade-offs, not restatements.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb+resource+outcome: inserting SVG markup as an editable group layer where each SVG element becomes its own vector layer. It also positions itself among siblings by calling itself 'the main way to create artwork', so an agent can distinguish it from graphite_export or graphite_new_document.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit selection guidance between the two input modes ('svg_path ... preferred for anything large'), tells the agent to generate the SVG itself first, and names the prerequisite (graphite_new_document) when NO_ACTIVE_DOCUMENT fires. The BRIDGE_TIMEOUT recovery path — check graphite_get_document before retrying to avoid duplicates — is exactly the kind of when-to-do-what guidance that prevents agent errors.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server