一个在桌面聊天客户端内渲染交互式 HTML 卡片的 MCP（Model Context Protocol）服务器。对话不再是一大段文字，而是获得选项卡框、表格、图表、表单、短视频片段、可折叠区块和编号大纲。在支持 MCP Apps 扩展（SEP-1865）的主机上，卡片以沙箱 iframe 的形式内联渲染在对话中；其他主机则将每张卡片作为自包含的嵌入式 HTML 资源接收。

特性

• 选项卡卡片：并排查看同一主题的不同上下文（按语言、按操作系统、按技能水平），包括带复制按钮的代码示例。

• 表格卡片：从显式行或松散分隔的原始文本构建 HTML 表格。分隔符自动检测，列自动对齐，URL 单元格变为链接。

• 图表卡片：动态生成的 SVG 柱状图、折线图、饼图和环形图，带图例和可折叠的数据表以支持无障碍访问。

• 表单卡片：用户填写以赋予对话上下文和方向的表单。提交后会将值作为下一条提示发送回聊天。

• 镜像网站表单：抓取真实页面，将其中的一个表单重建为卡片，然后通过 submit_web_form 用用户输入的值提交实际的网站表单。

• 视频卡片：用于短视频片段的 HTML <video> 播放器。

• 动画卡片：当没有直接的视频 URL 时，由模型编排的动画片段——文本的连续场景、错落的项目符号逐条构建、简单的 SVG 图示自行描画，以及单系列图表缩放到正在讨论的数据范围，全部带有视频风格的播放/暂停、重播和进度控制。

• 显示/隐藏卡片：带全部显示/全部隐藏控件的可折叠区块。

• 顺序列表卡片：通过 CSS 计数器编号为 1.、1.1.、1.1.1. 的嵌套有序列表。

• 文档卡片：将 markdown 文档（模型撰写的指南或演练）渲染为一张交互式卡片，带可折叠区块、样式化表格和可复制的代码。

• 代码导览卡片：将项目呈现为每个源文件一个选项卡，按给定文件的顺序排列（README 和清单文件优先置顶），带语言标记的代码和复制按钮。

• 模型生成文件的摄取：读取本地文本文件并解压模型在对话早期生成的 zip 归档，使其自己的交付物直接插入卡片，无需重新输入任何内容。

• 自动多部分拆分：大型文档和项目被打包成多个部分，每个部分都保持在卡片大小预算之内，因此主机永远不会截断过大的结果。每个部分渲染为一张自己的卡片，结果会准确说明如何获取下一部分。

• 参考抓取：fetch_reference 拉取一个公开页面并返回结构化数据（标题、文本、表格、图片、链接、表单规格），可直接馈入卡片工具。

• 卡片导师：教育类卡片可以标记术语，悬停停留后显示工具提示，并定义右键上下文操作以发送模型预期的提示。

• 可移动内容：卡片块可以拖拽重新排序，将块拖出卡片会以 HTML 形式携带该块，每张卡片都有一个"复制卡片"按钮，可复制独立 HTML 以粘贴到其他回复或文件中。

• 页眉开关：每张卡片的页眉都有一个 </> 按钮，用于在代码面板中显示或隐藏卡片自身的 HTML 源码，旁边还有一个 V 形按钮，可将卡片折叠到仅剩页眉行并再次展开。

• 可复制卡片：每张卡片的右键菜单都有一个内置的"复制卡片"项，可复制独立 HTML，与页眉按钮对应。为了视觉定位，get_insert_bookmarklet 返回一个小书签，在右键时显示一个浮动的"插入卡片"项，并将复制的卡片注入到该位置（页面本地预览；刷新后消失）。

Related MCP server: mcp-interactive-ui-server

模型何时应调用此服务器

该服务器在涉及研究、教育、职业技能、一般爱好技能（木工、艺术等类似领域）、专业话题、历史和新闻，以及相关主题的对话中自我宣传，只要卡片比文本传达得更好。

安装

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

需要 Node.js 18.17 或更高版本。

与 Claude Desktop 一起使用

将服务器添加到 claude_desktop_config.json（设置 > 开发者 > 编辑配置），调整为你克隆仓库的路径：

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

