Skip to main content
Glama

MCP Toplist

Semiotic

CI npm version TypeScript

A React data visualization library designed for AI-assisted development.

Simple charts in 5 lines. Network graphs, streaming data, and coordinated dashboards when you need them. Structured schemas and an MCP server so AI coding assistants generate correct chart code on the first try.

What's New in 3.9.2

3.9.2 expands Semiotic's portable chart, accessibility, evidence, and rendering surfaces while tightening browser/server parity and production entry graphs:

  • LineChart gains the dedicated semiotic/line entry, and chart HOCs, network layouts, force workers, and optional overlays load only the runtime code their chart paths need.

  • ChartAccessContract@1, ChartEvidenceEnvelope@1, and the new semiotic/access and semiotic/evidence entries provide schema-backed access inventories, privacy-aware provenance, deterministic hashing, MCP evidence fragments, and publication gates.

  • ParallelCoordinatesRecipe and CalendarHeatmapRecipe are now portable, JSON-safe chart recipes, while Minimap, ScatterplotMatrix, and ChainReaction gain evidence-backed static rendering through semiotic/server and MCP.

  • Typed realtime handles preserve authored row types, styleRules now spans ordinal, XY, network, geo, realtime, and physics families, and structured navigation provides overview-first hierarchy and choropleth semantics.

  • Renderer and interaction fixes cover constant-value heatmaps, linked selection and hover, automatic network legends, Waterfall and Radar geometry, marginal graphics, custom layouts, tree-shaken network registration, and instance-local accessible names.

  • Release evidence now includes controlled dense-browser measurements, deterministic linked-hover cohorts, generated bundle guidance, stronger AI diagnostics, and stricter shipped-product and contributor gates.

Related MCP server: nakkas

Why Semiotic

Semiotic is a data visualization library for React that combines broad chart coverage with first-class AI tooling. It handles the chart types that most libraries skip — network graphs, streaming data, statistical distributions, coordinated views — and ships with machine-readable schemas so LLMs can generate correct code without examples.

Built for AI-assisted development

Semiotic ships with everything an AI coding assistant needs to generate correct visualizations without trial and error:

  • semiotic/ai — a single import with the schema-backed chart capability catalog (XY, ordinal, network, realtime, geo, value, and portable recipes), optimized for LLM code generation. See ai/surface-manifest.json for the generated current inventory. Note: the published entry files are pre-bundled, so importing one chart from semiotic/ai still ships most of the bundle — treat it as a codegen/tooling surface and use family subpaths (semiotic/xy, semiotic/geo, semiotic/value, …) in production code, at roughly half the single-chart cost.

  • ai/schema.json — machine-readable prop schemas for every component

  • npx semiotic-mcp — an MCP server for tool-based chart rendering in any MCP client

  • npx semiotic-ai --doctor — validate component + props JSON from the command line with typo suggestions and anti-pattern detection

  • diagnoseConfig(component, props) — programmatic anti-pattern detector with actionable fixes, spanning validation, encoding, accessibility, and misleading-design (deception) checks

  • auditData(component, props, data?) — chart-aware numeric preflight for inputs that pass schema validation but break the math: non-finite values, zero-span domains, invalid log inputs, negative size geometry, unsafe normalized totals, and scale-dominating outliers. Returns bounded row evidence and flows into diagnoseConfig, Chart Clinic, CLI doctor, and opt-in ChartContainer notifications

  • AGENTS.md — concise repository workflow shared by modern coding agents; CLAUDE.md imports it and Copilot receives a short compatibility bridge

  • ai/reference.md — complete on-demand product reference, kept out of always-loaded coding-agent context

  • llms.txt — machine-readable documentation following the emerging standard

Every chart includes a built-in error boundary, dev-mode validation warnings with typo suggestions, and accessibility features (canvas aria-label, keyboard-navigable legends, aria-live tooltips, SVG <title>/<desc>) so AI-generated code fails gracefully with actionable diagnostics instead of a blank screen.

Accessibility is a release surface

The European Accessibility Act has applied to covered products and services since 28 June 2025. A chart library cannot certify an application's legal compliance: scope, content, surrounding controls, testing, and national enforcement remain the application owner's responsibility. Semiotic supplies testable infrastructure for that work: keyboard interaction, accessible data tables, layered descriptions, structured navigation, reduced-motion and forced-colors paths, and WCAG-derived contrast tests for shipped theme presets. See the Accessibility docs and run the application's own assistive-technology and user testing.

Beyond standard charts

Network visualization. Force-directed graphs, Sankey diagrams, chord diagrams, tree layouts, treemaps, circle packing, and orbit diagrams — all as React components with the same prop API as LineChart.

Streaming data. Realtime charts render on canvas at 60fps with a ref-based push API. Rapid network edge pushes coalesce into one layout per animation frame, while read/mutation methods preserve synchronous read-after-write semantics. Built-in decay, pulse, and staleness encoding for monitoring dashboards.

Coordinated views. LinkedCharts provides hover cross-highlighting, brush cross-filtering, coordinate-based linked crosshairs, and selection synchronization across any combination of chart types through shared selection state.

Geographic visualization. Choropleth maps, proportional symbol maps, flow maps with animated particles, and distance cartograms — all canvas-rendered with d3-geo projections, zoom/pan, tile basemaps, and drag-rotate globe spinning.

Statistical summaries. Box plots, violin plots, swarm plots, histograms, LOESS smoothing, forecast with confidence envelopes, and anomaly detection. Marginal distribution graphics on scatterplot axes with a single prop.

First-class annotations. Annotations are data-bound objects, not post-hoc artwork. Labels, callouts, thresholds, enclosures, statistical overlays, and React widgets move with the chart and render through browser, SSR, and export paths. Opt into placement, hierarchy, density, progressive disclosure, audience-aware amount, provenance, and editorial lifecycle when the chart needs to communicate more than its encoding alone.

Choose the API layer

Layer

For

Example

Charts

Common chart forms with chart-level props

