Using Schematex with AI

TL;DR

Schematex ships a tool layer built for LLMs — five tools that let an AI agent discover diagram types, learn their syntax, see curated examples, validate its own output, and render SVG. Three integration paths, same tools:

The five tools

Every path exposes the same five tools with identical semantics.

listDiagrams()

Returns all 45 diagram types with tagline, "use when" hint, cluster, and authoritative standard. 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.

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 ai and zod are installed (both are optional peer-deps). 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 } 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)

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.