maidr-mcp

# maidr-mcp

<!-- mcp-name: io.github.xability/maidr-mcp -->

An [MCP](https://modelcontextprotocol.io) server that shows accessible [maidr](https://maidr.ai) 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](https://modelcontextprotocol.io/extensions/apps). 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](#try-it-in-the-reference-host)). 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](https://github.com/xability/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](https://github.com/xability/maidr) 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](https://github.com/xability/maidr/blob/main/docs/WEBMCP.md) on `document.modelContext`. No host hands a view's tools to the model yet ([ext-apps#797](https://github.com/modelcontextprotocol/ext-apps/issues/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](https://github.com/modelcontextprotocol/ext-apps/pull/798) proposes, maidr's tools reach the model directly and the relay can go.
4. On each key the reader presses in the chart, the view sends their position with `ui/update-model-context`.
5. `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.
6. 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: <title>", until the reader enters the chart, by Tab or with `focus: true`; when a move or command waits as well, it says both.

## Tools

| Tool | Called by | Does |
| --- | --- | --- |
| `show_chart` | model | Draws the chart and shows it. Returns the `viewId` the other tools take. |
| `update_chart` | model | Draws a new chart and puts it in place of the one in that `viewId`'s view. Adds no view. A reader in the chart stays in it, on the new chart; anyone else keeps their focus. Both are told it changed. |
| `maidr_list_charts` | model | Returns the chart's layers, point counts, and, while the reader is in the chart, where they are, live. Silent. |
| `maidr_get_layer_data` | model | Returns a page of a layer's points, each with the `target` that `maidr_navigate` takes. Silent. |
| `maidr_navigate` | model | Moves the reader to a point and announces it. With `focus: true`, for a reader who asked to be taken there, maidr first moves their keyboard focus into the chart, and answers `focused: true`, or `focused: false` when it could not, leaving the move to wait for them. |
| `maidr_list_commands` | model | Returns the reader's commands, each with its id, title, keys, and whether the model can run it, and the reader's current modes (text, sound, braille, autoplay and more). Silent. |
| `maidr_run_command` | model | Runs one of the reader's commands, such as `toggle_braille`, `autoplay_forward` or `go_to_max_value`, as if they had pressed its keys, and announces the result. Commands that open a dialog or text field are the reader's own. With `focus: true`, for a reader who asked for it now, maidr first moves their keyboard focus into the chart, and the command runs in turn half a second after they hear where they are (`applied: "queued"`, `focused: true`), or answers `focused: false` when it could not, leaving the command to wait for them. |
| `maidr_view_poll`, `maidr_view_reply`, `maidr_view_svg` | the chart view only | Carry the relay, and the SVG for `update_chart` and for hosts that drop `_meta`. |

`show_chart` and `update_chart` take one of these chart types, the ones py-maidr marks [stable](https://py.maidr.ai/stability.html). Each maps onto the maidr layer type shown:

| `type` | Fields | maidr layer | The model can move the reader there |
| --- | --- | --- | --- |
| `bar` | `categories`, `series` (one series, or several side by side, or `stacked`) | `bar`, `dodged_bar`, `stacked_bar` | yes |
| `line` | `x` (numbers or labels), `series` | `line` | yes |
| `step` | `x`, `series`, `where` (`post`, `pre` or `mid`) | `step` | yes |
| `scatter` | `x`, `y`, and `trend` for a least-squares line | `point`, and `smooth` for the trend line | to the points, not the line |
| `histogram` | `values`, `bins` | `hist` | yes |
| `box` | `groups` | `box` | no |
| `violin` | `groups` | `violin_box`, `violin_kde` | no |
| `heatmap` | `x_labels`, `y_labels`, `values`, `z_label` | `heat` | yes |
| `pie` | `categories`, `values` (read clockwise from 12 o'clock) | `pie` | no |
| `candlestick` | `dates`, `open`, `high`, `low`, `close` | `candlestick` | no |

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`.

## Use it

maidr-mcp is published three ways, at the same version:

- **PyPI:** [`maidr-mcp`](https://pypi.org/project/maidr-mcp/), run with [uv](https://docs.astral.sh/uv/). `uvx maidr-mcp` serves HTTP at `127.0.0.1:8000/mcp`; `uvx maidr-mcp --stdio` serves a host that starts the server itself. `uvx maidr-mcp@latest` takes the newest release rather than one uv has cached.
- **Container image:** `ghcr.io/xability/maidr-mcp`, tagged with each version and `latest`. It serves HTTP at `/mcp` on port 8000.
- **MCP Registry:** `io.github.xability/maidr-mcp`, for clients that add servers from the [registry](https://registry.modelcontextprotocol.io).

What the server needs depends on how the host reaches it:

| Host | How it connects | What the server needs |
| --- | --- | --- |
| Claude (web, Desktop, mobile) | a custom connector, which takes a remote MCP server | a public HTTPS address |
| ChatGPT | a developer-mode app | a public HTTPS address, or [Secure MCP Tunnel](#chatgpt-without-a-public-address) to your own machine |
| ChatGPT desktop app | its own MCP servers, started over STDIO | nothing hosted; see [below](#chatgpt-without-a-public-address) for what is untested |

### With a public address

```bash
# Make a token once, and keep it: it is the <token> in each host's URL below.
export MAIDR_MCP_TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
uvx maidr-mcp --host 0.0.0.0 --port 8000
# or
docker run -p 8000:8000 -e MAIDR_MCP_TOKEN ghcr.io/xability/maidr-mcp
```

The endpoint is `/mcp`, over Streamable HTTP, and with a token also `/mcp/<token>`.
- **Run one instance.** The relay keeps each chart's queue