How Dolex Works

Dolex is an npm package that exposes visualization intelligence through three interfaces: an MCP server (for AI assistants), a React component library (for apps), and a programmatic API (for scripts). All three share the same pattern library, selector, and rendering pipeline.

The key insight: an LLM will always suggest bar/line/pie. Dolex's pattern selector encodes design expertise as scoring rules — it knows when a bump chart, beeswarm, Sankey diagram, or waffle chart is the right answer.

The Model Context Protocol lets AI assistants call external tools over a standardized JSON-RPC transport. Dolex runs as a stdio MCP server — the assistant's host process spawns it, sends tool calls over stdin, and reads results from stdout.

For Claude Desktop, a shell wrapper (scripts/mcp-server.sh) sets up nvm PATH before launching the server, so Node.js is found regardless of the host environment.

The server registers 15 tools organized into four groups. Tools marked with App use MCP Apps for inline chart rendering.

The selector (src/patterns/selector.ts) is the core IP. It analyzes data shape + user intent, scores every registered pattern against a set of hand-tuned selection rules, and returns ranked recommendations.

Key functions

Selection Rules

Each of the 43 patterns defines an array of selection rules. A rule has a condition (human-readable label), a weight (positive = boost, negative = penalty), and a matches(ctx) function that tests the data context.

// Example: bar chart selection rule
{
  condition: 'Moderate categories (5-15)',
  weight: 30,
  matches: (ctx) =>
    ctx.dataShape.categoryCount >= 5 &&
    ctx.dataShape.categoryCount <= 15,
}

The scoring pipeline sums all matching rule weights, adds a category alignment boost when the inferred intent matches the pattern's category, and sorts. The top recommendation always wins — no randomness, fully deterministic.

Force Pattern Override

The pattern parameter (MCP) / forcePattern option (API) lets callers bypass scoring. The selector still runs the full pipeline (so alternatives are available), then promotes or constructs the forced pattern as the recommended result. Unknown IDs or spec failures fall back gracefully with a note in the reasoning.

Here's exactly what happens when the visualize tool is called, step by step.

Token-Efficient Response

The text content returned to the LLM is compact — just a specId, recommended pattern + title + reasoning, alternatives (pattern + reasoning only), and a data shape summary. The full spec with data is stored server-side in the SpecStore and never round-tripped through the conversation. The pre-rendered chart HTML goes to the UI via structuredContent.

For refinements, the LLM just passes back the specId — no data, no encoding, no config. The refine response is equally lean: just specId + an array of changes applied (no spec echo). This reduces a typical visualize + 2 refines workflow from ~36,500 tokens to ~3,000.

Additional token-saving features: set title and subtitle on the initial visualize call to avoid a refine round-trip just for titles. Use resultId from a query_data call to pass data by reference instead of re-sending rows. Use detail: "compact" on load_csv / describe_data to get minimal column metadata when full stats aren't needed.

Key functions

CSV mode is Dolex's answer to the biggest problem in AI-driven data visualization: token cost. A typical CSV might have 500,000 rows — passing that through the AI assistant's context window would burn tens of thousands of tokens per visualization. CSV mode ensures the raw data never touches the AI assistant at all.

The Token-Efficient Architecture

The AI assistant never sees your data. It sees a compact profile (column types, stats, top values, a few sample rows) and writes a tiny query. The Dolex server — running locally on your machine — handles the actual data, runs the query, selects the pattern, and renders the chart. The result that flows back through the assistant is a spec + pre-rendered HTML.

CSV Persistence

Loaded CSVs persist to ~/.dolex/sources.json automatically. On server restart, list_data shows previously-loaded datasets immediately. The first query triggers a lazy reload — no upfront overhead. Re-calling load_csv with an existing name is idempotent: it reloads and returns the schema without duplicating the entry.

Compact vs. Full Schema

Both load_csv and describe_data accept a detail parameter. In "full" mode (default), you get numeric stats, categorical top values, and sample rows. In "compact" mode, you get just column names, types, and row counts — perfect for multi-table sources where the assistant already knows the schema and just needs a quick reminder.

What the AI Assistant Sees vs. What It Doesn't

The Server-Side Pipeline

SQL Capabilities

Claude writes standard SQL. Dolex runs it locally via SQLite with some handy extensions.

Key functions

A compound visualization pairs a chart with a sortable data table and links them with interactive highlighting. When you hover a bar, the corresponding table row highlights — and vice versa.

The interaction bus uses postMessage between the parent compound document and the chart iframe. The compound HTML builder produces a single self-contained document with CSS grid layout.

Three rendering targets share a single source of truth: the D3 renderers.

The Build Pipeline

HTML builders are 2-line wrapper files (html/render/*.render.ts) that re-export from D3 renderers. The npm run build:bundles command uses esbuild to compile each renderer into an IIFE string stored in _generated/bundles.ts.

This means there's one source of truth for each chart's rendering logic. Edit a D3 renderer, run npm run build:bundles, and both React and HTML outputs pick up the change.

D3 Renderer Organization

MCP Apps lets tools render rich UI inline in the AI assistant. Dolex uses this to show charts directly in the Claude Desktop conversation instead of just returning JSON.

How the App Shell Works

The app shell (src/mcp/app-shell.ts) is a minimal HTML page registered as a resource at ui://dolex/chart.html. Claude Desktop loads it once, then for each tool call:

1. The host sends a ui/notifications/tool-result notification with the chart HTML
2. The shell creates a nested srcdoc iframe with the chart HTML
3. The shell sends ui/notifications/size-changed with the desired height (500px charts, 700px compound)

Colors are applied through the colorPreferences parameter on the visualize tool, or via natural language refinement with refine_visualization (using a specId from a previous call).

The applyColorPreferences() function mutates the spec's encoding.color before HTML generation. All palettes are WCAG AA compliant and tested for colorblind safety.

Dolex runs entirely on your machine. No telemetry, no analytics, no data sent to Anthropic or any third party. This section explains what data the server holds and how to manage it.

What's in Memory

The MCP server is a long-lived process — it starts when Claude Desktop launches and stays running for the session. Data accumulates across tool calls and is automatically cleaned up by TTL-based expiration.

Inspecting & Clearing Data

Two tools give you visibility and control over cached data:

HTML Output

Every chart embeds its data as JSON in the HTML document for client-side rendering. Data is capped at 10,000 rows per view to limit exposure. The HTML lives in a sandboxed iframe and is not persisted by the MCP host.

CSV Persistence

Loaded CSV paths persist to ~/.dolex/sources.json automatically. Use remove_data to delete entries when done.

What Leaves Your Machine