<LineChart data={d} xAccessor="x" yAccessor="y" />

Frames

Full control over rendering, interaction, and layout

<StreamXYFrame chartType="line" lineStyle={...} />

Chart HOCs register only the mark plugins they need. Direct StreamXYFrame loads the remaining built-ins on first client paint. Call registerBuiltInXYPlugins() from semiotic/xy or semiotic/realtime/core before the first render when SSR or the first frame must include marks.

Every Chart component accepts a frameProps prop to access the underlying Frame API without leaving the simpler interface.

Serialization and interop

Charts serialize to JSON and back: toConfig, fromConfig, toURL, copyConfig, configToJSX. Have Vega-Lite specs? fromVegaLite(spec) translates them to Semiotic configs — works with configToJSX() for full round-trip from notebooks and AI-generated specs.

Need an external pitfall review? The experimental unstable_toDataPitfallsChain() builds a dependency-free chain input for datapitfalls, combining the Semiotic config, JSX, reader grounding, diagnostics, accessibility audit, and optional rendered SVG/image evidence:

import { unstable_toDataPitfallsChain } from "semiotic/experimental"
import { detectPitfalls } from "datapitfalls"

const input = unstable_toDataPitfallsChain("LineChart", props, {
  narrative: "Monthly sales are accelerating.",
  rendered: { svg, evidence },
})

const report = await detectPitfalls(input, { apiKey: process.env.ANTHROPIC_API_KEY })

The return path stays dependency-free too. Use whole-chart findings as ChartContainer notifications, and only turn findings into annotations after your app can anchor them to marks or semantic positions:

import { ChartContainer } from "semiotic"
import { LineChart } from "semiotic/xy"
import {
  unstable_toDataPitfallsAnnotations,
  unstable_toDataPitfallsNotifications,
} from "semiotic/experimental"

const notifications = unstable_toDataPitfallsNotifications(report)
const annotations = unstable_toDataPitfallsAnnotations(report, {
  anchorFor: (finding) =>
    finding.ruleId === "truncated-axis" ? { x: 9, y: 9000 } : null,
})

<ChartContainer notifications={notifications}>
  <LineChart {...props} annotations={annotations} />
</ChartContainer>

When to use something else

Need a standard bar or line chart for a dashboard you'll never need to customize beyond colors and labels? Recharts has a larger ecosystem and more community examples. Need GPU-accelerated rendering for millions of data points? Apache ECharts handles that scale.

Semiotic is for projects that outgrow those libraries — when you need network graphs alongside time series, streaming data alongside static snapshots, or coordinated views across chart types.

Install

npm install semiotic

Requires React 18.1+ or React 19.

Quick Examples

Coordinated Dashboard

Hover one chart and highlight the same data in another through a shared selection:

import { LinkedCharts, Scatterplot, BarChart } from "semiotic"

<LinkedCharts>
  <Scatterplot
    data={data} xAccessor="age" yAccessor="income" colorBy="region"
    linkedHover={{ name: "hl", fields: ["region"] }}
    selection={{ name: "hl" }}
  />
  <BarChart
    data={summary} categoryAccessor="region" valueAccessor="total"
    selection={{ name: "hl" }}
  />
</LinkedCharts>

Streaming Metrics with Decay

Live data fades old points, flashes new ones, flags stale feeds:

import { RealtimeLineChart } from "semiotic"

const chartRef = useRef()
chartRef.current.push({ time: Date.now(), value: cpuLoad })

<RealtimeLineChart
  ref={chartRef}
  timeAccessor="time"
  valueAccessor="value"
  decay={{ type: "exponential", halfLife: 100 }}
  staleness={{ threshold: 5000, showBadge: true }}
/>

Network Graphs

Force-directed graphs and Sankey diagrams — same API as LineChart:

import { ForceDirectedGraph, SankeyDiagram } from "semiotic"

<ForceDirectedGraph
  nodes={people} edges={friendships}
  colorBy="team" nodeSize={8} showLabels
/>

<SankeyDiagram
  edges={budgetFlows}
  sourceAccessor="from" targetAccessor="to" valueAccessor="amount"
/>

Geographic Visualization

Choropleth maps, flow maps, and distance cartograms with canvas rendering, zoom/pan, tile basemaps, and animated particles:

import { ChoroplethMap, FlowMap, DistanceCartogram } from "semiotic/geo"

<ChoroplethMap
  areas={geoJsonFeatures} valueAccessor="gdp"
  colorScheme="viridis" projection="equalEarth" zoomable tooltip
/>

<FlowMap
  nodes={airports} flows={routes} valueAccessor="passengers"
  showParticles particleStyle={{ color: "source", speedMultiplier: 1.5 }}
/>

<DistanceCartogram
  points={cities} center="rome" costAccessor="travelDays"
  showRings costLabel="days" lines={routes}
/>

Streaming System Monitor

Live service topology with threshold alerting and click-to-inspect:

import { StreamNetworkFrame, ChartContainer, DetailsPanel, LinkedCharts } from "semiotic"

const chartRef = useRef()
chartRef.current.push({ source: "API", target: "Orders", value: 15 })

<LinkedCharts>
  <ChartContainer title="System Monitor" status="live"
    detailsPanel={
      <DetailsPanel position="right" trigger="click">
        {(datum) => <div>{datum.id}: {datum.value} req/s</div>}
      </DetailsPanel>
    }>
    <StreamNetworkFrame ref={chartRef} chartType="sankey"
      showParticles particleStyle={{ proportionalSpeed: true }}
      thresholds={{ metric: n => n.value, warning: 100, critical: 250 }}
    />
  </ChartContainer>
</LinkedCharts>

Standard Charts

Line, bar, scatter, and area charts share the same accessor-driven API:

import { LineChart, BarChart } from "semiotic"

<LineChart
  data={salesData}
  xAccessor="month" yAccessor="revenue"
  curve="monotoneX" showPoints
/>

<BarChart
  data={categoryData}
  categoryAccessor="department" valueAccessor="sales"
  orientation="horizontal" colorBy="region"
