@happyvertical/smrt-mcp-apps

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module零依赖近 30 天下载 2万

Framework-neutral browser bridge for portable MCP Apps

原始使用文档
文档目录5 节
  1. Usage
  2. Supported contract
  3. Svelte and mounted interactions
  4. Validation
  5. Optional extension contracts

@happyvertical/smrt-mcp-apps

Framework-neutral, browser-only view-side bridge for portable MCP Apps. It is not a server adapter, host/sandbox implementation, authorization layer or WebMCP tool registrar. Importing it does not require a browser until construction.

Usage

import { McpAppBridge } from '@happyvertical/smrt-mcp-apps';

const bridge = new McpAppBridge({
  hostWindow: window.parent,
  hostOrigin: 'https://trusted-host.example',
  appInfo: { name: 'Opportunity viewer', version: '1.0.0' },
});
await bridge.connect();
if (bridge.snapshot.hostCapabilities.serverTools) {
  const result = await bridge.callTool('opportunity_list', {});
  // Render text with textContent and validate domain-shaped structuredContent.
}
// Owning component unmount:
bridge.dispose();

Supply the immediate parent window and its exact origin from trusted deployment configuration. Do not learn them from the first message, URL query, untrusted referrer or tool arguments. The same window and origin remain bound for the instance lifetime. HTTPS is required except explicit loopback HTTP development. Opaque (null) parent origins and wildcard targets are intentionally unsupported; a host with an opaque immediate sandbox proxy needs a reviewed transport design. The view itself may have an opaque origin. Host authentication stays outside it.

Supported contract

Pinned upstream revision: 82221c0c8ce7661efa6771c9d461511b1650495f. The runtime schema is authoritative for implemented fields; its protocol constant is 2026-01-26, independent of server MCP 2026-07-28. The same revision's prose examples differ: ui/message shows singleton content and omits message/context modality capabilities, whereas the runtime schema uses a content array, capability modality objects, required hostContext, optional tool-input arguments and optional cancellation reason. Contract tests pin these runtime shapes explicitly.

Implemented methods: initialize/initialized, server tools/call, ui/open-link, text ui/message, text/structured ui/update-model-context, display-mode requests, size notifications, ping and resource teardown. Tool input/result/cancellation and host-context notifications are accepted only after initialization. Exactly one complete initial input and terminal result/cancellation are accepted; late or out-of-order updates are ignored. Partial input is ignored. No app-tools capability is advertised; inbound tools/call receives method-not-found. Resource proxying, sampling and downloads have no built-in typed adapter; an opt-in extension adapter may register a bounded contract below. Binary content in built-in tool results and executable host CSS remain unsupported. Unknown capabilities never grant a supported feature. Unsupported tool content modalities reject explicitly. Text and structured results remain available without interactive capabilities; consumers must retain a normal app/review URL fallback.

Host context exposes only theme, display mode(s), platform, locale and timezone. Unknown context fields are ignored by the typed projection; executable CSS/tool definitions are never applied. snapshot.rawHostContext and snapshot.rawHostCapabilities retain bounded JSON for opt-in extension adapters. Context notifications merge into the raw context; capabilities remain fixed at handshake. Every snapshot/observer receives an isolated clone. Extension adapters must validate their own fields and treat raw data as untrusted; raw capabilities cannot enable typed methods or bypass their gates. There is no global arbitrary RPC method. Optional adapters must explicitly register the capability-gated contract described below. Unknown supported-field enum values fail closed. A missing display-mode list permits only inline. Host rejection (isError: true) and RPC errors propagate.

Payload limits: 24 nested levels, 4096 array items, 1024 object keys, conservative 128 KiB character/node budget; text blocks 32 KiB, 128 blocks; 32 pending requests; 15-second default timeout (configurable 1–120000 ms). Arrays must be dense own data properties with no named/symbol properties; their iterators are never invoked. Cycles/non-JSON/accessors and prototype keys are rejected. Requests use per-instance random correlated IDs. Timeout, abort and disposal reject pending calls and send best-effort cancellation. Disposal removes the listener, aborts signal, and clears observers. Cancellation is not a rollback guarantee: server workflows retain idempotency/transaction rules.

Svelte and mounted interactions

Explicitly import useMcpApp and useMcpAppIntent from @happyvertical/smrt-svelte/mcp-apps. useMcpApp(() => options) constructs only on mount and disposes on unmount; its state contains bridge, snapshot and error. Use bridge.signal or an owned abort signal for associated asynchronous work.

useMcpAppIntent(intent, binding) binds an existing public view-intent declaration to a mounted ControlInteractionRegistry or DataSurfaceRegistry. It uses the public compileViewIntentToolSpec implementation and requires no document.modelContext. It is a component-local callable, never forwarded or advertised as a remote tool. Control proposals remain agent-sourced; existing trusted human staged review owns application of values. The component owns registry registrations and their cleanup. No new REST engine, browser permission engine or final-submission API is introduced.

