visualiser

# Visualiser Visualiser is a mobile-first MCP App for turning a prompt into a routed visual learning experience inside chat. The server exposes one host-visible tool, `visualise_learning_view`, which selects the best family for the question and renders a single embedded teaching surface. The current families are: - `concept` -> `concept_map` - `flow` -> `flow_runner` - `system` -> `layered_architecture` - `data` -> `entity_map` - `time` -> `timeline` - `compare` -> `compare_matrix` - `simulate` -> `state_machine` - `practice` -> `build_it_back` ## Commands - `npm run dev` watches the UI bundle and runs the server with `tsx` - `npm run build` type-checks the project and bundles the UI into `dist/` - `npm run serve:stdio` starts the MCP server over stdio - `npm run serve:http` starts the MCP server over streamable HTTP on `http://localhost:3001/mcp` ## Codex local install This workspace includes a portable [.codex/config.toml](/Users/ipad/Desktop/mcp/visualiser/.codex/config.toml). The current machine also has the same `visualiser` server added to `~/.codex/config.toml`. 1. Run `npm run build` once so the MCP App HTML is bundled. 2. Reopen Codex or reload the workspace if the server list is already cached. 3. Run `codex mcp list` and confirm that `visualiser` is enabled. 4. In chat, call `visualise_learning_view`, for example: ```json { "prompt": "Explain OAuth token refresh for a visual learner", "preferredFamily": "flow" } ``` ## Practical verification - `npm run smoke:mcp` checks that the MCP server starts, validates all 8 routed view families, verifies prompt-based routing, and confirms Mermaid-like source material routes into `flow_runner`. - `npm run verify` runs the build and the MCP smoke test together. ## VS Code local install This workspace includes [.vscode/mcp.json](/Users/ipad/Desktop/mcp/visualiser/.vscode/mcp.json), so VS Code can start the server directly from the workspace. 1. Run `npm run build` once so the MCP App HTML is bundled. 2. Reload the VS Code window after the workspace files are picked up. 3. In VS Code, run `MCP: List Servers` and confirm that `visualiser` is enabled and running. 4. If VS Code prompts for trust, approve the workspace server. 5. In chat, enable the `visualiser` tool and ask for a visual explanation, for example: `Use visualise_learning_view to explain event-driven architecture visually.` 6. The app should render inline in chat when the tool returns its UI resource. ## Notes - Build the UI before using the server in a host, otherwise the resource endpoint returns a placeholder page. - HTTP mode also exposes `GET /health`. - App QA without a host can use `mcp-app.html?demo=1` or `mcp-app.html?demo=1&family=compare`. - On this machine, the global Codex config uses `model_reasoning_effort = "high"` so `codex mcp` CLI commands work reliably with the installed binary. ## Documentation Project documentation lives under `docs/`. - `docs/project-overview.md` explains the product scope and repository layout. - `docs/user-stories.md` records the primary validated user jobs across the 8 view families. - `docs/use-cases.md` captures concrete real-world usage patterns and example prompts. - `docs/architecture.md` explains server, UI, and shared contract flow. - `docs/interfaces-and-contracts.md` lists the MCP resource, tool, and schema contracts. - `docs/features/routed-learning-view.md` tracks the main product workflow.