SEP-973: 为实现、资源、工具和提示词暴露额外元数据

为实现、资源、工具和提示词暴露额外元数据

最终版

标准轨道

字段	值
SEP	973
标题	为实现、资源、工具和提示词暴露额外元数据
状态	最终版
类型	标准轨道
创建日期	2025-07-15
作者	@jesselumarie
赞助者	无
PR	#973

---

摘要

本 SEP 提议添加两个可选字段——icons 和 websiteUrl。icons 和 websiteUrl 将被添加到 Implementation 模式中，以便客户端能够直观地识别第三方实现并直接链接到其文档。icons 参数也将被添加到 Tool、Resource 和 Prompt 模式中。虽然这对于所有实现的服务器和客户端都可以使用，但我们预计它最初将用于服务器提供的实现。

动机

当前状态

当前的实现仅暴露命名空间元数据，迫使客户端显示没有视觉提示的通用标签。

提议状态

提议的实现将允许我们添加视觉辅助功能和文档链接，使得更容易直观地识别哪些服务器/客户端正在提供实现，例如斜杠命令界面中的工具：

• 视觉辅助： 图标让用户立即清楚正在使用哪个工具或资源源。
• 可发现性： 指向文档的链接（websiteUrl）允许客户端通过一次点击将用户引导至更多信息。

理由

此设计建立在 Web 清单（MDN）的先前工作基础上，并整合了社区反馈：

• 合并 PR： 将 PR #417 和 PR #862 的更改合并为一个连贯的增强功能。
• 灵活的图标尺寸： 支持多种图标尺寸（例如 48x48、96x96 或 any 用于矢量格式），以适应不同的客户端 UI 需求。
• 可选字段： 通过将两个字段都设为可选，现有实现保持完全兼容。

规范

扩展 Implementation 对象如下：

/**
 * 一个指向图标 URL 或 base64 编码数据 URI 的 url
 *
 * 支持渲染图标的客户端必须至少支持以下 MIME 类型：
 * - image/png - PNG 图像（安全，通用兼容）
 * - image/jpeg (and image/jpg) - JPEG 图像（安全，通用兼容）
 *
 * 支持渲染图标的客户端还应该支持：
 * - image/svg+xml - SVG 图像（可缩放但需要安全措施）
 * - image/webp - WebP 图像（现代，高效格式）
 */
export interface Icon {
  /**
   * 一个指向图标资源的标准 URI。
   *
   * 使用者必须采取措施确保提供图标的 URL 来自
   * 与客户端/服务器相同的域或受信任的域。
   *
   * 使用者在使用 SVG 时必须采取适当的预防措施，因为它们可能包含
   * 可执行的 JavaScript
   *
   * @format uri
   */
  src: string;
  /** 如果服务器的 MIME 类型缺失或通用，则为可选覆盖。 */
  mimeType?: string;
  /** 例如 "48x48", "any"（用于 SVG），或 "48x48 96x96" */
  sizes?: string;
}

/**
 * 描述 MCP 实现
 */
export interface Implementation extends BaseMetadata {
  version: string;
  /**
   * 此实现的可选图标列表。
   * 客户端可以使用此列表在用户界面中显示实现。
   * 每个图标应有一个 `kind` 属性，指定它是数据表示还是 URL 源，一个 `src` 属性指向图标文件或数据表示，并且可能还包括 `mimeType` 和 `sizes` 属性。
   * `mimeType` 属性应为图标文件的有效 MIME 类型，例如 "image/png" 或 "image/svg+xml"。
   * `sizes` 属性应为一个字符串，指定图标文件可以使用的尺寸，例如 "48x48" 或 "any" 用于 SVG 等可缩放格式。
   * `sizes` 属性是可选的，如果未提供，客户端应假设图标可以在任何尺寸下使用。
   */
  icons?: Icon[];
  /**
   * 此实现的网站的可选 URL。
   *
   * 使用者必须采取措施确保提供图标的 URL 来自
   * 与客户端/服务器相同的域或受信任的域。
   *
   * 使用者在使用 SVG 时必须采取适当的预防措施，因为它们可能包含
   * 可执行的 JavaScript
   *
   * @format: uri
   */
  websiteUrl?: string;
}

使用以下类型扩展 Tool、Resource 和 Prompt 接口：

  /**
   * 资源的可选图标列表。
   * 客户端可以使用此列表在用户界面中显示资源的图标。
   * 每个图标应有一个 `kind` 属性，指定它是数据表示还是 URL 源，一个 `src` 属性指向图标文件或数据表示，并且可能还包括 `mimeType` 和 `sizes` 属性。
   * `mimeType` 属性应为图标文件的有效 MIME 类型，例如 "image/png" 或 "image/svg+xml"。
   * `sizes` 属性应为一个字符串，指定图标文件可以使用的尺寸，例如 "48x48" 或 "any" 用于 SVG 等可缩放格式。
   * `sizes` 属性是可选的，如果未提供，客户端应假设图标可以在任何尺寸下使用。
   */
  icons?: Icon[];

向后兼容性

icons 和 websiteUrl 都是可选字段；忽略它们的客户端将回退到现有行为。

安全影响

这不应引入任何新的安全影响。