React MCP SPA

一个极简的 React 单页应用，被打包成一个 HTML blob 并由 MCP Apps 服务器提供服务。该 SPA 不使用 URL 路径路由——它通过读取 MCP 宿主上下文中的当前工具名称来选择要渲染的页面。

布局

• packages/ui/ — React + Vite SPA，通过 vite-plugin-singlefile 构建为单文件 HTML blob。

• packages/mcp/ — 使用 @modelcontextprotocol/ext-apps/server 的 MCP 服务器。注册了指向同一个 ui:// 资源的工具（show-home、show-counter、show-profile）。

• packages/playground/ — 仅用于开发的测试工具，在模拟聊天 UI 中渲染 SPA，并为 hostContext 和 toolResult 提供 JSON 输入，以便在没有 MCP 宿主的情况下测试页面。

安装

需要 Node.js ≥ 20 和 pnpm ≥ 9。

pnpm install

独立开发 UI

pnpm run dev:ui

打开打印出的 URL（例如 http://localhost:5173）。SPA 会检测到没有 MCP 宿主，并显示一个路由选择器，以便您可以预览每个页面。

Playground — 在没有 MCP 的情况下测试渲染

pnpm run dev:playground

在 http://localhost:5174 打开。Playground 重用了 SPA 的真实路由渲染器（来自 packages/ui/src/Router.tsx 的 RouteRenderer），并将其包装在模拟聊天 UI 中。页眉有两个 JSON 文本区域——一个用于 hostContext（通过 toolInfo.tool.name 驱动页面渲染），另一个用于传递给页面的 toolResult。预设按钮会为每个已注册的工具加载现成的上下文+结果对；对任一文本区域的编辑都会实时重新渲染助手的工具输出气泡。

构建并运行 MCP 服务器

pnpm run build       # builds packages/ui → dist/index.html, then packages/mcp
pnpm run serve:mcp   # starts Streamable HTTP server on http://localhost:3001/mcp

对于 stdio 传输：

pnpm --filter @react-mcp-spa/mcp run serve:stdio

使用 cloudflared 暴露服务器

一些 MCP 客户端（包括托管客户端）无法访问 localhost。使用 cloudflared 打开一个快速隧道，分配一个公共 HTTPS URL。

通过您的操作系统包管理器安装 cloudflared：

# macOS (Homebrew)
brew install cloudflared

# Linux (Debian/Ubuntu)
# See https://pkg.cloudflare.com/ for the apt repo, or grab the .deb from
# https://github.com/cloudflare/cloudflared/releases

# Windows (winget)
winget install --id Cloudflare.cloudflared

在本地启动服务器：

pnpm run serve:mcp

在另一个终端中运行：

cloudflared tunnel --url http://localhost:3001
# or: pnpm run tunnel

cloudflared 会打印一个类似 https://<random>.trycloudflare.com 的 URL。附加 /mcp 并将其用作您的 MCP 服务器 URL：

https://<random>.trycloudflare.com/mcp

隧道会一直保持开启，直到您终止 cloudflared。如需稳定的主机名，请配置 命名 Cloudflare 隧道，而不是使用快速隧道。

打包为 Claude Desktop 扩展 (.mcpb)

该仓库提供了一个打包工具，可生成用于 Claude Desktop 的可安装 MCP Bundle。该扩展通过 stdio 运行服务器——无需隧道。

pnpm run pack:mcpb

这将构建两个包，将编译后的服务器 + UI HTML + 生产环境 node_modules 暂存到 build/mcpb-staging/ 下，并调用 mcpb pack 来生成：

build/react-mcp-spa.mcpb

要安装它，请在 Finder/资源管理器中双击 .mcpb（或将其拖到 Claude Desktop 上）。Claude 会验证清单并注册服务器；安装后，三个工具（show-home、show-counter、show-profile）即可使用，每个工具都会将其页面渲染为内联 React UI。

捆绑包清单位于 mcpb/manifest.json — 在发布新扩展版本时，请在此处（以及 packages/mcp/package.json 中）更新 version。

路由工作原理

SPA 从不读取 window.location。相反，packages/ui/src/App.tsx 使用来自 @modelcontextprotocol/ext-apps/react 的 useApp()，并执行以下操作：

1. 读取 app.getHostContext().toolInfo.tool.name 以了解宿主调用了哪个工具——这就是“路由”。

2. 订阅 app.ontoolresult 以从服务器接收 CallToolResult 并将其作为数据传递给页面。

3. 监视 app.onhostcontextchanged，以便主题/安全区域/区域设置更新能正确重新渲染。

添加新页面只需两步更改：

1. 在 packages/mcp/src/server.ts 中注册一个工具，并将 _meta.ui.resourceUri 指向共享的 ui://react-mcp-spa/app.html 资源。

2. 在 packages/ui/src/App.tsx 中的 renderRoute() 内为该工具名称添加一个 case。