保存后重启桌面客户端。相同的 stdio 命令适用于任何 MCP 主机；对于支持 MCP UI 资源的主机，卡片以沙箱 iframe 的形式渲染。

工具

示例：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"]
  ]
}

输出： 一个文本摘要加上一个嵌入式资源 （ui://mcp-chat-cards/<id>、text/html），包含完整的卡片文档。

示例：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"] }
  ]
}

当用户提交卡片时，填好的模板会作为下一条提示发布到主机。如果主机不消费该消息，卡片会显示提示文本并带一个复制按钮作为后备方案。

示例：与模型生成的文件即插即用

假设在对话早期，模型构建了一个小项目并交付了 project.zip 以及一份 GUIDE.md 演练。模型无需用户手动解压和阅读，而是通过两次调用将它们变成交互式卡片：

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

发送给 create_markdown_card 会将整个指南渲染为一张卡片：第一个 H1 成为标题，每个 H2 区块折叠为显示/隐藏的揭示区，表格获得卡片样式，每个围栏代码块获得复制按钮。

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

发送给 create_code_tour_card 会在内存中解压归档，并为每个文本文件渲染一个选项卡，顺序为 README、清单文件、然后是源码，每个都带语言标记和复制按钮。显式的 files 保持调用者给定的顺序（README 和清单文件被提升到最前面），因此精心安排的教学顺序——先是数据模型，然后是错误，再是入口点——会按原样渲染，而不是按字母顺序。构建缓存（target/、node_modules/）和二进制条目会被自动跳过。当模型需要先检查内容再决定构建哪些卡片时，请先使用 unpack_archive 或 read_local_file。

当文档或项目超过卡片大小预算（默认约 32,000 个字符的卡片标记，可通过 MCP_CHAT_CARDS_CARD_BUDGET 调整）时，工具会在自然边界处拆分——文档按 H2 区块，导览按整个文件——并返回第 1 部分，附上类似"再次调用 create_code_tour_card 并传入 part: 2"的说明。模型重复调用，直到每个部分都渲染为自己的卡片，而过大的单个文件会被截断并附上可见的通知。

预算衡量的是文件在渲染后的成本，而不是其在磁盘上的长度：源码被 HTML 转义到选项卡面板中，其中单个 < 会变成四个字符，因此少量标记密集的文件可能比其原始大小所暗示的成本高得多。每个完成的结果随后会再次对照主机的上限进行衡量（约 40,000 个字符的序列化结果，可通过 MCP_CHAT_CARDS_RESULT_LIMIT 调整）。一张仍然过大且无法自行拆分的卡片——比如一个有数千行的表格——会返回一个可操作的错误，指明超出量，而不是返回一个主机将静默拒绝渲染的过大结果。

示例：镜像网站表单

1. 使用 { "url": "https://example.com/newsletter" } 调用 mirror_web_form，将页面的注册表单渲染为卡片。

2. 用户填写并提交；卡片将结构化负载返回给聊天。

3. 模型与用户一起审阅这些值，然后使用该负载调用 submit_web_form 提交真实表单，并报告 HTTP 结果。

卡片如何渲染

服务器支持两种交付路径，由主机自动协商：

内联在对话中（MCP Apps，SEP-1865）。 服务器预先声明一个 UI 模板资源，位于 ui://mcp-chat-cards/card.html，MIME 类型为 text/html;profile=mcp-app，每个卡片工具都通过 _meta.ui.resourceUri 链接到它，并声明一个输出模式（主机从无模式的工具中丢弃 structuredContent，使卡片没有可绘制的内容）。支持 Apps 扩展的主机（包括最近的 Claude Desktop 版本）将模板以沙箱 iframe 的形式内联渲染在聊天中，完成 ui/initialize 握手，并将工具结果交付给它。模板对静默失败的部分具有防御性：它在超时时以及握手回复时都宣布 ui/notifications/initialized（主机在看到该宣布之前会扣留工具结果），通过深度搜索而不是单一固定嵌套来定位卡片负载，在每次绘制后以及调整大小时报告 ui/notifications/size-changed，以便 iframe 采用其真实高度，并采用主机的主题（包括完整的深色调色板）。卡片交互通过 JSON-RPC postMessage 传回：表单提交和上下文操作成为 ui/message 请求（下一条对话提示），链接通过 ui/open-link 打开，遥测使用日志通知。

