This page ships a Markdown twin for AI tools.

Texuli MCP

A Model Context Protocol server that lets an agent search the Texuli component catalog, read manifests and worked examples, validate blueprint drafts, pick and check themes, run the deck and document commands, and read texuli.com itself. Every tool is read-only.

Remote: https://texuli.com/mcp
Local: npx -y @texuli/mcp
Protocol: 2025-11-25
Server card: /.well-known/mcp/server-card.json
Serves: 35 tools, 9 resources, 5 resource templates and 4 prompts, with completions

The developer portal puts the server next to the JSON API and the CLI; this page is the whole server.

Two doors, one registry

Both servers are generated from the same operations registry (@texuli/tools/ops), so a tool has one name, one input schema and one set of limits wherever it runs.

Remote: https://texuli.com/mcp. Stateless Streamable HTTP: POST JSON-RPC, JSON answers, no session and no key. It serves 29 tools: the edge tools and the site tools.
Local: npx -y @texuli/mcp, or npx -p @texuli/tools texuli mcp when a project already has @texuli/tools. Over stdio, on Node.js, offline once installed. It serves 32 tools: the edge tools and the Node tools.

Set up your host

Each host takes either door. The local one runs the same command everywhere; the remote one is a URL. On Windows, hosts that cannot start npx directly take "command": "cmd" with "args": ["/c", "npx", "-y", "@texuli/mcp"].

Claude Code

In a terminal in the project.

Local

claude mcp add texuli -- npx -y @texuli/mcp

Remote

claude mcp add --transport http texuli https://texuli.com/mcp

Cursor

In .cursor/mcp.json in the project, or ~/.cursor/mcp.json.

Local

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

Remote

{
  "mcpServers": {
    "texuli": { "url": "https://texuli.com/mcp" }
  }
}

VS Code

In .vscode/mcp.json in the workspace.

Local

{
  "servers": {
    "texuli": { "type": "stdio", "command": "npx", "args": ["-y", "@texuli/mcp"] }
  }
}

Remote

{
  "servers": {
    "texuli": { "type": "http", "url": "https://texuli.com/mcp" }
  }
}

Windsurf

In ~/.codeium/windsurf/mcp_config.json.

Local

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

Remote

{
  "mcpServers": {
    "texuli": { "serverUrl": "https://texuli.com/mcp" }
  }
}

Codex

In ~/.codex/config.toml.

Local

[mcp_servers.texuli]
command = "npx"
args = ["-y", "@texuli/mcp"]

Remote

[mcp_servers.texuli]
url = "https://texuli.com/mcp"

Any other host

In the host’s MCP settings.

Local

stdio command: npx -y @texuli/mcp
(already using @texuli/tools: npx -p @texuli/tools texuli mcp)

Remote

Streamable HTTP URL: https://texuli.com/mcp

Tools

35 tools, grouped by where they can run. Each one has an input and an output JSON Schema and read-only annotations; a failure is an isError result with a stable code. Limits are the input size, the item cap and the time budget.

Edge tools

Pure functions over the built catalog and themes: served by both doors.

