basic-host: filter app-only tools, prioritize tools with UIs

- Add getToolVisibility() and isToolVisibleToModel() helpers
- Filter out tools with visibility: ['app'] from host tool list
- Sort tools to show UI-enabled tools first
- Add comprehensive tests for visibility helpers

Author: ochafik

examples/basic-host/src/index.tsx

@@ -1,4 +1,4 @@
-import { getToolUiResourceUri } from "@modelcontextprotocol/ext-apps/app-bridge";
+import { getToolUiResourceUri, isToolVisibleToModel } 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";
@@ -81,10 +81,17 @@ function CallToolPanel({ serversPromise, addToolCall }: CallToolPanelProps) {
   const [selectedTool, setSelectedTool] = useState("");
   const [inputJson, setInputJson] = useState("{}");
 
-  // Only show tools that have a UI resource
+  // Filter out app-only tools, prioritize tools with UIs
   const toolNames = selectedServer
     ? Array.from(selectedServer.tools.values())
-        .filter((tool) => !!getToolUiResourceUri(tool))
+        .filter((tool) => isToolVisibleToModel(tool))
+        .sort((a, b) => {
+          const aHasUi = !!getToolUiResourceUri(a);
+          const bHasUi = !!getToolUiResourceUri(b);
+          if (aHasUi && !bHasUi) return -1;
+          if (!aHasUi && bHasUi) return 1;
+          return a.name.localeCompare(b.name);
+        })
         .map((tool) => tool.name)
     : [];
 
@@ -99,9 +106,17 @@ function CallToolPanel({ serversPromise, addToolCall }: CallToolPanelProps) {
 
   const handleServerSelect = (server: ServerInfo) => {
     setSelectedServer(server);
-    // Only consider tools with UI resources
-    const uiTools = Array.from(server.tools.values()).filter((tool) => !!getToolUiResourceUri(tool));
-    const firstTool = uiTools[0]?.name ?? "";
+    // Filter out app-only tools, prioritize tools with UIs
+    const visibleTools = Array.from(server.tools.values())
+      .filter((tool) => isToolVisibleToModel(tool))
+      .sort((a, b) => {
+        const aHasUi = !!getToolUiResourceUri(a);
+        const bHasUi = !!getToolUiResourceUri(b);
+        if (aHasUi && !bHasUi) return -1;
+        if (!aHasUi && bHasUi) return 1;
+        return a.name.localeCompare(b.name);
+      });
+    const firstTool = visibleTools[0]?.name ?? "";
     setSelectedTool(firstTool);
     // Set input JSON to tool defaults (if any)
     setInputJson(getToolDefaults(server.tools.get(firstTool)));

src/app-bridge.test.ts

@@ -17,6 +17,8 @@ import { App } from "./app";
 import {
   AppBridge,
   getToolUiResourceUri,
+  getToolVisibility,
+  isToolVisibleToModel,
   type McpUiHostCapabilities,
 } from "./app-bridge";
 
@@ -921,3 +923,72 @@ describe("getToolUiResourceUri", () => {
     });
   });
 });
