mcp-chat-cards

Overview Schema Source Related Servers Discussions Admin

Create code tour card

create_code_tour_card

Render project source as an interactive code-tour card with per-file tabs, syntax highlighting, line numbers, and a Raw/Code toggle; large projects split into parts for browsing.

Instructions

Render a project's source as an interactive card with one tab per file. Source files are syntax-highlighted for their detected language and line-numbered, with a Raw/Code toggle and a copy button, the way a repository browser shows a file; a language with no grammar renders as a plain code block. Markdown files (.md, .markdown, .mdx) render as a formatted page - headings, tables, links, copyable fenced code - with a Raw/Rendered toggle back to the source, so a README in a tour reads as documentation rather than as source. Explicit files keep the order they are given in, with README and manifests hoisted to the front; archive files are ordered README, manifest, then src. Pass the path of a zip archive generated earlier in the conversation for a one-call plug-n-play tour, or pass files explicitly. Files are packed into parts of about 32,000 rendered characters each regardless of how many there are, so a handful of medium files still splits. The result's structuredContent.parts {current,total,hasMore} reports the split: while hasMore is true some files were withheld, so call again with part: current + 1 and identical other arguments until every part has rendered.

Input Schema

Name	Required	Description
`part`	No	Part number for large projects (1-based). Big tours split automatically; while structuredContent.parts.hasMore is true, call again with the next part.
`files`	No	Explicit files to show when not using archivePath
`intro`	No	Guidance shown in a leading 'Start here' tab
`title`	Yes
`include`	No	With archivePath: only include entries whose path contains one of these
`maxTabs`	No
`subtitle`	No
`tutorTerms`	No	Educational tutor terms. The first occurrence of each term in the card's visible prose is underlined; hovering ~1.2s shows the tip and notifies the host so the model can follow up. Terms are matched once per card, longest first, and never inside code samples, tooltips, or another term's tip. Matching is CASE-SENSITIVE, so "PATH" does not attach its tip to a filesystem "path"; set caseInsensitive on a term to match any casing. Term and tip are PLAIN text.
`archivePath`	No	Path to a zip ON THE MACHINE RUNNING THIS SERVER, not in the caller's sandbox. Over a remote bridge those are different machines: if the archive exists only on your side, pass its text files as files instead.
`contextActions`	No	Right-click menu actions the model anticipates being useful. Choosing one sends its prompt to the conversation; use {{selection}} to include the user's selected text.
`tutorTermsInCode`	No	Also highlight tutorTerms inside the code samples. Off by default, because marking up language keywords in source is noise rather than teaching.

Output Schema

Name	Required	Description
`card`	Yes
`parts`	Yes	Split state, present on EVERY card result so one completeness check works for all card types. Cards that cannot split always report {current:1,total:1,hasMore:false}; create_markdown_card and create_code_tour_card pack oversized content into parts and can report more. Read hasMore rather than the card title to decide whether content was withheld.
`display`	No	Present only when the host is not mounting this server's MCP Apps template (see MCP_CHAT_CARDS_RENDER): the card ships as a ready-made visualizer widget instead.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.0.0-alpha.1.0.1Oct 17, 2026

addedOutput schema / properties / display