独立文档回退。 对于未声明 Apps 扩展的客户端，每个结果都携带指向 ui://mcp-chat-cards/html/<card-id> 的链接。读取该资源会返回同一张卡片，形式为自包含的 HTML 文档（内联 CSS 和 JS、严格的 Content-Security-Policy、无外部脚本）。不支持 Apps 但支持 MCP-UI 风格渲染的主机会在沙箱面板中显示该文档；在那里，卡片会发送 MCP-UI 风格的消息（prompt、notify、link）。

该文档刻意不内联在工具结果中。其主题和运行时在每张卡片中逐字节相同，因此内联意味着每次调用都要重复约 16 KB 的样板代码：这会挤占调用方的上下文，也是原本普通的卡片可能超出主机结果上限并最终什么都渲染不出来的主要原因。设置 MCP_CHAT_CARDS_EMBED_HTML=1 可为无法跟随资源链接的主机恢复内联副本。服务器会保留最近渲染的 24 张卡片供读取。

一致的结果结构

每个卡片工具都返回同样的三样内容，无论卡片类型如何：

渲染表面

卡片在 Claude 桌面应用侧边栏中内联渲染。其他表面（移动端和 Web）会收到文本摘要和结构化负载，但不会绘制卡片，因此每份摘要都写得可以独立成立，且工具被指示也要在对话中说明卡片的结论。

文本字段是纯文本

工具接受的每个文本字段——标题、标签、单元格值、辅导提示——都是纯文本，并由服务器恰好转义一次。调用方不得预先转义：请传 Predict, Spot & Fix，而不是 Predict, Spot & Fix。

任何字段的输入都不会先被解码。确实传入 & 的调用方会得到一张显示六个字符 & 的卡片，因为这正是讲解 HTML、转义或模板的指南想要向读者展示的内容。规则在所有地方都一样，因此同一个字符串在表格单元格、标签页、Markdown 表格和代码示例中渲染结果完全相同。

原始 HTML 仅在名为 html 的字段（create_tab_card 和 create_reveal_card 的 section）中被接受，且会经过净化：脚本、事件处理器、框架、表单和危险 URL 会被剥离，而 <b>、<i> 等格式会被保留。其他所有地方——包括写在 create_markdown_card 文档内部的 HTML——标签都会按字面文本渲染，因此请在那里使用 Markdown 语法进行格式化。被转义的块级 HTML 会按 Markdown 结构所隐含的段落包裹，而不是作为松散文本丢弃在兄弟元素之间；HTML 注释会被丢弃而非显示，因为 <!-- markdownlint-disable --> 指令不是正文。

路径在哪里解析

create_markdown_card(path)、create_code_tour_card(archivePath)、read_local_file 和 unpack_archive 都在运行此服务器的机器的文件系统上解析路径。当服务器通过远程桥接访问时，那不是调用方的沙箱：模型在自己一侧生成的文件在这里并不存在。这种情况下请内联传递内容（markdown、files）。来自错误操作系统的路径——例如将 /home/demo-user/project.zip 发送给运行在 Windows 上的服务器——会被拒绝并报出指明不匹配的错误，而不是解析到某个从未存在过的驱动器上；Windows 路径发送给 POSIX 服务器以及未展开的 ~/ 路径也是如此。设置 MCP_CHAT_CARDS_FS_ROOT 可将本地读取限制在单个目录内。

交互说明与限制

• 拖放可在单张卡片内对块重新排序。将块拖出卡片会将其 HTML 携带在拖拽数据中；拖放到另一个响应中需要主机支持，桌面聊天客户端目前通常还不提供此能力。

• “复制卡片”会复制独立 HTML 文档，以便在另一个响应、文件或浏览器标签页中重现卡片。

