MCP 应用宿主 katticot/dsh-mcp-apps

dsh-mcp-apps

npm
Downloads
TypeScript
React
Cordis
Tests
License: MIT

在 DeepSeek Harness (DSH) 网页聊天中，将 MCP Apps 渲染为沙箱化的交互式 iframe。

这是什么？

MCP 服务器可以返回的不仅仅是文本：MCP Apps 扩展（SEP-1865）允许工具结果携带一个 ui:// 资源——一个小巧、自包含的 Web 应用，例如仪表盘、地图或表单。默认情况下，DSH 不知道如何处理这些内容，只会显示原始的工具结果。dsh-mcp-apps 是一个用于 DSH 的 Cordis 4 插件，它能识别这些 ui:// 资源，并将其作为实时、可交互的应用直接渲染在聊天轮次中，置于沙箱化的 iframe 内。该应用还可以回调宿主以运行更多工具（例如“刷新”按钮），此功能受每个服务器显式审批策略的控制。

功能特性

- 在 DSH 聊天中直接将 MCP Apps（ui:// 资源）渲染为交互式仪表盘、图表、地图和表单。
- 每个应用都在带有自动生成的内容安全策略（Content Security Policy）的 iframe 中沙箱化运行——没有 allow-same-origin，也无法随意访问宿主页面。
- 可通过 stdio、SSE 或 Streamable HTTP 连接到任何 MCP 服务器，并支持自动重连。
- 应用可以回调宿主工具（例如“刷新数据”按钮），默认关闭，并可按服务器配置（deny / approve / allow）。
- 渲染出的应用带有 Interactive App 徽章，并会抵抗 DSH 的自动折叠行为，因此当模型完成流式输出时它们不会折叠消失。
- 安全地处理机密信息：针对环境变量和 headers 块的 ${VAR} 展开会阻止 DSH 内部及机密形态的变量名，除非你明确允许它们。

要求

- Node.js >= 22
- DSH (DeepSeek Harness)
- web 配置文件。插件的客户端 bundle 仅在 dsh.client.platform 为 web 时注入（参见 package.json），因此即使插件安装在其他配置文件中（例如 tui、headless），其 UI 也不会渲染。

安装

markdown
npx @deepseek-ai/dsh plugin --profile web add dsh-mcp-apps

这会在你的 DSH profile 目录（$DSH_HOME/profiles/web）内转发给 pnpm，而不是你当前的项目——它会把 dsh-mcp-apps 添加到该 profile 自己的 package.json 中。不要在一个无关的项目里直接运行 pnpm add dsh-mcp-apps 并指望它对 DSH 起任何作用。

仅安装并不会激活插件——你仍然需要把它添加到你的 profile 配置中（下一节），这样加载器才会拾取它。

配置

将插件添加到你的 profile 补丁文件，例如 ~/.dsh/profiles/web/cordis.patch.yml。该文件是一个顶层 YAML 数组，包含加载器补丁条目；要添加一个新插件（而不是按 id 覆盖已有插件），请将其包裹在 insert: 列表中： yaml
- insert:
- id: mcp-apps
name: 'dsh-mcp-apps'
config:
servers:
一个使用 Streamable HTTP 或 SSE 的远程服务器 my-server: transport: streamable-http url: 'https://your-mcp-server.example.com/mcp'

一个受 OAuth 保护的远程服务器，通过 mcp-remote 代理 my-oauth-server: transport: stdio command: npx
args: [-y, mcp-remote@0.1.37, 'https://your-mcp-server.example.com/mcp']

一个裸的顶层条目（没有 insert:）会被视为对已有 id 的补丁，如果该 id 尚不存在，则会以 entry "" not found 失败——它不会创建新的插件条目。

一个更完整的示例，展示了环境变量展开、请求头和反向工具调用： yaml
- insert:
- id: mcp-apps
name: 'dsh-mcp-apps'
config:
defaultTimeoutMs: 30000
servers:
本地 stdio 子进程（env 值支持 ${VAR} / ${VAR:-default} 展开） local-tool: transport: stdio command: go
args: ['run', 'main.go']
cwd: '/path/to/mcp-server'
env:
DATABASE_URL: '${DATABASE_URL}'
toolCallTimeoutMs: 45000
allowAppToolCalls: approve