Tool	What it does	Arguments	Doors	Limits
`catalog.search`	Search the built, content-addressed Texuli component catalog by text, group and emit tier. Returns the catalog hash and file name, the match count and one summary per component (id, package, label, summary, tier, group, emit tiers).	`query`, `group`, `tier`, `limit`	Remote and local	input 4 KiB · 100 items · 5 s
`catalog.validate`	Validate one candidate catalog manifest, or a set (which also catches duplicate ids), without writing files. Returns valid and a list of diagnostics, each with a code, a JSONPath, a message and a hint.	`manifest`, `manifests`	Remote and local	input 977 KiB · 500 items · 5 s
`component.get`	Read one component manifest from the catalog by id. Returns { component }: its props with kinds and schemas, events, worked examples, useWhen and dontUseWhen guidance, accessibility notes and the emit tiers that may place it (an empty emit list means agent output may not).	`id` (required)	Remote and local	input 1 KiB · 5 s
`example.search`	Find worked manifest examples (props an agent can copy) by component id and/or example id, or search their titles and descriptions. Returns the match count and each example with its component id and package.	`componentId`, `exampleId`, `query`, `limit`	Remote and local	input 4 KiB · 100 items · 5 s
`blueprint.validate`	Validate a blueprint draft (a catalog tree, an array of trees, or a texuli-blueprint envelope, migrated first) with the catalog's checks: structure, sinks, tree limits, component ids, tiers, prop, block and document schemas, the envelope's designSystem (codes under $.designSystem), grammar and the frame root. Returns valid, status, tier, migratedFrom and diagnostics with stable codes.	`draft` (required), `tier`, `fragment`	Remote and local	input 264 KiB · 512 items · 5 s
`blueprint.theme`	Set a blueprint envelope's designSystem to a reference ({ ref: "[email protected]" } or a library theme "texuli:ocean") or an inline document, wrapping a bare tree in a draft envelope first, then validate the result as blueprint.validate does; an inline document is also compiled for the contrast, focus and target guarantees. Returns valid, the themed blueprint and diagnostics with stable codes.	`blueprint` (required), `designSystem` (required), `tier`, `id`	Remote and local	input 1.3 MiB · 512 items · 10 s
`block.list`	List the content block types the blocks-* components render (table, stat, cta, poll …), optionally for one component or matching words. Returns the match count and, per type, the component that renders it, a label and when to use it; read one shape with block.schema.	`component`, `query`	Remote and local	input 1 KiB · 32 items · 5 s
`block.schema`	Read the shape of one content block type: the component that renders it, its fields as compact text and as a JSON Schema (required fields are the ones the validator refuses a block without), examples that validate in a blueprint, limits, when to use it and whether it can pass blueprint.validate today. Returns what a blocks-* node’s block prop needs.	`type` (required)	Remote and local	input 1 KiB · 5 s
`theme.search`	Search the Texuli theme library (200+ offline themes) by words, category, collection, mood or tag. Returns the match count and each theme’s metadata: id, name, description, category, collection, mood, tags, contrast level and whether it is dark-first.	`query`, `category`, `collection`, `mood`, `tag`, `limit`	Remote and local	input 4 KiB · 500 items · 5 s
`theme.get`	Read the full token definition of one library theme by id. Returns { theme }: its id, name, description and every light and dark color, radius, font and chart token, ready to compile or apply.	`id` (required)	Remote and local	input 1 KiB · 5 s
`theme.preview`	Preview one library theme in light or dark mode. Returns its summary, the key tokens of that mode (background, foreground, primary, border, radius, font …) and the WCAG 2.x AA contrast report for both modes (aa.pass and issue counts).	`id` (required), `mode`	Remote and local	input 1 KiB · 5 s
`ds.validate`	Validate a design-system document. Set full to run the complete locked-design-system validator, including catalog allow sets, extensions and an optional prototype's component and CSS policy checks. Returns every finding with stable code, severity, area, path and fix hint; the full mode is read-only and does not execute prototype sources.	`document` (required), `trust`, `variant`, `bases`, `full`, `report`, `strict`, `catalog`, `extensions`, `prototype`	Remote and local	input 1 MiB · 16 items · 10 s
`ds.compile`	Compile a design-system document to concrete --tx-* variables per mode and emit one format: compiled JSON, scoped CSS, a Tailwind preset, DTCG or Tokens Studio. Returns valid, the format, its media type, the content as text, the hash and warnings; a refused document returns errors with stable codes instead.	`document` (required), `format`, `selector`, `dark`, `mode`, `trust`, `variant`, `bases`	Remote and local	input 1 MiB · 10 s
`ds.contrast`	Compile a design-system document and report every contrast pair the guarantees check, per mode: foreground and background roles, kind (text, ui, focus), ratio, requirement and pass, plus the solver adjustments. Returns valid, the target (AA or AAA), targetMin and the per-mode pairs, or errors with stable codes.	`document` (required), `mode`, `trust`, `variant`, `bases`	Remote and local	input 1 MiB · 10 s
`ds.suggest`	Suggest a starting design-system document from one seed color, up to three brand colors (seed, secondary, accent) or a logo as RGBA pixels (the dominant colors pick the seed). Returns valid, the document, the dominant palette for pixels, the key tokens of each mode and warnings.	`seed`, `colors`, `pixels`, `count`, `id`, `version`, `name`, `trust`	Remote and local	input 1 MiB · 65536 items · 10 s
`ds.import`	Turn what a team already has into a valid design-system document: a brand one-liner ("brand #4f46e5, font Inter, rounded, compact"), a W3C DTCG file, a Tokens Studio file, a flat role palette or a Texuli theme (an object, or a library theme id). Returns valid, the document and warnings for every value it dropped, or errors with stable codes.	`from` (required), `input` (required), `id`, `version`, `name`, `trust`	Remote and local	input 1 MiB · 10 s
`ds.generate`	Combine a brand brief, token JSON, site CSS, logo pixels and/or a Texuli theme into a validated design-system draft. Returns the document, every reported loss, automatic AA repairs and guarantee results; it never saves or approves the draft.	`brief`, `tokens`, `css`, `logoPixels`, `theme`	Remote and local	input 1 MiB · 65536 items · 10 s
`ds.allow`	Build the allow section of a locked design system from the catalog: a preset (minimal, a documented core; all, every component) or the ids you name, each with every variant, size, tone, density, color and state the catalog declares. Narrow it, put it under "allow" and run ds.validate. Returns allow, count, unknown ids and the minimal preset ids.	`preset`, `components`	Remote and local	input 32 KiB · 256 items · 10 s
`ds.bundle`	Pack a design-system document with its library sources and release history into one JSON bundle, or unpack a bundle and return those parts. Returns ok, the bundle or the document, allowManifest, librarySources and history; hash mismatches, oversized sources and path-traversing ids are refused with stable codes. Sources are never executed.	`bundle`, `document`, `librarySources`, `history`	Remote and local	input 1 MiB · 64 items · 10 s
`ds.diff`	Compile two design-system documents (before is the baseline) and compare them: every added, removed or changed --tx-* variable per mode, contrast pairs that regressed below the target, changed component defaults and attributes. Returns valid, identical, the summary counts and each list, or errors tagged with their side.	`before` (required), `after` (required), `mode`, `trust`, `variant`, `bases`	Remote and local	input 1 MiB · 10 s
`ds.preview`	Render a static, deterministic snapshot of a compiled design system: svg (swatches, a button and a card per mode) or html (the review report: swatches, type ramp, component sheet, contrast table and adjustments). Fixed fonts, no time, no scripts; every value escaped. Returns valid, the format, media type, content and hash.	`document` (required), `format`, `title`, `mode`, `trust`, `variant`, `bases`	Remote and local	input 1 MiB · 10 s
`deck.run`	Inspect, lint and convert a Texuli deck on the shared v2 model: capabilities, the JSON Schema, layouts, lint, inspect, from-markdown and to-markdown. Pure compute; returns { result } with the command output (ok, issues, deck, markdown …).	`command` (required), `deck`, `markdown`	Remote and local	input 2 MiB · 10 s
`document.run`	Create, validate, inspect, patch and convert a Texuli document (spec 0.7.0): capabilities, the JSON Schema, validate, inspect, a bounded RFC 6902 patch (at most 1000 operations), from-markdown, to-markdown and to-blueprint. Returns { result } with the command output; PDF and DOCX are document.export.	`command` (required), `document`, `markdown`, `patch`, `tier`, `key`	Remote and local	input 2 MiB · 1000 items · 10 s
`md.convert`	Convert untrusted Markdown, HTML or a chat dialect (Slack, Discord, WhatsApp, Telegram MarkdownV2 and HTML, Teams, Google Chat, Mattermost, plain text) through the texuli-md/v1 AST. URLs use the untrusted policy. Returns { value, diagnostics }.	`source` (required), `from` (required), `to` (required)	Remote and local	input 1 MiB · 200 items · 10 s
`md.render`	Parse untrusted Markdown (GFM by default; gfm: false for strict CommonMark 0.31.2) and write a safe HTML fragment through the markup allowlist. Every href and src uses the untrusted URL policy; raw HTML is dropped. Returns { html, diagnostics }.	`source` (required), `gfm`	Remote and local	input 1 MiB · 200 items · 10 s
`emoji.convert`	Convert untrusted plain text between Unicode sequences and canonical Texuli shortcodes through the lean engine. dialect texuli is the default. dialect legacy is unsupported here and returns a diagnostic pointing at the local MCP. Returns { value, diagnostics }. Never throws.	`source` (required), `to` (required), `dialect`, `mode`	Remote and local	input 195 KiB · 200 items · 10 s