Validation

After pnpm install and documented dependency builds:

  • pnpm --filter @happyvertical/smrt-mcp-apps build
  • pnpm --filter @happyvertical/smrt-mcp-apps typecheck
  • pnpm --filter @happyvertical/smrt-mcp-apps test
  • pnpm --filter @happyvertical/smrt-mcp-apps test:e2e
  • pnpm --filter @happyvertical/smrt-mcp-apps verify:pack
  • pnpm --filter @happyvertical/smrt-svelte check
  • pnpm --filter @happyvertical/smrt-svelte exec playwright test -c e2e/playwright.config.ts mcp-apps.spec.ts

The Chromium host fixture bundles an Iolaus-shaped synthetic list/detail viewer, prepares and reads it through the public M3 resource APIs, and routes host-proxied calls through createMcpAppServer with a server-owned synthetic principal. It checks resource digest/MIME/CSP metadata and revoked-resource/tool denial, raw generated HTML below 100 KiB, and hash-only script/style CSP with no external network/assets. Browser gates cover hostile messages, capability absence, repeated teardown/reconnect, late superseded results, and keyboard navigation at 320/390px without horizontal overflow. The visible review URL wraps and remains copyable even where sandbox policy blocks opening a new window. The Svelte browser fixture uses real public registries and a genuine Playwright click to apply a staged proposal; fabricated approval is denied. These fixtures prove synthetic browser behavior only. No actual OpenAI or other external host compatibility is claimed. M3 resource metadata still requires the host to enforce CSP and sandbox permissions; the browser bridge cannot enforce a host's policy on its behalf. The reference view only opens a human-review URL and contains no candidate records or transmission/approval operation.

Optional extension contracts

bridge.registerExtension(definition) returns a McpAppExtension only after the Apps handshake completes and the declaration's capability path selects a plain object in the initialized host capabilities. Declarations are trusted local code; never derive capability paths or method lists from host/model input. For example:

const resources = bridge.registerExtension({
  id: 'example.resources',
  capability: { path: ['experimental', 'example/resources'] },
  methods: ['resources/read', 'resources/subscribe', 'resources/unsubscribe'],
  notifications: ['notifications/resources/updated'],
});
const unsubscribe = resources.subscribe((method, params) => {
  // Adapter validates its exact URI/schema/ownership before acting.
});
const result = await resources.request('resources/read', { uri: 'test://fixture' });
// Validate the extension's exact result schema before consuming it.
unsubscribe();
resources.dispose();

If a wire capability declares a version, specify capability.version: { key: 'version', supported: ['1'] }; mismatches reject. Omit this field for capabilities without wire versions rather than inventing one. The bridge copies declarations and permits at most 16 registrations, 16 request methods and 16 notification names per registration, and 32 listeners per handle. Duplicate IDs/method ownership, unlisted requests, reserved lifecycle/tool methods and malformed JSON reject. Unknown notifications are ignored; host requests never invoke notification callbacks. Every observer receives isolated bounded data.

Native ui/message and ui/update-model-context are narrow allowlist exceptions for extension metadata: the core capability and text/structured modality gates, user role, text-content shape/limits and failure-result checks still apply in addition to the extension capability. No image modality or tool-call bypass is introduced. Extension adapters own semantic metadata/result validation and any additional application authorization, not this transport API.

The handle shares the existing bound host/origin, JSON budget, 32-pending limit, correlated IDs and timeout behavior. signal aborts on handle or bridge disposal; pending work rejects and later notifications/results cannot revive the handle. A new registration has a new lifetime. Adapters should request remote unsubscribe before disposal when practical; teardown aborts immediately and does not wait for a host acknowledgement. This is cancellation, not a server rollback guarantee.

版本与发布记录

@happyvertical/smrt-mcp-apps 共发布 128 个版本,首次发布于 2026/10/15;过去 12 个月发布了 128 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-mcp-apps 的常见问题

@happyvertical/smrt-mcp-apps 是什么?

Framework-neutral browser bridge for portable MCP Apps

如何安装 @happyvertical/smrt-mcp-apps?

在项目目录运行 npm install @happyvertical/smrt-mcp-apps,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-mcp-apps 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/smrt-mcp-apps 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/smrt-mcp-apps 可以商用吗?

@happyvertical/smrt-mcp-apps 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-mcp-apps 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/smrt-mcp-apps 在 2026/10/17 – 2026/11/15 这 30 天内被下载 20,382 次,日均约 679 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/smrt-mcp-apps 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 128 个版本,其中过去 12 个月发布了 128 个;首次发布于 2026/10/15。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。