企业官网建设流程全解析

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模块中 MCP（Model Context Protocol）服务器新增的图标（Icon）能力：MCP 服务器现在可以为服务器信息（server information）、资源（resources）、资源模板（resource templates）、提示词（prompts）与工具（tools）提供图标，且每个图标可声明来源 URI、MIME 类型、支持的尺寸以及浅色/深色主题。读完本文，你将掌握McpSchema.Icon的完整字段语义、它在五种场景中的挂载位置，以及如何在自己实现的 MCP 服务器中为 serverInfo、资源、提示词和工具配置图标，并理解其从注册到协议下发的完整数据流。

一、功能背景：为什么 MCP 需要图标

MCP（Model Context Protocol）让宿主应用（Host）能够枚举并展示远端服务器提供的资源、提示词与工具。在实际产品界面中，服务器、资源、提示词和工具通常会以列表或树状结构呈现，而图标是提升这些条目可辨识度的关键视觉信息——例如用主题图标标识某种工具的用途，或在深色/浅色界面下分别提供适配的图标资源。

本次 changeset 引入的能力正是为此服务：MCP 服务器可以借助McpSchema.Icon为其服务器信息、资源、资源模板、提示词和工具提供图标描述。每个图标都可以声明：

• 图标图片的来源 URI（source URI）；
• 图标的 MIME 类型；
• 支持的尺寸（supported sizes）；
• 适用的浅色（light）或深色（dark）主题。

这样，客户端在渲染这些 MCP 条目时，就能根据自身界面主题与尺寸需求，从服务器给出的多个图标中选择最合适的一个。

二、核心数据结构：McpSchema.Icon

图标能力的核心类型是Icon，定义于 packages/effect/src/unstable/ai/McpSchema.ts#L321-L338，属于@category schemas，标注为@since 4.0.0：

export class Icon extends Schema.Class<Icon>("@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"])) }) {}

字段语义如下：

从字段设计可以看出，图标描述遵循宽松、渐进增强的原则：src是唯一必填字段，其余均可选。服务器可以只提供一个通用图标，也可以同时提供多尺寸、多主题的图标集合，由客户端按需消费。

三、图标可挂载的五类对象

在 McpSchema.ts 中，icons字段（类型为optional(Schema.Array(Icon))）被挂载在以下五类 schema 上：

1. 服务器信息（Implementation）：McpSchema.ts#L346-L353 中Implementation（描述 MCP 实现的名字与版本）新增了icons字段，用于在握手阶段向客户端声明服务器本身的图标。
2. 资源（Resource）：McpSchema.ts#L930-L932 的Resource上带有注释 "Icons that clients can display for this resource."，即客户端可为该资源展示的图标。
3. 资源模板（ResourceTemplate）：McpSchema.ts#L990-L992 的ResourceTemplate同样携带icons字段。
4. 提示词（Prompt）：McpSchema.ts#L1260-L1262 的Prompt上带有 "Icons that clients can display for this prompt." 注释。
5. 工具（Tool）：McpSchema.ts#L1637-L1639 的Tool上带有 "Icons that clients can display for this tool." 注释。

也就是说，本次图标能力覆盖了 MCP 服务器对外暴露的所有主要可展示条目类型，客户端在渲染服务器列表、资源浏览器、提示词面板和工具选择器时均可读取对应的icons数组。

四、协议层面的图标 Schema（2025-11-25 wire 版本）

McpSchema.Icon是 Effect 对外暴露的公共类型；在内部，针对 MCP 协议版本2025-11-25，其 wire schema 定义于 packages/effect/src/unstable/ai/internal/mcpSchema/v2025_11_25.ts#L24-L29：

export 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 delta（export * from "./v2025_06_18.ts"继承全部既有 schema），并在此基础上为五类对象扩展了图标字段（见同一文件 L32-L37、L59-L63、L66-L70、L73-L76、L124-L127）：

• Implementation在既有字段之上扩展了description、websiteUrl与icons；
• Resource与ResourceTemplate扩展了annotations与icons；
• Prompt扩展了icons；
• Tool扩展了icons。

可见协议侧的字段结构与公共 API 保持一致，保证 Effect 声明的图标能力可以被标准 MCP 客户端正确解析。

五、实操：在自己的 MCP 服务器中配置图标

5.1 为服务器信息（serverInfo）配置图标

启动 MCP 服务器使用McpServer.run，其options已接受icons?: ReadonlyArray<McpSchema.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/svg+xml", 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.icons（serverInfo接口在 mcpRuntime.ts#L122-L129 定义了icons?: ReadonlyArray<PublicMcpSchema.Icon>字段）。也就是说，run选项中配置的服务器图标会在 initialize 响应中随serverInfo返回给客户端。

（2）tools/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/svg+xml、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