Node tools

Need Node.js (file formats): served by the local door only; the remote answers runtime-unavailable.

Tool	What it does	Arguments	Doors	Limits
`ds.save`	Validate a design-system document (as ds.validate does) and write it as two-space JSON to an explicit .json path inside the working directory (traversal, symlinks, dot paths, node_modules, package.json and existing files without overwrite are refused). Anything marked approved is refused (approval-human-only). Local doors only. Returns saved, the path and bytes, or errors with stable codes.	`path` (required), `document` (required), `overwrite`, `dryRun`, `trust`, `variant`, `bases`	Local only	input 1 MiB · 10 s
`document.export`	Write a Texuli document as PDF or DOCX bytes with the owned writers, links and media checked at the tier. Returns { result } with ok, mime, byteLength, base64 bytes (no files are written), diagnostics and, for PDF, pageCount. Needs Node.	`format` (required), `document` (required), `tier`	Local only	input 2 MiB · 30 s
`emoji.search`	Search the closed Unicode emoji catalog by name, shortcode or keyword. Returns { items }: approved ids with unicode, name, shortcode, category and score. Query at most 256 characters; at most 100 hits. Untrusted input; never throws. Needs Node (local MCP and CLI; not on texuli.com/mcp).	`query` (required), `locale`, `category`, `limit`	Local only	input 8 KiB · 100 items · 5 s
`emoji.get`	Look up one closed catalog record by hyphenated id, Unicode sequence or :shortcode:. Returns { emoji } with unicode, name, shortcode, category and variant fields. Unknown ids are not-found. Untrusted input; never throws. Needs Node (local MCP and CLI; not on texuli.com/mcp).	`id` (required)	Local only	input 2 KiB · 5 s
`emoji.categories`	List the closed Unicode emoji categories with how many catalog records each holds. Returns { categories: [{ id, count }] }. No input. Never throws. Needs Node (local MCP and CLI; not on texuli.com/mcp).		Local only	input 1 KiB · 9 items · 5 s
`emoji.variants`	List tone and other variants for a closed catalog id (or a variant of it). Returns { base, variants }. Unknown ids are not-found. Untrusted input; never throws. Needs Node (local MCP and CLI; not on texuli.com/mcp).	`id` (required)	Local only	input 2 KiB · 100 items · 5 s

