@happyvertical/smrt-mcp-openai

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 1.7万

Optional OpenAI navigation and settings for authorized SMRT MCP Apps

原始使用文档
文档目录5 节
  1. Contract and scope
  2. Server composition
  3. Browser navigation and fallbacks
  4. Context, messages and composer mentions
  5. Validation and evidence

@happyvertical/smrt-mcp-openai

Optional navigation, settings, context, messages and mentions for s-m-r-t MCP Apps. Ordinary s-m-r-t apps do not import this package. The ./client entry is browser-only and depends on the portable @happyvertical/smrt-mcp-apps bridge; the root entry composes existing app-MCP workflows without creating another server or authorization policy.

Contract and scope

This package implements the navigation/settings and context/messages/mentions children of #3202 under the M0 integration standard:

  • Global and thread entrypoint metadata on idempotent read UI tools accepting {}.
  • Structured primitive settings and permission-filtered layout actions; modern discovery advertises capabilities.extensions['openai/settings'] only when both settings tools are in the request's authorized catalog.
  • Resource display-mode metadata and portable display requests with inline fallback.
  • Validated native/web app links and observed host deep links resolved through an existing domain-authorized read tool.
  • Manifest onboarding declaration; packaged skill/assets verification belongs to M7.

Exact baseline: OpenAI extension spec e314720, revalidated as upstream main on 2026-09-30 UTC, and the official extension guide and UI guide. The SDK v1 OpenAI helper is deliberately not a dependency. Server transport uses native scoped MCP SDK 2.0.0 / protocol 2026-07-28; browser Apps uses 2026-01-26.

Only implemented features are declared. Files/forms remain separate planned M6 children. Settings support booleans, strings/enums/length bounds, numbers/integers/range/multiple bounds. Arbitrary regex patterns are explicitly rejected to avoid running unbounded patterns; applications can use an enum or an existing domain validator. No silent schema downgrade occurs. Metadata is bounded to 64 KiB, depth 16; settings to 64 fields, strings to 4096 characters, routes to 2048 characters. Unknown fields/types fail closed.

Server composition

Use withOpenAiEntrypoints(existingReadWorkflow, ['global', 'thread']) and pass the result to the existing createMcpAppServer({ workflowTools }). It retains the handler and portable _meta.ui.resourceUri. Initial tool results still render without duplicate entrypoint calls. Give thread views distinct descriptive titles.

bindOpenAiSettings({ schema, read, update, server: () => appServer }) wraps two existing workflow definitions. Add its workflows to that server, then mount it with extensions: ({ tools }) => settings.extensions(tools). The callback runs on server/discover with the same verified principal and filtered catalog used for tool discovery. Neither annotations nor extension metadata grant permission.

Read handlers return structuredContent: { schema, values, layout? }, with a value for every property. Update handlers receive { set: { changedField: value } } and return structuredContent: { values }. Updates are absolute-value assignments, not toggles or increments. The binding verifies their declared read/write effects, requires idempotent assignment, validates inputs/outputs, and never retries.

Owning handlers must authorize resource ownership, recheck active tenant and membership, and persist patches atomically using their existing executor and revision policy. The adapter does not provide persistence, transaction guards, or domain approval. The host wire contract has no revision parameter; do not add an invented field. Workflows requiring a human review/revision token should keep that flow in the application, rather than force it into native settings. Tests exercise an owning SQLite transaction, guarded update, rollback and retries.

Pass openAiDisplayMetadata({ availableDisplayModes: ['inline', 'fullscreen'], preferredDisplayMode: 'fullscreen' }) as a declared resource's metadata. Resource security metadata and digest remain owned by app-MCP. pip is not part of this pinned OpenAI display contract. Omitted fields preserve upstream defaults; preferences remain hints.

openAiOnboardingDeclaration('./skills/setup/SKILL.md') returns only { extensions: { 'com.openai': { onboardingSkill: ... } } }. Merge that into the plugin manifest; it does not install or execute the skill.

Browser navigation and fallbacks

Import ./client, pass the existing McpAppBridge to observeOpenAiNavigation({ bridge, resolveTool, onResult, onFallback }), and call the returned disposer when unmounting. It consumes bounded rawHostContext from the bridge's validated origin/source and lifecycle, recognizes only openai/deepLink: { url }, and calls the designated server tool with { url }. The domain tool must reject guessed or cross-tenant objects. Server applications can use resolveOpenAiNavigationTarget to dispatch only an authorized read tool.

Repeated identical routes do not duplicate calls; new routes cancel old requests and ignore stale replies. URLs are app-relative, fragment-free, traversal-free, and reject protocol-relative, double-encoded and control-character forms. Treat query parameters as untrusted input, never as identity or approval. The literal query delimiter is separated before pathname decoding, so encoded question marks cannot hide traversal segments. Traversal-like text in query values remains legal.

