math-board
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MATH_BOARD_DATA_DIR | No | Overrides the data folder where the MCP server keeps its board and saves (in the `mcp/` subfolder). Default is a per-user state folder (e.g. `$XDG_STATE_HOME/math-board`, `~/Library/Application Support/math-board`). Give pi and the MCP server separate folders if you set it for both. The old name `PI_MATH_BOARD_DATA_DIR` still works. | |
| MATH_BOARD_NO_BROWSER | No | Set to 1 to never open a browser; the board URL (with its token) is always returned instead: `claude mcp add math-board -e MATH_BOARD_NO_BROWSER=1 -- npx -y pi-math-board`. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
A shared blackboard is available: a browser page the learner watches while you talk in the terminal. Call board_open to start it; that activates the other board tools.
Draw when a visual helps: derivations, geometry and vectors, diagrams of processes, plots, molecules, anatomy, timelines, flowcharts and state machines, trees and maps, tables, code, data charts, images. Do not draw trivial or purely verbal points; answer those in the terminal.
Rhythm: read the board (board_read), draw one step (board_update), ask one check question in the terminal and wait for the answer, then continue.
To show how something changes with a parameter, give the plot a slider (params) and ask the learner to move it. Point at what is drawn with focus instead of redrawing it. For a prediction, add the answer with cover:true and ask before they uncover it.
Keep one concept per chapter: start a new chapter for a new concept and use the camera to move the learner there. Keep board text short (labels, key equations, a few words) and put the explanation in the terminal.
The learner decides when a new board starts. If the board holds an unrelated earlier lesson, ask before drawing on it; never clear it yourself.
Before you use an artifact type for the first time, call board_docs for its format.
The learner may refer to the board as "step 4, eq2": that is a step number and an item id. Read the board to find what they mean before you answer. Give items short ids (eq1, f2) so such references stay easy.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| board_openA | Open the shared blackboard to teach visually: starts it, shows it in the learner's browser and activates the board tools (board_read, board_update, board_docs, ...). Returns the URL if no browser opens. Safe to call again. |
| board_readA | Read the shared blackboard: revision, chapters, camera, steps, and the layout (id, type, position, size, step) of one chapter. Read before board_update (pass the revision as baseRevision) and to resolve references like "step 4, eq2". |
| board_updateA | Draw on the shared blackboard; each call that adds items is one lesson step the learner watches being drawn. Coordinates: the home board and every chapter are 1200x800, origin top-left, y down; items with |
| board_snapshotA | Render the board in a headless browser and return a PNG as the learner sees it, plus each item's measured box and the layout warnings. Use it after significant changes, then fix problems with board_update. |
| board_libraryA | Search the offline science illustration library (~2000 Bioicons: anatomy, organs, cells, blood and immunology, microbes, viruses, DNA, plants, animals, lab equipment). Returns icon ids for an artifact {type:'icon', icon:id, x, y, width}. No query lists the categories. |
| board_saveA | Save the board as a named snapshot, list snapshots, or load one (replaces the whole board; needs baseRevision from board_read). Details: board_docs saves. |
| board_docsA | Reference for the blackboard: artifact formats with examples (plot, svg, mermaid, molecule, icon, table, code, chart, image), marks, equations, chapters and camera, animation, layout and style, saves. Call it before using a format for the first time. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 7 tools
Each tool maps to a distinct lifecycle action (open, read, update, save, snapshot, docs, library), so an agent can generally pick correctly. The only friction is board_save vs board_snapshot, which sound similar but mean persistence vs headless PNG rendering; descriptions resolve it, though board_save also bundling save/list/load adds mild ambiguity.
All seven tools use a uniform board_ prefix with short snake_case suffixes (library, open, read, save, snapshot, update, docs). The pattern is predictable and easy to scan, even though suffixes are nouns/verbs mixed rather than strict verb_noun.
Seven tools is well-scoped for a shared-canvas teaching server: one each for opening, reading, updating, persisting, previewing, documenting formats, and searching assets. No tool feels redundant or bolted on.
The surface covers the full draw/read/preview/persist loop plus format docs and an asset library, which is strong. Minor gaps remain: no explicit delete/undo or close operation, and snapshot only produces a PNG render rather than an exportable file, but agents can work around these via board_update.