+
+describe("getToolVisibility", () => {
+  it("returns default visibility when no metadata", () => {
+    const tool = {};
+    expect(getToolVisibility(tool)).toEqual(["model", "app"]);
+  });
+
+  it("returns default visibility when no ui metadata", () => {
+    const tool = { _meta: {} };
+    expect(getToolVisibility(tool)).toEqual(["model", "app"]);
+  });
+
+  it("returns default visibility when ui metadata has no visibility", () => {
+    const tool = { _meta: { ui: { resourceUri: "ui://test/app.html" } } };
+    expect(getToolVisibility(tool)).toEqual(["model", "app"]);
+  });
+
+  it("returns app-only visibility", () => {
+    const tool = { _meta: { ui: { visibility: ["app"] } } };
+    expect(getToolVisibility(tool)).toEqual(["app"]);
+  });
+
+  it("returns model-only visibility", () => {
+    const tool = { _meta: { ui: { visibility: ["model"] } } };
+    expect(getToolVisibility(tool)).toEqual(["model"]);
+  });
+
+  it("returns both visibility values", () => {
+    const tool = { _meta: { ui: { visibility: ["model", "app"] } } };
+    expect(getToolVisibility(tool)).toEqual(["model", "app"]);
+  });
+
+  it("filters out invalid visibility values", () => {
+    const tool = { _meta: { ui: { visibility: ["model", "invalid", "app"] } } };
+    expect(getToolVisibility(tool)).toEqual(["model", "app"]);
+  });
+
+  it("returns empty array for invalid visibility type", () => {
+    const tool = { _meta: { ui: { visibility: "model" } } };
+    expect(getToolVisibility(tool)).toEqual(["model", "app"]);
+  });
+});
+
+describe("isToolVisibleToModel", () => {
+  it("returns true when no metadata", () => {
+    const tool = {};
+    expect(isToolVisibleToModel(tool)).toBe(true);
+  });
+
+  it("returns true when visibility includes model", () => {
+    const tool = { _meta: { ui: { visibility: ["model", "app"] } } };
+    expect(isToolVisibleToModel(tool)).toBe(true);
+  });
+
+  it("returns true when visibility is model-only", () => {
+    const tool = { _meta: { ui: { visibility: ["model"] } } };
+    expect(isToolVisibleToModel(tool)).toBe(true);
+  });
+
+  it("returns false when visibility is app-only", () => {
+    const tool = { _meta: { ui: { visibility: ["app"] } } };
+    expect(isToolVisibleToModel(tool)).toBe(false);
+  });
+
+  it("returns false when visibility is empty array", () => {
+    const tool = { _meta: { ui: { visibility: [] } } };
+    expect(isToolVisibleToModel(tool)).toBe(false);
+  });
+});

src/app-bridge.ts

@@ -127,6 +127,63 @@ export function getToolUiResourceUri(tool: {
   return undefined;
 }
 
+/**
+ * Get tool visibility from metadata.
+ *
+ * @param tool - A tool object with optional `_meta` property
+ * @returns The visibility array, or `["model", "app"]` (default) if not specified
+ *
+ * @example
+ * ```typescript
+ * const visibility = getToolVisibility({
+ *   _meta: { ui: { visibility: ["app"] } }
+ * });
+ * // Returns: ["app"]
+ *
+ * // Tool without visibility defaults to visible to both
+ * const visibility = getToolVisibility({});
+ * // Returns: ["model", "app"]
+ * ```
+ */
+export function getToolVisibility(tool: {
+  _meta?: Record<string, unknown>;
+}): ("model" | "app")[] {
+  const uiMeta = tool._meta?.ui as { visibility?: unknown } | undefined;
+  const visibility = uiMeta?.visibility;
+
+  if (Array.isArray(visibility)) {
+    return visibility.filter(
+      (v): v is "model" | "app" => v === "model" || v === "app",
+    );
+  }
+  return ["model", "app"];
+}
+
+/**
+ * Check if a tool is visible to the model (agent).
+ *
+ * Tools with `visibility: ["app"]` are only callable by the app and should
+ * not be shown in tool lists presented to the model.
+ *
+ * @param tool - A tool object with optional `_meta` property
+ * @returns true if the tool is visible to the model
+ *
+ * @example
+ * ```typescript
+ * // Tool visible to model
+ * isToolVisibleToModel({ _meta: { ui: { visibility: ["model", "app"] } } }); // true
+ * isToolVisibleToModel({}); // true (default)
+ *
+ * // App-only tool
+ * isToolVisibleToModel({ _meta: { ui: { visibility: ["app"] } } }); // false
+ * ```
+ */
+export function isToolVisibleToModel(tool: {
+  _meta?: Record<string, unknown>;
+}): boolean {
+  return getToolVisibility(tool).includes("model");
+}
+
 /**
  * Build iframe `allow` attribute string from permissions.
  *