/>

All Chart Components

Category

Components

XY

LineChart AreaChart DifferenceChart StackedAreaChart Scatterplot ConnectedScatterplot BubbleChart Heatmap QuadrantChart MultiAxisLineChart MinimapChart CandlestickChart ScatterplotMatrix

Categorical

BarChart StackedBarChart GroupedBarChart LikertChart SwimlaneChart FunnelChart SwarmPlot BoxPlot Histogram ViolinPlot RidgelinePlot DotPlot PieChart DonutChart GaugeChart

Network

ForceDirectedGraph ChordDiagram SankeyDiagram ProcessSankey TreeDiagram Treemap CirclePack OrbitDiagram

Geo

ChoroplethMap ProportionalSymbolMap FlowMap DistanceCartogram

Realtime

RealtimeLineChart RealtimeHistogram RealtimeSwarmChart RealtimeWaterfallChart RealtimeHeatmap

Coordination

LinkedCharts

Layout

ChartGrid ContextLayout CategoryColorProvider

Frames

StreamXYFrame StreamOrdinalFrame StreamNetworkFrame StreamGeoFrame

Vega-Lite Translation

Paste a Vega-Lite spec, get a Semiotic chart:

import { fromVegaLite } from "semiotic/data"
import { configToJSX, fromConfig } from "semiotic"

const config = fromVegaLite({
  mark: "bar",
  data: { values: [{ a: "A", b: 28 }, { a: "B", b: 55 }] },
  encoding: {
    x: { field: "a", type: "nominal" },
    y: { field: "b", type: "quantitative" },
  },
})

// Render directly
const { componentName, props } = fromConfig(config)
// → componentName: "BarChart", props: { data, categoryAccessor: "a", valueAccessor: "b" }

// Or generate JSX code
configToJSX(config)
// → <BarChart data={[...]} categoryAccessor="a" valueAccessor="b" />

Supports bar, line, area, point, rect, arc, tick marks with encoding translation for color, size, aggregation, and binning.

Conversation Arc Telemetry

Capture and replay the path an AI-assisted chart session took:

import {
  createLocalStorageConversationArcSink,
  enableConversationArc,
  getConversationArcStore,
  loadConversationArc,
  registerConversationArcSink,
} from "semiotic/ai"

const sink = createLocalStorageConversationArcSink({ key: "my-app:arc" })
registerConversationArcSink(sink)
enableConversationArc({ sessionId: "session-abc" })

getConversationArcStore().record({ type: "chart-rendered", component: "LineChart" })
loadConversationArc(sink.load(), { enabled: false })

Bundle Sizes

Semiotic ships 34 stable JavaScript entry points (33 subpaths plus the root). Don't import from "semiotic" unless you need everything — use the smallest sub-path that matches your charts or tooling.

The numbers below are first-party artifact cost: the gzip size of Semiotic's own code for each sub-path. They exclude React and other runtime dependencies, so they are not a prediction of a cold application bundle. Do not add artifact rows to estimate an app: dependency resolution and cross-import deduplication happen in the consumer bundler and are measured separately below.

Entry Point

gzip

What's inside

semiotic/access

34 KB

Chart Access Contract factory and first-wave baseline contracts

semiotic/evidence

46 KB

Chart Evidence Envelope, deterministic hashing, and publication gate

semiotic/artifact

118 KB

Renderer-independent contracts, claims, time, policy, grounding, and transfer audits

semiotic/artifact/react

4 KB

Accessible progressive disclosure for artifact contracts and policy evaluations

semiotic/line

135 KB

LineChart only — one-chart micro boundary

semiotic/xy

166 KB

LineChart, AreaChart, Scatterplot, Heatmap, + 8 more XY charts

semiotic/ordinal

130 KB

BarChart, PieChart, BoxPlot, Histogram, + 11 more categorical charts

semiotic/network

156 KB

ForceDirectedGraph, SankeyDiagram, ProcessSankey, Treemap, + 4 more

semiotic/geo

113 KB

ChoroplethMap, FlowMap, DistanceCartogram, ProportionalSymbolMap

semiotic/realtime

163 KB

RealtimeLineChart, RealtimeHistogram, + 4 streaming charts

semiotic/realtime/core

162 KB

Streaming chart types, HOCs, and buffer helpers

semiotic/realtime/react

1 KB

Stream status and synced push hooks

semiotic/server

225 KB

renderChart, renderDashboard, renderToImage, renderToAnimatedGif

semiotic/server/node

225 KB

renderChart, renderDashboard, renderToImage, renderToAnimatedGif

semiotic/server/edge

227 KB

renderChart, renderChartWithEvidence, renderToStaticSVG, renderDashboard

semiotic/utils

95 KB

ThemeProvider, numeric/accessibility audits, serialization — no chart components

semiotic/utils/core

88 KB

Pure theme helpers, numeric/accessibility audits, and serialization

semiotic/utils/react

7 KB

ThemeProvider, useTheme, useReducedMotion, useHighContrast, useStreamStatus

semiotic/recipes

99 KB

Pure layout functions (waffle, marimekko, flextree, dagre, …)

semiotic/recipes/core

92 KB

Pure layout functions (waffle, marimekko, flextree, dagre, …)

semiotic/recipes/react

8 KB

Glyph and React layout-selection helpers

semiotic/themes

12 KB

Theme presets only (tufte, carbon, etc.)

semiotic/themes/core

12 KB

Theme presets and token helpers

semiotic/themes/react

7 KB

ThemeProvider/useTheme and hooks

semiotic/data

3 KB

bin, rollup, groupBy, pivot, fromVegaLite

semiotic/value

6 KB

BigNumber — focal-value KPI / scorecard (SingleValueFrame POC)

semiotic/physics

168 KB

GaltonBoardChart, EventDropChart, UnitPileChart, CollisionSwarmChart, PacketFlowChart, PhysicsCustomChart

semiotic/physics/matter

1 KB

Matter.js migration helpers + optional peer guard (no chart components)