Added value: +{
+  "additionalProperties": false,
+  "description": "Present only when the host is not mounting this server's MCP Apps template (see MCP_CHAT_CARDS_RENDER): the card ships as a ready-made visualizer widget instead.",
+  "properties": {
+    "action": {
+      "description": "What the caller must do to put the card in front of the user",
+      "type": "string"
+    },
+    "loading_messages": {
+      "description": "show_widget loading_messages",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "shown": {
+      "description": "False: the user cannot see this card until action is taken",
+      "type": "boolean"
+    },
+    "title": {
+      "description": "show_widget title (snake_case)",
+      "type": "string"
+    },
+    "widget_code": {
+      "description": "show_widget widget_code, passed unchanged",
+      "type": "string"
+    }
+  },
+  "required": [
+    "shown",
+    "action",
+    "title",
+    "loading_messages",
+    "widget_code"
+  ],
+  "type": "object"
+}

Changed7 schema fields changedv0.1.3-alphaAug 21, 2026

removedInput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

changedInput schema / properties / part / description

Previous value: -"Part number for large projects (1-based). Big tours split automatically; when the result says more parts remain, call again with the next part."New value: +"Part number for large projects (1-based). Big tours split automatically; while structuredContent.parts.hasMore is true, call again with the next part."

changedInput schema / properties / tutorTerms / description

Previous value: -"Educational tutor terms. The first occurrence of each term in the card's visible prose is underlined; hovering ~1.2s shows the tip and notifies the host so the model can follow up. Terms are matched once per card, longest first, and never inside code samples, tooltips, or another term's tip. Term and tip are PLAIN text."New value: +"Educational tutor terms. The first occurrence of each term in the card's visible prose is underlined; hovering ~1.2s shows the tip and notifies the host so the model can follow up. Terms are matched once per card, longest first, and never inside code samples, tooltips, or another term's tip. Matching is CASE-SENSITIVE, so \"PATH\" does not attach its tip to a filesystem \"path\"; set caseInsensitive on a term to match any casing. Term and tip are PLAIN text."

addedInput schema / properties / tutorTerms / items / properties / caseInsensitive

Added value: +{
+  "description": "Match the term regardless of letter case (default false)",
+  "type": "boolean"
+}

removedOutput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

addedOutput schema / properties / parts

Added value: +{
+  "additionalProperties": false,
+  "description": "Split state, present on EVERY card result so one completeness check works for all card types. Cards that cannot split always report {current:1,total:1,hasMore:false}; create_markdown_card and create_code_tour_card pack oversized content into parts and can report more. Read hasMore rather than the card title to decide whether content was withheld.",
+  "properties": {
+    "current": {
+      "description": "Part number this result rendered (1-based)",
+      "type": "number"
+    },
+    "hasMore": {
+      "description": "True when content was withheld; call again with part: current + 1",
+      "type": "boolean"
+    },
+    "total": {
+      "description": "How many parts the content splits into",
+      "type": "number"
+    }
+  },
+  "required": [
+    "current",
+    "total",
+    "hasMore"
+  ],
+  "type": "object"
+}

changedOutput schema / required

Previous value: -[
-  "card"
-]New value: +[
+  "card",
+  "parts"
+]

Changed3 schema fields changedv0.1.1-alphaAug 12, 2026

changedInput schema / properties / archivePath / description

Previous value: -"Path to a local zip; its text files become tabs"New value: +"Path to a zip ON THE MACHINE RUNNING THIS SERVER, not in the caller's sandbox. Over a remote bridge those are different machines: if the archive exists only on your side, pass its text files as files instead."

changedInput schema / properties / tutorTerms / description

Previous value: -"Educational tutor terms. Occurrences in the card are underlined; hovering ~1.2s shows the tip and notifies the host so the model can follow up."New value: +"Educational tutor terms. The first occurrence of each term in the card's visible prose is underlined; hovering ~1.2s shows the tip and notifies the host so the model can follow up. Terms are matched once per card, longest first, and never inside code samples, tooltips, or another term's tip. Term and tip are PLAIN text."

addedInput schema / properties / tutorTermsInCode

Added value: +{
+  "description": "Also highlight tutorTerms inside the code samples. Off by default, because marking up language keywords in source is noise rather than teaching.",
+  "type": "boolean"
+}

First observedv0.0.0-alphaAug 10, 2026

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden, and it delivers: ordering rules (explicit order with README/manifests hoisted; archive order README, manifest, src), the ~32,000-character part split and why small files still split, the exact resume loop against structuredContent.parts.hasMore, and the archivePath-on-server-vs-sandbox caveat. This is unusually rich behavioral disclosure for a mutation/render tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then rendering behavior, then input-mode selection, then pagination — a sensible order. A few clauses are UI minutiae ('copy button,' 'Raw/Code toggle') that don't aid invocation, keeping it just short of tight.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, annotation-free tool this covers the risky paths — archive vs explicit files, part-splitting and resumption, ordering, tutor-term matching rules. Remaining gaps (maxTabs interaction with the split, subtitle/intro/contextActions purpose) are covered by the schema, so the omission is minor.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

At 73% schema coverage the baseline is elevated, and the description genuinely adds meaning for the high-stakes params: the part/resume protocol, files ordering and hoisting behavior, and the archivePath machine caveat. It is silent on maxTabs, subtitle, and intro, which are left entirely to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Render a project's source as an interactive card with one tab per file,' then elaborates with syntax highlighting, Raw/Code toggle, and markdown rendering. An agent can immediately tell this is the code-tour card, not the table, chart, or markdown card among its siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit selection criteria between the two input modes ('Pass the path of a zip archive generated earlier... or pass files explicitly') and a precise continuation protocol for pagination. It does not name sibling tools as alternatives, so it stops short of full when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.