mallory-grapher
Run headless MCP-driven reactive compute-graph sessions with cells, sessions, and computed definitions.
Open sessions (
session_open) as generic or graph-theory with optional seed data.Close sessions (
session_close) and list open sessions (session_list).Set input cells (
session_set_cell) to any JSON value, demoting computed cells to inputs.Get cell values (
session_get_cell), recomputing stale computed cells.List all cells (
session_list_cells) with role and defining op.Define computed cells (
session_define) via ops:math_eval,graph_parse_edge_list,graph_analyze,graph_bfs,graph_dfs,graph_dijkstra, using literals or{"$cell": "name"}live references for reactive dependencies.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mallory-grapher start a headless session and compute 5 * 7 = ?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
math-grapher
Full documentation: opensource.johnhenry.me/math/math-grapher
A headless, DOM-less session runtime for the @johnhenry/math family's reactive
compute graph (CellGraph), agent-drivable over MCP.
Usage
# stdio (the transport MCP hosts speak natively -- e.g. `claude mcp add`)
npx @johnhenry/math-grapher
# Streamable HTTP on http://localhost:3920/mcp (or a custom port)
npx @johnhenry/math-grapher --http
npx @johnhenry/math-grapher --http 8123Tools: session_open (kind generic or graph-theory), session_close,
session_list, session_set_cell, session_get_cell,
session_list_cells, session_explain_cell (a cell's own op/args/
immediate dependencies with their current values, one level -- issue #5),
session_snapshot/session_resume (serialize a session's free-cell
values + define-specs; reconstruct an equivalent session, possibly on a
different process -- issue #6), session_define. Computed cells are
declared as
JSON define-specs over a server-side op catalog (math_eval,
graph_parse_edge_list, graph_analyze, graph_bfs/dfs/dijkstra)
with {"$cell": "name"} live references — see
docs/design.md §5. An op MAY declare a
requiresCapability (issue #7); session_define rejects it unless
session_open/session_resume's own optional capabilities arg granted
it for that session (default none — matching the existing write-path
gating precedent below, just per-op instead of one global switch). No op
in the catalog above declares one yet.
Resource guards default modest and are overridable:
MATH_GRAPHER_MAX_SESSIONS (16), MATH_GRAPHER_MAX_CELLS (512),
MATH_GRAPHER_EVAL_BUDGET_MS (250), MATH_GRAPHER_MAX_PAYLOAD_BYTES
(262144).
Related MCP server: chuk-mcp-runtime
Platform
The . entry (SessionTable, buildServer, CellGraph, the op catalog)
is Node- and browser-safe — no node:* import in its graph, verified by
bundling it with esbuild under platform: 'browser' (see
test/browser-bundle.test.ts). randomUUID uses globalThis.crypto
(Node ≥19, every modern browser) rather than node:crypto. The bin
(npx @johnhenry/math-grapher, src/cli.ts) is Node-only — it owns the
--http transport (node:http) — and is never imported by .; embedding
this runtime in a browser page or bundler build means importing .
directly (e.g. via an in-page MCP Client/InMemoryTransport pair, ORRERY's
own pattern), not the CLI.
Status
v1 implemented. docs/design.md is the settled design; the session runtime, op catalog, MCP tool surface, and both transports are built and tested.
Why this exists
mallory's (the graphing-calculator app, formerly mallory-graph)
in-page WebMCP tools (useCellGraphTools:
${prefix}_list_cells/get_cell/set_cell) already let an agent drive a
live, reactive CellGraph — but only from inside a rendered browser tab.
The server-side MCP endpoint mallory ships today (@johnhenry/math-plus-mcp,
math-plus's packages/mcp) only covers stateless math tools
(Symbolic eval, guarded tensor/linalg) plus read-only, serialized
gallery access (gallery_list/gallery_get read NotebookState.blocks[]
JSON — no computed/derived-cell evaluation, no reactivity).
Real session parity — "an agent could run an entire modeling session headlessly" — means running the reactive compute graph itself server-side, with no DOM/React tree at all. That's a materially different, bigger project than either of the above, so it lives here instead of inside mallory.
Split out of mallory#163
after that issue's own audit trail: a feasibility spike
(cell-graph-headless-spike.test.ts) already confirmed CellGraph itself
has zero window/document references — set/define/get/
subscribe/subscribeAll are plain data-structure + closure code. What
doesn't exist yet is the actual session API around it.
Relationship to mallory
Optional, not coupled. math-grapher does not depend on
mallory (the app), and mallory does not need to depend on
math-grapher to function. mallory may choose to mount a
math-grapher-backed MCP route the same way it mounts @johnhenry/math-plus-mcp
today (src/routes/api.mcp.ts) — a separate integration issue, not a
prerequisite for this repo to exist or ship v1.
Concretely, this repo owns:
The headless session runtime (open a session, drive its cells, read results) — no rendering, no React, no DOM.
An MCP tool surface over that runtime.
It deliberately does NOT own:
Canvas/WebGL rendering — session parity is about the same get/set/list contract WebMCP already gives an in-page agent, not pixels.
mallory's specific panel components, gallery storage, or UI.
What's known so far (carried over from #163's audit)
CellGraph's core (cell-graph.tsin mallory, ~500 lines) has no structural blocker to running headless — proven empirically, not just asserted.Most panels'
useXGraph()seed step readswindow.location.hash/getComputedStylefor URL-state hydration and theming. Both are already guarded withtypeof window !== "undefined"checks (existing SSR-safety code), so they degrade gracefully rather than crash — but a real agent-drivable session needs a way to seed state from something other than a browser's URL bar (an MCP tool argument, presumably).Write-path auth precedent: mallory's
gallery_savetool (#163 item 1, shipped) is gated OFF by default behind an explicit env var (MALLORY_GRAPH_ENABLE_MCP_WRITE=1), mirroringllmtm'sLLMTM_HUB_ENABLE_*convention. A session-runtime write surface should follow the same default-off, explicit-opt-in posture.
Available Tools
10 toolssession_closeB
Close a session and free its cells.
Inputs: sessionId (required).
session_defineA
Define a computed cell from a catalog op. args values may be literal JSON or live cell references ({"$cell": "name"}) -- referenced cells become reactive dependencies, so the cell recomputes when they change. Available ops:
math_eval: Evaluate an @johnhenry/math Symbolic expression string over named numeric variables. args: { expr: string, vars?: { name: number | {"$cell": ...} } }. value: number.
graph_parse_edge_list: Parse a
from to [weight]-per-line edge list into a graph value. args: { text: string, directed?: boolean (default true) }. value: graph (opaque; project with session_get_cell).graph_analyze: Structural analysis of a graph cell. args: { graph: graph }. value: { hasCycle, connectedComponents, stronglyConnectedComponents, topologicalOrder, adjacencyMatrix: { matrix, order } }.
graph_bfs: Breadth-first traversal order. args: { graph: graph, start: string }. value: string[].
graph_dfs: Depth-first traversal order. args: { graph: graph, start: string }. value: string[].
graph_dijkstra: Dijkstra shortest-path distances from a start vertex. args: { graph: graph, start: string }. value: [{ vertex, distance }].
Inputs: op (required), args (required), cell (required), sessionId (required).
session_explain_cellA
Explain a cell's own derivation (issue #5): its role (free input vs computed), the op and raw args that defined it (if computed), its immediate upstream cells with their current values, and its own current value. One level only -- call again on a listed dependency's "cell" name to go deeper.
Inputs: cell (required), sessionId (required).
session_get_cellB
Read a cell's current value (recomputing it if stale). Rich values project to typed JSON (a graph cell returns { "$type": "graph", vertices, edges, directed }).
Inputs: cell (required), sessionId (required).
session_listA
List open sessions with kind, cell count, and creation time.
Inputs: no named parameters.
session_list_cellsA
List every cell in a session with its role ("free" input vs "computed") and, for computed cells, the op that defines it.
Inputs: sessionId (required).
session_openA
Open a reactive cell session. kind "generic" starts empty; "graph-theory" pre-wires an edge-list -> analysis -> BFS pipeline (input cells: edgeListText, directed, startVertex; computed cells: parsed, analysis, bfsOrder). Optional seed sets input cells in the same call (overriding preset defaults). Optional capabilities (issue #7) grants this session use of ops that declare a requiresCapability -- see session_define's own description for which ops (if any) need one; default none. Sessions are in-memory and die with the server.
Inputs: kind (required), seed, capabilities.
session_resumeA
Reconstruct a session from a session_snapshot document. A resumed session is freshly opened, not re-authorized from wherever it paused -- every existing resource guard (session/cell/payload limits) applies exactly as it would to session_open, and capabilities (issue #7) are NOT carried forward from the original session: pass this call's own optional capabilities to grant any, default none.
Inputs: snapshot (required), capabilities.
session_set_cellA
Set an input cell's value (any JSON). Setting a previously-computed cell demotes it to a plain input. Dependent computed cells recompute lazily on their next get.
Inputs: cell (required), sessionId (required), value.
session_snapshotA
Serialize a session's portable state (issue #6): current free-cell values plus define-specs. Does NOT include computed-cell cache -- those re-derive from define() on resume. Hand the returned document to session_resume, possibly on a different math-grapher process, to reconstruct an equivalent session.
Inputs: sessionId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Session lifecycle tools and graph/math operations are mostly distinct, with clear boundaries between get, set, list, and explain cell operations. However, session_define lists catalog ops that are also exposed as standalone tools (math_eval, graph_*), which could confuse whether to invoke an op directly or via define.
All tool names use snake_case with predictable prefixes: session_* for session lifecycle and graph_* for graph operations. Minor deviations like math_eval lacking a prefix and graph_bfs using an acronym rather than verb_noun keep it from perfect consistency.
The actual tool list contains 16 tools (despite the stated count of 10), which is slightly above the 3-15 sweet spot. The set is still reasonably scoped for a reactive-cell session server with graph and math operations, and each tool covers a distinct lifecycle or op.
The surface covers session open/resume/snapshot/close/list, cell get/set/list/explain/define, and a useful graph/math op catalog. A few gaps exist, such as no explicit cell deletion or session update/capability modification after opening, but core workflows are supported.
Maintenance
Related MCP Connectors
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
Unofficial Browserless MCP — wraps the Browserless headless-Chromium REST API (browserless.io)
Hosted runtime for persistent agent teams, durable workflows, memory, schedules, and goals.
Private-by-default, local-first memory/context/task orchestrator for MCP apps and agents.
Related MCP Servers
- AlicenseAqualityAmaintenanceHeadless WorkPaper MCP server for spreadsheet formulas, workbook edits, JSON persistence, and verified readback from TypeScript services.735MIT

chuk-mcp-runtimeofficial
AlicenseNot gradedqualityBmaintenanceA robust runtime for the official Model Context Protocol (MCP) that adds proxying, session management, JWT auth, persistent user storage with scopes, and progress notifications.9Apache 2.0- AlicenseNot gradedqualityBmaintenanceExposes the Nodus orchestration runtime as MCP tools for memory management, goal/workflow execution, and sandboxed code execution.241 PyPIMIT
- FlicenseNot gradedqualityDmaintenanceA runtime for inspectable agent workflows that provides MCP tools, bounded Python execution, session memory, and deterministic evaluation.-