Semiotic ships two zero-install entry points for AI agents and tooling. Both run throughnpx with no project setup, and both read from the same source of truth the library validates against — so an agent gets the real component surface, not a guess.
npx semiotic-ai — a context & validation CLI that dumps the AI reference, lists components, prints schemas, suggests charts, and validates a config (including accessibility).npx semiotic-mcp — aModel Context Protocolserver exposing the same capabilities as callable tools for MCP-aware assistants.
semiotic-ai (CLI)
Run with no flags to print the full CLAUDE.md reference — the same guide the library author keeps in sync with the API. Add a flag to narrow the output. Flags that validate read JSON from stdin.
BASH
# Full AI reference (CLAUDE.md) to stdout npx semiotic-ai # List components, categories, import paths, and renderability npx semiotic-ai --list npx semiotic-ai --list --json # machine-readable component index # Tool schemas (all components, or one) npx semiotic-ai --schema npx semiotic-ai --schema BarChart # one component schema + AI metadata # Compact system prompt / copy-paste examples npx semiotic-ai --compact # ai/system-prompt.md npx semiotic-ai --examples # ai/examples.md npx semiotic-ai --help
Suggest a chart
Pipe { data, intent? } to --suggest for a ranked recommendation. Valid intents are comparison, trend,distribution, relationship, composition,geographic, network, and hierarchy (the CLI lists them if you pass an unknown one).
BASH
echo '{"data":[{"region":"AMER","value":42},{"region":"EMEA","value":33}],"intent":"comparison"}' \ | npx semiotic-ai --suggest
Validate a config (--doctor)
Pipe { component, props, usageMode? } to --doctor to validate a proposed chart before rendering. It reports errors, warnings (with fixes), and the behavior contracts that apply. Pass usageMode: "push" when validating ref-based streaming code that omits data.
BASH
echo '{"component":"BarChart","props":{"data":[{"region":"AMER","value":42}],"categoryAccessor":"region","valueAccessor":"value"}}' \ | npx semiotic-ai --doctor
Beyond structural validation, the diagnostics include amisleading-design pack — checks for patterns that deceive readers (and, per the chart-deception literature, deceive vision-language models the same way): inverted axes (INVERTED_AXIS), unlabeled dual-axis charts (DUAL_AXIS_UNLABELED), trend windows cropped to a favorable slice (CHERRY_PICKED_WINDOW), negative values in part-to-whole encodings (PART_TO_WHOLE_NEGATIVE), B-spline curves that don’t pass through the data points (NON_PASSING_CURVE), slope-distorting aspect ratios (EXTREME_ASPECT_RATIO), and over-sliced pies (PIE_TOO_MANY_SLICES) — alongside the long-standing non-zero-baseline and color-contrast checks. Each diagnosis carries an actionable fix.
Audit accessibility (--audit-a11y)
Pipe { component, props, inChartContainer?, describe?, navigable? } to grade a config against Chartability (POUR-CAF) heuristics. It exits non-zero on a critical failure, so it works as a CI gate. SeeChartability Audit for the in-app equivalent.
BASH
echo '{"component":"PieChart","props":{"data":[{"k":"A","v":1}],"categoryAccessor":"k","valueAccessor":"v"}}' \ | npx semiotic-ai --audit-a11y
semiotic-mcp (MCP server)
npx semiotic-mcp starts a Model Context Protocol server over stdio. Point an MCP-aware assistant at it and the model can call Semiotic’s capabilities directly rather than guessing at the API.
The server exposes these tools:
renderChart — render a component + props to a static SVG/PNG snapshot. The response includes a render-evidence JSON block (mark counts by scene type, resolved axis domains, an empty flag, annotation count, and the accessible name) computed from the rendered scene graph — agents verify the chart actually drew data marks by reading the evidence instead of parsing SVG. The same payload is available in code as renderChartWithEvidence fromsemiotic/server.renderInteractiveChart — render a static-data chart into a ChatGPT Apps / MCP Apps widget. The MCP server runs Semiotic, returns a hidden SVG payload, and the iframe adds fit, zoom, data, hover, and render-evidence controls.suggestCharts — rank charts for a dataset and intent (seeChart Suggestions).suggestTokenEncoding — recommend semantic token encodings for ISOTYPE, natural-frequency grids, quantile dotplots, and hybrid bar-token views.diagnoseConfig — flag anti-patterns in a proposed config, includingtokenEncoding warnings when a chart declares token semantics.interrogateChart — answer a natural-language question about a chart’s data (see Interrogation).groundChart — return the agent-reader grounding payload (description + intent + structure; see Agent-Reader Grounding).auditAccessibility — the --audit-a11y grading as a tool.repairChartConfig — critique a chart choice and return safer alternatives (see Variant Discovery & Repair).proposeChartVariants — propose and score variants of a chart for a dataset.
Agent setup
Register the server in your assistant’s MCP configuration. For example, in a Claude / Cursor style mcpServers block:
JSON
{ "mcpServers": { "semiotic": { "command": "npx", "args": ["semiotic-mcp"] } } }
For a ChatGPT Apps SDK prototype, start the HTTP transport withnpx semiotic-mcp --http --port 3001, expose /mcp over HTTPS with a tunnel, then create a ChatGPT developer-mode connector pointed at that endpoint. The widget template is served from ui://semiotic/chart-widget.html.
Which one do I use?
- Authoring a prompt or a build step? Use the CLI — pipe its output into a system prompt, or run
--doctor / --audit-a11y as a pre-commit / CI check. - Driving an MCP-aware assistant? Use the MCP server so the model can call
suggestCharts, renderChart, and the rest as tools mid-conversation.