semiotic/physics/rapier

1 KB

Rapier peer guard + adapter decision metadata (no chart components)

semiotic/ai

587 KB

All schema-backed charts + validation — optimized for LLM code generation

semiotic/ai/core

135 KB

suggestCharts, auditData, describeChart, repairChartConfig, tool adapters — no chart components

semiotic/controls

10 KB

DirectManipulationControl, CircularBrush, MobileStandardControls, auditVisualizationControls — no frame renderer

semiotic/rough

3 KB

Optional deterministic Rough.js paint backend — exact Semiotic geometry remains authoritative

semiotic

370 KB

Everything below (full bundle)

Cold-consumer named imports

The table above is first-party artifact cost, not an application bundle. The generated table below measures a different thing: a fresh consumer bundles one retained named import from a packed semiotic tarball through the public export path. It includes Semiotic and its resolved runtime dependencies, but externalizes React/React DOM and optional adapter peers that the host application owns. Each row starts cold, so use it to compare one public import choice—not to add together an application's rows. The checked machine-readable baseline is benchmarks/setup/cold-consumer-imports.json; refresh it after a production build with npm run docs:cold-consumer.

Method: fresh npm pack --ignore-scripts tarball → temporary consumer → minified/tree-shaken esbuild ESM bundle → gzip -9. React/React DOM and optional adapter peers are external; Semiotic and its resolved runtime dependencies are included.

Public named import

Runtime

gzip cold-consumer bundle

import { LineChart } from "semiotic"

browser

140.0 KiB

import { LineChart } from "semiotic/xy"

browser

140.4 KiB

import { LineChart } from "semiotic/line"

browser

140.3 KiB

import { BarChart } from "semiotic/ordinal"

browser

133.1 KiB

import { SankeyDiagram } from "semiotic/network"

browser

157.4 KiB

import { RealtimeLineChart } from "semiotic/realtime"

browser

141.0 KiB

import { RingBuffer } from "semiotic/realtime/core"

browser

0.7 KiB

import { useStreamStatus } from "semiotic/realtime/react"

browser

0.6 KiB

import { GaltonBoardChart } from "semiotic/physics"

browser

150.2 KiB

import { MATTER_PHYSICS_CAPABILITIES } from "semiotic/physics/matter"

browser

0.2 KiB

import { RAPIER_PHYSICS_CAPABILITIES } from "semiotic/physics/rapier"

browser

0.2 KiB

import { renderChart } from "semiotic/server"

node

263.9 KiB

import { generateFrameSVGs } from "semiotic/server/edge"

node

119.1 KiB

import { renderToImage } from "semiotic/server/node"

node

264.5 KiB

import { suggestCharts } from "semiotic/ai"

browser

254.6 KiB

import { suggestCharts } from "semiotic/ai/core"

browser

46.4 KiB

import { buildArtifactContract } from "semiotic/artifact"

browser

19.0 KiB

import { ArtifactInspector } from "semiotic/artifact/react"

browser

3.8 KiB

import { createChartAccessContract } from "semiotic/access"

browser

31.0 KiB

import { toEvidenceEnvelope } from "semiotic/evidence"

browser

46.4 KiB

import { bin } from "semiotic/data"

browser

0.4 KiB

import { ChoroplethMap } from "semiotic/geo"

browser

115.4 KiB

import { createRoughRenderMode } from "semiotic/rough"

browser

3.1 KiB

import { resolveThemePreset } from "semiotic/themes"

browser

2.6 KiB

import { resolveThemePreset } from "semiotic/themes/core"

browser

2.6 KiB

import { ThemeProvider } from "semiotic/themes/react"

browser

5.2 KiB

import { validateProps } from "semiotic/utils"

browser

10.1 KiB

import { smartTickFormat } from "semiotic/utils/core"

browser

7.8 KiB

import { useReducedMotion } from "semiotic/utils/react"

browser

2.4 KiB

import { waffleLayout } from "semiotic/recipes"

browser

1.7 KiB

import { waffleLayout } from "semiotic/recipes/core"

browser

1.7 KiB

import { Glyph } from "semiotic/recipes/react"

browser

0.8 KiB

import { BigNumber } from "semiotic/value"

browser

5.9 KiB

import { DirectManipulationControl } from "semiotic/controls"

browser

1.3 KiB

Line-boundary interpretation: the retained named import from semiotic/line emits 422.7 KiB raw versus 422.7 KiB from semiotic/xy; gzip differs by 0.1 KiB (0.1%). Tree-shaking converges both paths on the same LineChart implementation graph. Treat semiotic/line as a narrower API/direct-ESM artifact boundary, not an application-bundle saving. Do not add another per-chart entry until its packed named import beats the family path by both 10 KiB gzip and 7%.

d3 packaging model: Semiotic externalizes the twelve d3 modules it imports and declares them as normal runtime dependencies. Consumers do not need to install d3 packages manually; their bundler resolves, deduplicates, and tree-shakes that dependency graph. A packed webpack comparison favored this model in three of four representative chart families, and a Next 16 webpack route was 21.8 KiB gzip smaller than the fully bundled alternative. The one bundled win, Sankey, was only 1.1 KiB gzip. This choice retains a 22-package, 1.9 MB unpacked d3 install closure in exchange for smaller common application graphs and an ordinary dependency contract. The checked policy is npm run check:d3-packaging; the reproducible evidence is in benchmarks/setup/d3-packaging.json and can be regenerated with npm run measure:d3-packaging -- --toolchain-root <dir> after installing webpack and Next in that isolated toolchain directory.

// Import from the sub-path, not from "semiotic"
import { LineChart } from "semiotic/xy"
import { BarChart } from "semiotic/ordinal"
import { SankeyDiagram } from "semiotic/network"
import { ChoroplethMap } from "semiotic/geo"