Tool	What it does	Arguments	Doors	Limits
`site.pages`	List the pages of texuli.com from its Markdown twin manifest, in path order, optionally under a path prefix, a page at a time. Returns the total, the offset, the next offset when more follow, and each page’s path, twin path, URL, title and description.	`prefix`, `offset`, `limit`	Remote only	input 1 KiB · 200 items · 5 s
`site.read`	Read one texuli.com page as its Markdown twin: the page’s own content with a header block (title, description, canonical URL, last updated). Accepts a route, its .md twin path or a texuli.com URL. Returns the path, twin, URL, title, the Markdown, its size and whether it was cut at the size cap.	`path` (required)	Remote only	input 1 KiB · 5 s
`site.search`	Search texuli.com pages by words in their titles, headings, descriptions and paths, ranked deterministically (more matched words first, then title over path over heading over description). Returns the total and, per hit, the path, twin, URL, title, description, score and up to three matching headings.	`query` (required), `limit`	Remote only	input 1 KiB · 50 items · 5 s

Resources and templates

URI	Title	What it holds	Type
`texuli://catalog`	Component catalog	The content-addressed Texuli component catalog (catalog-ff1f13434cff…, 199 components): every manifest with props, examples, useWhen, dontUseWhen and emit tiers. The exact bytes hash to the catalog id.	`application/json`
`texuli://llms/full`	Full agent docs	Every component page in one Markdown file, identical to texuli.com/llms/llms-full.txt. Read it when you need the whole catalog as prose; texuli://docs/{slug} has one page.	`text/markdown`
`texuli://schema/deck`	Deck JSON Schema	The JSON Schema of a Texuli deck (formatVersion 2): slides, layouts, notes and theme. Write decks against it, then check them with the deck.run lint command.	`application/json`
`texuli://schema/document`	Document JSON Schema	The JSON Schema of a Texuli document (format texuli-document, formatVersion 1): blocks, marks and metadata. Check documents with the document.run validate command.	`application/json`
`texuli://design-system/acme`	Acme design system	The fictional Acme brand: every section of the design-system document. A fictional example document as JSON; validate your own with ds.validate.	`application/json`
`texuli://design-system/minimal`	Minimal design system	An example design system. A fictional example document as JSON; validate your own with ds.validate.	`application/json`
`texuli://design-system/quillmark`	Quillmark design system	A fictional literary magazine: warm paper tones, a serif voice and calm motion. A fictional example document as JSON; validate your own with ds.validate.	`application/json`
`texuli://design-system/ledgerline`	Ledgerline design system	A fictional finance back office: dense tables, crisp edges and a high-contrast variant for long sessions. A fictional example document as JSON; validate your own with ds.validate.	`application/json`
`texuli://design-system/tumbletown`	Tumbletown design system	A fictional family game studio: big rounded shapes, lively motion and a pinned brand pink. A fictional example document as JSON; validate your own with ds.validate.	`application/json`
`texuli://component/{id}`	Component manifest	One component manifest as JSON: props with kinds and schemas, events, examples, useWhen and dontUseWhen, accessibility notes and emit tiers. Complete {id}, or find ids with catalog.search.	`application/json`
`texuli://docs/{slug}`	Component docs	The agent Markdown page of one component ({slug} is its id), identical to texuli.com/llms/components/{slug}.md. Package guides are not served here yet.	`text/markdown`
`texuli://theme/{id}`	Library theme	One library theme: the full light and dark token definition as JSON, then the compiled CSS ready for a stylesheet. Complete {id}, or search with theme.search.	`application/json`
`texuli://design-system/{id}`	Design-system document	One design-system document as JSON: a fictional example (acme shows every section, minimal the smallest; quillmark, ledgerline and tumbletown are example brands) or a library theme as a document (its generator input as color.brand), ready to extend, validate with ds.validate and compile with ds.compile. Complete {id} for every id; one document per read.	`application/json`
`texuli://schema/{name}`	Format JSON Schema	The JSON Schema of a Texuli data format. {name} is one of deck, document; the blueprint schema is not served yet.	`application/json`

