feat: tool visibility and nested _meta.ui format

antonpk1 · claude · antonpk1 · commit f46663a7fb50 · 2025-12-15T22:18:07.000Z
- Rename visibility "apps" → "app" in McpUiToolVisibility type - Add _meta.ui.resourceUri nested format (deprecate flat format) - Add getToolUiResourceUri() utility with backward compatibility - Add visibility demo to system-monitor-server: - get-system-stats: visibility ["model"] with resourceUri - refresh-stats: visibility ["app"] (app-only polling) - Update all example servers to use new _meta.ui format - Add 11 unit tests for getToolUiResourceUri() 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -97,7 +97,7 @@ Create `server.ts`:
 ```typescript
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { RESOURCE_URI_META_KEY } from "@modelcontextprotocol/ext-apps";
+import { RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps";
 import cors from "cors";
 import express from "express";
 import fs from "node:fs/promises";
@@ -119,7 +119,7 @@ server.registerTool(
     description: "Returns the current server time.",
     inputSchema: {},
     outputSchema: { time: z.string() },
-    _meta: { [RESOURCE_URI_META_KEY]: resourceUri }, // Links tool to UI
+    _meta: { ui: { resourceUri } }, // Links tool to UI
   },
   async () => {
     const time = new Date().toISOString();
diff --git a/examples/basic-host/src/implementation.ts b/examples/basic-host/src/implementation.ts
@@ -1,4 +1,4 @@
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY, type McpUiSandboxProxyReadyNotification, AppBridge, PostMessageTransport } from "@modelcontextprotocol/ext-apps/app-bridge";
+import { RESOURCE_MIME_TYPE, getToolUiResourceUri, type McpUiSandboxProxyReadyNotification, AppBridge, PostMessageTransport } from "@modelcontextprotocol/ext-apps/app-bridge";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
@@ -77,7 +77,7 @@ export function callTool(
 
   const toolCallInfo: ToolCallInfo = { serverInfo, tool, input, resultPromise };
 
-  const uiResourceUri = getUiResourceUri(tool);
+  const uiResourceUri = getToolUiResourceUri(tool);
   if (uiResourceUri) {
     toolCallInfo.appResourcePromise = getUiResource(serverInfo, uiResourceUri);
   }
@@ -86,16 +86,6 @@ export function callTool(
 }
 
 
-function getUiResourceUri(tool: Tool): string | undefined {
-  const uri = tool._meta?.[RESOURCE_URI_META_KEY];
-  if (typeof uri === "string" && uri.startsWith("ui://")) {
-    return uri;
-  } else if (uri !== undefined) {
-    throw new Error(`Invalid UI resource URI: ${JSON.stringify(uri)}`);
-  }
-}
-
-
 async function getUiResource(serverInfo: ServerInfo, uri: string): Promise<UiResourceData> {
   log.info("Reading UI resource:", uri);
   const resource = await serverInfo.client.readResource({ uri });
diff --git a/examples/basic-server-react/server.ts b/examples/basic-server-react/server.ts
@@ -3,7 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import { RESOURCE_MIME_TYPE } from "../../dist/src/app";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -28,7 +28,7 @@ function createServer(): McpServer {
       title: "Get Time",
       description: "Returns the current server time as an ISO 8601 string.",
       inputSchema: {},
-      _meta: { [RESOURCE_URI_META_KEY]: RESOURCE_URI },
+      _meta: { ui: { resourceUri: RESOURCE_URI } },
     },
     async (): Promise<CallToolResult> => {
       const time = new Date().toISOString();
diff --git a/examples/basic-server-vanillajs/server.ts b/examples/basic-server-vanillajs/server.ts
@@ -3,7 +3,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import type { CallToolResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import { RESOURCE_MIME_TYPE } from "../../dist/src/app";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -28,7 +28,7 @@ function createServer(): McpServer {
       title: "Get Time",
       description: "Returns the current server time as an ISO 8601 string.",
       inputSchema: {},
-      _meta: { [RESOURCE_URI_META_KEY]: RESOURCE_URI },
+      _meta: { ui: { resourceUri: RESOURCE_URI } },
     },
     async (): Promise<CallToolResult> => {
       const time = new Date().toISOString();
diff --git a/examples/budget-allocator-server/README.md b/examples/budget-allocator-server/README.md
@@ -47,7 +47,7 @@ Exposes a single `get-budget-data` tool that returns:
 - Historical data (~120 data points) - 24 months of allocation history per category
 - Industry benchmarks (~60 data points) - Aggregated percentile data by company stage
 
-The tool is linked to a UI resource via `_meta[RESOURCE_URI_META_KEY]`.
+The tool is linked to a UI resource via `_meta.ui.resourceUri`.
 
 ### App (`src/mcp-app.ts`)
 
diff --git a/examples/budget-allocator-server/server.ts b/examples/budget-allocator-server/server.ts
@@ -13,7 +13,7 @@ import type {
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import { RESOURCE_MIME_TYPE } from "../../dist/src/app";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -242,7 +242,7 @@ function createServer(): McpServer {
       description:
         "Returns budget configuration with 24 months of historical allocations and industry benchmarks by company stage",
       inputSchema: {},
-      _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
+      _meta: { ui: { resourceUri } },
     },
     async (): Promise<CallToolResult> => {
       const response: BudgetDataResponse = {
diff --git a/examples/cohort-heatmap-server/server.ts b/examples/cohort-heatmap-server/server.ts
@@ -4,7 +4,7 @@ import type { ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import { RESOURCE_MIME_TYPE } from "../../dist/src/app";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -163,7 +163,7 @@ function createServer(): McpServer {
       description:
         "Returns cohort retention heatmap data showing customer retention over time by signup month",
       inputSchema: GetCohortDataInputSchema.shape,
-      _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
+      _meta: { ui: { resourceUri } },
     },
     async ({ metric, periodType, cohortCount, maxPeriods }) => {
       const data = generateCohortData(
diff --git a/examples/customer-segmentation-server/README.md b/examples/customer-segmentation-server/README.md
@@ -48,7 +48,7 @@ Exposes a single `get-customer-data` tool that returns:
 - Segment summary with counts and colors for each group
 - Optional segment filter parameter
 
-The tool is linked to a UI resource via `_meta[RESOURCE_URI_META_KEY]`.
+The tool is linked to a UI resource via `_meta.ui.resourceUri`.
 
 ### App (`src/mcp-app.ts`)
 
diff --git a/examples/customer-segmentation-server/server.ts b/examples/customer-segmentation-server/server.ts
@@ -7,7 +7,7 @@ import type {
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import { RESOURCE_MIME_TYPE } from "../../dist/src/app";
 import { startServer } from "../shared/server-utils.js";
 import {
   generateCustomers,
@@ -72,7 +72,7 @@ function createServer(): McpServer {
         description:
           "Returns customer data with segment information for visualization. Optionally filter by segment.",
         inputSchema: GetCustomerDataInputSchema.shape,
-        _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
+        _meta: { ui: { resourceUri } },
       },
       async ({ segment }): Promise<CallToolResult> => {
         const data = getCustomerData(segment);
diff --git a/examples/scenario-modeler-server/README.md b/examples/scenario-modeler-server/README.md
@@ -47,7 +47,7 @@ Exposes a single `get-scenario-data` tool that returns:
 - Default input values for the sliders
 - Optionally computes custom projections when `customInputs` are provided
 
-The tool is linked to a UI resource via `_meta[RESOURCE_URI_META_KEY]`.
+The tool is linked to a UI resource via `_meta.ui.resourceUri`.
 
 ### App (`src/`)
 
diff --git a/examples/scenario-modeler-server/server.ts b/examples/scenario-modeler-server/server.ts
@@ -7,7 +7,7 @@ import type {
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import { RESOURCE_MIME_TYPE } from "../../dist/src/app";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -263,7 +263,7 @@ function createServer(): McpServer {
         description:
           "Returns SaaS scenario templates and optionally computes custom projections for given inputs",
         inputSchema: GetScenarioDataInputSchema.shape,
-        _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
+        _meta: { ui: { resourceUri } },
       },
       async (args: {
         customInputs?: ScenarioInputs;
diff --git a/examples/system-monitor-server/README.md b/examples/system-monitor-server/README.md
@@ -46,7 +46,7 @@ Exposes a single `get-system-stats` tool that returns:
 - Memory usage (used/total/percentage)
 - System info (hostname, platform, uptime)
 
-The tool is linked to a UI resource via `_meta[RESOURCE_URI_META_KEY]`.
+The tool is linked to a UI resource via `_meta.ui.resourceUri`.
 
 ### App (`src/mcp-app.ts`)
 
diff --git a/examples/system-monitor-server/server.ts b/examples/system-monitor-server/server.ts
@@ -9,7 +9,7 @@ import os from "node:os";
 import path from "node:path";
 import si from "systeminformation";
 import { z } from "zod";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import { RESOURCE_MIME_TYPE } from "../../dist/src/app";
 import { startServer } from "../shared/server-utils.js";
 
 // Schemas - types are derived from these using z.infer
@@ -108,45 +108,70 @@ function createServer(): McpServer {
     version: "1.0.0",
   });
 
-  // Register the get-system-stats tool and its associated UI resource
+  // VISIBILITY DEMO:
+  // - get-system-stats: visibility ["model"] - model calls this, returns widget
+  // - refresh-stats: visibility ["app"] - hidden from model, app calls for polling
   const resourceUri = "ui://system-monitor/mcp-app.html";
 
+  async function getStats(): Promise<CallToolResult> {
+    const cpuSnapshots = getCpuSnapshots();
+    const cpuInfo = os.cpus()[0];
+    const memory = await getMemoryStats();
+    const uptimeSeconds = os.uptime();
+
+    const stats: SystemStats = {
+      cpu: {
+        cores: cpuSnapshots,
+        model: cpuInfo?.model ?? "Unknown",
+        count: os.cpus().length,
+      },
+      memory,
+      system: {
+        hostname: os.hostname(),
+        platform: `${os.platform()} ${os.arch()}`,
+        arch: os.arch(),
+        uptime: uptimeSeconds,
+        uptimeFormatted: formatUptime(uptimeSeconds),
+      },
+      timestamp: new Date().toISOString(),
+    };
+
+    return {
+      content: [{ type: "text", text: JSON.stringify(stats) }],
+    };
+  }
+
   server.registerTool(
     "get-system-stats",
     {
       title: "Get System Stats",
       description:
         "Returns current system statistics including per-core CPU usage, memory, and system info.",
       inputSchema: {},
-      _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
-    },
-    async (): Promise<CallToolResult> => {
-      const cpuSnapshots = getCpuSnapshots();
-      const cpuInfo = os.cpus()[0];
-      const memory = await getMemoryStats();
-      const uptimeSeconds = os.uptime();
-
-      const stats: SystemStats = {
-        cpu: {
-          cores: cpuSnapshots,
-          model: cpuInfo?.model ?? "Unknown",
-          count: os.cpus().length,
-        },
-        memory,
-        system: {
-          hostname: os.hostname(),
-          platform: `${os.platform()} ${os.arch()}`,
-          arch: os.arch(),
-          uptime: uptimeSeconds,
-          uptimeFormatted: formatUptime(uptimeSeconds),
+      _meta: {
+        ui: {
+          resourceUri,
+          visibility: ["model"],
         },
-        timestamp: new Date().toISOString(),
-      };
+      },
+    },
+    getStats,
+  );
 
-      return {
-        content: [{ type: "text", text: JSON.stringify(stats) }],
-      };
+  // App-only tool for polling - hidden from model's tool list
+  server.registerTool(
+    "refresh-stats",
+    {
+      title: "Refresh Stats",
+      description: "Refresh system statistics (app-only, for polling)",
+      inputSchema: {},
+      _meta: {
+        ui: {
+          visibility: ["app"],
+        },
+      },
     },
+    getStats,
   );
 
   server.registerResource(
diff --git a/examples/system-monitor-server/src/mcp-app.ts b/examples/system-monitor-server/src/mcp-app.ts
@@ -260,7 +260,7 @@ const app = new App({ name: "System Monitor", version: "1.0.0" });
 async function fetchStats(): Promise<void> {
   try {
     const result = await app.callServerTool({
-      name: "get-system-stats",
+      name: "refresh-stats", // Use app-only tool for polling
       arguments: {},
     });
 
diff --git a/examples/threejs-server/server.ts b/examples/threejs-server/server.ts
@@ -9,7 +9,7 @@ import type { ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import { RESOURCE_MIME_TYPE } from "../../dist/src/app";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -160,7 +160,7 @@ function createServer(): McpServer {
           .default(400)
           .describe("Height in pixels"),
       },
-      _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
+      _meta: { ui: { resourceUri } },
     },
     async ({ code, height }) => {
       return {
diff --git a/examples/wiki-explorer-server/server.ts b/examples/wiki-explorer-server/server.ts
@@ -8,7 +8,7 @@ import * as cheerio from "cheerio";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { z } from "zod";
-import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from "../../dist/src/app";
+import { RESOURCE_MIME_TYPE } from "../../dist/src/app";
 import { startServer } from "../shared/server-utils.js";
 
 const DIST_DIR = path.join(import.meta.dirname, "dist");
@@ -89,7 +89,7 @@ function createServer(): McpServer {
           .default("https://en.wikipedia.org/wiki/Model_Context_Protocol")
           .describe("Wikipedia page URL"),
       }),
-      _meta: { [RESOURCE_URI_META_KEY]: resourceUri },
+      _meta: { ui: { resourceUri } },
     },
     async ({ url }): Promise<CallToolResult> => {
       let title = url;
diff --git a/specification/draft/apps.mdx b/specification/draft/apps.mdx
@@ -273,7 +273,7 @@ interface Tool {
 
 > **Deprecation notice:** The flat `_meta["ui/resourceUri"]` format is deprecated. Use `_meta.ui.resourceUri` instead. The deprecated format will be removed before GA.
 
-Example (tool visible to both model and apps):
+Example (tool visible to both model and app):
 
 ```json
 {
diff --git a/src/app-bridge.test.ts b/src/app-bridge.test.ts
diff --git a/src/app-bridge.ts b/src/app-bridge.ts
diff --git a/src/generated/schema.json b/src/generated/schema.json
diff --git a/src/generated/schema.ts b/src/generated/schema.ts
diff --git a/src/spec.types.ts b/src/spec.types.ts