Tree-shaking & multi-subpath imports: Family entries (semiotic/xy, semiotic/network, semiotic/ai, …) are built as one ESM graph with shared chunks. Stream frames, renderers, and other common code ship once and are imported by every entry that needs them — so combining semiotic/ai + semiotic/xy + semiotic/network does not mean paying for three full copies of the runtime. The package is marked "sideEffects": false, so modern bundlers keep only the named exports you retain (e.g. LineChart + suggestCharts). Prefer family subpaths for clarity; import AI helpers from semiotic/ai or the lighter semiotic/ai/core when you do not need the chart catalog.

When to use "semiotic": Fine when you want one import for mixed families. Shared chunks prevent duplicated runtime code across family subpaths; the cold-consumer table above is the better guide for a single named import.

CommonJS compatibility note: require("semiotic/xy") loads the shared CommonJS client bundle (about 2.1 MB before compression) so React contexts stay singletons across family imports. Prefer ESM imports in browser builds when bundle size matters; splitting that CJS client without a context-identity contract would be unsafe.

TypeScript

Built with strict: true. Full type definitions ship with the package. Generics for type-safe accessors:

interface Sale { month: number; revenue: number }

<LineChart<Sale>
  data={sales}
  xAccessor="month"    // TS validates this is keyof Sale
  yAccessor="revenue"
/>

Server-Side Rendering

All chart components render SVG automatically in server environments — no special imports or configuration needed. Non-streaming chart HOCs can be imported and rendered directly from a Next.js Server Component: Semiotic's "use client" directive defines the package boundary, so the importing page does not need its own wrapper or directive. Props crossing that boundary must remain serializable; add an app-owned client wrapper only when you introduce hooks, callback props, browser state, or a push-driven streaming chart.

// app/dashboard/page.tsx — a Next.js Server Component
import { LineChart } from "semiotic/xy"

// Server: renders <svg> with path/circle/rect elements
// Client: renders <canvas> with SVG overlay for axes
export default async function DashboardPage() {
  const data = await fetchMetrics()
  return <LineChart data={data} xAccessor="date" yAccessor="value" />
}

For standalone SVG/PNG/GIF generation (email, OG images, PDF, Slack), use the server entry point:

import { renderChart, renderToImage, renderToAnimatedGif } from "semiotic/server"

// SVG — sync, no dependencies
const svg = renderChart("LineChart", {
  data, xAccessor: "date", yAccessor: "value",
  theme: "tufte", title: "Revenue Trend",
})

// PNG — async, requires sharp
const png = await renderToImage("BarChart", { data, ... }, { format: "png", scale: 2 })

// Animated GIF — async, requires sharp + gifenc
const gif = await renderToAnimatedGif("line", data, { ... }, { fps: 12 })

MCP Server

mcp-name: io.github.nteract/semiotic

Semiotic ships with an MCP server that lets AI coding assistants render charts, diagnose configuration problems, discover schemas, read packaged AI guidance, and get chart recommendations via tool calls.

Setup

Add to your MCP client config (e.g. claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "semiotic": {
      "command": "npx",
      "args": ["semiotic-mcp"]
    }
  }
}

No API keys or authentication required. The server runs locally via stdio. HTTP mode is also available for inspectors, web clients, and ChatGPT Apps SDK experiments: npx semiotic-mcp --http --port 3001. It binds to 127.0.0.1 by default; intentionally expose another interface with --host 0.0.0.0 or MCP_HOST=0.0.0.0. Since 3.7.2, HTTP mode is stateless: each request gets a fresh read-only MCP server + transport, so it can autoscale on serverless hosts without sticky sessions.

For ChatGPT developer mode, expose the HTTP endpoint over HTTPS with a tunnel and create a connector that points at https://<your-tunnel>/mcp. The experimental Apps SDK surface is renderInteractiveChart, which returns a text/html;profile=mcp-app widget template plus a hidden SVG payload rendered by Semiotic on the MCP server.

For a hosted deployment, see deploy/cloud-run. The wrapper runs the published semiotic-mcp binary, exposes /mcp plus health endpoints, and supports MCP_ALLOWED_HOSTS for production host-header allowlisting. For ChatGPT Apps domain verification, set OPENAI_APPS_CHALLENGE_TOKEN so HTTP mode serves the raw token from /.well-known/openai-apps-challenge.

Tools

Tool

Description

renderChart

Render a Semiotic chart to static SVG. Supports the components returned by getSchema that are marked [renderable]. Pass { component: "LineChart", props: { data: [...], xAccessor: "x", yAccessor: "y" } }. Returns SVG string plus a "Render evidence" JSON block (mark counts by scene type, resolved axis domains, empty flag, annotation count, accessible name) so agents can verify the chart drew data marks, or validation errors with fix suggestions.

renderInteractiveChart

Render a static-data chart as a ChatGPT Apps widget. Uses the same Semiotic server render path as renderChart, then hydrates an iframe UI with fit, zoom, data, hover, and render-evidence controls.

getSchema

Return the prop schema for a specific component. Pass { component: "LineChart" } to get its props, or omit component to list the complete schema-backed catalog. Components marked [renderable] are available through renderChart; realtime charts require a browser/live environment.

suggestChart

Sample-row recommender. Pass { data: [{...}, ...] } with 1–5 sample objects plus optional broad intent/capability filters.

suggestCharts

Capability-based recommender for bounded row data. Returns ranked chart suggestions with scores, reasons, caveats, import paths, and ready-to-use props.

suggestStreamCharts

Recommend realtime charts from a stream schema, throughput, and retention hints.

suggestDashboard

Build a multi-panel dashboard suggestion that covers distinct analytical intents.

suggestStretchCharts

Recommend audience-literacy stretch picks from an AudienceProfile.

repairChartConfig

Check whether a requested chart fits a dataset and return ranked alternatives when it does not.

interrogateChart

Return a statistical summary and chart-aware context for answering natural-language questions with optional annotations.

diagnoseConfig

Check a chart configuration for common problems — empty data, bad dimensions, missing accessors, wrong data shape, and more. Returns a human-readable diagnostic report with actionable fixes.

reportIssue

