Merge remote-tracking branch 'origin/main' into feat/virtual-desktop-server

Author: ochafik

README.md

@@ -56,19 +56,28 @@ Or edit your `package.json` manually:
 
 ## Examples
 
-Start with these foundational examples to learn the SDK:
-
-- [`examples/basic-server-vanillajs`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vanillajs) — MCP server + MCP App using vanilla JS
-- [`examples/basic-server-react`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-react) — MCP server + MCP App using [React](https://github.com/facebook/react)
-- [`examples/basic-server-vue`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-vue) — MCP server + MCP App using [Vue](https://github.com/vuejs/vue)
-- [`examples/basic-server-svelte`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-svelte) — MCP server + MCP App using [Svelte](https://github.com/sveltejs/svelte)
-- [`examples/basic-server-preact`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-preact) — MCP server + MCP App using [Preact](https://github.com/preactjs/preact)
-- [`examples/basic-server-solid`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-server-solid) — MCP server + MCP App using [Solid](https://github.com/solidjs/solid)
-- [`examples/basic-host`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) — MCP host application supporting MCP Apps
+<!-- prettier-ignore-start -->
+| | | |
+|:---:|:---:|:---:|
+| [![Map](examples/map-server/grid-cell.png "Interactive 3D globe viewer using CesiumJS")](examples/map-server) | [![Three.js](examples/threejs-server/grid-cell.png "Interactive 3D scene renderer")](examples/threejs-server) | [![ShaderToy](examples/shadertoy-server/grid-cell.png "Real-time GLSL shader renderer")](examples/shadertoy-server) |
+| [**Map**](examples/map-server) | [**Three.js**](examples/threejs-server) | [**ShaderToy**](examples/shadertoy-server) |
+| [![Sheet Music](examples/sheet-music-server/grid-cell.png "ABC notation to sheet music")](examples/sheet-music-server) | [![Wiki Explorer](examples/wiki-explorer-server/grid-cell.png "Wikipedia link graph visualization")](examples/wiki-explorer-server) | [![Cohort Heatmap](examples/cohort-heatmap-server/grid-cell.png "Customer retention heatmap")](examples/cohort-heatmap-server) |
+| [**Sheet Music**](examples/sheet-music-server) | [**Wiki Explorer**](examples/wiki-explorer-server) | [**Cohort Heatmap**](examples/cohort-heatmap-server) |
+| [![Scenario Modeler](examples/scenario-modeler-server/grid-cell.png "SaaS business projections")](examples/scenario-modeler-server) | [![Budget Allocator](examples/budget-allocator-server/grid-cell.png "Interactive budget allocation")](examples/budget-allocator-server) | [![Customer Segmentation](examples/customer-segmentation-server/grid-cell.png "Scatter chart with clustering")](examples/customer-segmentation-server) |
+| [**Scenario Modeler**](examples/scenario-modeler-server) | [**Budget Allocator**](examples/budget-allocator-server) | [**Customer Segmentation**](examples/customer-segmentation-server) |
+| [![System Monitor](examples/system-monitor-server/grid-cell.png "Real-time OS metrics")](examples/system-monitor-server) | [![Transcript](examples/transcript-server/grid-cell.png "Live speech transcription")](examples/transcript-server) | [![Video Resource](examples/video-resource-server/grid-cell.png "Binary video via MCP resources")](examples/video-resource-server) |
+| [**System Monitor**](examples/system-monitor-server) | [**Transcript**](examples/transcript-server) | [**Video Resource**](examples/video-resource-server) |
+
+### Starter Templates
+
+| | |
+|:---:|:---|
+| [![Basic](examples/basic-server-react/grid-cell.png "Starter template")](examples/basic-server-react) | The same app built with different frameworks — pick your favorite!<br><br>[React](examples/basic-server-react) · [Vue](examples/basic-server-vue) · [Svelte](examples/basic-server-svelte) · [Preact](examples/basic-server-preact) · [Solid](examples/basic-server-solid) · [Vanilla JS](examples/basic-server-vanillajs) |
+<!-- prettier-ignore-end -->
 
 The [`examples/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples) directory contains additional demo apps showcasing real-world use cases.
 
-To run all examples together:
+To run all examples:
 
 ```bash
 npm install

docs/migrate_from_openai_apps.md

@@ -1,9 +1,30 @@
+import { getToolUiResourceUri, McpUiToolMetaSchema } from "@modelcontextprotocol/ext-apps/app-bridge";
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import { Component, type ErrorInfo, type ReactNode, StrictMode, Suspense, use, useEffect, useMemo, useRef, useState } from "react";
 import { createRoot } from "react-dom/client";
 import { callTool, connectToServer, hasAppHtml, initializeApp, loadSandboxProxy, log, newAppBridge, type ServerInfo, type ToolCallInfo, type ModelContext, type AppMessage } from "./implementation";
 import styles from "./index.module.css";
 
+/**
+ * Check if a tool is visible to the model (not app-only).
+ * Tools with `visibility: ["app"]` should not be shown in tool lists.
+ */
+function isToolVisibleToModel(tool: { _meta?: Record<string, unknown> }): boolean {
+  const result = McpUiToolMetaSchema.safeParse(tool._meta?.ui);
+  if (!result.success) return true; // default: visible to model
+  const visibility = result.data.visibility;
+  if (!visibility) return true; // default: visible to model
+  return visibility.includes("model");
+}
+
+/** Compare tools: UI-enabled first, then alphabetically by name. */
+function compareTools(a: Tool, b: Tool): number {
+  const aHasUi = !!getToolUiResourceUri(a);
+  const bHasUi = !!getToolUiResourceUri(b);
+  if (aHasUi && !bHasUi) return -1;
+  if (!aHasUi && bHasUi) return 1;
+  return a.name.localeCompare(b.name);
+}
 
 /**
  * Extract default values from a tool's JSON Schema inputSchema.
@@ -80,7 +101,13 @@ function CallToolPanel({ serversPromise, addToolCall }: CallToolPanelProps) {
   const [selectedTool, setSelectedTool] = useState("");
   const [inputJson, setInputJson] = useState("{}");
 
-  const toolNames = selectedServer ? Array.from(selectedServer.tools.keys()) : [];
+  // Filter out app-only tools, prioritize tools with UIs
+  const toolNames = selectedServer
+    ? Array.from(selectedServer.tools.values())
+        .filter((tool) => isToolVisibleToModel(tool))
+        .sort(compareTools)
+        .map((tool) => tool.name)
+    : [];
 
   const isValidJson = useMemo(() => {
     try {
@@ -93,10 +120,14 @@ function CallToolPanel({ serversPromise, addToolCall }: CallToolPanelProps) {
 
   const handleServerSelect = (server: ServerInfo) => {
     setSelectedServer(server);
-    const [firstTool] = server.tools.keys();
-    setSelectedTool(firstTool ?? "");
+    // Filter out app-only tools, prioritize tools with UIs
+    const visibleTools = Array.from(server.tools.values())
+      .filter((tool) => isToolVisibleToModel(tool))
+      .sort(compareTools);
+    const firstTool = visibleTools[0]?.name ?? "";
+    setSelectedTool(firstTool);
     // Set input JSON to tool defaults (if any)
-    setInputJson(getToolDefaults(server.tools.get(firstTool ?? "")));
+    setInputJson(getToolDefaults(server.tools.get(firstTool)));
   };
 
   const handleToolSelect = (toolName: string) => {

examples/basic-host/src/index.tsx

@@ -1,5 +1,7 @@
 # Example: Basic Server (React)
 
+![Screenshot](screenshot.png)
+
 An MCP App example with a React UI.
 
 > [!TIP]