人工智能MCP 服务MCP Clients【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址https://gitcode.com/gh_mirrors/pythonsd/python-sdk点击查看免费下载文本不是工具tool唯一能返回的东西。在 Model Context Protocol 的世界里一个工具的结果是一组**内容块content block**的列表——除了普通的字符串文本还可以是图片、音频、被嵌入的文档资源甚至是带图标的富元数据。本指南聚焦 python-sdkModel Context Protocol 的官方 Python SDK服务器端媒体处理能力如何使用Image与Audio两个辅助类型在工具中返回二进制结果如何使用EmbeddedResource把文档资源嵌入到工具结果中以及如何使用Icon为服务器、工具、资源和提示词在客户端界面中“配上一张脸”。读完本文你将能够用最短的代码写出返回图片、音频和文档的 MCP 工具并理解这些返回值在线缆上究竟以什么形式传输。内容块机制工具结果的本质在 MCP 协议中工具调用的结果CallToolResult由一个内容块列表构成。普通字符串结果会被包装为TextContent而二进制内容则对应ImageContent与AudioContent两种块。这两个类型位于mcp.types中与TextContent并列见 src/mcp/server/mcpserver/utilities/types.py 中从mcp_types的导入。python-sdk 的工具返回转换逻辑见 src/mcp/server/mcpserver/utilities/func_metadata.py会按以下顺序处理返回值返回None→ 空列表返回ContentBlock→ 原样包装进结果列表返回Image→ 调用to_image_content()转为ImageContent返回Audio→ 调用to_audio_content()转为AudioContent返回list/tuple→ 逐项递归转换后拼接这意味着一个工具可以同时返回文本与图片的混合列表返回其他类型 → 走结构化输出等路径序列化。也就是说Image和Audio是 SDK 提供的便捷包装器helper而不是协议原生类型——它们在返回时被转换成真正的协议类型ImageContent/AudioContent。返回一张图片在工具函数上把返回类型标注为Image指向一个文件然后返回它即可from pathlib import Path from mcp.server import MCPServer from mcp.server.mcpserver import Image mcp MCPServer(Brand kit) LOGO_FILE Path(__file__).parent / logo.png # or the path to your file on disk mcp.tool() def logo() - Image: The brand logo as a PNG. return Image(pathLOGO_FILE)对应源码见 docs_src/media/tutorial001.py。需要理解的关键点Image恰好接收path要读取的文件与data原始字节二者之一。构造时校验逻辑在 src/mcp/server/mcpserver/utilities/types.py两者都缺或都传都会抛出ValueError。客户端看到的 MIME 类型由文件后缀推断logo.png会被宣告为image/png。推断表见 types.py.png→image/png、.jpg/.jpeg→image/jpeg、.gif→image/gif、.webp→image/webp无法识别的后缀回退到application/octet-stream。这里对 logo 没有任何特殊要求。放在server.py旁边的任何 PNG 都可以你的代码渲染出的图表、示意图、照片皆可。在线缆上的形态ImageContentImage是 SDK 的便利设施而非协议类型。在网络上你的返回值会变成ImageContent块——文件的字节经 base64 编码再加上 MIME 类型result.content # [ImageContent(typeimage, dataiVBORw0KGgoAAAANSUhEUg..., mime_typeimage/png)] result.structured_content # NoneImage.to_image_content()的实现见 types.py用base64.b64encode读取文件字节并完成编码——你从未接触过原始字节SDK 替你读文件并处理了编码。两件值得注意的事data是 base64 字符串structured_content为None。Image是供模型“看”的内容而不是供应用程序“解析”的数据因此没有输出 schema。与之对比的是结构化输出那里的返回注解本身就是 schema。信息ImageContent与AudioContent位于mcp.types紧挨着普通str结果所变成的TextContent见工具。工具结果是一组内容块的列表Image和Audio是产出两种二进制块的最短路径。动手试一下在server.py旁边放任意一个 PNG命名为logo.png然后运行uv run mcp dev server.py打开Tools标签页并调用logo。结果不是字符串而是一个image内容块Inspector 会渲染出你的图片。从磁盘上的文件到屏幕上的像素中间发生的一切都由 SDK 完成。返回一段音频Audio与Image形状完全相同。保留logo.png不动在它旁边放任意一个 WAV 文件并命名为chime.wavfrom pathlib import Path from mcp.server import MCPServer from mcp.server.mcpserver import Audio, Image mcp MCPServer(Brand kit) LOGO_FILE Path(__file__).parent / logo.png CHIME_FILE Path(__file__).parent / chime.wav mcp.tool() def logo() - Image: The brand logo as a PNG. return Image(pathLOGO_FILE) mcp.tool() def chime() - Audio: The notification chime as a WAV. return Audio(pathCHIME_FILE)对应源码见 docs_src/media/tutorial002.py。结果是AudioContent块result.content # [AudioContent(typeaudio, dataUklGR..., mime_typeaudio/wav)] result.structured_content # None同样的套路磁盘文件进base64 与 MIME 类型出没有输出 schema。音频后缀推断表见 types.py.wav→audio/wav、.mp3→audio/mpeg、.ogg→audio/ogg、.flac→audio/flac、.aac→audio/aac、.m4a→audio/mp4未识别后缀同样回退application/octet-stream。字节还是文件path 与 data 两种模式两个辅助类型也都接受data原始字节来替代path。这是为那些“从未有过自己的文件”的字节准备的模式——数据库列、HTTP 响应、Pillow 刚刚绘制的图像等等from pathlib import Path from mcp.server import MCPServer from mcp.server.mcpserver import Image mcp MCPServer(Brand kit) LOGO_FILE Path(__file__).parent / logo.png mcp.tool() def logo_from_bytes() - Image: The brand logo as a PNG. png LOGO_FILE.read_bytes() # a database read, an HTTP response, Pillow output... return Image(datapng, formatpng)对应源码见 docs_src/media/tutorial003.py。使用path时无需额外声明文件在结果构建的那一刻被读取open(self.path, rb)发生在to_image_content()中见 types.pyMIME 类型由后缀推断Image.png、.jpg、.jpeg、.gif、.webpAudio.wav、.mp3、.ogg、.flac、.aac、.m4a。无法识别的后缀回退为application/octet-stream。注意使用data时没有文件名也就没有可供推断的依据。如果忘记传formatSDK 会回退到默认值图片默认image/png音频默认audio/wav。用这种方式从 MP3 字节构造Audio客户端收到的mime_type会是audio/wav然后忠实地解码失败。当你传data时务必同时传format。从实现上看format会被直接拼进 MIME 类型fimage/{self._format.lower()}与faudio/{self._format.lower()}见 types.py所以传formatpng就得到image/png传formatjpeg就得到image/jpeg以此类推。嵌入一个资源EmbeddedResource工具还可以返回一份文档文本或字节附带它所在的 URI 与 MIME 类型。这就是EmbeddedResource另一种内容块。与普通str不同它告诉客户端内容“是什么”因此客户端可以把它当作附件展示或识别出它已知的资源。from mcp.server import MCPServer from mcp.types import EmbeddedResource, TextResourceContents mcp MCPServer(Brand kit) mcp.resource(brand://guidelines, mime_typetext/markdown) def guidelines() - str: How to use the brand assets. return # Brand guidelines\n\nUse the primary colour for calls to action.\n mcp.tool() def brand_guidelines() - EmbeddedResource: The brand guidelines as a Markdown document. return EmbeddedResource( resourceTextResourceContents(uribrand://guidelines, mime_typetext/markdown, textguidelines()) )对应源码见 docs_src/media/tutorial005.py。要点brand://guidelines是一个普通资源资源一章专门讲解这类资源。工具在模型请求时把同一份文档交给模型而直接调用guidelines()保持了单一事实来源single source of truth。EmbeddedResource和TextResourceContents都来自mcp.types。与图片不同这里没有便捷辅助类型你构建的块原样进入结果也不存在structured_content。使用资源注册所用的 URI这样客户端才能判断“附件”与brand://guidelines是同一份文档。任何 URI 都是合法的无论是否已注册。线缆上的结果形态result.content # [EmbeddedResource(typeresource, resourceTextResourceContents(uribrand://guidelines, mime_typetext/markdown, text# Brand guidelines\n\n...))]对于二进制内容改用BlobResourceContents(uri..., mime_type..., blob...)把字节 base64 编码后放进blob字段替代TextResourceContents。如果只想发送一个指针、让客户端稍后通过resources/read读取则返回ResourceLink(name..., uri...)——它同样是一种内容块。图标Icon给服务器一个“脸”Icon是元数据而不是内容。它不携带图像本身而是通过一个 URI 指向图像客户端可以获取它并展示在你的服务器名称、工具、资源或提示词旁边。from mcp.server import MCPServer from mcp.types import Icon LOGO Icon(srchttps://example.com/brand-kit.png, mime_typeimage/png, sizes[48x48]) PALETTE Icon(srchttps://example.com/palette.svg, mime_typeimage/svgxml, sizes[any]) mcp MCPServer(Brand kit, icons[LOGO]) mcp.tool(icons[PALETTE]) def palette() - list[str]: The brand colour palette as hex codes. return [#1d4ed8, #f59e0b, #10b981] mcp.resource(brand://guidelines, icons[LOGO]) def guidelines() - str: How to use the brand assets. return Use the primary colour for calls to action.对应源码见 docs_src/media/tutorial004.py。Icon的字段语义src是客户端可以解析的 URIhttps:或者如果希望图标内嵌、无需额外请求则用data:URImime_type与sizes48x48或矢量格式用any让客户端在你提供多个图标时选出合适的那一个themelight或themedark把某个图标限定给一种配色方案。同一个icons[...]关键字被MCPServer(...)、mcp.tool()、mcp.resource()和mcp.prompt()接受。在底层服务器的icons参数贯穿到低层Server的list_server_info装配逻辑见 src/mcp/server/lowlevel/server.py工具、资源和提示词对象也各自带icons字段例如提示词定义在 src/mcp/server/mcpserver/prompts/base.py。仓库中的测试也覆盖了这些用法例如 tests/server/mcpserver/test_server.py 在构造服务器时传入icons[Icon(srchttps://example.com/icon.png, ...)]。客户端在哪里看到它们图标与它所装饰的对象一起传输。服务器的图标在客户端连接时到达位于client.server_info上在 2026 代连接中该字段是可选的所以先收窄类型assert client.server_info is not None # python-sdk servers identify themselves by default client.server_info.icons # [Icon(srchttps://example.com/brand-kit.png, mime_typeimage/png, sizes[48x48])]工具的图标在tools/list返回的Tool对象上资源的图标在resources/list返回的Resource上提示词的图标在prompts/list返回的Prompt上。字段名一律是icons。内容块转换与验证源码与测试的佐证除了func_metadata.py中工具返回值的自动转换Prompt的消息构造同样会处理Image与Audio辅助类型UserMessage/Message的构造函数会把str包装成TextContent把Image调to_image_content()、Audio调to_audio_content()或原样接收现成的内容块见 src/mcp/server/mcpserver/prompts/base.py。这意味着你在提示词prompt消息里也可以直接使用Image(data..., format...)这类便捷写法。仓库测试对上述行为提供了直接验证tests/server/mcpserver/prompts/test_base.py 断言Image(databimg, formatpng)与Audio(databsnd, formatwav)分别被转换为ImageContent(typeimage, dataaW1n, mime_typeimage/png)和AudioContent(typeaudio, datac25k, mime_typeaudio/wav)——注意data就是bimg的 base64 编码aW1n同文件 test_base.py 覆盖了路径不存在时抛出ValueErrorImage(pathtmp_path / missing.png)的错误路径tests/server/mcpserver/test_server.py 验证了Image(path)与Audio(path)作为工具返回值的接线方式。这些测试同时印证了“辅助类型在转换时读取文件/编码字节”与“MIME 由format或后缀决定”两条核心行为。小结从工具返回Image或Audio客户端会收到ImageContent/AudioContent块你的字节经 base64 编码并带有一个 MIME 类型。用path构建并让后缀决定 MIME 类型或用内存中的data加显式format构建。返回EmbeddedResource把一份文档文本或 base64 blob含 URI 与 MIME 类型放进结果或返回ResourceLink只发送指针。媒体结果不带structured_content也没有输出 schema。Icon是一个指针一个srcURI 加可选的mime_type、sizes和theme。icons[...]在服务器、工具、资源和提示词上都可用客户端在对应的对象上找到它们。以上就是工具能放进结果里的全部内容。工具失败时会发生什么以及该让谁知道见处理错误。赞分享人工智能MCP 服务MCP Clients【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址https://gitcode.com/gh_mirrors/pythonsd/python-sdk点击查看免费下载相关推荐Prime Agent调试技巧解决AI生成代码错误的10个实用方法Prime Agent调试技巧解决AI生成代码错误的10个实用方法 Prime Agent是一款用于编码工作流和长期自主任务的自我改进RLM代理能够帮助开发人工智能MCP 服务MCP Clients为什么选择PixelDiT-1300M-1024px对比传统扩散模型的7大优势为什么选择PixelDiT 1300M 1024px对比传统扩散模型的7大优势 PixelDiT 1300M 1024px是NVIDIA最新推出的文本到图像生人工智能MCP 服务MCP Clientspython-sdk 多媒体内容指南用 Image、Audio、EmbeddedResource 与 Icon 让 MCP 工具返回图片、音频、文档和图标python sdk 多媒体内容指南用 Image、Audio、EmbeddedResource 与 Icon 让 MCP 工具返回图片、音频、文档和图标 在人工智能MCP 服务MCP Clients创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
