Effect 4.0 MCP 服务器图标支持详解：基于 `McpSchema.Icon` 为 Server、资源与工具配置图标

Effect 4.0 MCP 服务器图标支持详解基于McpSchema.Icon为 Server、资源与工具配置图标【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect本篇文章以 Effect 仓库中 changeset 文档 add-mcp-icons.md 为主体系统讲解effect/ai模块中 MCPModel Context Protocol服务器新增的图标Icon能力MCP 服务器现在可以为服务器信息server information、资源resources、资源模板resource templates、提示词prompts与工具tools提供图标且每个图标可声明来源 URI、MIME 类型、支持的尺寸以及浅色/深色主题。读完本文你将掌握McpSchema.Icon的完整字段语义、它在五种场景中的挂载位置以及如何在自己实现的 MCP 服务器中为 serverInfo、资源、提示词和工具配置图标并理解其从注册到协议下发的完整数据流。一、功能背景为什么 MCP 需要图标MCPModel Context Protocol让宿主应用Host能够枚举并展示远端服务器提供的资源、提示词与工具。在实际产品界面中服务器、资源、提示词和工具通常会以列表或树状结构呈现而图标是提升这些条目可辨识度的关键视觉信息——例如用主题图标标识某种工具的用途或在深色/浅色界面下分别提供适配的图标资源。本次 changeset 引入的能力正是为此服务MCP 服务器可以借助McpSchema.Icon为其服务器信息、资源、资源模板、提示词和工具提供图标描述。每个图标都可以声明图标图片的来源 URIsource URI图标的 MIME 类型支持的尺寸supported sizes适用的浅色light或深色dark主题。这样客户端在渲染这些 MCP 条目时就能根据自身界面主题与尺寸需求从服务器给出的多个图标中选择最合适的一个。二、核心数据结构McpSchema.Icon图标能力的核心类型是Icon定义于 packages/effect/src/unstable/ai/McpSchema.ts#L321-L338属于category schemas标注为since 4.0.0export class Icon extends Schema.ClassIcon(effect/ai/McpSchema/Icon)({ /** * URI containing the icon image. */ src: Schema.String, /** * MIME type of the icon, when known. */ mimeType: optional(Schema.String), /** * Sizes supported by the icon, such as 48x48 or any. */ sizes: optional(Schema.Array(Schema.String)), /** * Color theme for which the icon was designed. */ theme: optional(Schema.Literals([light, dark])) }) {}字段语义如下字段类型必填含义与取值约定srcSchema.String是图标图片所在的 URI客户端据此加载图标内容。mimeTypeoptional(Schema.String)否图标文件的 MIME 类型when known即已知时提供例如image/png、image/svgxml。sizesoptional(Schema.Array(Schema.String))否该图标支持的尺寸源码注释给出的示例为48x48或any可声明多个。themeoptional(Schema.Literals([light, dark]))否该图标所适配的颜色主题取值限定为light与dark省略表示主题无关。从字段设计可以看出图标描述遵循宽松、渐进增强的原则src是唯一必填字段其余均可选。服务器可以只提供一个通用图标也可以同时提供多尺寸、多主题的图标集合由客户端按需消费。三、图标可挂载的五类对象在 McpSchema.ts 中icons字段类型为optional(Schema.Array(Icon))被挂载在以下五类 schema 上服务器信息ImplementationMcpSchema.ts#L346-L353 中Implementation描述 MCP 实现的名字与版本新增了icons字段用于在握手阶段向客户端声明服务器本身的图标。资源ResourceMcpSchema.ts#L930-L932 的Resource上带有注释 Icons that clients can display for this resource.即客户端可为该资源展示的图标。资源模板ResourceTemplateMcpSchema.ts#L990-L992 的ResourceTemplate同样携带icons字段。提示词PromptMcpSchema.ts#L1260-L1262 的Prompt上带有 Icons that clients can display for this prompt. 注释。工具ToolMcpSchema.ts#L1637-L1639 的Tool上带有 Icons that clients can display for this tool. 注释。也就是说本次图标能力覆盖了 MCP 服务器对外暴露的所有主要可展示条目类型客户端在渲染服务器列表、资源浏览器、提示词面板和工具选择器时均可读取对应的icons数组。四、协议层面的图标 Schema2025-11-25 wire 版本McpSchema.Icon是 Effect 对外暴露的公共类型在内部针对 MCP 协议版本2025-11-25其 wire schema 定义于 packages/effect/src/unstable/ai/internal/mcpSchema/v2025_11_25.ts#L24-L29export const Icon Schema.Struct({ src: Schema.String, mimeType: optional(Schema.String), sizes: optional(Schema.Array(Schema.String)), theme: optional(Schema.Literals([light, dark])) })该文件是2025-06-18协议版本的 dated deltaexport * from ./v2025_06_18.ts继承全部既有 schema并在此基础上为五类对象扩展了图标字段见同一文件 L32-L37、L59-L63、L66-L70、L73-L76、L124-L127Implementation在既有字段之上扩展了description、websiteUrl与iconsResource与ResourceTemplate扩展了annotations与iconsPrompt扩展了iconsTool扩展了icons。可见协议侧的字段结构与公共 API 保持一致保证 Effect 声明的图标能力可以被标准 MCP 客户端正确解析。五、实操在自己的 MCP 服务器中配置图标5.1 为服务器信息serverInfo配置图标启动 MCP 服务器使用McpServer.run其options已接受icons?: ReadonlyArrayMcpSchema.Icon参数见 packages/effect/src/unstable/ai/McpServer.ts#L673-L699。结合McpSchema.Icon.make可以这样配置import * as McpSchema from effect/ai/McpSchema import * as McpServer from effect/ai/McpServer const server McpServer.run({ name: example-server, version: 1.0.0, description: An example MCP server with icon support, websiteUrl: https://example.com, icons: [ McpSchema.Icon.make({ src: https://example.com/icons/server.png, mimeType: image/png, sizes: [48x48, 96x96], theme: light }), McpSchema.Icon.make({ src: https://example.com/icons/server-dark.png, mimeType: image/png, sizes: [48x48, 96x96], theme: dark }) ], protocols: [...] // 传入你的协议适配器 })在McpServer.ts中run的签名将icons显式列为顶层选项L678、L690、L707这些图标最终会进入握手阶段返回的serverInfo。5.2 为资源、资源模板、提示词与工具配置图标McpServer.ts中注册各类实体的 API 同样接收icons注册资源 / 资源模板的 API对应 McpServer.ts#L1374、L1387、L1429 的icons参数注册工具与提示词的 API对应 McpServer.ts#L1540 的icons参数。以工具为例注册时可在工具定义上附带图标import * as Tool from effect/ai/Tool import * as McpSchema from effect/ai/McpSchema const myTool Tool.define({ name: get-weather, title: Get Weather, description: Fetch the current weather for a city, input: WeatherInput, output: WeatherOutput }, { icons: [ McpSchema.Icon.make({ src: https://example.com/icons/weather.svg, mimeType: image/svgxml, sizes: [any], theme: light }) ] })资源、资源模板与提示词的写法类似——在各自的定义选项中传入icons数组即可。所有字段中仅src必填最简单的图标描述甚至可以只写一行McpSchema.Icon.make({ src: https://example.com/icons/weather.png })六、数据流图标如何从注册到达客户端图标能力贯穿服务器初始化与列表枚举两条链路源码中均有明确证据。1初始化initialize阶段——服务器信息图标下发在 packages/effect/src/unstable/ai/internal/mcpRuntime.ts#L516-L522 中服务器处理握手时会构造PublicMcpSchema.Implementation.make({ ... })其中显式包含icons: options.serverInfo.iconsserverInfo接口在 mcpRuntime.ts#L122-L129 定义了icons?: ReadonlyArrayPublicMcpSchema.Icon字段。也就是说run选项中配置的服务器图标会在 initialize 响应中随serverInfo返回给客户端。2tools/list 阶段——工具图标下发在 packages/effect/src/unstable/ai/internal/mcpProtocol/v2025_11_25.ts#L283-L308 的tools/list处理器中服务器把内部工具列表映射为协议层的McpSchema.Tool.make({ ... })并原样传递icons: tool.icons。客户端调用tools/list时即可拿到每个工具携带的图标数组。资源resources/list、资源模板resources/templates/list与提示词prompts/list的响应结构同样来自带icons字段的 schema遵循同一套序列化规则。七、使用建议与注意事项主题适配theme仅接受light与dark两个字面量由Schema.Literals([light, dark])约束非法取值会在编码/解码时被 schema 校验拒绝。若图标与主题无关直接省略该字段即可。多尺寸声明sizes是字符串数组可按需列出如16x16、32x32、48x48等或使用语义值any表示不限定尺寸。MIME 类型mimeType可选但建议提供帮助客户端在不嗅探内容的情况下正确解码图标常见取值如image/png、image/svgxml、image/webp。版本与协议适配图标字段出现在2025-11-25协议的 dated wire schema 中见 v2025_11_25.ts不同协议版本适配器对icons的支持以各自 schema 为准公共 API 层面的McpSchema.Icon标注为since 4.0.0因此该能力面向 Effect 4.0 及以上版本。渐进增强icons在所有位置均为可选字段未配置图标的服务器或条目依然完全兼容——旧客户端忽略该字段新客户端则能获得更丰富的界面信息。八、小结本次 changeset 为 Effect 的 MCP 服务器补齐了完整的图标描述能力从公共 API 的 McpSchema.Icon到2025-11-25协议层的 wire schema再到McpServer.run与资源/提示词/工具注册接口的icons参数以及initialize、tools/list等处理链路中的下发逻辑均已在当前仓库中落地。借助该能力MCP 服务器可以提供多尺寸、多主题的图标集合让宿主应用在浅色/深色界面中都能呈现清晰、一致的视觉标识。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考