Generate a pre-filled GitHub issue URL for bug reports or feature requests. Pass { title: "...", body: "...", labels: ["bug"] }. Returns a URL the user can open to submit.

applyTheme

List named theme presets or return ThemeProvider/CSS/token usage for a preset such as { name: "tufte" }.

auditArtifact

Evaluate an explicit artifact contract under a named policy without inferring missing source, review, or timing facts.

recommendRepresentation

Compare chart and non-chart outcomes against supplied data, claims, evidence, time state, and policy requirements.

repairArtifact

Propose contract repairs and optionally fill missing identity fields; existing mismatches require a revision and claim reassessment.

explainRefusal

Explain which explicit policy obligations prevent publication or action and identify safe follow-up work.

Artifact tools are opt-in diagnostics, not publication authorization. A conditional result (including CLI exit code 0) retains open work. Ordinary renderChart calls do not enforce artifact policy; governed hosts must enforce their own release boundary. Manual-check resolution and revision-bound release approval remain separate host workflow work.

Resources

Resource

Description

semiotic://artifact-contract-schema

Standalone JSON Schema for portable purpose, claim, evidence, timing, review, and transfer metadata.

semiotic://schema

Full machine-readable component schema JSON.

semiotic://schema-index

Compact discovery index with categories, renderability, import paths, and each component's schema resource URI.

semiotic://schema/{component}

One component's schema, metadata, accessibility guidance, and behavior contracts (for example semiotic://schema/LineChart).

semiotic://components

Backward-compatible component index showing renderable/browser-only status and MCP categories.

semiotic://surface-manifest

Generated inventory of the current AI schema, exports, renderability, tools, resources, and prompts.

semiotic://behavior-contracts

Agent-visible semantic rules for color precedence, required prop combinations, push refs, and renderability.

semiotic://system-prompt

Compact AI instructions with import rules, chart props, SSR guidance, and pitfalls.

semiotic://examples

Copy-paste chart examples by data shape.

ui://semiotic/chart-widget.html

ChatGPT Apps / MCP Apps widget template used by renderInteractiveChart.

Prompts

Prompt

Description

build-semiotic-chart

Reusable workflow for choosing a chart, reading schema, diagnosing props, and rendering a preview.

debug-semiotic-chart

Reusable workflow for debugging invalid props, rendering failures, and issue reports.

Example: get schema for a component

Tool: getSchema
Args: { "component": "LineChart" }
→ Returns: { "name": "LineChart", "description": "...", "parameters": { "properties": { "data": ..., "xAccessor": ..., ... } } }

Example: suggest a chart for your data

Tool: suggestChart
Args: {
  "data": [
    { "month": "Jan", "revenue": 120, "region": "East" },
    { "month": "Feb", "revenue": 180, "region": "West" }
  ]
}
→ Returns:
  1. BarChart (high confidence) — categorical field (region) with values (revenue)
  2. StackedBarChart (medium confidence) — two categorical fields (month, region)
  3. DonutChart (medium confidence) — 2 categories — proportional composition

Example: render a chart

Tool: renderChart
Args: {
  "component": "BarChart",
  "props": {
    "data": [
      { "category": "Q1", "revenue": 120 },
      { "category": "Q2", "revenue": 180 },
      { "category": "Q3", "revenue": 150 }
    ],
    "categoryAccessor": "category",
    "valueAccessor": "revenue"
  }
}
→ Returns: <svg>...</svg>

Example: render a ChatGPT Apps widget

Tool: renderInteractiveChart
Args: {
  "component": "BarChart",
  "props": {
    "title": "Revenue by Quarter",
    "data": [
      { "quarter": "Q1", "revenue": 120 },
      { "quarter": "Q2", "revenue": 180 }
    ],
    "categoryAccessor": "quarter",
    "valueAccessor": "revenue"
  }
}
→ Returns: structured chart summary for the model + hidden SVG/widget metadata for ChatGPT.

Example: diagnose a broken config

Tool: diagnoseConfig
Args: { "component": "LineChart", "props": { "data": [] } }
→ Returns: ✗ [EMPTY_DATA] data is an empty array — Fix: provide at least one data point

Example: report an issue

Tool: reportIssue
Args: {
  "title": "Bug: BarChart tooltip shows undefined for custom accessor",
  "body": "When using valueAccessor='amount', tooltip displays 'undefined'.\n\ndiagnoseConfig output: ✓ no issues detected.",
  "labels": ["bug"]
}
→ Returns: Open this URL to submit the issue: https://github.com/nteract/semiotic/issues/new?...

CLI alternative

For quick validation without an MCP client:

npx semiotic-ai --list         # list components with import paths and renderability
npx semiotic-ai --list --json  # machine-readable component index
npx semiotic-ai --schema GaugeChart
npx semiotic-ai --suggest '{"data":[{"category":"A","value":10}],"intent":"comparison"}'
npx semiotic-ai --doctor       # validate component + props JSON
npx semiotic-ai --schema       # dump all chart schemas
npx semiotic-ai --compact      # compact schema (fewer tokens)

--doctor uses the full diagnoseConfig checks when dist is available and falls back to schema-only validation in clean source checkouts.

Where to find Semiotic for AI assistants

Semiotic is indexed by AI-coding-agent documentation tools so your assistant (Claude Code, Cursor, Cline, Copilot, etc.) can pull current docs and tools without copy-paste:

The Official MCP Registry is the canonical MCP directory record; it is distinct from acceptance into any assistant vendor's curated connector directory. Secondary-directory freshness and release ownership are tracked in MCP_DISTRIBUTION.md.

