Diorama
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Diorama
A closed visual vocabulary for coding agents to show and ask inside the chat, as an MCP Apps server. The agent sends structured data; the view draws it and handles the interaction. The agent never writes layout, style or behaviour.
Try it in the playground: write a tool call, see the view and what comes back. No install, nothing leaves the browser.
Status:
1.0.0-beta.1. The vocabulary may still change before 1.0.
Two things it is for:
Showing: explaining a system, walking through an incident, reporting progress. Nothing is asked and the agent carries on.
Asking: choosing between options, approving a plan step by step, picking what makes the cut. The answer goes back to the chat as a message and is appended to a local log.
Install
Not on npm yet. The beta runs straight from the release tarball. In VS Code, add to .vscode/mcp.json (and turn on the chat.mcp.apps.enabled setting):
{
"servers": {
"diorama": {
"type": "stdio",
"command": "npx",
"args": ["-y", "https://github.com/PierreAlvim/diorama-mcp/releases/download/v1.0.0-beta.1/diorama-mcp-1.0.0-beta.1.tgz"],
"cwd": "${workspaceFolder}"
}
}
}Any MCP client that renders MCP Apps can use the same command. Clients that do not render them still get the text summary of each view.
Related MCP server: widget-studio
Setup from source
git clone https://github.com/PierreAlvim/diorama-mcp.git && cd diorama-mcp
npm install
npm run build # view → dist/ui/index.html, server → dist/server/index.js
npm test # schema check of all scenarios, stdio smoke test, browser end-to-endnpm test needs a system Chromium or Chrome (set CHROME_PATH to point at a specific binary).
VS Code / Code OSS
Open this folder. .vscode/mcp.json registers the server and .vscode/settings.json turns on chat.mcp.apps.enabled.
Run MCP: List Servers, pick
diorama, Start.Open Chat in Agent mode and check that
present_viewandpresent_decisionare enabled in the tools picker.Try the prompts under Checking it in a real host.
To use it in another project, add the same server to that project's .vscode/mcp.json with the absolute path to dist/server/index.js. Keep "cwd": "${workspaceFolder}" so each project gets its own log.
After changing code: npm run build, then restart the server from MCP: List Servers.
Tools
Tool | Called by | Waits for the user | What it does |
| the agent | no | Shows a view. For explaining, exploring and concluding. |
| the agent | yes | Shows a view with a question and a typed response. |
| the view | — | Appends the answer to |
| the agent | — | Returns the recorded answers, for recall or for writing ADRs. |
Set DIORAMA_DIR to move the log somewhere other than <cwd>/.diorama.
Vocabulary
A view is title, optional context, and 1–4 blocks. Blocks are named after the shape of the data, not after a diagram type.
Block | Data | Typical use |
| items with summary, pros, cons | options of a decision |
| items × axes, score 1–5 with a reason | comparing by criteria |
| nodes and edges; variants | architecture, pipeline, state machine, data model, branches |
| tracks with phases and point events | rollout plan, incident reconstruction |
| flat node list with | hypotheses, epic breakdown, file tree, query plan |
| rows × columns, cells with text, heat or markers | decision table, coverage, config per environment, heat map |
| ordered items | implementation plan, checklist, cut line, agent progress |
| actors and messages | API contract, service interaction |
| items on two axes | backlog prioritisation |
| cards in columns | sprint board |
| bar or line series | before/after measurements |
Markers are accepted on any element: in (lens ids it belongs to), refs (ids of related elements), change (added, removed, changed, affected), status (ok, fail, running, warn, pending), note. A diff, a blast radius or a pipeline status is a graph, tree or matrix with markers.
Ids are global in a view. The same id in two blocks means the same thing, which is what links the highlight across blocks.
Interaction is declared, never coded:
Linked highlight: hovering an element lights up everything sharing its id or connected by
refs.Lenses:
lenses[{id, label}]plusinon elements. The user switches perspective; the rest dims. Each card is also a lens when a lens has its id.Walkthrough:
walkthrough[{text, focus[]}]. The user steps through; the view follows.Ask about this: in a
present_view, clicking an element sends a question about it to the chat.
Responses (present_decision only): response: { type, of?, depth? }.
Type |
| The user |
| a block id | picks one item, or "None of these" |
| 2–4 block ids | picks one item per block (e.g. one resolution per conflict) |
| a block id | ticks any number of items |
| a block id | approves or rejects each item |
| omitted | approves or rejects the whole view |
depth selects the answerable level when the block is a tree.
The server checks every call for dangling references (unknown ids in edges, scores, focus, response.of, wrong cell counts, …) and returns the list to the model instead of showing a broken view.
The schema is in shared/schema.ts; the reference checks in shared/lint.ts.
Scenarios
docs/cenarios.md (in Portuguese, payloads in English) describes 36 scenarios with sample data, the tool call and a wireframe each. The data lives in docs/scenarios/data-*.mjs and is used three ways:
npm run docsregenerates the document and the wireframes.npm run test:scenariosvalidates every call against the schema, strictly.npm run test:e2eruns every scenario through the real server and view (below).
The same 36 calls are preloaded in the playground.
Playground
npm run preview # dev server
npm run build:playground # static site in dist/playground, hostable anywhere (GitHub Pages, any file server)A page to write a tool call and see what it does, without an MCP host or a model. Nothing leaves the browser.
Left: the tool call. Edit it as JSON or through a form; both edit the same value. The form is derived from the tool's JSON Schema, so a new block or field in
shared/schema.tsappears without any form code. Paste works for{tool, arguments}, for{name, arguments}as MCP logs print it, and for bare arguments.+ blockappends a minimal example of any block (playground/src/templates.ts).Update preview (Ctrl+Enter) runs the call. There is no live rendering.
Right: the real view, in a sandboxed iframe sized to its content as chat hosts do. Width and theme can be switched to see how it behaves in a narrow or dark chat.
Below: what comes back. The tool result exactly as the model reads it (the summary, or the list of what to fix when the call is rejected), the chat message sent when the user answers or asks, and the record that would be appended to the log. Validation is the same code the server runs (shared/present.ts).
Size: bytes and estimated tokens of the arguments, i.e. what the call costs the model to write.
Copy link packs the call into the URL hash.
#s=Nopens scenario N.
Tests
Command | What it covers |
| server, view and scripts |
| all scenario payloads against the schema and the reference checks |
| the built server over stdio: tool list, lint rejections, the UI resource, the decision log |
| a minimal MCP Apps host (test/host/) in headless Chromium: for each scenario it renders the view in a sandboxed iframe, exercises lenses, walkthrough and hover, answers the decision and checks the chat message, the |
| npm run test:playground | the static playground in headless Chromium: all scenarios load, form and JSON stay in sync, errors are reported, answers reach the output panel, shared links round-trip |
npx tsx scripts/e2e.ts --shots also writes light and dark screenshots of every scenario to dist/screens/.
The end-to-end host implements the same protocol a real client does, but it is not one. What it cannot tell: whether a given model picks the right tool and block for a prompt, and how a given client sizes and themes the iframe.
Checking it in a real host
One prompt per area. Start with "Use diorama" until you see how readily the model picks the tools up by itself.
Decision (
cards,tradeoff,graph) — "We need to keep a CRM in sync with our billing database within a few minutes; there is no message broker in production. Show me the alternatives and let me choose."Plan approval (
steps,approve) — "Plan adding rate limiting to the public API and let me approve or reject each step."Explanation (
graph+ walkthrough) — "Walk me through how a request travels through this repository."Diagnosis (
tree,choose_one) — "We get intermittent 502s on /api/reports at night. Show your hypotheses with the evidence for each and ask which to test first."sequence— "Show the OAuth authorization-code flow between browser, app, identity provider and API."quadrant— "Here are nine tech-debt items: … Place them by impact and effort and let me pick this cycle's."board— "Show the sprint as a board and point out what is stuck." (with a Jira/GitHub MCP, or paste the tickets)chart— "I ran the benchmark before and after the change: … Show the comparison."matrixwith markers — "Compare the configuration of dev, staging and production and mark what differs."Log — after a few answers: "Use list_decisions and write an ADR for each decision into docs/adr/."
Things to look at: the view fits the chat width, dark theme, the answer arrives as a chat message, and after a present_view the agent keeps going without waiting.
Layout
shared/schema.ts zod schemas, shared by server and view
shared/lint.ts reference checks, shared by server, view tests and docs
shared/present.ts what a present_* call returns to the model; shared by server and playground
server/index.ts MCP server (stdio)
ui/src/model.ts pure logic: highlight, picks, answer messages
ui/src/App.tsx shell: lenses, walkthrough, footer
ui/src/blocks/ one renderer per block
playground/ editor page + the view in an iframe; schema-derived form
test/host/ minimal MCP Apps host used by the end-to-end test
scripts/ smoke, e2e (host and playground), scenario check, docs generator
docs/ V1 definition and scenario catalogue (Portuguese)License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Build and publish full-stack apps from your coding agent: models, rules, pages, auth, per-app MCP.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for creating interactive Vega-Lite data visualizations that render inline in chat via MCP Apps.21MIT
- AlicenseAqualityDmaintenanceMCP server that lets agents create, display, and export rich UI widgets (cards, dashboards, charts, forms) inline in conversations, with interactive iframe support in MCP Apps hosts and PNG image fallback for other clients.3MIT
- AlicenseNot gradedqualityBmaintenanceMCP server that provides AI coding agents with real-time visual access to web apps, enabling them to see screens, run accessibility and layout inspections, and interact with pages through a shared live panel.95 npm130MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to present replies as interactive, validated UI trees rendered as MCP Apps—such as checklists and data grids—without requiring another LLM call.5 npm1MIT