mcp-chat-cards

An MCP (Model Context Protocol) server that renders interactive HTML cards inside desktop chat clients. Instead of walls of text, conversations get tab boxes, tables, charts, forms, short video clips, collapsible sections, and numbered outlines. On hosts that support the MCP Apps extension (SEP-1865), cards render inline in the conversation as sandboxed iframes; other hosts receive each card as a self-contained embedded HTML resource.

Features

• Tab cards: view different contexts of one subject side by side (per language, per OS, per skill level), including code samples with copy buttons.
• Table cards: build HTML tables from explicit rows or loosely delimited raw text. Delimiters are auto-detected, columns are balanced, and URL cells become links.
• Chart cards: dynamically generated SVG bar, line, pie, and donut charts with legends and a collapsible data table for accessibility.
• Form cards: forms the user fills in to give the conversation context and direction. Submitting sends the values back to the chat as the next prompt.
• Mirrored website forms: fetch a real page, rebuild one of its forms as a card, then submit the actual website form with the user-entered values via submit_web_form.
• Video cards: HTML <video> players for short clips.
• Animation cards: model-composed animated clips for when no direct video URL exists - sequential scenes of text, staggered bullet builds, simple SVG diagrams that trace themselves in, and single-series charts that zoom into the data range under discussion, all with video-style play/pause, replay, and progress controls.
• Show/hide cards: collapsible sections with show-all/hide-all controls.
• Sequential list cards: nested ordered lists numbered 1., 1.1., 1.1.1. via CSS counters.
• Document cards: render a markdown document (a guide or walkthrough the model wrote) as one interactive card with collapsible sections, styled tables, and copyable code.
• Code tour cards: present a project as one tab per source file, in the order the files are given (README and manifests hoisted first). Source files are syntax-highlighted for their detected language and line-numbered behind a Raw | Code toggle, the way a repository browser shows a file. Markdown files render as a formatted page instead, behind a Raw | Rendered toggle - a README in a tour reads as documentation, and the source is still one click away.
• Model-generated file ingestion: read local text files and unpack zip archives the model produced earlier in the conversation, so its own deliverables plug straight into cards without retyping anything.
• Automatic multi-part splitting: large documents and projects are packed into parts that each stay under a card size budget, so hosts never truncate an oversized result. Each part renders as its own card and the result says exactly how to fetch the next.
• Reference fetching: fetch_reference pulls a public page and returns structured data (headings, text, tables, images, links, form specs) ready to feed into card tools.
• Card tutor: educational cards can mark terms that show tooltips after a hover dwell, and define right-click context actions that send model-anticipated prompts.
• Movable content: card blocks can be drag-reordered, drag out of the card carries the block as HTML, and every card has a "Copy card" button that copies the standalone HTML for pasting into other responses or files.
• Header toggles: every card header has a </> button that shows or hides the card's own HTML source in a code panel, and a chevron button beside it that collapses the card down to its header row and expands it again.
• Efficient prompt builder: every card's right-click menu has a built-in "Generate Efficient Verbose Prompt" item that opens a three-step flow: a 350-character gist, up to three rounds of multiple-choice refinement (each question with a free-text "Other"), and a finished prompt shown with its character and token count, editable in place, copyable, and sent only after a confirmation box. The model reads a bounded gist and bounded answers instead of a rambling thread, so the only long text in the exchange is the prompt the user wanted.
• Copyable cards: every card's right-click menu has a built-in "Copy card" item that copies the standalone HTML, mirroring the header button. For visual placement, get_insert_bookmarklet returns a bookmarklet that shows a floating "Insert Card" item on right-click and injects the copied card at that spot (page-local preview; gone on reload).

When the model should call this server

The server advertises itself for conversations about research, education, professional skills, general hobbyist skills (woodworking, arts, and similar), professional topics, history, and news, plus related subjects, whenever a card communicates better than text.

Installation

git clone https://github.com/jhauga/mcp-chat-cards.git
cd mcp-chat-cards
npm install
npm run build

Requires Node.js 18.17 or newer.

Use with Claude Desktop

Add the server to claude_desktop_config.json (Settings > Developer > Edit Config), adjusting the path to where you cloned the repository:

{
  "mcpServers": {
    "chat-cards": {
      "command": "node",
      "args": ["C:/path/to/mcp-chat-cards/dist/index.js"]
    }
  }
}

Restart the desktop client after saving, or use Developer > Reload MCP Configuration (the Developer menu appears after Help > Troubleshooting > Enable Developer Mode). The same stdio command works in any MCP host; for hosts that support MCP UI resources, cards render as sandboxed iframes.

Where the desktop client keeps its logs depends on how it was installed: the Microsoft Store build writes mcp-server-chat-cards.log under %LOCALAPPDATA%\Claude\Logs\, the classic installer under %APPDATA%\Claude\logs\. The server's own stderr lines land in that file, which is what Debugging cards in Claude Desktop reads.

Host status (October 2026). Claude Desktop builds since September 2026 carry a local stdio server into Claude app chats through a device bridge that announces its tools without their ui binding and passes the model only structuredContent. The host never classifies a card tool as an App, never reads the template, and shows the result as a JSON row, in new and old conversations alike; the upstream report is anthropics/claude-ai-mcp#1069. Since 1.0.0-alpha.1.0.0 the server works around it: while a host has not read the card template, each result also carries a ready-made widget for the chat's own inline renderer (the visualizer's show_widget tool), and the model paints the card with it. See Visualizer widget. Hosts that mount the template render cards as before, and Run as a custom connector remains an untested alternative.

Run as a custom connector (Streamable HTTP)

npm run start:http starts the same server over Streamable HTTP so a chat client can reach it as a remote ("custom") connector. The client's cloud makes the connection, so the process has to be reachable from the internet, normally through a tunnel on the machine that runs it, and everything is gated by one bearer token.

Variable	Purpose
MCP_CHAT_CARDS_HTTP_TOKEN	Required. The server refuses to start without it and rejects every request that does not carry Authorization: Bearer <token> (16 characters minimum).
MCP_CHAT_CARDS_HTTP_PORT	Port to listen on (default 3310).
MCP_CHAT_CARDS_HTTP_HOST	Address to bind (default 127.0.0.1, loopback only).
MCP_CHAT_CARDS_FS_ROOT	Strongly recommended here. The local file tools read the filesystem of the machine running the server, so confine them to one folder before exposing it.

The endpoint is /mcp; every other path answers 404. Each client session gets its own server instance (the session id travels in the mcp-session-id header, as the transport specifies), request bodies are capped at 4 MiB, and the SDK's DNS-rebinding check is off, because behind a tunnel the Host header is the tunnel's name and the token is the gate.

A minimal setup, with set instead of export in a Windows command prompt:

export MCP_CHAT_CARDS_HTTP_TOKEN=<token>
export MCP_CHAT_CARDS_FS_ROOT=/path/to/an/empty/folder
npm run start:http
cloudflared tunnel --url http://127.0.0.1:3310

Then add the tunnel's URL plus /mcp (for example https://example.com/mcp) in the client's connector settings, with authentication set to "No sign in" and one request header, Authorization: Bearer <token>. In Claude, custom connectors live under Settings > Connectors and have to be enabled in each conversation's tools menu; the Free plan allows one.

Status: experimental. The entry point is covered by test/http.test.ts, has been exercised with the SDK's Streamable HTTP client and through a public tunnel, and is the route reported upstream as rendering Apps on current desktop builds, but a card has not yet been seen rendering in Claude through it from this repository. Nothing here is needed for the stdio setup above.

Tools