Agent-facing API surface:

  • AGENTS.md is the concise repository development contract and CLAUDE.md imports it for Claude Code. These stay repository-local rather than shipping irrelevant contributor instructions to package consumers.

  • ai/reference.md, ai/schema.json, ai/surface-manifest.json, ai/behaviorContracts.cjs, and agent-skill/semiotic-charts/SKILL.md are bundled in the npm tarball (see package.json#files). The reference is the on-demand product guide printed by npx semiotic-ai; the schema, manifest, contracts, and portable skill provide structured generation and validation guidance.

  • semiotic.nteract.io/llms.txt + /llms-full.txt — deployed at the docs site per the llms.txt standard. Agents fetch the navigation map (llms.txt) or the full inlined docs (llms-full.txt) over HTTP; they're not part of the npm package itself.

Documentation

Interactive docs and examples

  • Getting Started

  • Charts — chart types with live examples

  • Frames — full Frame API reference

  • Features — axes, tooltips, interaction, responsive behavior, and composition

  • Annotations — first-class annotation types, design guidance, provenance, and lifecycle

  • Cookbook — advanced patterns and recipes

  • Playground — interactive prop exploration

Upgrading

Contributing

See CONTRIBUTING.md. Our community follows the nteract Code of Conduct.

Acknowledgments

Development of this library owes a lot to Susie Lu, Jason Reid, James Womack, Matt Herman, Shelby Sturgis, and Tristan Reid.

The Sankey layout engine is based on sankey-plus by Tom Shanley, which improved on his earlier d3-sankey-circular with better cycle detection, hierarchical arc stacking, and dynamic extent adjustment.

Semiotic icon based on an icon by Andre Schauer.

License

Apache 2.0

Available Tools

5 tools
diagnoseConfigAInspect

Diagnose a Semiotic chart configuration for common problems (empty data, bad dimensions, missing accessors, wrong data shape, etc). Returns a human-readable diagnostic report with actionable fixes.

ParametersJSON Schema
NameRequiredDescriptionDefault
componentYesChart component name, e.g. 'LineChart'
propsNoChart props object, e.g. { data: [...], xAccessor: 'x' }.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: it performs diagnosis (analysis without mutation), returns a human-readable diagnostic report (output format), and provides actionable fixes (practical guidance). However, it doesn't mention error handling, performance, or authentication needs, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by specific problem examples and output details in a single, efficient sentence. Every part adds value without redundancy, making it highly concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (diagnosing configurations with nested objects) and no output schema, the description adequately covers the purpose, behavior, and output format. However, it could be more complete by specifying error cases or limitations, though it compensates well with clear problem examples and actionable output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema (e.g., examples of 'component' and 'props'), resulting in a baseline score of 3 where the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('diagnose') and resource ('Semiotic chart configuration'), listing concrete problem types like 'empty data, bad dimensions, missing accessors, wrong data shape'. It distinguishes from siblings like 'renderChart' (visualization) and 'suggestChart' (recommendation) by focusing on validation and debugging.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when a chart configuration might have issues, but doesn't explicitly state when to use this tool versus alternatives like 'getSchema' (for schema inspection) or 'reportIssue' (for reporting problems). It provides some context through the problem examples but lacks explicit guidance on prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getSchemaAInspect

Return the prop schema for a Semiotic chart component. Pass { component: '' } to get its props, or omit component to list all available components. Components marked [renderable] can be passed to renderChart for static SVG output.

ParametersJSON Schema
NameRequiredDescriptionDefault
componentNoComponent name, e.g. 'LineChart'. Omit to list all.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's behavior: it returns prop schemas or lists components, and it specifies that components marked [renderable] are usable with 'renderChart'. However, it doesn't mention potential errors, rate limits, or authentication needs, leaving some behavioral aspects uncovered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by usage instructions and a note about sibling tools. Every sentence adds value without redundancy, making it efficient and well-structured for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (1 optional parameter, no output schema, no annotations), the description is mostly complete. It covers purpose, usage, and a key behavioral note about [renderable] components. However, it lacks details on output format or error handling, which could be useful for an agent, though not strictly required given the context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the schema already documents the single parameter. The description adds minimal value beyond the schema by reiterating that the component parameter can be omitted to list all, but it doesn't provide additional syntax, format details, or examples beyond what's in the schema. This meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('Return the prop schema', 'list all available components') and distinguishes it from siblings by mentioning that components marked [renderable] can be passed to 'renderChart'. It explicitly identifies the resource ('Semiotic chart component') and differentiates between two modes of operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool: pass a component name to get its props, or omit it to list all components. It also distinguishes from alternatives by noting that [renderable] components can be used with 'renderChart', clarifying the relationship with a sibling tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

renderChartBInspect

Render a Semiotic chart to static SVG. Returns SVG string or validation errors. Available components: AreaChart, BarChart, BoxPlot, BubbleChart, ChordDiagram, ChoroplethMap, CirclePack, ConnectedScatterplot, DistanceCartogram, DonutChart, DotPlot, FlowMap, ForceDirectedGraph, GroupedBarChart, Heatmap, LineChart, OrbitDiagram, PieChart, ProportionalSymbolMap, SankeyDiagram, Scatterplot, StackedAreaChart, StackedBarChart, SwarmPlot, TreeDiagram, Treemap.

ParametersJSON Schema
NameRequiredDescriptionDefault
componentYesChart component name, e.g. 'LineChart', 'BarChart'
propsNoChart props object, e.g. { data: [...], xAccessor: 'x' }.

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses that the tool returns 'SVG string or validation errors' and lists available components, which adds some behavioral context. However, it lacks critical details: whether this is a read-only operation, if it has side effects, performance characteristics, authentication needs, or rate limits. For a tool with no annotations, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with two sentences: one stating the purpose and return values, another listing components. It's front-loaded with the core functionality. However, the component list is lengthy and could be summarized more efficiently (e.g., 'Available components include LineChart, BarChart, and 20+ others').

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and a tool with 2 parameters (including a complex nested object 'props'), the description is incomplete. It doesn't explain the structure of 'props', provide example inputs, describe error handling, or detail the SVG output format. For a visualization tool with nested parameters, this leaves significant gaps for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema: it lists specific component examples (e.g., 'AreaChart', 'BarChart') which slightly clarifies the 'component' parameter, but doesn't explain 'props' object structure or provide usage examples. It doesn't compensate for any gaps since coverage is already high.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Render a Semiotic chart to static SVG' with specific verb ('Render') and resource ('Semiotic chart'). It distinguishes from siblings by specifying chart rendering rather than configuration diagnosis, schema retrieval, issue reporting, or chart suggestion. However, it doesn't explicitly differentiate from 'suggestChart' which might be related.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context by listing available components, suggesting this tool is for chart visualization. However, it provides no explicit guidance on when to use this tool versus alternatives like 'suggestChart' or other siblings. No prerequisites, exclusions, or comparative context are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

reportIssueAInspect

Generate a GitHub issue URL for Semiotic bug reports or feature requests. Returns a URL the user can open to submit. For rendering bugs, include the component name, props summary, and any diagnoseConfig output in the body.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYesIssue title, e.g. 'Bug: BarChart tooltip shows undefined'
bodyNoIssue body with details, reproduction steps, diagnoseConfig output
labelsNoGitHub labels, e.g. ['bug'] or 'bug'

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool generates a URL and returns it to the user, which implies a read-only operation that doesn't modify data. However, it doesn't mention authentication requirements, rate limits, or what happens if the GitHub repository is inaccessible. The description adds some context about what to include in the body for rendering bugs, but lacks comprehensive behavioral details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly concise and well-structured in two sentences. The first sentence states the core purpose and return value. The second sentence provides specific usage guidance for a common scenario. Every word earns its place with zero wasted text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 3 parameters, 100% schema coverage, and no output schema, the description is reasonably complete. It explains what the tool does, when to use it, and provides specific guidance for rendering bugs. The main gap is the lack of output information - while it mentions 'Returns a URL,' it doesn't describe the URL format or what happens if generation fails. Given the good schema coverage, this is mostly adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds minimal value beyond the schema: it mentions that the body should include 'component name, props summary, and any diagnoseConfig output' for rendering bugs, which provides some semantic context for the body parameter. However, it doesn't add significant meaning beyond what's already in the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Generate a GitHub issue URL for Semiotic bug reports or feature requests.' It specifies the exact action (generate URL) and resource (GitHub issue), and distinguishes it from sibling tools like diagnoseConfig or renderChart by focusing on issue reporting rather than diagnostics or rendering.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool: 'For Semiotic bug reports or feature requests.' It gives specific guidance for rendering bugs: 'include the component name, props summary, and any diagnoseConfig output in the body.' However, it doesn't explicitly state when NOT to use it or name alternatives among sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

suggestChartAInspect

Recommend Semiotic chart types for a given data sample. Pass { data: [...] } with 1-5 sample objects. Optionally pass intent to narrow suggestions. Returns ranked recommendations with example props.

ParametersJSON Schema
NameRequiredDescriptionDefault
dataYes1-5 sample data objects
intentNoVisualization intent to narrow suggestions

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses that the tool returns 'ranked recommendations with example props,' which adds useful behavioral context about the output format. However, it lacks details on error handling, rate limits, authentication needs, or performance characteristics, leaving gaps for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by parameter guidance and output information in just two sentences. Every sentence earns its place by conveying essential information without redundancy or fluff, making it highly efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description is moderately complete. It covers the purpose, basic parameter usage, and output format ('ranked recommendations with example props'), but it lacks details on error cases, response structure, or advanced usage scenarios, which would be helpful for a tool with no structured output documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents both parameters (data and intent). The description adds minimal value by mentioning the data sample size ('1-5 sample objects') and the optional intent to narrow suggestions, but it does not provide additional syntax, format, or usage details beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Recommend Semiotic chart types') and resource ('for a given data sample'), distinguishing it from sibling tools like renderChart (which renders) or getSchema (which retrieves schema). It specifies the exact verb and scope without being vague or tautological.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by mentioning 'Optionally pass intent to narrow suggestions,' but it does not explicitly state when to use this tool versus alternatives like renderChart or diagnoseConfig. There is no guidance on prerequisites, exclusions, or specific contexts, leaving usage somewhat ambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv0.1.0
    • First observeddiagnoseConfig
    • First observedgetSchema
    • First observedrenderChart
    • First observedreportIssue
    • First observedsuggestChart

TDQS

A3.8/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: diagnoseConfig for configuration validation, getSchema for component schema retrieval, renderChart for SVG chart generation, reportIssue for GitHub issue creation, and suggestChart for chart type recommendations. There is no overlap or ambiguity in their functions.

Naming Consistency4/5

The naming follows a consistent verb_noun pattern (e.g., diagnoseConfig, getSchema, renderChart, reportIssue, suggestChart), with all tools using camelCase. However, the pattern is slightly inconsistent as some tools use verb+noun (e.g., renderChart) while others use verb+noun combinations that are less standard (e.g., diagnoseConfig, reportIssue), but overall it remains readable and predictable.

Tool Count5/5

With 5 tools, this server is well-scoped for its purpose of chart configuration and rendering in Semiotic. Each tool serves a specific role in the workflow, from diagnosis and schema retrieval to rendering and issue reporting, making the count appropriate and efficient.

Completeness4/5

The tool surface covers the core chart lifecycle: diagnosis, schema exploration, rendering, issue reporting, and chart type suggestion. Minor gaps exist, such as the lack of tools for updating or deleting chart configurations, but these are not critical for the server's stated purpose, and agents can work around them effectively.

Maintenance

ActivityActive
ResponsivenessWithin a week

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    A
    maintenance
    MCP server that turns AI into an SVG artist. One rendering engine with a rich JSON schema, AI controls all design parameters. Renders animated SVGs with CSS @keyframes and SMIL animations. Supports 16+ element types, parametric curves, pattern groups, gradient/filter/clip/mask definitions, and PNG preview. No external dependencies, runs locally via npx.
    3
    167
    21
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for creating and manipulating generative art with p5.js, Three.js, GLSL, Canvas2D, and SVG, featuring workspace management, parameter control, and screenshot capture.
    89
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/nteract/semiotic'

If you have feedback or need assistance with the MCP directory API, please join our Discord server