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

{
  "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, 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.