mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-17 04:21:24 +01:00
## 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>
400 lines
16 KiB
TypeScript
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;
|
|
}
|