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 20 diagram types with tagline, "use when" hint, cluster, and authoritative standard. Call first to pick a type.

getSyntax({ type })

Compact syntax reference for one diagram — rules, grammar (EBNF), and inline examples. Call after picking a type.

The returned content is a trimmed slice of the public docs page: ## 1. Your first … through ## N. Grammar (EBNF). Decorative sections (About, Standard compliance, Related examples, Roadmap) are dropped at build time — they don't help an LLM generate DSL. Expect ~2,100–3,700 tokens per call (avg ~2,600, max ~3,700 for circuit). If you need the full narrative version, link to https://schematex.js.org/docs/{type} directly.

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}] }. 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. Returns { ok: true, svg } or { ok: false, errors }.

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';

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

The connector will appear 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 })                     → learn the grammar
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. Read it carefully.
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,
  type: 'genogram' | null,
  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 20 parsers emit line info yet (genogram, pedigree, ecomap, venn, sld, fishbone do today; others return message-only). The shape is stable — line is optional.

Licensing notes

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