sugarforever/dsh-mcp-apps

DeepSeek Harness MCP Apps

@sugarforever/dsh-mcp-apps 是一个双面 Cordis 插件，它使 DeepSeek Harness 成为 MCP Apps 宿主。

Host 部分连接到一个 MCP Server，将其对模型可见的工具注册到 ctx.tools 上，并负责所有 MCP 网络或 stdio 流量。Web Client 部分将带有 _meta.ui.resourceUri 的工具渲染为 Harness 对话中的沙箱化交互式 App。

支持的功能

- MCP Apps 扩展协商：io.modelcontextprotocol/ui
- text/html;profile=mcp-app UI 资源
- 现代 _meta.ui.resourceUri 和旧版 _meta["ui/resourceUri"]
- stdio 和 Streamable HTTP MCP 传输
- 对模型可见、对 App 可见以及仅 App 可用的工具
- 向 View 传递原始 CallToolResult，包括 structuredContent
- View 到 Server 的 tools/call、resources/list 和 resources/read
- 资源 CSP 元数据和 iframe Permission Policy 请求
- 针对工具、连接、RPC 路由、Slot 和 App 桥接的 Cordis 生命周期释放

普通 MCP 工具仍然是普通的 Harness 工具。MCP Server 不需要为每个工具都提供 UI。

安装 DeepSeek Harness

DeepSeek Harness 目前需要 Node.js ^22.19.0 或 >=24.0.0。其 profile 插件管理器还会调用 pnpm；请安装当前 DSH 版本所使用的版本：

npm install --global pnpm@11.7.0

然后无需全局安装 DSH 即可启动 Web profile：

npx @deepseek-ai/dsh web

Web UI 默认在  提供服务。首次运行会在 ~/.dsh/profiles/web 下初始化 web profile（当设置了 DSH_HOME 时则为 $DSH_HOME/profiles/web）。

安装插件

将已发布的包安装到 DSH Web profile 中：

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

对于本地开发，改为安装此检出目录：

npx @deepseek-ai/dsh plugin --profile web add /absolute/path/to/dsh-mcp-apps

你也可以安装从 GitHub Release 下载的 tarball：

npx @deepseek-ai/dsh plugin --profile web add ./sugarforever-dsh-mcp-apps-0.1.2.tgz

该包是一个 DSH bundle。安装它还会应用其捆绑的 cordis.patch.yml，默认将公共 VibeFun MCP Apps 服务器挂载到 https://vibefun.app/api/mcp。

要连接其他服务器，请编辑已安装 profile 中的补丁文件 ~/.dsh/profiles/web/cordis.patch.yml，并替换生成的实例配置。相关条目为：

- insert:
- id: mcp-apps-vibefun
name: '@sugarforever/dsh-mcp-apps'
config:
serverName: vibefun
transport: streamable-http
url: https://vibefun.app/api/mcp
failOnStartupError: true

启动或重启 DSH 并打开 ：

npx @deepseek-ai/dsh web

要移除包依赖：

npx @deepseek-ai/dsh plugin --profile web remove @sugarforever/dsh-mcp-apps

插件管理器还会移除该包所贡献的 bundle 补丁。
配置 stdio 服务器

创建 mcp-apps.cordis.yml：

- insert:
- id: mcp-apps-vibefun
name: '@sugarforever/dsh-mcp-apps'
config:
serverName: vibefun
transport: stdio
command: node
args: ['/absolute/path/to/your-mcp-server.js']
env:
VIBEFUN_API_KEY: !!js process.env.VIBEFUN_API_KEY
failOnStartupError: true

使用覆盖层运行 Harness Web 配置文件：

dsh web --patch "$PWD/mcp-apps.cordis.yml"

配置 Streamable HTTP 服务器

- insert:
- id: mcp-apps-vibefun
name: '@sugarforever/dsh-mcp-apps'
config:
serverName: vibefun
transport: streamable-http
url: http://127.0.0.1:3000/mcp
headers:
Authorization: !!js 'Bearer ${process.env.VIBEFUN_MCP_TOKEN}'
failOnStartupError: true

浏览器永远不会接收到 URL、命令、请求头、环境变量或凭据。其包级私有的 RPC 通道仅限回环地址。

开发

npm install
npm test
npm run typecheck
npm run build

集成测试会启动一个真实的 stdio MCP Apps 服务器，并验证发现、工具执行、结构化输出、资源读取和拆卸。

发布

该仓库包含 .github/workflows/publish.yml。发布 GitHub Release 会运行完整的发布门禁，创建 npm tarball，将其作为工作流产物和 GitHub Release 资产上传，并将同一个 tarball 发布到 npm。重新运行是安全的：当该确切的 npm 版本已存在时，工作流会跳过不可变的 npm 发布，并且仍会完成 GitHub 产物。

该工作流使用 npm Trusted Publishing 与 GitHub OIDC，因此不需要 NPM_TOKEN 密钥。

一次性 npm 设置

1. 如果 @sugarforever/dsh-mcp-apps 在 npm 上尚不存在，请在本地发布第一个版本：

npm login
npm ci
npm test
npm run typecheck
npm run build
npm pack --dry-run
npm publish --access public

2. 在 npmjs.com 上，打开该包的 Settings → Trusted Publisher，选择 GitHub Actions，并配置：

- 组织或用户：sugarforever
- 仓库：dsh-mcp-apps
- 工作流文件名：publish.yml
- 允许的操作：npm publish

3. 除非工作流也更新为使用该确切的 GitHub 环境，否则不要添加环境名称。

发布新版本

更新并提交包版本，然后推送匹配的标签：

npm version patch
git push origin main --follow-tags

为该标签创建并发布 GitHub Release。例如，包版本 0.1.1 必须使用标签 v0.1.1。发布 Release 会触发工作流；标签不匹配会在 npm 发布之前失败。

在创建 Release 之前，可以在本地运行相同的检查：

npm ci
npm test
npm run typecheck
npm run build
npm pack --dry-run

架构

Model ── native Harness tool ── Host MCP Client ── MCP Server
│                    │
│ loopback RPC       │ ui:// resource
▼                    │
Harness Web 工具卡片 ── AppBridge ── 沙箱化 iframe View

参见 docs/architecture.md 和 docs/security.md。

当前限制

- 一个插件实例拥有一个 MCP Server。挂载多个实例以对应多个 Server。
- UI 工具发现发生在 Client 插件激活时。Server 更改其 UI 工具列表需要 Client 刷新或插件重新加载。
- Prompts、sampling、downloads、external-link opening 和 model-context updates 尚未向 Apps 暴露。
- App HTML 通过 srcdoc 加载；Apps 应提供自包含的 HTML，或在资源 CSP 元数据中声明每一个远程源。
- 当前 iframe 路径面向 Web 客户端。Headless 和 ACP 入口点仍会接收这些工具，但没有内嵌的 App 界面。

协议参考

- MCP Apps 概述
- 官方 MCP Apps SDK
- DeepSeek Harness

许可证

MIT