Tool	Purpose
create_tab_card	Tabbed views of one subject (text, HTML, or code per tab)
create_table_card	HTML table from rows or raw text with delimiter detection
create_chart_card	SVG bar, line, pie, or donut chart with data table
create_form_card	Form whose submission becomes the next conversation prompt
create_video_card	HTML video player for a short clip (direct file URL, data:video/*, or blob:; streaming platform pages are rejected)
create_reveal_card	Collapsible show/hide sections (text, HTML, or code per section)
create_list_card	Nested sequential outline (1., 1.1., 1.1.1.)
create_markdown_card	Render a markdown document (content or file path) as one card
create_code_tour_card	Render a project (zip path or explicit files) as file tabs: highlighted source behind Raw/Code, .md behind Raw/Rendered
create_prompt_gist_card	Step 1 of the efficient-prompt flow: collect a 350-character gist
create_prompt_refine_card	Step 2: multiple-choice questions that close the gaps (max 3 rounds)
create_efficient_prompt_card	Step 3: the finished prompt, editable, copyable, sent on confirmation
read_local_file	Read a local text file for review or card building
unpack_archive	List a local zip and return its text file contents
fetch_reference	Fetch a public page and return structured extracted data
mirror_web_form	Rebuild a website form as an interactive card
submit_web_form	Submit user-confirmed values to the real website form

Example: create_table_card

{
  "title": "JavaScript array methods",
  "headers": ["Method", "Purpose"],
  "rows": [
    ["map", "Transform each item"],
    ["filter", "Keep matching items"],
    ["reduce", "Fold items into one value"]
  ]
}

Output: a text summary plus an embedded resource (ui://mcp-chat-cards/<id>, text/html) containing the full card document.

Example: create_form_card

{
  "title": "Study preferences",
  "promptTemplate": "Teach {{topic}} with {{style}} examples.",
  "fields": [
    { "name": "topic", "label": "Topic", "required": true },
    { "name": "style", "type": "select", "options": ["practical", "theoretical"] }
  ]
}

When the user submits the card, the filled template is posted to the host as the next prompt. If the host does not consume the message, the card reveals the prompt text with a copy button as a fallback.

Example: the efficient-prompt flow

"Generate Efficient Verbose Prompt" in any card's right-click menu sends a message tagged [efficient-prompt]. The model answers with create_prompt_gist_card, and the gist the user submits carries the rules for the rest of the flow, so nothing has to be restated:

{
  "round": 1,
  "questions": [
    {
      "name": "depth",
      "question": "How much detail?",
      "options": ["Overview", "Step by step", "Line by line"]
    },
    {
      "name": "output",
      "question": "What should come back?",
      "options": ["A table", "A checklist", "Prose"],
      "multiple": true
    }
  ]
}

Each question also renders a free-text "Other" input under the group's own name, so a typed answer arrives joined with the checked ones. Anything left blank comes back empty, which the submitted prompt spells out as "no preference". The flow ends with:

{
  "prompt": "Audit config/loader.py for unhandled error paths. Output: a table of file, line, failure mode, and fix, then one line on the riskiest one.",
  "notes": "Assumes the current logging setup stays."
}

The card shows that prompt with its character and token count and a Send this prompt button. Clicking it opens a confirmation box; only "Yes, send it" hands the prompt to the conversation. On hosts with no channel back to the chat, the copy button is the whole story: the prompt is copied and the user pastes it as their next message.

Example: plug-n-play with files the model generates

Suppose earlier in the conversation the model built a small project and delivered project.zip plus a GUIDE.md walkthrough. Instead of the user unpacking and reading them by hand, the model turns them into interactive cards in two calls:

{ "path": "C:/Users/jane/Downloads/GUIDE.md" }

sent to create_markdown_card renders the whole guide as one card: the first H1 becomes the title, each H2 section folds into a show/hide reveal, tables get card styling, and every fenced code block gets a copy button.

{
  "title": "Project source tour",
  "archivePath": "C:/Users/jane/Downloads/project.zip",
  "intro": "Read the guide card first, then follow these files in order."
}

sent to create_code_tour_card unpacks the archive in memory and renders one tab per text file, ordered README, manifest, then source, each language-tagged with a copy button. Explicit files keep the order the caller gives them (README and manifests are hoisted to the front), so a deliberate teaching order - data model, then errors, then the entry point - renders as written instead of alphabetically. Build caches (target/, node_modules/) and binary entries are skipped automatically. Use unpack_archive or read_local_file first when the model needs to inspect contents before deciding which cards to build.

When a document or project exceeds the card size budget (default about 32,000 characters of card markup, tunable via MCP_CHAT_CARDS_CARD_BUDGET), the tool splits it at natural boundaries - H2 sections for documents, whole files for tours - and returns part 1 with an instruction like "call create_code_tour_card again with part: 2". The model repeats the call until every part has rendered as its own card, and oversized single files are truncated with a visible notice.

The budget is measured against what a file costs after rendering, not its length on disk: source is HTML-escaped into the tab panel, where a single < becomes four characters, so a handful of markup-dense files can cost far more than their raw size suggests. Every finished result is then measured once more against the host's ceiling (about 40,000 characters of serialized result, tunable via MCP_CHAT_CARDS_RESULT_LIMIT). A card that is still too large and cannot split itself - a table with thousands of rows, say - returns an actionable error naming the overage instead of an oversized result that the host would silently refuse to render.

Example: mirrored website form

1. mirror_web_form with { "url": "https://example.com/newsletter" } renders the page's signup form as a card.
2. The user fills it in and submits; the card returns a structured payload to the chat.
3. The model reviews the values with the user, then calls submit_web_form with the payload to submit the real form and reports the HTTP result.

How cards render

The server supports three delivery paths, chosen automatically per connection:

Inline in the conversation (MCP Apps, SEP-1865). The server pre-declares one UI template resource at ui://mcp-chat-cards/card.html with MIME type text/html;profile=mcp-app, and every card tool links to it through _meta.ui.resourceUri and declares an output schema (hosts drop structuredContent from schema-less tools, leaving the card nothing to paint). Hosts that support the Apps extension render the template inline in the chat as a sandboxed iframe, complete the ui/initialize handshake, and deliver the tool result to it (Claude Desktop did so until September 2026; see the host status note under Use with Claude Desktop). The template is defensive about the parts that fail silently: it announces ui/notifications/initialized on a timeout as well as on the handshake reply (the host withholds the tool result until it sees the announcement), locates the card payload by deep search rather than one fixed nesting, reports ui/notifications/size-changed after every paint and on resize so the iframe takes its real height, and adopts the host's theme (including a full dark palette). Card interactions travel back over JSON-RPC postMessage: form submissions and context actions become ui/message requests (the next conversation prompt), links go through ui/open-link, and telemetry uses logging notifications.

Standalone document fallback. For clients that did not declare the Apps extension, each result carries a link to ui://mcp-chat-cards/html/<card-id>. Reading that resource returns the same card as a self-contained HTML document (inline CSS and JS, restrictive Content-Security-Policy, no external scripts). Hosts without Apps support but with MCP-UI style rendering show that document in a sandboxed panel; there the card posts MCP-UI style messages (prompt, notify, link).

The document is deliberately not inlined in the tool result. Its theme and runtime are byte-for-byte identical in every card, so inlining repeated about 16 KB of boilerplate per call: it crowded out the caller's context and was the main reason an otherwise ordinary card could exceed a host's result ceiling and render nothing at all. Set MCP_CHAT_CARDS_EMBED_HTML=1 to restore the inline copy for a host that cannot follow a resource link. The server keeps the last 24 rendered cards available for reading.

Visualizer widget (hosts that never mount the template). Some hosts negotiate the Apps extension, call the card tools, and still never mount a view: Claude's device bridge, which carries local stdio servers into Claude app chats, strips the ui binding and hands the model only structuredContent. Those chats have an inline HTML renderer of their own, the visualizer tool show_widget. Until the host reads the card template on a connection (the one act that proves it mounts Apps views), every card result for an Apps client also carries structuredContent.display:

{
  "shown": false,
  "action": "This host does not mount MCP Apps views for this server, so ... call show_widget ...",
  "title": "rust_iterator_adapters_table_card",
  "loading_messages": ["Laying out the table card"],
  "widget_code": "<style id=\"mcc-critical\">...</style><h2 class=\"sr-only\">...</h2><article class=\"mcc-card\">...</article><script type=\"application/json\" id=\"mcc-config\">...</script><script src=\"https://cdn.jsdelivr.net/gh/jhauga/mcp-chat-cards@v<version>/widget/mcc-widget.js\"></script>"
}

The model passes title, loading_messages, and widget_code to show_widget and the card renders inline. widget_code is the card's own article plus a short critical style that keeps it legible while it streams, and one script tag for widget/mcc-widget.js: the full card theme mapped onto the host's design tokens (light and dark), a bridge that turns form submissions and context actions into sendPrompt() and links into openLink(), and the same card runtime the Apps template runs. The bundle is generated by npm run build, committed, and served by jsDelivr from the release tag (the visualizer only loads scripts from a few CDNs), so it can never disagree with the server that emitted the markup. If it cannot load, the card still reads correctly with the critical style; tabs, copy buttons, and menus need the bundle.

Variable	Effect
MCP_CHAT_CARDS_RENDER	auto (default): widget until the host reads the template. apps: never ship a widget (use once the host mounts cards again, to avoid painting twice). widget: always ship one.
MCP_CHAT_CARDS_WIDGET_SRC	Bundle URL override, for a fork or a local test server.

Because a widget result carries the article twice (once for the template, once inside widget_code), cards that split by size pack half as much per part while a widget ships. Known limits of this path: the visualizer's sandbox loads nothing from origins outside its CDN allowlist, so video and image cards show their captions and links but not the media; the card's hover and ready notifications have no channel back to the model; and on the first card after a host starts mounting Apps views again, the card can appear twice (once in the Apps frame, once as a widget) until the template read switches the connection to apps.

Consistent result shape

Every card tool returns the same three things, whatever the card kind:

Part	Contents
content[0]	Text summary of the card, meaningful on its own
content[1]	Resource link to the standalone HTML (omitted for Apps hosts)
structuredContent	{ "card": { "articleHtml": "…", "config": { "id", "kind", … } }, "parts": { … } }, plus display while a visualizer widget ships

Rendering surface

Cards render inline in the Claude desktop app on builds that mount the template, and in Claude app chats that reach a local server through the device bridge by way of the visualizer widget (see the host status note under Use with Claude Desktop). Other surfaces (mobile and web) receive the text summary and the structured payload but do not paint the card, so each summary is written to stand alone and tools are instructed to state a card's conclusion in the conversation as well.

Text fields are plain text

Every text field a tool accepts - titles, labels, cell values, tutor tips - is plain text and is escaped by the server exactly once. Callers must not pre-escape: pass Predict, Spot & Fix, not Predict, Spot & Fix.

Input is never decoded first, in any field. A caller who does pass & gets a card that displays the six characters &, because that is what a guide documenting HTML, escaping, or templating means to show its reader. The rule is the same everywhere, so the same string renders identically in a table cell, a tab, a markdown table, and a code sample.

Raw HTML is only honoured in fields named html (create_tab_card and create_reveal_card sections), where it is sanitized: scripts, event handlers, frames, forms, and dangerous URLs are stripped while formatting such as <b> and <i> is kept. Everywhere else - including HTML written inside a create_markdown_card document - tags render as literal text, so use markdown syntax for formatting there. Escaped block-level HTML is wrapped in the paragraph the markdown structure implies rather than dropped between siblings as loose text, and HTML comments are dropped rather than shown, since a <!-- markdownlint-disable --> directive is not prose.

Where paths resolve

create_markdown_card(path), create_code_tour_card(archivePath), read_local_file, and unpack_archive all resolve paths on the filesystem of the machine running this server. When the server is reached over a remote bridge, that is not the caller's sandbox: a file the model generated on its own side does not exist here. Pass the content inline (markdown, files) in that case. A path from the wrong operating system - say /home/demo-user/project.zip sent to a server running on Windows - is rejected with an error naming the mismatch rather than resolved onto a drive where it never existed; the same goes for Windows paths sent to a POSIX server and for unexpanded ~/ paths. Set MCP_CHAT_CARDS_FS_ROOT to confine local reads to one directory.

Interactivity notes and limits

• Drag and drop reorders blocks inside one card. Dragging a block out of the card carries its HTML in the drag data; dropping into another response requires host support, which desktop chat clients generally do not expose yet.
• "Copy card" copies the standalone HTML document so a card can be reproduced in another response, a file, or a browser tab.
• Tutor tooltips appear after hovering a marked term for about 1.2 seconds; the card also notifies the host so the model can follow up while the user explores. Each term is marked once per card (longest term wins where two overlap), duplicates in the term list are ignored, and marking never happens inside code samples, native tooltips, or another term's tip. Matching is case-sensitive, so a tip written for PATH does not attach itself to a filesystem path; set caseInsensitive: true on a term to match any casing. Pass tutorTermsInCode: true to create_code_tour_card to opt code in.
• Every card result carries structuredContent.parts as { current, total, hasMore }, so one completeness check works on every card type. While hasMore is true, content has been withheld and the caller calls the same tool again with part: current + 1. Only create_markdown_card and create_code_tour_card can split; every other card always reports { current: 1, total: 1, hasMore: false }. The rendered title keeps its human-readable (part 1 of 2) suffix for the reader.
• The split threshold is measured on rendered characters, not on the input a caller writes. Escaping expands source unpredictably - <, >, &, and quotes each become four to six characters - so a payload that looks well under the budget can cross it and a larger-looking one may not. Read parts.hasMore rather than predicting from input size. A markdown document with no H2 headings has no split boundary and always renders as one part.
• In a code tour, a source file whose language the highlighter knows gets a Raw | Code toggle. Code is the view on arrival: syntax-highlighted, with line numbers in an unselectable gutter, so a copy or a drag through the file picks up the file and not its numbering. Raw is the same text with the highlighting and gutter switched off, so the card carries one copy of the source rather than two. Languages covered: C, C++, C#, CSS, Go, Java, JavaScript, JSON, JSX, PHP, Python, Ruby, Rust, shell, SQL, TOML, TSX, TypeScript, and YAML, plus the usual aliases (node, js, py, golang, yml, and so on). Anything else renders as the plain code block it always did.
• Highlighted files cost more card budget than plain ones (roughly two to three times, since every token carries a span), and the packer measures the rendered panel, so a large tour splits into more parts than it used to rather than overflowing a card.
• In a code tour, a .md, .markdown, or .mdx file gets a Raw/Rendered toggle. Rendered is the view on arrival and shows the document as a page (headings, card-styled tables, links, fenced code with copy buttons, never folded into reveals); Raw is the ordinary code block, whitespace preserved, whose copy button returns the source byte for byte. Both views ship inside the card, so switching costs no round trip and the choice survives switching between file tabs. Every other extension is unchanged.
• Right-click context actions are defined by the model per card; {{selection}} in an action prompt is replaced with the user's selected text. Two items are always present regardless of what the model defined: "Generate Efficient Verbose Prompt" and "Copy card".
• The finished prompt card never sends on a single click. The first click opens a confirmation box; the prompt goes to the conversation only when that box is accepted, and what is sent is whatever the textarea holds at that moment, edits included.
• Form answers are gathered per field name, and empty values are dropped, so a choice group and a text input can share one name and arrive as a single comma-joined answer. Every named control still yields a key, so an unanswered group renders as an empty value rather than leaving a literal {{name}} in the prompt.

Security

• Local file tools (read_local_file, unpack_archive, and the path/archive inputs of the document and code tour cards) read text only, cap sizes, refuse binaries, and cap archive extraction (entry count, per-file, and total bytes). Set MCP_CHAT_CARDS_FS_ROOT to confine all local reads to one directory.
• Outbound requests are limited to http(s) URLs resolving to public addresses. Localhost, RFC 1918, link-local, CGNAT, and equivalent IPv6 ranges are blocked, redirects are re-validated, bodies are size-capped, and requests time out. Set MCP_CHAT_CARDS_ALLOW_PRIVATE=1 only if you intentionally need intranet fetches.
• All model- and user-supplied text is HTML-escaped; fetched third-party HTML is sanitized (scripts, event handlers, frames, forms, and dangerous URLs are stripped).
• Cards ship a restrictive CSP and load no external scripts, stylesheets, or fonts.
• submit_web_form should only be called with values the user entered in a mirrored form card or explicitly confirmed.

Debugging cards in Claude Desktop

A card that arrives as text, or mounts and stays empty, fails silently. Work down this list; each step separates the host from the server.

1. Did the host mount anything? Enable Developer Mode (Help > Troubleshooting > Enable Developer Mode), press Ctrl+Shift+I (Cmd+Option+I on macOS), and inspect the tool call. A rendered card is an iframe nested inside another iframe. No inner iframe means the host never treated the tool as an App: continue with step 2. An inner iframe that stays empty means the handshake or the payload failed: go to step 5.

2. Did the host read the template? Open mcp-server-chat-cards.log (locations under Use with Claude Desktop). The server writes one stderr line per host interaction, all prefixed mcp-chat-cards:

   mcp-chat-cards client <name> <version> connected (apps extension: declared)
   mcp-chat-cards card table card-abc123-1 rendered (1658 chars, apps client: yes)
   mcp-chat-cards template read by host (ui://mcp-chat-cards/card.html, 66232 chars)
   

   A card ... rendered line with no template read by host line near it is the signature of the host-side regression: the host negotiated Apps, called the tool, and never asked for the template. In the default render mode the next line then reads card <id> sent as a visualizer widget (render mode auto, template read by host: no), which means the result carried structuredContent.display and the card appears only once the model calls show_widget with it. A JSON row with no widget after it means the model skipped that call (ask it to show the card) or the chat has no visualizer. The host's own resources/read entries in the same file are only a lower bound (it logs one of its connections and never logs tools/call), so read the server's lines rather than the host's.

3. Is the server side healthy? Run npm run probe. It spawns dist/index.js over real stdio as a client that declares the Apps extension and checks the things a host needs: the server's extension capability, the ui binding on every card tool, output schemas, a visualizer widget on a result before any template read, the template's MIME type and content, a card result's structuredContent with no widget once the template was read, and the absence of the standalone fallback for Apps clients. All passing means a text-only card is the host's doing.

4. What does the model see? Ask, in the same conversation, which chat-cards tools advertise a ui:// resource. The model answers from the tool list the host gave it; "none" means the host dropped the binding before the model ever saw it.

5. Inside a mounted iframe, filter its console for [mcp-chat-cards]: every JSON-RPC message the card sends and receives is logged with its direction (tx/rx), so a missing handshake reply or an undelivered tool result is visible immediately. Run window.__mccDebug() there for a snapshot: template version, whether initialized was announced, whether a card painted, the rendered card HTML, and the last 50 protocol messages. Paste its output when reporting a rendering issue.

Supplemental ports

The extension/ folder contains supplemental ports of the card tools for other hosts. Both are self-contained - they do not import from src/ or dist/, and the MCP server is unaffected by them.

• extension/github/ - a GitHub Copilot canvas extension named chat-cards. The agent drives the same card kinds (tabs, tables, charts, forms, show/hide, sequential lists, markdown documents, video) through canvas actions, and form submissions come back to the conversation as prompts. Its README covers the action list, the differences from the MCP tools, and how the folder maps onto the awesome-copilot contribution layout.
• extension/claude/ - a Claude artifact template: one self-contained HTML page whose card spec block Claude fills and publishes as an artifact. Forms and right-click actions produce prompts the user copies back into the conversation.

Development

npm run build      # compile TypeScript to dist/ and regenerate widget/mcc-widget.js
npm test           # run the vitest suite (unit + in-memory MCP integration)
npm run probe      # check the built server over real stdio, as a host would
npm run coverage   # run tests with V8 coverage
npm run dev        # compile in watch mode

widget/mcc-widget.js is committed because jsDelivr serves it from the tagged repository; a test fails when it drifts from the sources. Cards point at @v<package version>, so push the release tag along with the commit (git push origin main v<version>), or widget-delivered cards fall back to their critical style until it exists. Do not load the bundle URL before the tag is on GitHub: jsDelivr caches the miss. If that happened, opening https://purge.jsdelivr.net/gh/jhauga/mcp-chat-cards@v<version>/widget/mcc-widget.js clears it.

The bundle runs inside the host's frame, so it must never feed back into the host: no observers on :root style or class, no DOM writes on a host-triggered path, no microtask loops. test/widget.test.ts mounts it beside a host that touches :root on every DOM change and fails if the two keep triggering each other.

License

MIT. See LICENSE.