MCP 应用渲染器 openma-ai/dsh-mcp-apps

dsh-mcp-apps

为 DeepSeek Harness (DSH) 提供 MCP Apps 支持，以普通 Cordis 插件的形式打包。

该项目刻意将协议宿主与每个呈现界面保持分离。安装该捆绑包会添加两个独立的行：一个共享现有 MCP 连接的 Host 服务，以及一个在双重 iframe 沙箱后运行 App HTML 的 Web 渲染器。一个 AppBridge 会话可以在内联、全屏和画中画界面之间移动，而无需重新挂载其 iframe。

我应该安装哪个包？

| 目标 | 安装 |
| 在 DSH 中使用 Codex、Claude Code、Pi 或可移植的 Agent Plugins，包括它们的 MCP Apps | 仅 @openma/dsh-agents-plugins-bridge；它已自带 MCP Apps |
| 在没有外部插件桥接的情况下向 Web 配置文件添加 MCP Apps | @openma/dsh-mcp-apps |

独立包和 Bridge 使用相同的 Host 和 Web 运行时包。不要仅仅为了获得两次渲染器而将两个捆绑包都安装到同一个配置文件中。

安装

dsh plugin --profile web add @openma/dsh-mcp-apps

从本地检出安装依赖并仅添加根捆绑包：

npm install
dsh plugin --profile web add .

完整捆绑包在已提供 ctx.mcpApps 和生成的 remote.mcpApps 命名空间的 DSH 组合上是安全的：回退 Host 行会变为空操作，而 Web 渲染器会复用现有的 Remote。如果已知活动配置文件已包含官方 Host，则仅安装渲染器是最小等效方案：

dsh plugin --profile web add ./packages/web

渲染器在存在组合提供的 Remote 时会使用它，并且仅在独立回退 Host 时挂载其已检入的描述符。

捆绑包补丁挂载一个内核：

- id: mcp-apps-bundle
name: '@openma/dsh-mcp-apps'

该内核拥有两个独立的子行：mcp-apps-host 和 mcp-apps-web。两行都指向包自有的包装器导出。每个包装器从该包的依赖图中解析其运行时，通过 DSH Loader 导入它，并使用 ctx.plugin 挂载它；不需要配置文件级别的依赖提升。Agent Plugins Bridge 从其自己的根包中使用相同的包装器形态。

将 MCP 服务器连接保留为其自己的插件行。DSH 的 mcp-client 会注意到可选的 ctx.mcpApps 服务，并自动贡献其活动连接：

- name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: weather
transport: stdio
command: weather-mcp-server

因此，工具、资源、提示、面向模型的执行以及 AppBridge 调用都复用同一个 MCP SDK Client，包括其身份验证和重连代次。本项目不会打开第二个连接。

包

| 包 | 角色 |
| @openma/dsh-mcp-apps | 可安装且可嵌套的捆绑包内核；拥有 Host/Web 子行生命周期 |
| @openma/dsh-mcp-apps-host | 内部运行时包：ctx.mcpApps 提供者注册表以及生成的 Typert Host/Remote 契约 |
| @openma/dsh-mcp-apps-web | 内部运行时包：形状驱动的 Tool 结果渲染器、官方 AppBridge 以及浏览器沙箱 |

流程如下：

dsh mcp-client
└─ provider → @openma/dsh-mcp-apps-host
└─ Typert Remote → @openma/dsh-mcp-apps-web
└─ AppBridge → sandboxed MCP App

只有 callTool 和 readResource 会跨越浏览器 Remote 边界。readResource 仅接受 ui:// URI。Host 插件也可以在进程内调用 listResources、listPrompts 和 getPrompt；此包不会将这些结果注入模型上下文。

Web 渲染器仅认领同时满足以下所有条件的已敲定结果：

- 呈现卡片 mcp-app；
- ui:// 资源 URI；
- 精确 MIME 类型 text/html;profile=mcp-app；
- 符合 schema 的 MCP Tool 结果。

其他所有结果都会拒绝 tool.call.takeover 链，从而保留正常的键控 Tool 视图和通用回退。

浏览器安全边界

不受信任的 App HTML 绝不会在 DSH 文档中运行。它会被加载到不透明源中继文档背后的不透明源内部数据文档中。渲染器会：

- 在 App 代码之前安装 CSP，仅接受经过验证的 HTTP(S)/WS(S) 域来源；
- 对每条中继消息检查确切的父/子窗口和预期来源；
- 保留内部沙箱消息，并使用按文档区分的代际标记；
- 一旦内部文档发生导航，立即关闭 Host 到 App 的转发；
- 仅允许在新标签页中外部导航到 HTTP(S) URL；
- 将内联高度请求限制在 96–720 px；
- 在内联、协议 fullscreen 模式的右侧面板以及有界画中画之间移动同一个实时 iframe 包装器，而不是重新创建 App 状态；
- 仅针对 App 通过 appCapabilities.availableDisplayModes 声明的显示模式，显示不显眼的左下角 Host 控件。

该实现使用官方 @modelcontextprotocol/ext-apps 的 AppBridge 和 PostMessageTransport。

其他客户端

Host 包与 UI 无关。完整的 HTML/AppBridge 路径目前仅由 Web 包实现。TUI 可以独立安装 Host 并提供自己的渲染器（例如文本回退或“在浏览器中打开”操作）；终端客户端不应内联执行任意 App HTML。

@openma/dsh-agents-plugins-bridge
直接使用此边界：其 Web 配置文件获得沙箱化渲染器，而其 TUI 配置文件保留共享的 MCP 工具、资源、提示和后端生命周期，而不尝试在终端中绘制 App HTML。

相关项目

- DeepSeek Harness — Host、 Loader、MCP 客户端和 Web 插件平台。
- Agent Plugins Bridge —一个包，兼容 Codex、Claude Code、Pi 和 Agent Plugins 的兼容层。
- DeepSeek Harness TUI —用于相同 Host 端工具和命令的终端客户端。
- DeepSeek Harness ACP —向 ACP 客户端暴露 Host 能力。

开发

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

npm install
npm run build
npm test
npm run typecheck
npm run test:browser

test:browser 会启动 Playwright Chromium（在 macOS 上则为本地 Google Chrome），以验证双 iframe 的 origin 和导航边界。

examples/display-modes 是一个真实的 stdio MCP 服务器，使用官方 MCP Apps 服务器辅助工具和 App 客户端构建。其 display_modes 工具会打开 ui://dsh/display-modes；递增计数器并在全部三个界面之间切换，以验证 App 会话保持活跃：

npm run build:example:display-modes
node examples/display-modes/server.mjs

兼容性

Web 渲染器面向当前 DSH Web 构建中存在的 tool.call.takeover 链。当与 DSH 0.1.0-rc.7 组合使用时，其优先级 -110 让这个三模式渲染器能够在优先级为 -100 的内置仅内联渲染器之前接管 MCP App 结果。其他工具结果则继续沿普通接管链向下传递。

下载、App 到聊天的消息以及采样尚未启用。

许可证

MIT