Files
PaperClipAI/packages/shared/src/mcp-apps.ts
T
DottaandClaude Opus 5.5 8af889f612 feat(mcp-apps): view messages with consent, app context, full screen and provider tool icons (#21266)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - MCP Apps (#21119) show interactive widgets from MCP servers, such as
Circleback meeting cards, with the agent's reply in the task chat.
> - The first version deferred three parts of the MCP Apps spec. A
widget could not propose a chat message (`ui/message`). It could not
give the agent context (`ui/update-model-context`). It could not go full
screen.
> - Paperclip also ignored the `icons` that MCP servers declare on tools
(SEP-973).
> - The security review of #21119 showed what these features need from
day one: explicit consent, untrusted-data labels and strict icon
sanitizing.
> - This pull request adds the three host features and provider tool
icons, with those protections built in.
> - The benefit is that widgets can now work with the person and the
agent, not only display data.

## Linked Issues or Issue Description

Refs #21119

**Subsystem affected**
MCP Apps host (task chat widgets), tool catalog, run wake prompt.

**Problem or motivation**
The MCP Apps host refused `ui/message` (-32601), dropped
`ui/update-model-context` and kept every view inline. MCP tool `icons`
were not parsed or shown. So widgets could not ask the agent a
follow-up, the agent could not see what the person selected in a widget,
large widgets were cramped, and tool rows used only generic icons.

**Proposed solution**
Add consent-gated view messages, per-view app context delivered to the
task's next run as untrusted data, a full-screen dialog, and sanitized
provider icons. Details are under "What Changed".

**Alternatives considered**
- Send view messages with a new server route that creates the comment
itself. Rejected: comment creation has many rules (agent chat ownership,
paused conversations, queued delivery, wakeups, receipts). The widget's
Send button uses the same send path as the composer. A small route then
records which view the comment came from.
- Keep the iframe in place for full screen with CSS. Rejected: chat
containers can create containing blocks that break `position: fixed`. A
moved iframe always reloads, so the dialog hosts a new frame instead.

**Roadmap alignment**
Continues the MCP feature work after #21119, #21140 and #21219. It does
not touch the MCP Tasks work (gateway `tools/call` polling and
elicitation).

## What Changed

- **`ui/message`.** The host shows "<App> wants to send: …" with
**Send** and **Dismiss** under the widget (and inside the full-screen
dialog). Nothing is sent before the click. Send posts the text as the
viewer's own comment through the chat's normal send path
(`handleThreadAdd`). `POST
/api/issues/:issueId/mcp-app-views/:viewId/messages` then logs
`issue.mcp_app_message_sent`. It accepts only the caller's own comment
on the same task, matched by `clientRequestId`, from the last 10
minutes. One proposal per view can wait at a time. The view gets `{}`
after the send, or -32000 "Message sending denied" after Dismiss. Only
`user` text up to 8,000 characters is accepted.
- **`ui/update-model-context`.** `PUT
/api/issues/:issueId/mcp-app-views/:viewId/model-context` stores the
latest context per view in `tool_mcp_app_views.model_context` (text
blocks and `structuredContent`, 16 KB at most). Updates are applied in
order and deduped in the browser and on the server. A change logs
`issue.mcp_app_context_updated`, and an empty update clears the context.
The task's next run gets the three most recently updated contexts as an
`## App context (untrusted)` wake-prompt section. The section quotes the
data as JSON and says it is third-party data, not instructions. The read
runs in parallel with the other run preparation and never fails the run.
CLI adapters and the native runner render it through the same
`renderPaperclipWakePrompt`.
- **Who may do this.** Messages and context need a signed-in person with
`issue:comment` on the task. Agents and API keys get 403. Other tasks
and companies get 404. `message` and `updateModelContext` are advertised
in `hostCapabilities` only where the viewer can send messages.
- **Full screen.** The host advertises `availableDisplayModes:
["inline","fullscreen"]` and handles `ui/request-display-mode`. It
honors the view's declared modes and answers with the resulting mode. It
sends `host-context-changed` with `displayMode` and the container (fixed
`height`/`width` in full screen), and again when that container resizes.
A new **Open full screen** control sits next to "Widget from …". Full
screen is a Paperclip dialog that closes with Exit, Escape or the view's
own request.
- **Provider tool icons.** `icons` on MCP tool descriptors are sanitized
into the new `tool_catalog_entries.icons` column, outside the version
hash, so a new icon never quarantines a reviewed tool. Only `https:`
URLs and `data:image/*` URIs are kept, and SVG only as `data:`. A
`data:` icon is at most 32 KB, a URL at most 2,048 characters, with at
most 4 icons per tool. `GET /api/companies/:companyId/tool-icons` lists
them keyed by gateway tool name, in one cached request per chat. Task
chat tool rows and the app's actions list show them through
`ProviderToolIcon`. It renders `<img referrerPolicy="no-referrer">` at a
fixed size and never inlines markup. It checks the source again before
rendering and falls back to the taxonomy icon.
- **Schema.** Migration `0477` adds `tool_catalog_entries.icons`,
`tool_mcp_app_views.model_context` and `model_context_updated_at`, all
nullable.
- **Docs and stories.** `doc/connections/MCP-APPS.md` documents the new
behavior, and the finished items are removed from "Limits and
follow-ups". `Tasks/MCP App views` has new stories: "View asks to send a
message", "Full screen" and "Tool rows with provider icons". The fixture
view now uses `ui/message`, `ui/request-display-mode` and
`ui/update-model-context`.

## Verification

- `pnpm exec vitest run server/src/__tests__/mcp-apps.test.ts
server/src/__tests__/tool-catalog-publication.test.ts
server/src/__tests__/openapi-routes.test.ts
packages/shared/src/mcp-icons.test.ts
packages/shared/src/mcp-apps.test.ts`: pass (embedded Postgres). These
tests cover:
- Context: stored, deduped, logged once, 413 when too large, cleared,
scoped to the task and company, refused for agents (403), and rendered
into the wake prompt as untrusted data.
- Messages: attributed only to the viewer's own recent comment on the
same task. A teammate's comment, an unknown request id or an old comment
gets 404. An agent gets 403.
- Icons: stored sanitized, and the version hash and status do not
change. Another company sees nothing.
- `cd ui && pnpm exec vitest run src/components/mcp-app/
src/components/ProviderToolIcon.test.tsx src/pages/apps/app-detail/`: 69
pass. These tests cover:
- The host protocol for each new method: capabilities, consent wait, one
proposal at a time, invalid input, ordered and deduped context, the size
limit, and the display-mode rules.
  - The consent card (nothing sent without Send).
  - The full-screen dialog (one frame at a time).
  - Icon rendering (no-referrer `img`, no inline SVG, fallback).
- `cd ui && pnpm typecheck` (including Storybook) and `tsc --noEmit` for
the server: clean.
- Red/green: the new route and host tests fail on `master`, where the
routes do not exist and the host answers -32601 or drops updates. The
icon descriptor test failed when the publication write was removed.
- Not run locally: the full suite, and
`packages/adapter-utils/src/server-utils.test.ts › runChildProcess ›
does not crash when the child closes stdin before a delayed write`. That
test times out on this Mac with or without this change, so it is a local
platform issue. CI covers both.

## Risks

- Migration risk is low: three nullable columns, no backfill.
- Every run on a task now does one extra indexed read, in parallel with
the other preparation. Errors are logged and the run continues without
app context.
- If the attribution request fails after the comment is sent, the
comment stays without the `mcp_app_message_sent` activity row. This is
documented.
- Switching between inline and full screen restarts the view, so state
inside the widget resets. This is documented as a limit.
- Icon names shortened with a hash by the gateway (very long names) do
not match, and those rows keep the taxonomy icon.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and
code execution. One subagent (the same model) built the provider-icon
part.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [ ] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 07:32:48 -06:00

400 lines
16 KiB
TypeScript

/**
* MCP Apps (SEP-1865, spec 2026-01-26): interactive `ui://` views that an MCP
* server attaches to a tool. Paperclip is the host: it keeps the tool's UI
* declaration, records each call whose tool has one, and renders the view in a
* sandboxed iframe in the task chat.
*
* https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx
*/
import { z } from "zod";
export const MCP_APPS_EXTENSION_ID = "io.modelcontextprotocol/ui";
export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
export const MCP_APPS_PROTOCOL_VERSION = "2026-01-26";
/** Largest view document Paperclip renders. Larger documents fall back to the plain tool row. */
export const MCP_APP_MAX_HTML_BYTES = 4 * 1024 * 1024;
/** Client capability Paperclip advertises in `initialize` to MCP servers. */
export const MCP_APPS_CLIENT_CAPABILITY = {
[MCP_APPS_EXTENSION_ID]: { mimeTypes: [MCP_APP_MIME_TYPE] },
} as const;
export type McpAppToolVisibility = "model" | "app";
/**
* A tool's normalized `_meta.ui` declaration. `resourceUri` is null for a tool
* that only declares visibility, such as an app-only helper without a view.
*/
export interface McpAppToolUi {
resourceUri: string | null;
visibility: McpAppToolVisibility[];
}
export interface McpAppResourceCsp {
connectDomains?: string[];
resourceDomains?: string[];
frameDomains?: string[];
baseUriDomains?: string[];
}
export interface McpAppResourcePermissions {
camera?: boolean;
microphone?: boolean;
geolocation?: boolean;
clipboardWrite?: boolean;
}
/** The view document plus the resource's `_meta.ui` rendering hints. */
export interface McpAppResource {
uri: string;
html: string;
csp: McpAppResourceCsp;
permissions: McpAppResourcePermissions;
prefersBorder: boolean | null;
}
/** One recorded tool call whose tool declares a view. */
export interface McpAppViewSummary {
id: string;
issueId: string | null;
runId: string | null;
connectionId: string;
applicationName: string;
/** Name the agent called (the gateway tool name). */
toolName: string;
/** The provider's own tool name. */
upstreamToolName: string;
resourceUri: string;
toolInput: Record<string, unknown>;
createdAt: string;
}
export interface McpAppViewDetail extends McpAppViewSummary {
/** The MCP `CallToolResult` sent to the view as `ui/notifications/tool-result`. */
toolResult: McpAppCallToolResult;
resource: McpAppResource;
}
export interface McpAppCallToolResult {
content: unknown[];
structuredContent?: Record<string, unknown>;
_meta?: Record<string, unknown>;
isError?: boolean;
}
/** Body of `POST /api/issues/:issueId/mcp-app-views/:viewId/tool-calls`: a view's `tools/call`. */
export const mcpAppToolCallSchema = z.object({
name: z.string().min(1).max(256),
arguments: z.record(z.string(), z.unknown()).optional(),
}).strict();
export type McpAppToolCallRequest = z.infer<typeof mcpAppToolCallSchema>;
function record(value: unknown): Record<string, unknown> | null {
return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
}
function stringList(value: unknown): string[] | undefined {
if (!Array.isArray(value)) return undefined;
const list = value.filter((item): item is string => typeof item === "string" && item.trim().length > 0).map((item) => item.trim());
return list;
}
/**
* Reads a tool's UI declaration from its `_meta`. Accepts the deprecated flat
* `_meta["ui/resourceUri"]` key, which servers still emit during the
* transition. Visibility is kept even without a view, so an app-only helper
* stays hidden from agents. Returns null when the tool declares neither.
*/
export function readMcpAppToolUi(meta: unknown): McpAppToolUi | null {
const metaRecord = record(meta);
if (!metaRecord) return null;
const ui = record(metaRecord.ui);
const rawUri = typeof ui?.resourceUri === "string"
? ui.resourceUri
: typeof metaRecord["ui/resourceUri"] === "string" ? metaRecord["ui/resourceUri"] as string : null;
const resourceUri = rawUri && rawUri.startsWith("ui://") && rawUri.length <= 2048 ? rawUri : null;
const declared = Array.isArray(ui?.visibility)
? (ui.visibility as unknown[]).filter((item): item is McpAppToolVisibility => item === "model" || item === "app")
: null;
if (!resourceUri && declared === null) return null;
// An explicit list with no valid entries (for example `[]`) grants nothing.
const visibility = declared === null ? ["model", "app"] as McpAppToolVisibility[] : [...new Set(declared)];
return { resourceUri, visibility };
}
export function mcpAppToolVisibleToModel(ui: McpAppToolUi | null | undefined): boolean {
return !ui || ui.visibility.includes("model");
}
export function mcpAppToolCallableFromApp(ui: McpAppToolUi | null | undefined): boolean {
return !ui || ui.visibility.includes("app");
}
/**
* Picks the view document out of a `resources/read` result. The content must be
* the requested `ui://` resource with the MCP Apps mime type; `text` or base64
* `blob` content is accepted.
*/
export function readMcpAppResource(result: unknown, uri: string): McpAppResource | null {
const contents = record(result)?.contents;
if (!Array.isArray(contents)) return null;
for (const item of contents) {
const content = record(item);
if (!content) continue;
if (typeof content.uri === "string" && content.uri !== uri) continue;
const mimeType = typeof content.mimeType === "string" ? content.mimeType.replace(/\s+/g, "").toLowerCase() : "";
if (mimeType !== MCP_APP_MIME_TYPE) continue;
const html = typeof content.text === "string"
? content.text
: typeof content.blob === "string" ? decodeBase64Utf8(content.blob) : null;
if (html === null || html.length === 0) continue;
const ui = record(record(content._meta)?.ui);
const csp = record(ui?.csp);
const permissions = record(ui?.permissions);
return {
uri,
html,
csp: {
connectDomains: stringList(csp?.connectDomains),
resourceDomains: stringList(csp?.resourceDomains),
frameDomains: stringList(csp?.frameDomains),
baseUriDomains: stringList(csp?.baseUriDomains),
},
permissions: {
camera: permissions?.camera === true || record(permissions?.camera) !== null,
microphone: permissions?.microphone === true || record(permissions?.microphone) !== null,
geolocation: permissions?.geolocation === true || record(permissions?.geolocation) !== null,
clipboardWrite: permissions?.clipboardWrite === true || record(permissions?.clipboardWrite) !== null,
},
prefersBorder: typeof ui?.prefersBorder === "boolean" ? ui.prefersBorder : null,
};
}
return null;
}
function decodeBase64Utf8(value: string): string | null {
try {
const binary = globalThis.atob(value);
const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
return new TextDecoder().decode(bytes);
} catch {
return null;
}
}
/**
* A CSP source is accepted only when it is an https origin (optionally with a
* leading `*.` subdomain wildcard). Anything else (keywords, schemes, paths,
* quotes) is dropped so a server cannot widen the policy beyond origins.
*/
export function sanitizeMcpAppCspSource(source: string): string | null {
const trimmed = source.trim();
const match = /^https:\/\/(\*\.)?([a-z0-9-]+(\.[a-z0-9-]+)+)(:\d{1,5})?\/?$/i.exec(trimmed);
if (!match) return null;
return `https://${match[1] ?? ""}${match[2]!.toLowerCase()}${match[4] ?? ""}`;
}
/**
* The CSP for a view: the spec's restrictive default plus only the origins the
* server declared in `_meta.ui.csp`.
*/
export function buildMcpAppCsp(csp: McpAppResourceCsp): string {
const list = (values: string[] | undefined) => (values ?? []).map(sanitizeMcpAppCspSource).filter((value): value is string => value !== null);
const resource = list(csp.resourceDomains);
const connect = list(csp.connectDomains);
const frame = list(csp.frameDomains);
const base = list(csp.baseUriDomains);
const join = (...parts: string[]) => parts.filter(Boolean).join(" ");
return [
"default-src 'none'",
`script-src ${join("'unsafe-inline'", ...resource)}`,
`style-src ${join("'unsafe-inline'", ...resource)}`,
`img-src ${join("data:", "blob:", ...resource)}`,
`font-src ${join("data:", ...resource)}`,
`media-src ${join("data:", "blob:", ...resource)}`,
`connect-src ${connect.length > 0 ? connect.join(" ") : "'none'"}`,
`frame-src ${frame.length > 0 ? frame.join(" ") : "'none'"}`,
`base-uri ${base.length > 0 ? base.join(" ") : "'none'"}`,
"object-src 'none'",
"form-action 'none'",
].join("; ");
}
/* ------------------------------------------------------------------------- */
/* View-to-chat messages (`ui/message`) */
/* ------------------------------------------------------------------------- */
/** Longest message a view may propose to the task chat. */
export const MCP_APP_MESSAGE_MAX_CHARS = 8_000;
/**
* The text of a `ui/message` request (`{ role: "user", content: ContentBlock[] }`).
* Only text blocks are kept. Returns null when there is no text, the role is
* not "user", or the text is too long.
*/
export function readMcpAppMessageText(params: unknown): string | null {
const value = record(params);
if (!value || (value.role !== undefined && value.role !== "user")) return null;
const blocks = Array.isArray(value.content) ? value.content : record(value.content) ? [value.content] : [];
const text = blocks
.map((block) => record(block))
.filter((block): block is Record<string, unknown> => block?.type === "text" && typeof block.text === "string")
.map((block) => block.text as string)
.join("\n\n")
.trim();
if (!text || text.length > MCP_APP_MESSAGE_MAX_CHARS) return null;
return text;
}
/**
* Body of `POST /api/issues/:issueId/mcp-app-views/:viewId/messages`. The
* viewer has already sent the comment through the task's normal comment path;
* this records that it came from the view.
*/
export const mcpAppMessageSentSchema = z.object({
/** The `clientRequestId` the viewer's comment was sent with. */
clientRequestId: z.string().uuid(),
}).strict();
export type McpAppMessageSentRequest = z.infer<typeof mcpAppMessageSentSchema>;
/* ------------------------------------------------------------------------- */
/* View context for the agent (`ui/update-model-context`) */
/* ------------------------------------------------------------------------- */
/** Largest stored context per view, in UTF-8 bytes of its JSON. */
export const MCP_APP_MODEL_CONTEXT_MAX_BYTES = 16 * 1024;
/** The latest context a view gave the agent. Untrusted app data, never instructions. */
export interface McpAppModelContext {
text: string | null;
structuredContent: Record<string, unknown> | null;
}
/** Body of `PUT /api/issues/:issueId/mcp-app-views/:viewId/model-context`. */
export const mcpAppModelContextUpdateSchema = z.object({
content: z.array(z.unknown()).max(64).optional(),
structuredContent: z.record(z.string(), z.unknown()).optional(),
}).strict();
export type McpAppModelContextUpdate = z.infer<typeof mcpAppModelContextUpdateSchema>;
/**
* Normalizes `ui/update-model-context` params: text blocks only, plus the
* structured content. Returns null for an empty update (which clears the
* context) and throws a RangeError when the result exceeds the size limit.
*/
export function normalizeMcpAppModelContext(params: unknown): McpAppModelContext | null {
const value = record(params) ?? {};
const blocks = Array.isArray(value.content) ? value.content : [];
const text = blocks
.map((block) => record(block))
.filter((block): block is Record<string, unknown> => block?.type === "text" && typeof block.text === "string")
.map((block) => block.text as string)
.join("\n\n")
.trim();
const structuredContent = record(value.structuredContent);
const context: McpAppModelContext = {
text: text || null,
structuredContent: structuredContent && Object.keys(structuredContent).length > 0 ? structuredContent : null,
};
if (!context.text && !context.structuredContent) return null;
if (utf8Length(JSON.stringify(context)) > MCP_APP_MODEL_CONTEXT_MAX_BYTES) {
throw new RangeError(`App context is larger than ${MCP_APP_MODEL_CONTEXT_MAX_BYTES} bytes`);
}
return context;
}
function utf8Length(value: string): number {
return new TextEncoder().encode(value).length;
}
/* ------------------------------------------------------------------------- */
/* Tool icons (SEP-973) */
/* ------------------------------------------------------------------------- */
/** A provider icon for a tool, resource or prompt, after sanitizing. */
export interface McpIcon {
src: string;
mimeType?: string;
sizes?: string[];
theme?: "light" | "dark";
}
export const MCP_ICON_MAX_COUNT = 4;
export const MCP_ICON_MAX_URL_LENGTH = 2048;
/** A `data:` icon larger than this is dropped. */
export const MCP_ICON_MAX_DATA_URI_LENGTH = 32 * 1024;
const RASTER_ICON_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp", "image/x-icon", "image/vnd.microsoft.icon"]);
const SVG_MIME_TYPE = "image/svg+xml";
/**
* Accepts only `https:` raster images and `data:image/*` URIs. SVG is allowed
* only inline as `data:`: a remote SVG could change after review. Icons are
* always rendered as `<img referrerPolicy="no-referrer">`, never inlined, so
* an SVG's scripts never run.
*/
export function sanitizeMcpIconSrc(src: unknown, mimeType?: string | null): string | null {
if (typeof src !== "string") return null;
const trimmed = src.trim();
if (/^data:/i.test(trimmed)) {
if (trimmed.length > MCP_ICON_MAX_DATA_URI_LENGTH) return null;
const match = /^data:(image\/[a-z0-9.+-]+)(;[a-z0-9=.+-]+)*,/i.exec(trimmed);
if (!match) return null;
const type = match[1]!.toLowerCase();
return type === SVG_MIME_TYPE || RASTER_ICON_MIME_TYPES.has(type) ? trimmed : null;
}
if (trimmed.length > MCP_ICON_MAX_URL_LENGTH) return null;
let url: URL;
try {
url = new URL(trimmed);
} catch {
return null;
}
if (url.protocol !== "https:" || url.username || url.password) return null;
if (mimeType && mimeType.toLowerCase() === SVG_MIME_TYPE) return null;
if (/\.svgz?$/i.test(url.pathname)) return null;
return url.toString();
}
/** Reads and sanitizes an MCP `icons` array. Returns null when none survive. */
export function readMcpIcons(value: unknown): McpIcon[] | null {
if (!Array.isArray(value)) return null;
const icons: McpIcon[] = [];
for (const item of value) {
if (icons.length >= MCP_ICON_MAX_COUNT) break;
const icon = record(item);
if (!icon) continue;
const rawMime = typeof icon.mimeType === "string" ? icon.mimeType.trim().toLowerCase() : null;
const mimeType = rawMime && (rawMime === SVG_MIME_TYPE || RASTER_ICON_MIME_TYPES.has(rawMime)) ? rawMime : null;
if (rawMime && !mimeType) continue;
const src = sanitizeMcpIconSrc(icon.src, mimeType);
if (!src) continue;
const sizes = Array.isArray(icon.sizes)
? icon.sizes.filter((size): size is string => typeof size === "string" && /^(any|\d{1,4}x\d{1,4})$/i.test(size)).slice(0, 8)
: [];
icons.push({
src,
...(mimeType ? { mimeType } : {}),
...(sizes.length > 0 ? { sizes } : {}),
...(icon.theme === "light" || icon.theme === "dark" ? { theme: icon.theme } : {}),
});
}
return icons.length > 0 ? icons : null;
}
/** The icon to show for a theme: a matching or theme-less icon, preferring small sizes. */
export function pickMcpIcon(icons: readonly McpIcon[] | null | undefined, theme: "light" | "dark"): McpIcon | null {
if (!icons?.length) return null;
const candidates = icons.filter((icon) => !icon.theme || icon.theme === theme);
const pool = candidates.length > 0 ? candidates : icons;
const smallest = (icon: McpIcon) => Math.min(...(icon.sizes ?? ["any"]).map((size) => {
const match = /^(\d+)x/i.exec(size);
return match ? Math.abs(Number(match[1]) - 32) : 1_000;
}));
return [...pool].sort((a, b) => smallest(a) - smallest(b))[0] ?? null;
}