带认证请求头的远程 SSE 服务器 remote-analytics: transport: sse url: 'https://mcp.example.com/sse' headers: Authorization: 'Bearer ${MCP_TOKEN}'
allowedVars: [MCP_TOKEN] # 除非列出，否则形似密钥的变量会被阻止
reconnectOptions:
maxRetries: 10

运行并验证 bash
npx @deepseek-ai/dsh web

在已配置的服务器上调用一个返回 ui:// 资源的工具。如果一切连接正常，工具结果会在聊天回合中渲染为一个实时应用，并带有 Interactive App 徽章，而不是原始的 JSON/文本。

反向工具调用安全模型

渲染后的应用可以回调宿主工具（例如一个“Refresh Data”按钮）。该路径默认是锁定的：
- 会话令牌：来自应用的每个 tools/call 请求都必须携带有效的 AppSessionStore 会话令牌，且该令牌的作用域限定为其签发时所针对的工具名称和服务器。缺失、已过期或服务器不匹配的令牌会在工具运行之前就被拒绝（src/index.ts）。
- allowAppToolCalls（按服务器配置，默认 false/'deny'）：一个 'deny' | 'approve' | 'allow' 设置（也接受普通 boolean 作为 false/'allow' 的旧式简写）。
- 'deny'（默认）：该服务器的应用发起的反向调用不会暴露任何工具。
- 'allow' / true：允许反向调用，无需审批。
- 'approve'：每个反向调用都会经由 ctx.approval（@deepseek-ai/dsh-user-approval）路由，并要求发起调用的 agent 有一个打开的轮次（agent.status === 'running'）；在该窗口之外，或者审批/agent 服务不可用时，调用会以 unavailable 失败，而不是静默允许或挂起。
- 仅应用 / 仅模型可见性：标记为仅应用可见（isToolVisibilityAppOnly）的工具永远不会注册到 LLM 的工具列表中，而标记为仅模型可见（isToolVisibilityModelOnly）的工具会被排除在应用允许回调的集合之外——每个方向都是单向门控。

配置参考

| 选项 | 类型 | 默认值 | 描述 |
| servers | Record | {} | 服务器标识符到传输配置的映射。名称不能包含 __ 或以 _ 结尾。 |
| defaultTimeoutMs | number | 30000 | 工具调用的回退超时时间（毫秒）（必须 >= 1）。 |
| servers..transport | 'stdio' \| 'sse' \| 'streamable-http' | （必填） | 传输机制。仅支持 MCP 规范定义的传输方式：stdio、streamable-http 和 sse（上游已弃用，为较旧的服务器保留）。 |
| servers..command | string | — | 可执行二进制文件路径（用于 stdio）。 |
| servers..args | string[] | [] | 命令参数（用于 stdio）。 |
| servers..cwd | string | — | 工作目录（用于 stdio）。 |
| servers..env | Record | {} | 环境变量，支持 ${VAR} / ${VAR:-default} 展开（用于 stdio）。 |
| servers..url | string | — | 远程端点 URL（用于 sse、streamable-http）；必须匹配 http(s)://。纯 http:// 仅允许连接到回环主机（localhost、127.0.0.1、::1）——其他任何情况都会在连接时被拒绝。 |
| servers..headers | Record | {} | 自定义 HTTP 头，支持与 env 相同的 ${VAR} 展开（用于 sse、streamable-http）。 |
| servers..toolCallTimeoutMs | number | 30000 | 每个服务器的工具调用超时时间（毫秒）（必须 >= 1）。 |
| servers..reconnectOptions | { maxRetries?, initialDelayMs?, maxDelayMs?, backoffFactor? } | {5, 1000, 30000, 1.5} | 指数退避重连调优，应用于 stdio 和远程（sse、streamable-http）传输。 |
| servers..allowAppToolCalls | 'deny' \| 'approve' \| 'allow' \| boolean | false ('deny') | 反向工具调用策略——参见反向工具调用安全模型。 |
| servers..allowedPermissions | string[] | [] | 针对资源 UI 元数据所请求的 camera、microphone 和 geolocation iframe 权限的允许列表；除非在此处显式列出，否则这三项均被拒绝。其他权限键会未经筛选地传入 iframe 的 allow 属性。 |
| servers..allowedVars | string[] | [] | 该服务器可通过 ${VAR} 展开（在 env 或 headers 中）读取的环境变量名，尽管这些变量以 DSH_ 为前缀、形似机密（KEY/PASSWORD/SECRET/TOKEN），或是 agent socket（SSH_AUTH_SOCK、GPG_AGENT_INFO）——这些默认均被阻止。例如 allowedVars: ['API_TOKEN'] 可让 headers: { Authorization: 'Bearer ${API_TOKEN}' } 解析成功（适用于 stdio、sse、streamable-http）。 |
| servers..maxMessageBytes | number | 16777216 (16MB) | 来自远程服务器的单条传入消息的最大字节数（适用于 sse、streamable-http；必须 >= 1）。这通过一个围绕 fetch 的字节计数包装器限制每个单独的 SSE 事件（而非整个流的生命周期）。用于防止恶意或行为异常的远程服务器耗尽主机内存。 |

