@toolgrain/protocol 0.3.0-alpha.1 → 0.3.0-alpha.3

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @toolgrain/protocol
 
+## 0.3.0-alpha.3
+
+### Minor Changes
+
+- Add named Apps resource, styling, theme-token, and content-modality wire types,
+  with explicit host capability advertisements and pinned specification/type
+  provenance. Preserve custom styling variables and unknown host capability fields.
+  
+  `AppToolMeta` now rejects resource-only CSP and permissions, including metadata
+  assigned through a variable. Put those fields on the resource content item's
+  `_meta.ui`; tool metadata retains its resource URI and visibility settings.
+  
+  Document the published React alpha, matching-version installation, resource
+  metadata examples, and implemented versus deferred React protocol features.
+- Add native React host actions for links, user messages, replacement model context,
+  and display modes, with capability checks, cancellation/deadlines, and typed
+  request/result contracts. Let providers declare supported display modes and expose
+  live action availability through `useHostActions()`.
+
+## 0.3.0-alpha.2
+
+### Minor Changes
+
+- Add native MCP Apps protocol contracts and typed React widgets with shared-entry routing.
+
 ## 0.3.0-alpha.1
 
 No changes in this release.

package/README.md

@@ -57,6 +57,34 @@ The root exports the modern schema, `LEGACY_PROTOCOL_VERSION`,
 `ProtocolResponse` envelopes. The `2025-06-18` subpath exports the legacy schema.
 These are wire definitions; runtime validation remains in `@toolgrain/mcp`.
 
