io.github.docdiagram/docdiagram-mcp

Generate a standalone diagram from a prompt. No MDX file or repo binding required: this is the zero-setup path for a customer who has only run /docdiagram:auth. Creates a chat in the account's default project and polls briefly for the render. NON-BLOCKING on a slow render: if the render is not done within a few seconds it returns a pending handle (``render_status`` is the inflight value, ``image_urls`` empty) that you resolve later with ``diagram_get(chat_slug)`` rather than raising. Does NOT download bytes; the caller fetches the short-lived signed URLs (valid ~5 min) WITHOUT credentials. Prefer the ``light`` theme (``default_theme``). Output is watermarked while the account is on the free tier (``is_free_tier``). Returns {chat_slug, chat_url, render_status, default_theme, image_urls, is_free_tier}, or, if a generation is already in flight on the resolved chat, {status: "generation_in_flight", chat_id}.

Resolve a standalone diagram by its handle (the chat ``slug`` that ``diagram_create`` and ``diagram_list`` return). This is how you pick up a diagram that ``diagram_create`` returned as pending, and the dereference half of the deterministic-handle round-trip. Reads the correctly-resolved revision (the pinned one if pinned, else the one referenced by the last chat message, NEVER ``revisions[0]`` by position) and returns its freshly signed ``image_urls``. Returns {chat_slug, chat_url, render_status, default_theme, image_urls, pinned}, where ``pinned`` is true when the resolved revision is the pinned one. A brand-new chat with no rendered revision yet returns ``render_status: "unknown"`` with empty ``image_urls`` rather than erroring.

List the caller's standalone diagrams. Defaults to the account's default project (the zero-setup project); pass ``project_id`` to scope to another. Returns {items: [{chat_slug, title, thumbnail_url, updated_at}]}, the handle paired with the human label. Show ``title`` to the user, resolve their natural-language pick to the corresponding ``chat_slug``, then call ``diagram_get``/``diagram_revise`` with that ``chat_slug``. Titles are NOT unique and are never a key; always carry the ``chat_slug`` forward.

Revise an existing standalone diagram with a follow-up prompt, addressed by its handle (the chat ``slug``). Resolve a human pick to a ``chat_slug`` first (via ``diagram_list``); never re-create, which would silently duplicate. Appends a turn to the chat and polls briefly for the new render, with the same non-blocking behavior as ``diagram_create``: a slow render returns a pending handle to resolve later with ``diagram_get``. If a generation is already in flight on the chat, returns {status: "generation_in_flight", chat_slug, chat_id} as a retry signal instead of erroring. On success returns {chat_slug, chat_url, render_status, default_theme, image_urls, message_id, job_id}.

Look up a binding by (repo, docs_path, slot). Returns None if no live binding exists. Soft-deleted rows are excluded so a re-create after delete works without surfacing the tombstone.

Create a new embedded diagram bound to (repo, docs_path, slot). Errors with 409 if a binding already exists (use embedded_diagram_revise). Render runs as an arq job; blocks on the status URL until terminal (30s timeout) and returns the result. Returns {docdiagram_id, binding, sidecar, mdx_reference}; does NOT inline render bytes.

Soft-delete a binding. Does not delete the diagram itself; the canonical revision history remains addressable via the chat.

Fetch a binding (and its referenced diagram metadata) by id. Returns soft-deleted rows too so the orphan view in TECH-065 works.

List bindings for a repo. Cursor-paginated per TECH-062's (created_at, id) base64-JSON convention. Returns {items, next_cursor}.

Regenerate an existing embedded diagram by re-running the last prompt. Server resolves the current revision via diagram_revision_service.resolve_current and re-invokes the LLM with the most recent user message on the bound chat. Use when the diagram drifted or you want a fresh sample without retyping the prompt. Blocks until terminal (30s).

Return {full_png_url, expires_at}. full_png_url is a short-lived signed render URL (TECH-069) the caller fetches WITHOUT credentials, so it works off-origin where a bearer header can't be attached. Render is compute-on-demand via arq. Binary payloads in MCP tools are awkward; a URL is the right primitive.

Return {full_svg_url, expires_at, byte_size}. full_svg_url is a short-lived signed render URL (TECH-069) the caller fetches WITHOUT credentials, so it works off-origin where a bearer header can't be attached. Render is compute-on-demand via arq (no cache table). The full SVG is NOT inlined: large diagrams blow out the model's context and SVG XML is rarely useful for the model to read directly.

Revise an existing embedded diagram via a follow-up prompt. Addressed by docdiagram_id, not by repo/docs_path/slot. Render runs as an arq job; blocks until terminal (30s timeout).

Fetch a repo row by its DocDiagram UUID. Use repo_lookup if you only have the GitHub node id.

Look up a repo by GitHub node id. Scoped to the caller's account (TECH-062 UNIQUE(account_id, host, host_id)). Returns the repo row or None if not registered.

Register or update a repo. Idempotent on (account_id, host, host_id). Account scoping is implicit from the bearer token. Returns {id, account_id, host, host_id, repo_full_name, default_branch, docs_tool, docs_config_path, installation_id, sidecar_mode}.

Poll a sync run by id. Returns {status, pr_url, pr_number, bindings_updated, error_message, last_human_commit_sha, created_at, completed_at}.

List recent sync runs for a repo, newest first. Cursor-paginated per TECH-062's (created_at, id) base64-JSON convention. Returns {items, next_cursor}.

Trigger a sync run: pushes pending revisions to the customer's repo via PR. Idempotent in-flight dedup (partial unique index on pending/running/pr_opened states). Returns {sync_run_id, status, job_id, already_in_flight}.