Only a rejected tool call or an isError result selects the denied fallback. Consumer callback exceptions are not authorization failures and never retry a fallback. Callbacks should handle their own rendering errors; uncaught exceptions in asynchronous result/fallback callbacks surface as unhandled promise rejections.

createOpenAiAppLink emits pinned desktop (codex), mobile (chatgpt) or web formats with separately encoded plugin/tool/path components. openAiNavigationLink requires explicit 'present' support to choose a native link; 'absent', unknown or malformed support uses a configured HTTPS application URL. This support input is a deployment/observed-host decision, not an invented MCP capability field. Entrypoints/onboarding similarly have no client advertisement in the pinned spec; keep ordinary tool/setup navigation available. Native structured settings are optional: the same settings tools and application settings page remain usable.

requestOpenAiDisplayMode uses negotiated portable modes; missing/unknown modes or a rejected request return 'inline'. The UI must actually retain its inline layout and render an ordinary link when navigation cannot be resolved.

Context, messages and composer mentions

Browser consumers import updateOpenAiModelContext from ./context and sendOpenAiMessage from ./messages. Server consumers import withOpenAiMentionSearch and resolveOpenAiMentionSelection from ./mentions. These subpaths share the existing portable bridge and authorized app-MCP server.

updateOpenAiModelContext({ bridge, value, native }) replaces context with { text: { text, title?, thumbnail? }, structuredContent? }. Text is nonempty and at most 16384 characters; titles are limited to 512. Set background: true on the text value to emit assistant-only audience metadata; background is a presentation hint, not a privacy boundary: the model/provider still receives the context. Only send data authorized for that recipient. Negotiated openai/modelContext uses the supplied native callback. Missing support or native failure falls back to portable text and structured content, without native metadata. Abort/disposal prevents a late fallback.

sendOpenAiMessage({ bridge, value, native }) accepts text and target: 'active' (the default) or 'new'. Active conversations can use portable text messages. New conversations require negotiated openai/message and a native callback; missing or malformed support rejects before any message reaches the active conversation. Unknown targets/modalities fail closed and sends are not retried.

withOpenAiMentionSearch(existingReadWorkflow) declares app-only composer search metadata and a { query } input (at most 256 characters, including empty search). Its owning handler returns structuredContent: { items }, with at most 25 { type: 'resource', resourceUri, title, subtitle?, icons? } entries. Handles are nonempty opaque strings of at most 2048 characters; titles/subtitles are nonempty and bounded to 512. Each of at most eight icons requires src (2048), with optional mimeType (128), up to eight nonempty sizes strings (32 each), and theme: 'light' | 'dark'. Unknown fields and malformed values reject. The published output schema describes these same closed objects and limits.

Search results are discovery hints, never authorization grants. Pass the exact returned resourceUri as the existing selection workflow's argument through resolveOpenAiMentionSelection({ server, tool, arguments, principal }). The application supplies the trusted, freshly resolved principal; app-MCP policy rechecks actor, active tenant, scopes and membership on every call, and the owning workflow rechecks handle ownership. Never derive identity from a handle, browser metadata or search-time permission. Guesses, cross-tenant calls and revocation after search must not select private data. This helper adds no selection handler, identity provider, persistence or authorization policy.

Validation and evidence

Run pnpm install, then the documented dependency build and package gates:

pnpm exec turbo build --filter=@happyvertical/smrt-mcp-openai...
pnpm --filter @happyvertical/smrt-mcp-openai typecheck
pnpm --filter @happyvertical/smrt-mcp-openai test
pnpm --filter @happyvertical/smrt-mcp-openai test:e2e
pnpm --filter @happyvertical/smrt-mcp-openai verify:pack

The behavior/threat matrix is in TEST-DESIGN.md. Protocol tests use the actual SDK client and HTTP mount, including real loopback JWKS/MCP sockets through the public M2 auth gateway with token, actor, tenant and revocation denials; the browser suite uses a real Chromium sandboxed iframe with no-network CSP and built browser output. Packed exports are checked for declaration and browser/server boundaries. Existing app-MCP full suite/typecheck/pack and portable bridge gates also apply to integration changes. The coordinator schedules all root gates and independent review.

No actual OpenAI host compatibility is claimed. The synthetic host does not prove desktop, Work web, iOS, Android or account rollout support. No configured OpenAI host connection or deployable registered synthetic plugin was provided; record exact host/build/platform, auth profile, asset revision and observed navigation/settings outcomes before claiming supported-host acceptance. The upstream support matrix is expected support only; web refers to Work, excluding classic ChatGPT. Actual host acceptance remains open for M8.

版本与发布记录

@happyvertical/smrt-mcp-openai 共发布 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-openai 的常见问题

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

Optional OpenAI navigation and settings for authorized SMRT MCP Apps

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

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

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

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

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

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

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

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

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

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

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

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