${VAR} / ${VAR:-default} 展开仅适用于 env 和 headers 的值——不适用于 url、args 或 cwd。$$ 是转义后的字面量 $。默认值本身不能包含嵌套的 ${...} 展开（例如 ${MISSING:-${PORT}} 会被按字面量处理，而不会递归展开）。

故障排查

- 工具出现两次：在同一个 MCP 服务器上同时运行 @deepseek-ai/dsh-mcp-client 和此插件，会通过两个插件注册该服务器的工具，导致重复。对于给定的服务器，请只使用其中之一。
- ${VAR} 未展开：以 DSH_ 为前缀以及形似机密（KEY/PASSWORD/SECRET/TOKEN）的变量名，加上 SSH_AUTH_SOCK/GPG_AGENT_INFO，默认均被阻止——请将该名称添加到该服务器的 allowedVars 中。
- 应用的按钮无任何反应：allowAppToolCalls 默认为 deny。请将其设置为 approve 或 allow。在 approve 模式下，该调用还需要一个已打开且正在运行的 agent 轮次来提示批准——在该窗口之外会以 unavailable 失败。
- 远程连接被拒绝：纯 http:// 仅允许连接到回环主机（localhost、127.0.0.1、::1）；其他任何地址都必须使用 https://。
- 什么都不渲染：客户端 UI 仅在 web 配置文件（dsh.client.platform: "web"）下加载。它不会在 tui、headless 或其他配置文件中渲染。
- 插件似乎没有加载：检查你的 patch 条目是否使用了 insert: 形式（参见配置）——一个裸的顶层 - id: 条目是对现有 id 的 patch，会报错而不是注册新插件。运行 npx @deepseek-ai/dsh --profile web --patch --dump-config 来打印组合后的配置，并确认你的条目出现了。

工作原理

该插件通过基于 postMessage 的 JSON-RPC 在沙箱化 iframe 和 DSH 宿主之间架起桥梁，管理一个 MCP 服务器连接池，并为 LLM 规范化工具名称/可见性。关于完整的内部机制——CSP 合成、postMessage 握手、工具指纹识别、防折叠行为以及 resize 断路器——请参见 docs/how-it-works.md。

开发与测试

Install dependencies
pnpm install

Type-check
pnpm typecheck

Build host and client bundles (tsdown)
pnpm build

Run Vitest test suite
pnpm test

./client（由 DSH 的 window.__ModuleLoader__ 加载的浏览器端 bundle）仅用于 loader：它在 package.json#exports 中没有 types 条目，无法直接从 Node 或打包工具导入——只有 .（宿主）条目会附带类型声明。

许可证

MIT © katticot