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

Related MCP server: mcp-interactive-ui-server

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. The same stdio command works in any MCP host; for hosts that support MCP UI resources, cards render as sandboxed iframes.

Tools

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 two delivery paths, negotiated automatically by the host:

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 (recent Claude Desktop builds among them) render the template inline in the chat as a sandboxed iframe, complete the ui/initialize handshake, and deliver the tool result to it. 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.

Consistent result shape

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

Rendering surface

Cards render inline in the Claude desktop app sidebar. 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

If a card mounts but stays empty, the failure is usually silent, so the template traces everything to the console:

1. Enable Developer Mode in Claude Desktop (Settings, Developer), then open the webview developer tools for the conversation.

2. Filter the 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.

3. Run window.__mccDebug() in that console 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/
npm test           # run the vitest suite (unit + in-memory MCP integration)
npm run coverage   # run tests with V8 coverage
npm run dev        # compile in watch mode

License

MIT. See LICENSE.