Using Schematex with AI

Machine clients can discover the complete public surface without scraping the rendered site: /llms.txt is the curated index, /llms-full.txt contains the full English documentation, every docs URL has a .md mirror, and /api/interactive-capabilities exposes the canonical editor capability registry as JSON.

TL;DR

Schematex ships a tool layer built for LLMs — eight tools that let an AI agent discover, generate, validate, render, inspect, and safely edit diagrams. Three integration paths, same contracts:

The eight tools

Every path exposes the same eight tools with identical semantics.

listDiagrams()

Returns all 50 diagram types with tagline, "use when" hint, cluster, authoritative standard, and interactive capability summary. Call first to pick a type.

getSyntax({ type, detail? })

Canonical syntax for one diagram. Call after picking a type.

The default detail: "canonical" response is designed for first-shot LLM generation: canonical header, preferred mode, core forms, avoid/repair guidance, and shared generation rules. Use detail: "reference" only when the request needs an advanced feature or an imported adapter; that returns the trimmed public docs slice from ## 1. through the grammar section.

getExamples({ type, limit?, preferFeatured?, maxComplexity? })

Curated real-world DSL examples with scenario notes. Use as few-shot context before generation.

validateDsl({ type?, dsl })

Parse-only check. Returns { ok: true } or { ok: false, errors: [{line, column, message, source, hint}] }. Pass the selected canonical type once you know it, and always call before returning DSL to the user — agents that self-correct with this loop are dramatically more reliable.

renderDsl({ type?, dsl, theme?, padding? })

Render DSL to an SVG string. Success returns { ok: true, status, svg }. Failure returns { ok: false, status: 'invalid', svg, errors }, where svg is a visible diagnostic fallback instead of an empty preview.

getDiagramCapabilities({ type })

Returns the diagram's safe text and position-editing contract. Call before proposing direct manipulation or geometry changes.

inspectDiagram({ type?, dsl })

Returns a source revision plus stable editable target keys, labels, bounds, and allowed operations. It intentionally does not expose raw source offsets to the model.

applyDiagramEdits({ type?, dsl, revision, edits })

Atomically applies up to 50 setLabel / setPosition operations. A stale revision, unknown target, unsafe operation, or invalid result returns the original DSL—never a partially edited document.

For an in-app AI preview, render the returned DSL with renderResult() or renderPreview():

import { renderResult } from 'schematex';

const result = renderResult(dsl, { type });
preview.innerHTML = result.svg;

if (!result.ok) {
  queueRepair(result.diagnostics);
}

The preview can stay visible while your app still treats ok: false as an invalid user result for repair, retry, telemetry, or billing policy.

Path 1 — Vercel AI SDK (in-app)

The quickest way to add Schematex generation to a Next.js / Node app.

import { streamText } from 'ai';
import { schematexTools } from 'schematex/ai/sdk';

const result = streamText({
  model: 'anthropic/claude-opus-4-7',
  tools: schematexTools,
  maxSteps: 5,
  system: `You write Schematex DSL. First call listDiagrams to pick a type.
Then call getSyntax and getExamples for that type. Write the DSL, then
call validateDsl and self-correct on errors before returning to the user.`,
  prompt: userMessage,
});

The schematex/ai/sdk subpath only loads if the optional ai peer dependency is installed. It uses JSON Schema directly, so your app does not need Zod. If you don't use the AI SDK, import the plain functions from schematex/ai and wire them to any framework:

import {
  listDiagrams,
  getSyntax,
  getExamples,
  validateDsl,
  renderDsl,
  getDiagramCapabilities,
  inspectDiagram,
  applyDiagramEdits,
} from 'schematex/ai';

Single-shot generation (no tool loop)

High-volume backends often generate with one model call instead of a multi-step tool loop — cheaper and lower latency. For that, buildPromptContext(type) assembles the canonical grammar card and a featured few-shot example into one inject-ready block, so you don't have to stitch getSyntax + getExamples together yourself:

import { buildPromptContext, validateDsl } from 'schematex/ai';

const ctx = buildPromptContext('genogram');          // grammar card + featured example
const system = `Generate only Schematex DSL.\n\n${ctx.text}`;
const dsl = await generate(system, userMessage);     // your single model call

const check = validateDsl('genogram', dsl);          // always gate server-side
if (!check.ok) {
  // one repair pass: re-prompt with check.errors[].message + .hint
}

buildPromptContext is pure sugar over getSyntax({ detail: 'canonical' }) + getExamples({ preferFeatured: true }) — both remain available if you'd rather compose the prompt yourself. Options: { examples?: number, detail?, preferFeatured?, maxComplexity? }.

Path 2 — Hosted MCP (zero install)

The Schematex MCP server is hosted at:

https://schematex.js.org/mcp

Any MCP client that speaks JSON-RPC over HTTP can connect. No install, no local process, always up to date with the latest schematex release.

Claude.ai (web)

Use the connect block at the top of this page — one click opens the connector dialog, paste the URL, done. The connector then appears under Settings → Connectors and is available in every conversation.

Claude Desktop (app)

Settings → Connectors → Add custom connector → paste https://schematex.js.org/mcp.

ChatGPT / Cursor / Windsurf

Follow your client's "Add MCP server" flow and use the HTTP transport with the URL above.

Path 3 — Local stdio MCP

For offline development or clients that only support stdio transport.

npm i -g @schematex/mcp
# or
npx @schematex/mcp

Claude Desktop config

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "schematex": {
      "command": "npx",
      "args": ["-y", "@schematex/mcp"]
    }
  }
}

Recommended agent loop

The single biggest reliability win is making the agent validate its own output and self-correct.

1. listDiagrams()                          → pick the right type
2. getSyntax({ type })                     → get canonical generation syntax
3. getExamples({ type, maxComplexity: 2 }) → get few-shot context
4. write DSL
5. validateDsl({ type, dsl })
   ├─ ok:    return DSL to user
   └─ error: read line/column/message, fix, goto 5
6. (optional) renderDsl({ type, dsl })     → return SVG (skip if app renders natively)
7. (for edits) inspectDiagram({ type, dsl })
   → applyDiagramEdits({ dsl, revision, edits })

A simple system prompt that implements this loop:

You generate Schematex DSL for diagrams. Always follow this procedure:

1. If you don't already know which diagram type matches the user's request,
   call listDiagrams and pick the best match.
2. Call getSyntax for the chosen type. Stay on the canonical path unless an
   advanced feature requires getSyntax({ type, detail: "reference" }).
3. Call getExamples (maxComplexity: 2) for few-shot context.
4. Write the DSL.
5. Call validateDsl. If ok:false, read the error's line, column, and message,
   fix the DSL, and call validateDsl again. Repeat up to 3 times.
6. Return the validated DSL to the user, inside a ```schematex code block.

Error shape

validateDsl and renderDsl return structured errors on failure:

{
  ok: false,
  status: 'invalid',     // renderDsl only
  type: 'genogram' | null,
  svg: string,           // renderDsl only: visible diagnostic fallback
  errors: [
    {
      line?: number;        // 1-based, if the parser reported it
      column?: number;
      source?: string;      // the offending line text
      message: string;      // human-readable
      hint?: string;
    }
  ]
}

Not all parsers emit line info yet (genogram, pedigree, ecomap, venn, sld, fishbone do today; others return message-only). The shape is stable — line is optional.

Ready to try it?

Licensing notes

Schematex is AGPL-3.0. For closed-source commercial integrations contact victor@mymap.ai for a commercial licence.