@toolgrain/protocol 0.3.0-alpha.2 → 0.3.0

package/CHANGELOG.md

@@ -1,18 +1,28 @@
 # @toolgrain/protocol
 
-## 0.3.0-alpha.2
+## 0.3.0
 
 ### Minor Changes
 
-- Add native MCP Apps protocol contracts and typed React widgets with shared-entry routing.
+- 1cde354: 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 React widgets, matching-version installation, resource
+  metadata examples, and implemented versus deferred React protocol features.
+- 712e975: 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()`.
+- 1cde354: Add native MCP Apps protocol contracts and typed React widgets with shared-entry routing.
 
-## 0.3.0-alpha.1
-
-No changes in this release.
-
-## 0.3.0-alpha.0
+### Patch Changes
 
-No changes in this release.
+- 414e8f5: Clarify MCP Apps installation, browser support, and implemented React APIs for the combined 0.3.0 release; preserve dated prerelease acceptance evidence.
 
 ## 0.2.0
 

package/README.md

@@ -57,6 +57,35 @@ 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.
+
+Toolgrain 0.3.0 or later 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. Check the
+[publication status](https://toolgrain.mintlify.site/project/releases#current-release-status)
+before installing these APIs.
+
+`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.
+
+Named resource CSP/permission, host styling, theme-token, and content-modality
+types describe the wire protocol. A type declaration does not implement a browser
+action. 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

@@ -1,7 +1,15 @@
 {
   "revision": "2026-01-26",
-  "specification": "https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx",
+  "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 stable specification; no upstream implementation is vendored.",
-  "reviewed": "2026-11-06"
+  "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

@@ -1,6 +1,6 @@
-/** Native wire contracts derived from SEP-1865, stable revision 2026-01-26.
- * Source: https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx
- * Toolgrain-authored declarations; no upstream implementation is vendored.
+/** 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. */
@@ -13,35 +13,56 @@ export declare const APPS_MIME_TYPE = "text/html;profile=mcp-app";
 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?: {
-        connectDomains?: readonly string[];
-        resourceDomains?: readonly string[];
-        frameDomains?: readonly string[];
-        baseUriDomains?: readonly string[];
-    };
-    permissions?: {
-        camera?: Record<string, never>;
-        microphone?: Record<string, never>;
-        geolocation?: Record<string, never>;
-        clipboardWrite?: Record<string, never>;
-    };
+    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?: "light" | "dark";
-    styles?: {
-        variables?: Record<string, string | undefined>;
-        css?: {
-            fonts?: string;
-        };
-    };
+    theme?: AppTheme;
+    styles?: AppHostStyles;
     locale?: string;
     timeZone?: string;
     displayMode?: AppDisplayMode;
@@ -70,8 +91,18 @@ export interface AppHostContext {
     };
     [key: string]: unknown;
 }
+/** Content kinds a host advertises for message and model-context actions. */
+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;
     };
@@ -79,7 +110,17 @@ export interface AppHostCapabilities {
         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. */
@@ -105,3 +146,23 @@ export interface AppInitializeResult {
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolgrain/protocol",
-  "version": "0.3.0-alpha.2",
+  "version": "0.3.0",
   "description": "Pinned MCP wire types, protocol versions, and upstream provenance for Toolgrain.",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -22,7 +22,7 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
-    "tag": "alpha"
+    "tag": "latest"
   },
   "type": "module",
   "exports": {