maidr

maidr-mcp

An MCP server that shows accessible maidr charts inside ChatGPT and Claude conversations, and lets the conversation's model move the reader through them and run the chart's commands for them.

The model calls show_chart with the data, and the chart appears in the conversation as an MCP App. A blind or low-vision reader Tabs into it and explores it the way they explore any maidr chart: arrow keys, screen reader, sonification, braille. Three things then happen through the model:

• The model can take the reader somewhere. When the reader asks for "the highest bar", the model calls maidr_get_layer_data to find it and maidr_navigate to move there, and maidr announces the point by speech, braille and sound. When the reader is typing to the model rather than in the chart, it passes focus: true, since they asked to be taken there, and maidr moves their keyboard focus into the chart to make the move.
• The model can press the chart's keys for the reader. When the reader asks to turn braille off, play the chart, or jump to the lowest value, the model calls maidr_list_commands to find the command and the reader's current modes, and maidr_run_command to run it. maidr announces the result as if the reader had pressed the key, and the model tells them which key that was.
• The model knows where the reader is. As the reader moves, the chart tells the model their position, so "what is this point?" needs no tool call. Within a turn, maidr_list_charts reads it live.

Experimental. Checked end to end in the MCP Apps SDK's reference host (below). Not yet checked in claude.ai or ChatGPT.

How it works

1. show_chart draws the chart on the server with matplotlib and py-maidr, so the model sends numbers rather than an SVG. The SVG reaches the chart view in the tool result's _meta, which is not added to the model's context.
2. The view loads maidr.js and the MCP Apps SDK from cdn.jsdelivr.net, the only domain its CSP declares, at pinned versions.
3. maidr.js registers its own WebMCP tools on document.modelContext. No host hands a view's tools to the model yet (ext-apps#797), so the view supplies document.modelContext itself. Each server tool of the same name relays its call to the view that is open:

• the model calls the server tool;
• the view polls an app-only tool, picks up the call, runs maidr's tool, and posts maidr's answer back;
• that answer becomes the model's tool result.

The poll is a long poll: the server holds it for up to 20 seconds until a call comes, so the call reaches the chart at once. If the host cuts or refuses a request held that long, the view falls back to short polls, which the server answers at once, one every 2 seconds, so the model's call is still answered within the 10 seconds the server waits for the chart. The view tries a long poll again after a minute, and waits twice as long after each one the host cuts.

If hosts adopt WebMCP for MCP Apps, as ext-apps#798 proposes, maidr's tools reach the model directly and the relay can go.

1. On each key the reader presses in the chart, the view sends their position with ui/update-model-context.
2. update_chart draws a new chart for a viewId and relays it to that view, which swaps it in place: maidr lets go of the old chart, with any move or command still waiting for the reader in it, and binds the new one. When something was waiting, the chart's status line says it went, and update_chart tells the model so it can take back what it promised the reader. The server keeps the latest chart, so a view that missed the swap, out of view or mounted again by the host, catches up on its next poll.
3. The view never moves the reader's focus itself, except to put a reader back into the chart update_chart replaced. maidr moves it into the chart only when the model passes focus: true, which the server's instructions and the tools' descriptions tell it to do only when the reader asked to be taken somewhere or for something now, and never because they left the chart. Any other move or command the model makes while the reader is outside the chart waits for them, as does one with focus: true that could not take them in (focused: false). Until they enter the chart, the view's status line says so: "The assistant has a move waiting for you: Tab into the chart to hear it." After update_chart the same line says "Chart updated: ", until the reader enters the chart, by Tab or with focus: true; when a move or command waits as well, it says both.

Tools

show_chart and update_chart take one of these chart types, the ones py-maidr marks stable. Each maps onto the maidr layer type shown:

Every type also takes title, x_label and y_label. A pie has no axes, so there they name what the slices are and what the values measure.

The model reads every layer's points with maidr_get_layer_data. Where the last column says no, maidr gives the points no target: the reader moves through them with the keys, and maidr_navigate answers layer not navigable.

Example prompts

Once the server is connected, a reader asks in plain words; nobody names a tool. The prompts below are grouped by what the reader is doing, and each says which tools the model is expected to call. Paste the data into the conversation, or let the model use numbers it already has from earlier in the chat.

Show a chart

The model calls show_chart once, and the chart appears with the viewId the other tools use.

Explore the chart through the model

Have the model press the chart's keys

| "Go to the maximum val