MCP Python SDK计算机视觉集成：在工具中处理图像和视频

你是否还在为如何在MCP（Model Context Protocol）工具中高效处理图像和视频而烦恼？本文将带你一文掌握MCP Python SDK的计算机视觉集成方案，通过简单几步即可实现在工具中处理图像和视频的功能。读完本文后，你将能够：了解MCP SDK中图像数据的处理流程、掌握图像资源的定义与读取方法、学会在工具中集成图像操作功能，以及解决常见的图像格式转换问题。

MCP图像数据模型基础

MCP Python SDK通过定义结构化的数据模型来处理图像内容，主要涉及ImageContent类和资源处理机制。ImageContent类位于src/mcp/types.py文件中，是表示图像内容的核心数据结构，其定义如下：

class ImageContent(BaseModel):
    """Image content for a message."""
    type: Literal["image"]
    data: str
    """The base64-encoded image data."""
    mimeType: str
    """The MIME type of the image."""
    annotations: Annotations | None = None
    meta: dict[str, Any] | None = Field(alias="_meta", default=None)
    model_config = ConfigDict(extra="allow")

该模型要求图像数据以Base64编码字符串形式存储，并指定MIME类型（如"image/png"）。这种设计确保了图像数据能在不同系统间安全传输和正确解析。

图像资源的定义与读取

在MCP SDK中，图像通常作为资源（Resource）进行管理。你可以通过@mcp.resource装饰器定义图像资源，并指定正确的MIME类型。以下是一个示例，展示了如何定义返回图像数据的资源：

@mcp.resource("test://image", mime_type="image/png")
def get_image_as_string() -> str:
    """Return a test image as base64 string."""
    image_bytes = b"fake_image_data"
    return base64.b64encode(image_bytes).decode("utf-8")

@mcp.resource("test://image_bytes", mime_type="image/png")
def get_image_as_bytes() -> bytes:
    """Return a test image as bytes."""
    return image_bytes

上述代码定义了两个资源：一个返回Base64编码的图像字符串，另一个返回原始字节数据。这两种方式都被MCP SDK支持，你可以根据实际需求选择合适的返回类型。

要读取这些图像资源，你可以使用MCP客户端的read_resource方法：

# 读取Base64编码的图像资源
string_result = await client.read_resource(AnyUrl("test://image"))
# 读取字节类型的图像资源
bytes_result = await client.read_resource(AnyUrl("test://image_bytes"))

读取后，你可以通过检查mimeType属性来验证资源类型是否正确：

assert string_result.contents[0].mimeType == "image/png", "String resource mime type not respected"
assert bytes_result.contents[0].mimeType == "image/png", "Bytes resource mime type not preserved"

更多关于资源处理的细节，可以参考测试文件tests/issues/test_152_resource_mime_type.py。

在工具中集成图像操作

MCP SDK的FastMCP模块提供了便捷的工具集成方式，使你能够轻松地在工具中处理图像。下面是一个示例，展示了如何创建一个处理图像的工具函数：

def image_tool_fn(path: str) -> Image:
    # 读取图像文件
    with open(path, "rb") as f:
        image_data = f.read()
    # 创建并返回Image对象
    return Image(data=image_data, mimeType="image/png")

然后，你可以使用mcp.add_tool方法将这个函数添加为MCP工具：

mcp.add_tool(image_tool_fn)

调用这个工具时，MCP SDK会自动处理图像数据的转换和封装：

result = await client.call_tool("image_tool_fn", {"path": str(image_path)})

调用结果会包含一个ImageContent对象，你可以通过检查其属性来验证图像数据：

content = result.content[0]
assert content.type == "image"
assert content.mimeType == "image/png"
assert base64.b64decode(content.data) == b"fake png data"

这个过程中，MCP SDK会自动将工具返回的Image对象转换为符合协议的ImageContent结构，确保图像数据能被正确传输和解析。详细的工具测试案例可以在tests/server/fastmcp/test_server.py中找到。

图像格式处理与转换

MCP SDK提供了灵活的图像格式处理机制，支持多种常见图像格式。在src/mcp/server/fastmcp/utilities/types.py文件中，定义了Image辅助类，用于处理工具返回的图像数据：