+## MCP Apps contracts
+
+The `@toolgrain/protocol/apps` subpath describes the Apps iframe channel,
+independently of either outer MCP revision. It exports the Apps version,
+extension identifier, HTML MIME type, resource/tool metadata, host context,
+capabilities, initialization envelopes, and tool-result envelope.
+
+The `0.3.0-alpha.3` candidate also exports `AppMessageParams`,
+`AppModelContextParams`, `AppActionResult`, and `AppDisplayModeResult` for native
+host requests. They describe user messages, replacement model context, full
+acknowledgements, and actual selected display modes. These new exports are absent
+from published `0.3.0-alpha.2`.
+
+`AppResourceMeta` describes CSP, requested browser permissions, sandbox origin,
+and border preference. Tool `_meta.ui` uses `AppToolMeta` for `resourceUri` and
+visibility; CSP and permissions belong on the resource content item.
+
+The `0.3.0-alpha.3` candidate adds named resource CSP/permission, host styling,
+theme-token, and content-modality types. They are not additional
+browser actions in the published `0.3.0-alpha.2`. Known styling tokens support
+autocomplete while custom variables and unknown host capability fields remain
+accepted for forward compatibility.
+
+The package retains `dist/apps-provenance.json` with exact reviewed specification
+and upstream type-file commits/checksums. The declarations are Toolgrain-authored;
+no Apps SDK implementation is vendored and there are no runtime dependencies.
+See the [Apps API reference](https://toolgrain.mintlify.site/mcp-apps/reference).
+
 ## Requirements
 
 ESM only. Supported application runtimes are Node.js `^24.20.0` or Bun

package/dist/apps-provenance.json

@@ -0,0 +1,15 @@
+{
+  "revision": "2026-01-26",
+  "specification": "https://github.com/modelcontextprotocol/ext-apps/blob/298e884ec3f02daba085acdb02042d73bd00b355/specification/2026-01-26/apps.mdx",
+  "specificationCommit": "298e884ec3f02daba085acdb02042d73bd00b355",
+  "specificationSha256": "ee452a7d1b9b7fb900acfeb4d6932d3963375b0f3f37d196a4b93eb80312af0e",
+  "upstreamTypes": {
+    "source": "https://github.com/modelcontextprotocol/ext-apps/blob/040942b3af064bf76b705021e3472b6593ae839e/src/spec.types.ts",
+    "commit": "040942b3af064bf76b705021e3472b6593ae839e",
+    "sha256": "f46212be3355fa0437c81b01659187efacdeef6fa50be23be02a47d03610bc6a",
+    "scope": "Capability advertisements, styling tokens, and host-action request/result contracts. Declarations alone do not implement optional host actions."
+  },
+  "apiReference": "https://apps.extensions.modelcontextprotocol.io/api/",
+  "implementation": "Toolgrain-authored wire declarations derived from the reviewed specification and type contracts; no upstream implementation is vendored.",
+  "reviewed": "2026-11-07"
+}

package/dist/apps.d.ts

@@ -0,0 +1,168 @@
+/** Native Apps 2026-01-26 wire contracts. Reviewed specification and upstream
+ * type references are pinned in apps-provenance.json. Toolgrain authors these
+ * declarations directly; browser implementations live in @toolgrain/react.
+ */
+import type { ContentBlock, Implementation, MetaObject, Tool } from "./index.js";
+/** Apps iframe revision; independent of the outer MCP connection revision. */
+export declare const APPS_PROTOCOL_VERSION = "2026-01-26";
+/** Client capability extension identifier. */
+export declare const APPS_EXTENSION_ID = "io.modelcontextprotocol/ui";
+/** HTML resource MIME type required by MCP Apps. */
+export declare const APPS_MIME_TYPE = "text/html;profile=mcp-app";
+/** UI association and host-enforced visibility on a tool's `_meta.ui`. */
+export interface AppToolMeta {
+    resourceUri?: string;
+    visibility?: readonly ("model" | "app")[];
+    /** Resource configuration belongs on the returned HTML content item's `_meta.ui`. */
+    csp?: never;
+    /** Resource configuration belongs on the returned HTML content item's `_meta.ui`. */
+    permissions?: never;
+}
+/** Origins requested by a resource; the host constructs and enforces its CSP. */
+export interface AppResourceCsp {
+    connectDomains?: readonly string[];
+    resourceDomains?: readonly string[];
+    frameDomains?: readonly string[];
+    baseUriDomains?: readonly string[];
+}
+/** Requested browser permissions; empty objects request access without guaranteeing a grant. */
+export interface AppResourcePermissions {
+    camera?: Record<string, never>;
+    microphone?: Record<string, never>;
+    geolocation?: Record<string, never>;
+    clipboardWrite?: Record<string, never>;
+}
+/** Requested sandbox configuration on a resource content item's `_meta.ui`. */
+export interface AppResourceMeta {
+    csp?: AppResourceCsp;
+    permissions?: AppResourcePermissions;
+    domain?: string;
+    /** Request a host-provided border/background; omission leaves the choice to the host. */
+    prefersBorder?: boolean;
+}
+/** Display modes of the iframe view. */
+export type AppDisplayMode = "inline" | "fullscreen" | "pip";
+/** Host color-scheme preference. */
+export type AppTheme = "light" | "dark";
+/** Standardized Apps theme tokens; custom host variables may also be supplied. */
+export type AppStyleVariableKey = `--color-${"background" | "text" | "border"}-${"primary" | "secondary" | "tertiary" | "inverse" | "ghost" | "info" | "danger" | "success" | "warning" | "disabled"}` | `--color-ring-${"primary" | "secondary" | "inverse" | "info" | "danger" | "success" | "warning"}` | `--font-${"sans" | "mono"}` | `--font-weight-${"normal" | "medium" | "semibold" | "bold"}` | `--font-text-${"xs" | "sm" | "md" | "lg"}-${"size" | "line-height"}` | `--font-heading-${"xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl"}-${"size" | "line-height"}` | `--border-radius-${"xs" | "sm" | "md" | "lg" | "xl" | "full"}` | "--border-width-regular" | `--shadow-${"hairline" | "sm" | "md" | "lg"}`;
+/** Optional known tokens with string-valued extensions for forward compatibility. */
+export type AppStyleVariables = Partial<Record<AppStyleVariableKey, string | undefined>> & Record<string, string | undefined>;
+/** Host font-loading CSS applied by the React provider when host styling is enabled. */
+export interface AppHostCss {
+    fonts?: string;
+    [key: string]: unknown;
+}
+/** Host-provided theme variables and font-loading CSS. */
+export interface AppHostStyles {
+    variables?: AppStyleVariables;
+    css?: AppHostCss;
+    [key: string]: unknown;
+}
+/** Host-provided presentation hints. These are not verified identity or policy. */
+export interface AppHostContext {
+    theme?: AppTheme;
+    styles?: AppHostStyles;
+    locale?: string;
+    timeZone?: string;
+    displayMode?: AppDisplayMode;
+    availableDisplayModes?: AppDisplayMode[];
+    containerDimensions?: {
+        width?: number;
+        maxWidth?: number;
+        height?: number;
+        maxHeight?: number;
+    };
+    platform?: "web" | "desktop" | "mobile";
+    deviceCapabilities?: {
+        touch?: boolean;
+        hover?: boolean;
+    };
+    safeAreaInsets?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    userAgent?: string;
+    toolInfo?: {
+        id?: string | number;
+        tool: Tool;
+    };
+    [key: string]: unknown;
+}
+/** Content kinds a host advertises for an optional action; this declares no React action API. */
+export interface AppContentModalities {
+    text?: Record<string, unknown>;
+    image?: Record<string, unknown>;
+    audio?: Record<string, unknown>;
+    resource?: Record<string, unknown>;
+    resourceLink?: Record<string, unknown>;
+    structuredContent?: Record<string, unknown>;
+}
+/** Capabilities negotiated by the host on the iframe channel. */
+export interface AppHostCapabilities {
+    experimental?: Record<string, object>;
+    serverTools?: {
+        listChanged?: boolean;
+    };
+    serverResources?: {
+        listChanged?: boolean;
+    };
+    openLinks?: Record<string, unknown>;
+    downloadFile?: Record<string, unknown>;
+    logging?: Record<string, unknown>;
+    sandbox?: {
+        permissions?: AppResourcePermissions;
+        csp?: AppResourceCsp;
+    };
+    updateModelContext?: AppContentModalities;
+    message?: AppContentModalities;
+    sampling?: {
+        tools?: Record<string, unknown>;
+    };
+    [key: string]: unknown;
+}
+/** Tool envelope delivered by the host; structured data can be omitted by legacy conversion. */
+export interface AppToolResult<Structured = unknown, Meta = MetaObject> {
+    content: ContentBlock[];
+    structuredContent?: Structured;
+    _meta?: Meta;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+/** View-to-host Apps handshake parameters. */
+export interface AppInitializeParams {
+    protocolVersion: typeof APPS_PROTOCOL_VERSION;
+    appInfo: Implementation;
+    appCapabilities: {
+        availableDisplayModes?: AppDisplayMode[];
+    };
+}
+/** Host-to-view Apps handshake response. */
+export interface AppInitializeResult {
+    protocolVersion: string;
+    hostInfo: Implementation;
+    hostCapabilities: AppHostCapabilities;
+    hostContext?: AppHostContext;
+}
+/** User message submitted through the host; sending can trigger a model follow-up. */
+export interface AppMessageParams {
+    role: "user";
+    content: readonly ContentBlock[];
+}
+/** Replacement context for future model turns. An empty object can clear prior app context. */
+export interface AppModelContextParams {
+    content?: readonly ContentBlock[];
+    structuredContent?: Record<string, unknown>;
+}
+/** Full host acknowledgement; explicit denials may resolve with isError. RPC errors reject. */
+export interface AppActionResult {
+    isError?: boolean;
+    [key: string]: unknown;
+}
+/** Actual display mode selected by the host, which can differ from the requested mode. */
+export interface AppDisplayModeResult {
+    mode: AppDisplayMode;
+    [key: string]: unknown;
+}

package/dist/apps.js

@@ -0,0 +1,6 @@
+/** Apps iframe revision; independent of the outer MCP connection revision. */
+export const APPS_PROTOCOL_VERSION = "2026-01-26";
+/** Client capability extension identifier. */
+export const APPS_EXTENSION_ID = "io.modelcontextprotocol/ui";
+/** HTML resource MIME type required by MCP Apps. */
+export const APPS_MIME_TYPE = "text/html;profile=mcp-app";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolgrain/protocol",
-  "version": "0.3.0-alpha.1",
+  "version": "0.3.0-alpha.3",
   "description": "Pinned MCP wire types, protocol versions, and upstream provenance for Toolgrain.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -33,6 +33,10 @@
     "./2025-06-18": {
       "types": "./dist/legacy.d.ts",
       "import": "./dist/legacy.js"
+    },
+    "./apps": {
+      "types": "./dist/apps.d.ts",
+      "import": "./dist/apps.js"
     }
   },
   "files": [