Prompts

Prompt	What it does	Arguments
`build-ui`	Turn a brief into a validated Texuli catalog tree (a blueprint draft): read the component catalog, pick components by useWhen and dontUseWhen, compose from worked examples, and validate with blueprint.validate until it passes. Returns the step-by-step loop with the brief filled in.	`brief` (required), `tier`, `theme`
`theme-blueprint`	Choose a library theme for a blueprint or screen from its brief (brand, mood, audience), check WCAG 2.x AA contrast in light and dark, and hand back the theme id, its key tokens and how the host applies it. Returns the step-by-step loop with the brief filled in.	`brief` (required), `mode`, `theme`
`create-design-system`	Turn a brand brief, token file, stylesheet, logo pixels or library theme into a proposed Texuli design-system draft. The agent may inspect reference screenshots with its own vision and translate observations into proposed generator inputs; screenshots are never silently imported. Review the generator loss and repair report, validate the draft, then report contrast and a preview. Approval stays human.	`brief` (required), `base`, `contrast`, `locked`
`convert-deck`	Convert a Texuli deck from Markdown to the JSON model (from-markdown) or back (to-markdown), lint it until it has no errors, and return the result. Paste the source as an argument or provide it when asked. Returns the step-by-step loop.	`direction` (required), `source`

Completions suggest values for the prompt arguments and the resource template variables.