class Image:
    """Helper class for returning images from tools."""
    def __init__(self, data: bytes | str, mimeType: str | None = None, path: Path | str | None = None):
        # 初始化逻辑...
    
    @property
    def mime_type(self) -> str:
        """Determine the MIME type of the image."""
        if self._mime_type:
            return self._mime_type
        # 根据文件扩展名推断MIME类型
        if self._path:
            ext = Path(self._path).suffix.lower()
            return _EXTENSION_TO_MIME.get(ext, "image/png")
        return "image/png"  # default for raw binary data
    
    def to_image_content(self) -> ImageContent:
        """Convert to ImageContent for MCP protocol."""
        # 转换逻辑...

Image类支持通过文件路径、原始字节数据或Base64编码字符串创建图像对象，并能自动推断或设置MIME类型。它还提供了to_image_content方法，方便地将图像数据转换为符合MCP协议的ImageContent结构。

目前支持的图像格式和对应的MIME类型映射如下：

文件扩展名	MIME类型
.png	image/png
.jpg	image/jpeg
.jpeg	image/jpeg
.gif	image/gif
.webp	image/webp

如果你需要支持其他图像格式，可以扩展_EXTENSION_TO_MIME字典来添加新的映射关系。

综合示例：构建图像处理工具

下面我们将综合前面介绍的内容，构建一个完整的图像处理工具示例。这个工具将读取本地图像文件，进行简单的处理（这里只是模拟），然后返回处理后的图像数据。

from mcp.server.fastmcp.utilities.types import Image
import base64
from pathlib import Path

def process_image(input_path: str, output_path: str) -> Image:
    """处理图像的工具函数"""
    # 读取输入图像
    with open(input_path, "rb") as f:
        input_data = f.read()
    
    # 模拟图像处理：这里只是简单地将数据反转
    processed_data = input_data[::-1]
    
    # 保存处理后的图像
    with open(output_path, "wb") as f:
        f.write(processed_data)
    
    # 返回Image对象
    return Image(path=output_path, mimeType="image/png")

# 将函数添加为MCP工具
mcp.add_tool(process_image)

在客户端调用这个工具：

# 准备输入输出路径
input_image_path = "input.png"
output_image_path = "output.png"

# 调用图像处理工具
result = await client.call_tool("process_image", {
    "input_path": input_image_path,
    "output_path": output_image_path
})

# 验证结果
for content in result.content:
    if content.type == "image":
        assert content.mimeType == "image/png"
        print(f"处理后的图像数据长度: {len(base64.b64decode(content.data))}")

这个示例展示了如何在MCP工具中完整地实现图像读取、处理和返回的流程。你可以根据实际需求，在process_image函数中添加更复杂的图像处理逻辑，例如使用OpenCV或Pillow库进行图像分析、滤镜应用等操作。

常见问题与解决方案

在使用MCP SDK处理图像时，可能会遇到一些常见问题，以下是一些解决方案：

1. MIME类型不匹配：确保在定义资源和返回图像时指定正确的MIME类型。如果未指定，MCP SDK会尝试自动推断，但显式指定可以避免很多问题。

2. 图像数据编码问题：MCP协议要求图像数据以Base64编码的字符串传输。使用Image辅助类可以自动处理编码转换，避免手动编码错误。

3. 大图像处理性能：对于大型图像，建议使用流式处理或分块处理，避免一次性加载整个图像到内存。你可以利用MCP的进度通知机制来跟踪处理进度：

class ProgressNotificationParams(NotificationParams):
    progressToken: ProgressToken
    progress: float
    total: float | None = None
    message: str | None = None

4. 跨平台兼容性：不同操作系统的文件路径处理可能有所不同，建议使用pathlib模块来处理文件路径，确保工具在不同平台上都能正常工作。

如果你遇到其他问题，可以参考MCP SDK的测试用例，或查看官方文档寻求帮助。

通过本文的介绍，你应该已经掌握了在MCP Python SDK中集成计算机视觉功能的基本方法。无论是定义图像资源、读取图像数据，还是创建图像处理工具，MCP SDK都提供了简洁而强大的API来简化这些操作。希望这篇文章能帮助你更好地在MCP项目中应用计算机视觉技术，实现更多有趣的功能。