• 辅导提示会在悬停标记术语约 1.2 秒后出现；卡片还会通知主机，以便模型在用户探索时跟进。每个术语在每张卡片中只标记一次（两个术语重叠时取最长者），术语列表中的重复项会被忽略，且标记绝不会发生在代码示例、原生提示或另一个术语的提示内部。匹配区分大小写，因此为 PATH 编写的提示不会附着到文件系统的 path 上；在术语上设置 caseInsensitive: true 可匹配任意大小写。向 create_code_tour_card 传入 tutorTermsInCode: true 可选择将代码纳入。

• 每个卡片结果都携带 structuredContent.parts，格式为 { current, total, hasMore }，因此一种完整性检查适用于所有卡片类型。当 hasMore 为 true 时，内容被扣留，调用方需以 part: current + 1 再次调用同一工具。只有 create_markdown_card 和 create_code_tour_card 可以拆分；其他所有卡片始终报告 { current: 1, total: 1, hasMore: false }。渲染后的标题会为读者保留人类可读的 (part 1 of 2) 后缀。

• 拆分阈值按渲染后的字符数衡量，而非调用方书写的输入。转义会不可预测地扩展源文本——<、>、& 和引号各会变成四到六个字符——因此看起来远低于预算的负载可能超出阈值，而看起来更大的负载可能不会。请读取 parts.hasMore，而不是根据输入大小来预测。没有 H2 标题的 Markdown 文档没有拆分边界，始终作为一个部分渲染。

• 右键上下文操作由模型按卡片定义；操作提示中的 {{selection}} 会被替换为用户选中的文本。

安全

• 本地文件工具（read_local_file、unpack_archive，以及文档和代码导览卡片的路径/归档输入）只读取文本、限制大小、拒绝二进制文件，并限制归档解压（条目数、单文件大小和总字节数）。设置 MCP_CHAT_CARDS_FS_ROOT 可将所有本地读取限制在单个目录内。

• 出站请求仅限于解析到公共地址的 http(s) URL。localhost、RFC 1918、链路本地、CGNAT 及等效 IPv6 范围会被阻止，重定向会重新验证，请求体有大小上限，请求会超时。仅当您确实需要内网抓取时，才设置 MCP_CHAT_CARDS_ALLOW_PRIVATE=1。

• 所有模型和用户提供的文本都会进行 HTML 转义；抓取的第三方 HTML 会经过净化（脚本、事件处理器、框架、表单和危险 URL 会被剥离）。

• 卡片附带严格的 CSP，且不加载任何外部脚本、样式表或字体。

• submit_web_form 只应使用用户在镜像表单卡片中输入或明确确认的值来调用。

在 Claude Desktop 中调试卡片

如果卡片挂载了但保持空白，失败通常是静默的，因此模板会将所有内容记录到控制台：

1. 在 Claude Desktop 中启用开发者模式（设置，开发者），然后打开该对话的 webview 开发者工具。

2. 在控制台中过滤 [mcp-chat-cards]。卡片发送和接收的每条 JSON-RPC 消息都会连同其方向（tx/rx）一起记录，因此缺失的握手回复或未送达的工具结果会立即显现。

3. 在该控制台中运行 window.__mccDebug() 获取快照：模板版本、initialized 是否已宣告、卡片是否绘制、渲染后的卡片 HTML，以及最近 50 条协议消息。报告渲染问题时请粘贴其输出。

补充端口

extension/ 文件夹包含卡片工具面向其他主机的补充端口。两者都是自包含的——它们不从 src/ 或 dist/ 导入，MCP 服务器也不受它们影响。

• extension/github/ —— 一个名为 chat-cards 的 GitHub Copilot canvas 扩展。代理通过 canvas 操作驱动相同的卡片类型（标签页、表格、图表、表单、显示/隐藏、顺序列表、Markdown 文档、视频），表单提交会作为提示返回对话。其 README 涵盖操作列表、与 MCP 工具的差异，以及该文件夹如何映射到 awesome-copilot 贡献布局。

• extension/claude/ —— 一个 Claude artifact 模板：一个自包含的 HTML 页面，Claude 会填充其卡片规范块并将其发布为 artifact。表单和右键操作会产生提示，用户将其复制回对话中。

开发

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

许可证

MIT。参见 LICENSE。