core: add AppInfo + extractAppInfo() to core/mcp/apps.ts

[cliffhall]

Summary

Add a machine-readable app summary to core/mcp/apps.ts: an AppInfo interface plus an extractAppInfo() function that merges a tool's _meta.ui (resourceUri, visibility) with the linked resource's _meta.ui (csp, permissions, domain, prefersBorder), so any client can report an MCP App's security posture without rendering it.

Why

Shared plumbing for the programmatic-review path. The CLI --app-info mode (follow-up issue) and integration tests need one canonical answer to "does this tool have an app, and what does it ask for?" — today that logic doesn't exist outside the web renderer.

Reference implementation (PR #1510)

Re-implement informed by these changes at 33fac3f:

• core/mcp/apps.ts — AppInfo interface, extractAppInfo(), helpers readUiMeta(), normalizeResourceUri(), findResourceContent() (+123 lines)
• clients/web/src/test/core/apps.test.ts — unit tests (+155 lines)

Depends on

Nothing — Wave 1 foundation, parallel-safe. Unblocks the mcp_app_demo test-server preset and CLI --app-info.

Notes

• Coverage gate: ≥90 on all four dimensions for core/mcp/apps.ts (measured by the web suite; test at clients/web/src/test/core/apps.test.ts).
• No any types — the PR's version uses concrete interfaces; keep that.

Part of the PR #1510 decomposition (see tracking issue).

[cliffhall]

Smoke test & AGENTS.md audit — PR #1584

Reviewed branch v2/1556-core-appinfo (HEAD ee4b232a), diffed against origin/v2/main. Change is scoped to core/mcp/apps.ts (+137) and its test clients/web/src/test/core/apps.test.ts (+157).

Smoke test

extractAppInfo() is a pure function (no React/DOM), so I exercised it directly with tsx (no Playwright) against representative inputs and printed the returned AppInfo objects as proof. The script imports the real core/mcp/apps.ts and resolves @modelcontextprotocol/ext-apps / sdk from clients/web.

=== (a) App tool + UI resource merged ===
{
  "hasApp": true,
  "toolName": "chart_view",
  "resourceUri": "ui://widget/chart.html",
  "visibility": [ "model" ],
  "csp": { "connect-src": [ "https://api.example.com" ] },
  "permissions": { "camera": false, "geolocation": true },
  "domain": "example.com",
  "prefersBorder": true,
  "resourceMimeType": "text/html;profile=mcp-app"
}

=== (b) Non-App tool ===
{
  "hasApp": false,
  "toolName": "add_numbers"
}

=== (c) Malformed/echoed URI (normalized match: trailing slash + case) ===
{
  "hasApp": true,
  "toolName": "chart_view",
  "resourceUri": "ui://widget/chart.html",
  "visibility": [ "model" ],
  "permissions": { "microphone": true },
  "domain": "normalized.example.com",
  "resourceMimeType": "text/html;profile=mcp-app"
}

=== (c2) Malformed resourceUri (not ui://) → throws ===
Invalid UI resource URI: "https://evil.example/x"

=== (d) App tool, no resource read ===
{
  "hasApp": true,
  "toolName": "chart_view",
  "resourceUri": "ui://widget/chart.html",
  "visibility": [ "model" ]
}

Observations, all as designed:

• (a) Tool-level _meta.ui (resourceUri + visibility) merges with the UI resource's _meta.ui (csp/permissions/domain/prefersBorder) plus the content block's mimeType. Correct — per spec, security posture lives on the resource, not the tool.
• (b) Non-App tool → { hasApp: false, toolName }.
• (c) When the server echoes the URI back in a different form (case + trailing slash), the normalized-match / single-block fallback still locates the content block and pulls its _meta.ui.
• (c2) A resourceUri that isn't ui://… throws (surfacing the ext-apps error) rather than silently dropping the tool.
• (d) App tool with no resource read → hasApp: true with only the tool-level fields.

AGENTS.md compliance

• Mantine idioms: N/A — this is core/ (isomorphic, no React/JSX/Mantine surface).

• TypeScript: PASS. git diff origin/v2/main...HEAD contains no any, no as any, and no eslint-disable/@ts-ignore/@ts-expect-error/v8 ignore suppressions. _meta.ui is read structurally: a local WithUiMeta = { _meta?: { ui?: unknown } } shape plus a UiMetaShape interface, narrowed from unknown in readUiMeta() via typeof === "object" guards and targeted type assertions (as WithUiMeta, as UiMetaShape) — not any. The file documents why the named ext-apps types (McpUiToolMeta/McpUiResourceMeta) can't be imported under NodeNext (extensionless re-export in the package .d.ts) and leaves a TODO to switch once upstream fixes it.

• Coverage (≥90 all four dims): PASS for the file under review. core/mcp/apps.ts is measured by the web suite:

  File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
  apps.ts   |     100 |   97.05  |    100  |    100  | 161
  

  100 / 97.05 / 100 / 100 — clears the 90 gate on every dimension. (Line 161 is the one uncovered branch: the readUiMeta(content) ?? readUiMeta(resource) result-level fallback arm.)

  Note: the full npm run test:coverage run reported 3 failing test files — ServerConfigModal.test.tsx, InspectorView.test.tsx (localStorage persistence), and inspectorClient.test.ts (integration message-matching). All three are unrelated to this PR (no apps.ts dependency) and are pre-existing timing/localStorage flakes; the apps numbers above were captured from a scoped, all-green run of src/test/core/apps.test.ts (25 passed).

Verdict: PASS

Clean, well-documented pure function; smoke output matches intent on all paths (merge, non-app, normalized-URI recovery, malformed-URI throw); no TS violations; per-file coverage clears the gate.

Custom smoke-test script

/**
 * Smoke test for core/mcp/apps.ts extractAppInfo() (PR #1584 / issue #1556).
 * Run with tsx from clients/web so package imports resolve.
 *   (imported ../../core/mcp/apps.ts; not committed)
 */
import { extractAppInfo, type AppInfo } from "../../core/mcp/apps.ts";
import type { ReadResourceResult, Tool } from "@modelcontextprotocol/sdk/types.js";

function print(label: string, info: AppInfo): void {
  console.log(`\n=== ${label} ===`);
  console.log(JSON.stringify(info, null, 2));
}

// (a) App tool with _meta.ui + linked UI resource carrying _meta.ui.
const appTool: Tool = {
  name: "chart_view",
  inputSchema: { type: "object" },
  _meta: { ui: { resourceUri: "ui://widget/chart.html", visibility: ["model"] } },
};
const uiResource: ReadResourceResult = {
  contents: [
    {
      uri: "ui://widget/chart.html",
      mimeType: "text/html;profile=mcp-app",
      text: "<html><body>chart</body></html>",
      _meta: {
        ui: {
          csp: { "connect-src": ["https://api.example.com"] },
          permissions: { camera: false, geolocation: true },
          domain: "example.com",
          prefersBorder: true,
        },
      },
    },
  ],
};
print("(a) App tool + UI resource merged", extractAppInfo(appTool, uiResource));

// (b) Non-App tool → { hasApp:false, toolName }.
print("(b) Non-App tool", extractAppInfo({ name: "add_numbers", inputSchema: { type: "object" } }));

// (c) Server echoes URI in a different form (case + trailing slash).
const normResource: ReadResourceResult = {
  contents: [
    {
      uri: "UI://Widget/Chart.html/",
      mimeType: "text/html;profile=mcp-app",
      text: "<html></html>",
      _meta: { ui: { domain: "normalized.example.com", permissions: { microphone: true } } },
    },
  ],
};
print("(c) Malformed/echoed URI (normalized match)", extractAppInfo(appTool, normResource));

// (c2) resourceUri that is not ui:// → should THROW.
const badTool: Tool = {
  name: "bad_app",
  inputSchema: { type: "object" },
  _meta: { ui: { resourceUri: "https://evil.example/x" } },
};
try {
  extractAppInfo(badTool);
  console.log("\n=== (c2) UNEXPECTED: no throw");
} catch (e) {
  console.log(`\n=== (c2) Malformed resourceUri (throws) ===\n${(e as Error).message}`);
}

// (d) App tool with no resource passed.
print("(d) App tool, no resource read", extractAppInfo(appTool));

[cliffhall]

🔗 Implemented by PR #1584. Its code is already integrated into the Wave 1 rollup branch 1579-wave-1 (see rollup PR #1601 / verification #1600). #1584 currently targets v2/main and will auto-show as Merged once the rollup lands in v2/main. The Development panel doesn't link it now because the closing keyword is on a non-default base branch.