feat(core): add AppInfo + extractAppInfo() to core/mcp/apps.ts (closes #1556)

Add a machine-readable summary of an MCP App's UI metadata: the AppInfo
interface plus extractAppInfo(), which merges a tool's _meta.ui
(resourceUri, visibility) with the linked UI resource's _meta.ui (csp,
permissions, domain, prefersBorder, mimeType). Content-block matching is
exact-URI first, then a lowercase + trailing-slash normalized match, then
a single-block fallback since resources/read returns the requested
resource by definition. Shared plumbing for the programmatic-review path
(CLI --app-info, integration tests) without rendering the app.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S3fTN8H3R8YV4yUGvZjYnX

core/mcp/apps.ts

@@ -1,5 +1,8 @@
 import { getToolUiResourceUri } from "@modelcontextprotocol/ext-apps/app-bridge";
-import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type {
+  ReadResourceResult,
+  Tool,
+} from "@modelcontextprotocol/sdk/types.js";
 
 /**
  * Returns the UI resource URI advertised by an MCP App tool, or `undefined`
@@ -35,3 +38,121 @@ export function getAppResourceUri(tool: Tool): string | undefined {
 export function isAppTool(tool: Tool): boolean {
   return getAppResourceUri(tool) !== undefined;
 }
+
+/**
+ * Machine-readable summary of an MCP App's UI metadata, combining what the
+ * tool advertises (`resourceUri`, `visibility`) with what the UI resource
+ * itself declares (`csp`, `permissions`, `domain`, `prefersBorder`). Emitted by
+ * the CLI's `--app-info` mode and reusable by any client that needs to surface
+ * an app's security posture without rendering it.
+ */
+export interface AppInfo {
+  hasApp: boolean;
+  toolName: string;
+  resourceUri?: string;
+  visibility?: readonly string[];
+  /** From the UI resource's `_meta.ui` (per spec, csp/permissions/domain live on the resource, not the tool). Absent when the resource was not read. */
+  csp?: Readonly<Record<string, unknown>>;
+  permissions?: Readonly<Record<string, unknown>>;
+  domain?: string;
+  prefersBorder?: boolean;
+  resourceMimeType?: string;
+}
+
+type WithUiMeta = { _meta?: { ui?: unknown } };
+
+/**
+ * Structural shape for `_meta.ui` carriers — the ext-apps package's named
+ * types (`McpUiToolMeta`, `McpUiResourceMeta`) are not importable under
+ * NodeNext module resolution because of an extensionless re-export in the
+ * package's `.d.ts`, so we read the fields structurally instead. The values
+ * pass through verbatim into {@link AppInfo}; callers can narrow them against
+ * the published Zod schemas if they need strict typing.
+ */
+interface UiMetaShape {
+  visibility?: readonly string[];
+  csp?: Record<string, unknown>;
+  permissions?: Record<string, unknown>;
+  domain?: string;
+  prefersBorder?: boolean;
+}
+
+function readUiMeta(carrier: WithUiMeta | undefined): UiMetaShape | undefined {
+  const ui = carrier?._meta?.ui;
+  return ui !== null && typeof ui === "object"
+    ? (ui as UiMetaShape)
+    : undefined;
+}
+
+/**
+ * Normalizes a `ui://…` URI for comparison so trivial server-side differences
+ * (case, trailing slash) don't cause us to miss the resource block and silently
+ * drop its `_meta.ui` (csp/permissions/domain). `ui://` is a non-special scheme
+ * so the WHATWG URL parser preserves case and trailing slashes verbatim — we
+ * apply a targeted lowercase + single trailing-slash strip instead.
+ */
+function normalizeResourceUri(uri: string): string {
+  const lowered = uri.toLowerCase();
+  return lowered.endsWith("/") ? lowered.slice(0, -1) : lowered;
+}
+
+/**
+ * Locates the content block in a `resources/read` result that corresponds to
+ * the requested UI resource. Tries exact match, then normalized-URI match, then
+ * falls back to the sole content block when there is only one — `resources/read`
+ * by definition returns the content for the URI we asked for, so a single-block
+ * response is the right block even when the server echoes the URI back in a
+ * slightly different form.
+ */
+function findResourceContent(
+  resource: ReadResourceResult,
+  requestedUri: string,
+): ReadResourceResult["contents"][number] | undefined {
+  const exact = resource.contents.find((c) => c.uri === requestedUri);
+  if (exact) return exact;
+  const norm = normalizeResourceUri(requestedUri);
+  const normalized = resource.contents.find(
+    (c) => normalizeResourceUri(c.uri) === norm,
+  );
+  if (normalized) return normalized;
+  return resource.contents.length === 1 ? resource.contents[0] : undefined;
+}
+
+/**
+ * Build an {@link AppInfo} from a tool definition and (optionally) the
+ * `resources/read` result for its UI resource. Per the spec, `csp` /
+ * `permissions` / `domain` belong on the resource — not the tool — so a caller
+ * that wants the security posture must read the resource and pass it here.
+ *
+ * Returns `{ hasApp: false, toolName }` for non-App tools. Throws on a
+ * malformed `resourceUri` for the same reason {@link getAppResourceUri} does.
+ */
+export function extractAppInfo(
+  tool: Tool,
+  resource?: ReadResourceResult,
+): AppInfo {
+  const resourceUri = getAppResourceUri(tool);
+  if (resourceUri === undefined) {
+    return { hasApp: false, toolName: tool.name };
+  }
+  const toolUi = readUiMeta(tool as WithUiMeta);
+  const content = resource && findResourceContent(resource, resourceUri);
+  const resourceUi =
+    readUiMeta(content as WithUiMeta | undefined) ??
+    readUiMeta(resource as WithUiMeta | undefined);
+  return {
+    hasApp: true,
+    toolName: tool.name,
+    resourceUri,
+    ...(toolUi?.visibility ? { visibility: toolUi.visibility } : {}),
+    ...(resourceUi?.csp ? { csp: resourceUi.csp } : {}),
+    ...(resourceUi?.permissions ? { permissions: resourceUi.permissions } : {}),
+    ...(resourceUi?.domain ? { domain: resourceUi.domain } : {}),
+    ...(resourceUi?.prefersBorder !== undefined
+      ? { prefersBorder: resourceUi.prefersBorder }
+      : {}),
+    ...(typeof content?.mimeType === "string"
+      ? { resourceMimeType: content.mimeType }
+      : {}),
+  };
+}