Limits and security

Remote

Bodies of at most 256 KiB (413 past it).
Batches of at most 10 messages.
60 messages per client per 60 seconds, best-effort (429 with Retry-After; every answer carries RateLimit-Policy and RateLimit).
A 5 s guard per message, on top of each tool’s own limits.
A browser request must come from texuli.com, a texuli.pages.dev preview or localhost; server-side agents send no Origin and are allowed.

Local

A stdio message over 2 MiB is refused before parsing.
No network: no tool fetches anything or needs a secret.
stdout is the protocol; logs and errors go to stderr.

No tool writes files, stores anything or fetches from the network. The remote logs nothing; when the site's analytics is provisioned it counts calls by tool name, status and duration bucket, never arguments or addresses. The threat models: SECURITY section 21, the remote MCP endpoint, section 21a, the WebMCP bridge, section 23, the public JSON API, and section 6, the local stdio server.

Versions

Server 0.18.0: @texuli/mcp depends on exactly one @texuli/tools version, its own, and both publish in the same release wave. Under 0.x a new minor may break, so pin the exact version (@texuli/mcp on npm).
Protocol versions: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. The remote reads the MCP-Protocol-Version header and answers 400 to an unsupported one.
The 0.8 tool names were removed in 0.10.0; a call to one is refused with a message that names the tool to call instead:

Old name	Use	Removed in
`deck`	`deck.run`	`0.10.0`
`document`	`document.run`, `document.export`	`0.10.0`
`catalog`	`catalog.search`	`0.10.0`
`component`	`component.get`	`0.10.0`
`validate`	`catalog.validate`	`0.10.0`
`example`	`example.search`	`0.10.0`
`theme`	`theme.search`, `theme.get`	`0.10.0`

Site tools and WebMCP

The site tools (site.pages, site.read, site.search) list, search and read the pages of texuli.com as their Markdown twins. They read the deployed build only, never the network, so the remote door serves them and the local one does not.

A browser agent gets the same pages without any setup: when the browser offers WebMCP (navigator.modelContext), every page registers 4 read-only tools that call this site only. Without WebMCP, nothing more loads.

WebMCP tool	What it does
`texuli_search_docs`	Search texuli.com (guides, components, themes, agent docs) by words in page titles, headings and descriptions. Returns ranked pages with their path, URL, Markdown twin and matching headings, as JSON.
`texuli_read_page`	Read a texuli.com page as Markdown (its twin): pass a path such as "/guides/theming/" or "/". Returns the Markdown text.
`texuli_get_component`	Read the agent documentation of one Texuli component (props, examples, tiers, accessibility) by its catalog id, e.g. "card". Returns Markdown.
`texuli_validate_blueprint`	Validate a Texuli blueprint draft (a catalog tree, an array of trees or a texuli-blueprint envelope) with the catalog's checks. Returns valid, status and diagnostics with stable codes, as JSON.

Try it

List the remote tools with curl:

curl -s https://texuli.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Then call one:

curl -s https://texuli.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"site.search","arguments":{"query":"dark mode","limit":3}}}'

The protocol details (lifecycle, errors, every limit) are in mcp.md, and the local server in the @texuli/mcp README.