MCP 卡片宿主 oriliz/dsh-mcp-apps-host

DSH MCP Apps Host

DeepSeek Harness 的 MCP Apps Host 插件。连接声明了 io.modelcontextprotocol/ui 扩展的 MCP 服务器，在工具结果中保留 _meta.ui，在沙箱 iframe 中渲染交互式 HTML 卡片，并在卡片与 MCP 服务器之间桥接 postMessage。

功能

- 工具发现并保留 _meta —— 注册 MCP 工具时完整保留 _meta.ui 载荷
- 交互式 HTML 卡片 —— 沙箱 iframe 渲染，每张卡片独立 CSP
- postMessage 桥接 —— ui/initialize、tools/call、resources/read、ui/update-model-context、ui/message
- 结果重放通知 —— ui/initialize 回复之后，宿主按 FIFO 顺序发送 ui/notifications/tool-input 和 ui/notifications/tool-result；新规范卡片忽略 lastToolResult，只订阅这些通知，因此晚挂载的卡片（重放 / 注入会话）仍能恢复工具结果
- 注入会话 ID —— 自动向卡片发起的 tools/call 注入 session_id
- 隐形上下文注入 —— ui/update-model-context 上下文通过 agent.inject() 以插件来源消息注入，归类为折叠的上下文行（不是可见的用户消息气泡）
- HTTP 桥接端点 —— /mcp-apps/<serverName>/bridge，用于安全代理 iframe 到 MCP 服务器（为直接 fetch 的沙箱卡片启用 CORS）
- 桥接调试日志 —— GET /mcp-apps/<serverName>/debug 返回最近 64 次桥接交互；桥接调用绕过智能体管线，永远不会进入会话 JSONL，因此该端点是观察卡片发起 tools/call 的唯一途径
- 多实例安全 —— 每个插件实例注册自己的按服务器桥接路由，因此一个 DSH 配置档中可以共存多个 MCP Apps 服务器
- stdio + streamable-http —— 同时支持两种 MCP 传输类型

演示

工具结果携带内嵌卡片时，在对话中的样子：

MCP Apps 演示卡片

截图展示了内置演示服务器的两张卡片（demo/server.mjs —— 零依赖，仅 Node stdio）：

- demo_interactive（内联形式）：工具结果携带 _meta.ui.resource.text，卡片 HTML 随结果一起传输。它的按钮演练完整桥接往返：一次 tools/call 刷新卡片（宿主自动注入 session_id），以及 ui/update-model-context + ui/message 回话给模型。
- demo_referenced（引用形式）：工具定义携带 _meta.ui.resourceUri（ui://demo/referenced-card）；宿主通过 resources/read 解析一次 HTML 并内联。卡片还演示了桥接的 ui:// 安全门 —— 读取 file:///etc/passwd 会被拒绝。

试试看：

Protocol-level self-check: spawns the demo server over stdio and asserts
the handshake, both card forms, session_id echo, and the ui:// resource
table（8 项检查，不需要 DSH）。
node demo/selftest.mjs

完整 E2E：启动 dsh web 并加载 demo overlay，然后让模型调用 demo_interactive 和 demo_referenced。请从本仓库的父目录运行（overlay 的 server 路径相对于 cwd）；或者把 overlay 里的 !!js 路径改成你的目录结构。
dsh web --patch dsh-mcp-apps-host/demo/mcp-apps-demo.cordis.yml

安装

还没上 npm —— 从 GitHub 安装。DSH 宿主在运行时提供所有 @deepseek-ai/dsh- peer 包，所以不需要单独安装 peer：

npm install github:oriliz/dsh-mcp-apps-host

从源码构建

所有 dsh peer 包都在 deepseek-harness pnpm workspace 里解析，所以要在那里构建（这样也跟打包好的 lib/ 的构建目录结构一致）：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
git clone https://github.com/oriliz/dsh-mcp-apps-host.git packages/mcp/mcp-apps-host
pnpm install
npx tsc -b packages/mcp/mcp-apps-host
pnpm --filter @deepseek-ai/dsh-mcp-apps-host bundle

用法

1. 配置连接

在 overlay 里为每个 MCP Apps 服务器声明一个插件实例（serverName 同时决定工具前缀 mcp__<serverName>__ 和桥接路径 /mcp-apps/<serverName>/bridge）。examples/connect-server.patch.yml 里有一份可以直接改的模板：

- insert:
- id: mcp-apps-host-my-server
name: '@deepseek-ai/dsh-mcp-apps-host'
config:
transport: stdio
serverName: my-server
command: my-apps-server
args: []
env: {}
cwd: ''
toolCallTimeoutMs: 60000

也支持 transport: streamable-http 加 url 字段。

2. 启动 DSH

dsh --profile web --patch ./examples/connect-server.patch.yml

3. 验证

让智能体调用你服务器上的某个工具。工具结果会在对话里渲染成一张可交互卡片，而不是普通的结果行 —— 卡片上的按钮会通过桥接回到你的服务器（tools/call、resources/read、ui/message）。手头没有服务器？先用自带的 demo。

架构

Architecture

工具结果从左到右流动（服务器 → 工具注册表 → 对话 → 卡片），卡片交互则通过 HTTP 桥接回到服务器。卡片 HTML 永远不会进入模型上下文，桥接也只允许 iframe 调用该服务器上注册的工具、读取 ui:// 资源。

文件

| 文件 | 作用 |
| src/index.ts | 服务端：MCP 连接、工具注册、HTTP 桥接 |
| src/client/McpAppCard.tsx | 卡片组件：iframe、postMessage 处理 |
| src/client/index.ts | 客户端插件：slot 注册、sendUserMessage |
| src/invariant.ts | Cordis 配套文件（无运行时 invariant） |
| demo/ | 零依赖 demo 服务器 + 协议自测 + overlay |
| examples/ | 连接浮层模板 |

开发

Build
npx tsc -b packages/mcp/mcp-apps-host/tsconfig.json
pnpm --filter @deepseek-ai/dsh-mcp-apps-host bundle

Run DSH with the plugin
dsh --profile web --patch ./examples/connect-server.patch.yml --port 8089

已修复的坑

| # | 问题 | 修复 |
| P0 | 服务端会剥掉 _meta.ui | 在客户端能力里声明 mimeTypes |
| P1 | 卡片能渲染，但不显示工具数据 | presentationMeta() 把结果包装成 CallToolResult 形状的对象 |
| P2 | session_id 注入失败 | readSessionId() 优先读 meta.lastToolResult.structuredContent |
| P3 | 外部图片被 CSP 拦截 | buildCsp() 在默认 img-src 里加上 https: |
| P4 | ui/update-model-context 还是 TODO | 用 _stagedContext Map 存下上下文并前置插入 |
| P5 | 上下文会显示成用户消息文本 | ui/inject-context 桥接层通过 agent.inject() 注入，作为插件来源的消息 |

详细根因分析见 FINDINGS.md。

License

MIT