ohmyartifact reference

ohmyartifact is a local slide and document editor. Every artifact is one markdown string, stored as the source of truth. A person edits it on a canvas in the web app; a model edits it over MCP. Both write the same string, so edits from either side appear on the other within a few seconds.

• Two kinds of artifact: document (one GFM markdown file) and slideshow (Marp-style: slides separated by ---, each with an optional ```overlays JSON block).
• The MCP server runs inside the backend on the same port as the app (make dev in app/). It is always on, stateless, and unauthenticated; it sends the authoring guide as its instructions on connect.
• Every write is optimistically concurrent: it carries the version you last read and is rejected as stale version if anyone saved in between. Every read and write returns the current version.
• Every write is validated as a whole: an invalid overlay or an unsupported mermaid line rejects the entire write with one message per problem, and nothing is saved.

1. list_artifacts (optionally with a query) to find an id, then read_artifact. Keep the version; for a deck, the outline gives you slide numbers.
2. Pick the narrowest write: edit_artifact for a sentence, replace_slide for one slide, insert_slide for a new one, update_artifact only to rewrite most of it.
3. Send the version you read. On stale version, read again, reapply your change to the fresh text, and write once more. Do not loop.
4. On invalid content, fix the fields named in the message and retry. Never drop an element to make an error go away.

read_artifact returns the artifact both as structured JSON (the fields above, plus slides for decks) and as text in this shape:

The first line is metadata; the [slides] line lists 1-based slide numbers with each slide's title (its first # heading, else its first heading of any level, else Slide N); the markdown starts after the blank line.

A document is ordinary GitHub-flavored markdown: headings, paragraphs, lists, tables, links, images, code fences, blockquotes. On write, \r\n is normalized to \n and any ```mermaid block is converted to a ```drawing block (see Diagrams). Nothing else is rewritten.

A deck is one markdown string. Slides are separated by a line containing only ---. Each slide is markdown, optionally followed by exactly one fenced ```overlays block holding a JSON array of positioned elements on a 1280×720 canvas.

• A leading YAML frontmatter block (--- … --- at the very top) is stripped and ignored.
• A --- line inside any fenced code block is content, not a separator. Empty chunks between separators are dropped. A deck always has at least one slide.
• The overlays block is ```overlays on its own line, the JSON array, then ```. Only one per slide is parsed; whatever precedes and follows it is the slide body.
• A slide's body starts with an optional <!-- background: URL --> line for a full-bleed background image (URL or data: URL). Removing the line removes the image.

Every write re-serializes the deck: each slide is its trimmed body, then (if present) a blank line and the overlays fence with every element given an id; slides are joined with \n\n---\n\n and the deck ends with a newline. read_artifact returns this form, so old_text for edit_artifact must be copied from it.

Slide tools (replace_slide, insert_slide) take the markdown of one slide, without --- separators, and validate it the same way.

The ```overlays block is a JSON array. Each element is one of five types, selected by type. The full JSON Schema (draft 2020-12) is served as the resource oma://schema/overlays; the server validates every write against it, choosing the variant by type so errors name the field that is wrong. Elements without an id get one on save. Keep the id of any element you were given so the app can tell an edit from a replacement.

The one enum behind color on text/stat/panel and tone on card:

• The block must be a JSON array of objects. Each object's type selects its schema; an unknown type is rejected.
• Required fields, enums and numeric ranges are enforced exactly as listed above. Fields outside the schema are not validated.
• Failures are collected per element and reported together as invalid content, prefixed with slide N: in deck-wide writes. Nothing is saved.

Write a fenced ```mermaid flowchart in a document or a slide body. On save the server converts it to a ```drawing block that a person can then rearrange by hand. Unsupported syntax rejects the write and names the block and line.

Existing ```drawing blocks are hand-drawn diagrams; do not edit their JSON.

Eleven tools. Every tool returns a human-readable text line and a structured object. Read tools are annotated read-only; delete_artifact and delete_slide are annotated destructive. Parameters shared by all writes:

Every successful write returns { id, kind, title, version } where version is the new version to pass to your next write.

Tool errors are plain messages written to be acted on. The complete set: