托管 MCP 应用示例画廊

一个独立托管、请求受限的六个官方 MCP Apps 示例的改编版本。该画廊旨在让用户复制远程 Streamable HTTP URL，将其连接到 MCP Apps 主机，并尝试完整的交互式工具/资源流程，而无需克隆源代码或打开隧道。

此仓库和服务是独立的学习基础设施。它们不是官方的 Model Context Protocol 项目或服务，没有服务等级协议（SLA），也不接受账户、上传、凭据或持久用户数据。

尝试托管画廊

已验证的生产画廊位于 openwork-mcp-app-gallery-sol.vercel.app。将以下任意一个 Streamable HTTP URL 添加到兼容 MCP Apps 的主机：

在支持 MCP 工具但不支持 MCP Apps 的主机中，相同的端点仍然返回普通文本和结构化工具结果；仅省略嵌入的交互式资源。每个 URL 仅暴露一个应用，因此当需要多个示例时，连接多个 URL。复制的端点无需账户、令牌或自定义标头。

该服务故意没有 SLA。输入是受限且合成的。Transcript 应用将麦克风音频保留在浏览器中，不会上传到此服务器。在共享或自动化环境中使用画廊之前，请参阅 限制和故障行为 和 诊断与安全可观测性。

画廊目录

每个路径都是一个独立的 MCP 服务器表面，恰好包含一个画廊工具和一个不可变的 ui:// 资源。故意没有根级 mega-MCP 和跨应用工具或资源访问。

协议和主机契约

运行时使用 mcp-handler 2.1.1 和 @modelcontextprotocol/server 2.0.0，通过画廊拥有的 SDK-v2 注册适配器。它支持：

• 当前 MCP 2026-07-28 发现和请求信封；

• 无状态 2025 时代 Streamable HTTP 回退；

• initialize、tools/list、tools/call 和 resources/read；

• 带有嵌套和传统扁平 UI 元数据的 text/html;profile=mcp-app 资源；

• 针对非 App 主机的普通文本内容和结构化内容；

• App 初始化、初始输入/结果交付以及 UI 触发的同服务器工具调用；

• 从 Vercel 通过网关、处理器、工具和资源工作传播的请求取消。

该服务是无状态的。POST 携带 MCP 请求。GET 被路由到处理器并返回其故意的无会话 405；DELETE 返回 405；受限的 OPTIONS 仅对允许列表中的浏览器来源可用。这符合双时代处理器的无状态传输契约，并避免暗示存在服务器端会话。

运行时架构

一个 Vercel 识别的 Hono 入口点 app.ts 通过一个无状态函数提供着陆页、诊断和六个参数化的 MCP 路径。Vercel 通过其 CDN 从 public/ 提供生成的公共资产。

构建过程故意封闭在已检入的源代码和冻结的锁定文件中：

1. scripts/generate-upstream-manifest.ts 记录冻结的源代码和画廊拥有的改编。

2. scripts/bundle-mcp-app-resources.ts 构建确定性的单文件 HTML 资源，并在超过 512 KiB 时失败。

3. scripts/generate-gallery.ts 生成着陆页清单和内容哈希的静态资产。

4. scripts/generate-sbom.ts 生成已提交的 CycloneDX 清单。

5. src/resources.ts 在就绪成功之前验证确切的源出处、资源身份、字节大小和 SHA-256。

没有运行时源获取、包安装、子进程、任意 URL 输入、上传、预期的服务器端出口或可变文件系统路径。

限制和故障行为

• 请求体：每个 MCP 请求 256 KiB。

• 工具结果和 App 资源：每个 512 KiB。

• 应用截止时间：15 秒。

• Vercel 函数上限：30 秒，启用取消功能。

• 并发：每个进程 48，每个应用有更小的声明上限。

并发门控仅是实例级别的保护；它不代表跨 Fluid 实例的全局权威分布式速率限制器。超限请求返回 429 加上 Retry-After；超大请求返回 413；超大的下游结果返回 502；截止时间返回 504；客户端取消在内部被区分。公共响应包含受限错误，从不包含堆栈跟踪或文件系统路径。

将 DISABLED_APP_SLUGS 设置为六个 slug 的逗号分隔子集，作为运行时终止开关。禁用的应用从生成的实时目录中消失并返回 404；/readyz、/version 和 /apps.json 报告启用的集合。apps.json 使用较短的 public, max-age=60, must-revalidate 策略，因此禁用的应用更改不能隐藏在长期不可变缓存之后。

诊断与安全可观测性

• /healthz 仅证明函数响应。

• /readyz 验证注册表、启用的 slug、捆绑资源计数、大小和摘要。

• /version 仅在配置时返回构建 SHA、冻结的上游提交、模型命名空间、适配器版本、Node 版本、启用的 slug 和安全构建时间。

MCP 请求日志是结构化的，仅限于 sol 命名空间、应用 slug、方法类别、状态、持续时间、字节计数和安全构建 SHA。禁止记录参数、结果、提示、资源内容、授权标头、cookie、IP 地址、用户标识符、凭据和私有部署 URL。

本地开发

使用 Node.js 24.x 和 pnpm 10.28.0：

pnpm install --frozen-lockfile
pnpm generate
pnpm dev

打开 http://127.0.0.1:4173。对于本地或隧道化的规范来源，设置一个明确验证的 BASE_URL。在环回开发之外，公共基础 URL 必须使用 HTTPS，并且不能包含凭据、查询字符串或片段。任意 Host 和转发主机标头永远不会被信任用于可复制端点。

完整的仓库拥有的验证路径是：

pnpm exec playwright install chromium
pnpm run release:check:ci

该路径运行格式化、lint、严格 TypeScript、网关和双时代契约测试、真实浏览器 MCP App 桥接测试、通知/出处检查、Vercel 架构检查、生产依赖审计、源代码边界和秘密扫描、SBOM 生成以及生产形状的应用构建。pnpm run release:check 在链接了确切的 Vercel 项目时添加 vercel build --prod --yes。

验证设计

契约矩阵使用官方 SDK-v2 客户端，在固定的当前和传统模式下针对所有六个端点。它列出工具、调用每个代表性工具、读取每个 App 资源、验证普通回退、拒绝外来资源、检查无效输入、重复连接周期，并在隔离目录中运行 20 个代表性客户端。

网关测试涵盖未知、禁用、遍历形状和欺骗路由；CORS；方法策略；实际和声明的请求体上限；格式错误的 JSON 和 JSON-RPC；处理器包含；结果上限；截止时间；取消；并发；缺失资源启动失败；以及冷/热就绪。

Playwright 在每个捆绑的 UI 内部运行一个单独的官方 AppBridge 主机，交付初始工具输入/结果，执行 UI 到工具的往返，并检查目录渲染、复制行为、可访问名称、可见键盘焦点、图像替代和 320 像素布局。该工具集证明了画廊的浏览器/桥接契约；它没有被误标为来自无关生产主机的证明。

发布证据和任何部署特定的证明状态记录在 BENCHMARK_REPORT.md、benchmark/result.json、TIMELINE.md 和 benchmark/timeline.json 中。缺失的外部主机证明保持为 Incomplete 或 Skipped，绝不会通过替换变为 Passed。

源代码和许可边界

审计快照冻结到 modelcontextprotocol/ext-apps@10195ad91851502134930e9b80ec2c04e277a720。仅包含以下上游示例目录：

• examples/basic-server-react

• examples/budget-allocator-server

• examples/cohort-heatmap-server

• examples/customer-segmentation-server

• examples/scenario-modeler-server

• examples/transcript-server

每个复制的文件在 upstream/ext-apps/ 下保持逐字节一致，并在 upstream/manifest.json 中包含原始路径、SHA-256、字节数、有效许可、通知和修改声明。所选包在冻结修订版中声明 MIT。

三个大小受限的 UI 重新表达位于 ui-adaptations/ 下；受限的图表兼容层位于 src/ui/chart-shim.ts。这些是画廊拥有的 Apache-2.0 代码，清单记录了它们的精确文件、摘要、大小、基础和理由。有关完整的上游 MIT 授权和许可过渡通知，请参阅 THIRD_PARTY_NOTICES.md。画廊拥有的代码在 LICENSE 下为 Apache-2.0。

分支和发布策略

forward 是唯一的集成和生产分支。工作通过聚焦的拉取请求（如 sol/gallery-v1）进入；main 和 dev 不是发布分支。受保护分支要求拉取请求、线性历史、已解决的对话，并禁止强制推送和删除。生产环境提升是与合并分开的已验证操作。

有关本地工作流程，请参阅 CONTRIBUTING.md；有关威胁模型和私有报告途径，请参阅 SECURITY.md。