fix: 修复图片序列化错误，解决 FastMCP Image 类型兼容性问题 #171

hexonal · 2025-08-03T14:33:17Z

修复在直接粘贴截图的方式使用的时候,mcp 报错了:Unable to serialize unknown type: <class 'fastmcp.utilities.types.Image'>, 看起来是图片序列化失败了 #154: 直接粘贴截图时的序列化错误
修复 [Bug] interactive_feedback tool fails with Image serialization error in Augment Agent environment #168: Augment Agent 环境中的图片序列化失败
将 FastMCP Image 类型替换为标准的 MCP ImageContent 类型
改进图片数据处理逻辑，统一使用 base64 字符串格式
增强 MIME 类型检测，支持更多图片格式
优化错误处理和调试日志

变更详情:

移除 fastmcp.utilities.types.Image 导入
使用 mcp.types.ImageContent 替代
统一图片数据为 base64 字符串格式
改进 MIME 类型推断逻辑
增强错误处理和日志记录

- 修复 Minidoracat#154: 直接粘贴截图时的序列化错误 - 修复 Minidoracat#168: Augment Agent 环境中的图片序列化失败 - 将 FastMCP Image 类型替换为标准的 MCP ImageContent 类型 - 改进图片数据处理逻辑，统一使用 base64 字符串格式 - 增强 MIME 类型检测，支持更多图片格式 - 优化错误处理和调试日志变更详情: - 移除 fastmcp.utilities.types.Image 导入 - 使用 mcp.types.ImageContent 替代 - 统一图片数据为 base64 字符串格式 - 改进 MIME 类型推断逻辑 - 增强错误处理和日志记录

gemini-code-assist

Summary of Changes

Hello @hexonal, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses critical image serialization issues within the system, specifically resolving problems encountered when pasting screenshots directly and when images fail to serialize in Augment Agent environments. My changes involve migrating from the FastMCP Image type to the standard MCP ImageContent type, unifying image data handling to use base64 strings, and enhancing MIME type detection for broader image format support. These updates aim to improve robustness, compatibility, and error handling for image processing.

Highlights

Image Type Standardization: I've replaced the fastmcp.utilities.types.Image type with the more standard mcp.types.ImageContent to ensure better compatibility and adherence to the core MCP specification.
Unified Image Data Handling: All image data is now consistently processed and stored as base64 encoded strings, simplifying data flow and resolving serialization inconsistencies.
Enhanced MIME Type Detection: I've improved the logic for inferring image MIME types based on file extensions, including support for .webp and more robust handling of .jpg, .jpeg, and .gif formats.
Bug Fixes: This PR directly resolves reported issues #154 (serialization errors when pasting screenshots) and #168 (image serialization failures in Augment Agent environments).

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments or fill out our survey to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request refactors the image processing logic to use the standard mcp.types.ImageContent and base64 strings, which improves compatibility. The changes are well-aligned with the description. I've provided two suggestions to further improve the code: one to make MIME type detection more maintainable, and another to enhance error handling accuracy by allowing automatic error classification.

gemini-code-assist · 2025-08-03T14:35:11Z

src/mcp_feedback_enhanced/server.py

+            # 根據文件名推斷 MIME 類型
            file_name = img.get("name", "image.png")
            if file_name.lower().endswith((".jpg", ".jpeg")):
-                image_format = "jpeg"
+                mime_type = "image/jpeg"
            elif file_name.lower().endswith(".gif"):
-                image_format = "gif"
+                mime_type = "image/gif"
+            elif file_name.lower().endswith(".webp"):
+                mime_type = "image/webp"
            else:
-                image_format = "png"  # 默認使用 PNG
+                mime_type = "image/png"  # 默認使用 PNG


For better maintainability and readability, you could use a dictionary to map file extensions to MIME types instead of a long if/elif/else chain. This makes it easier to add support for new image formats in the future. Using os.path.splitext() is also a more robust way to extract file extensions.

Suggested change

# 根據文件名推斷 MIME 類型

file_name = img.get("name", "image.png")

if file_name.lower().endswith((".jpg", ".jpeg")):

image_format = "jpeg"

mime_type = "image/jpeg"

elif file_name.lower().endswith(".gif"):

image_format = "gif"

mime_type = "image/gif"

elif file_name.lower().endswith(".webp"):

mime_type = "image/webp"

else:

image_format = "png" # 默認使用 PNG

mime_type = "image/png" # 默認使用 PNG

# 根據文件名推斷 MIME 類型

file_name = img.get("name", "image.png")

file_ext = os.path.splitext(file_name)[1].lower()

mime_type = {

".jpeg": "image/jpeg",

".jpg": "image/jpeg",

".gif": "image/gif",

".webp": "image/webp",

}.get(file_ext, "image/png") # 默認使用 PNG

eugene-info-stw · 2025-08-04T04:42:52Z

@Minidoracat

- 新增 FastMCP Image 兼容性工具模块 - 添加 format 属性的公共访问接口 - 修复图片序列化时的 AttributeError 问题 - 保持向后兼容性，不影响现有功能 - 添加完整的单元测试覆盖解决问题： - FastMCP Image 类将 format 存储在私有属性 _format 中 - 某些代码可能尝试访问公共属性 .format 导致错误 - 通过动态添加属性解决兼容性问题测试： - 10个单元测试全部通过 - 验证了真实使用场景的兼容性 - 确保 MCP 服务器正常运行

hgcode1130 · 2025-09-22T04:16:24Z

修复在直接粘贴截图的方式使用的时候,mcp 报错了:Unable to serialize unknown type: <class 'fastmcp.utilities.types.Image'>, 看起来是图片序列化失败了 #154: 直接粘贴截图时的序列化错误

修复 [Bug] interactive_feedback tool fails with Image serialization error in Augment Agent environment #168: Augment Agent 环境中的图片序列化失败

将 FastMCP Image 类型替换为标准的 MCP ImageContent 类型

改进图片数据处理逻辑，统一使用 base64 字符串格式

增强 MIME 类型检测，支持更多图片格式

优化错误处理和调试日志

变更详情:

移除 fastmcp.utilities.types.Image 导入

使用 mcp.types.ImageContent 替代

统一图片数据为 base64 字符串格式

改进 MIME 类型推断逻辑

增强错误处理和日志记录

如何使用您的分支呢，现在官方这个分支还没有release，导致还用不了修复后的mcp（QAQ）

HaoweiChan · 2025-10-20T02:22:28Z

@hgcode1130 you can add this to your mcp setting, which installs the fix from the branch

"mcp-feedback-enhanced": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hexonal/mcp-feedback-enhanced@fix/image-serialization-issues",
        "mcp-feedback-enhanced"
      ],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "true",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",
        "MCP_DEBUG": "false"
      },
      "autoApprove": [
        "interactive_feedback"
      ]
    },

hgcode1130 · 2025-10-27T06:47:16Z

@hgcode1130 you can add this to your mcp setting, which installs the fix from the branch

"mcp-feedback-enhanced": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hexonal/mcp-feedback-enhanced@fix/image-serialization-issues",
        "mcp-feedback-enhanced"
      ],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "true",
        "MCP_WEB_HOST": "127.0.0.1",
        "MCP_WEB_PORT": "8765",
        "MCP_DEBUG": "false"
      },
      "autoApprove": [
        "interactive_feedback"
      ]
    },

thank you

gemini-code-assist bot reviewed Aug 3, 2025

View reviewed changes

Mr-chen-05 approved these changes Aug 5, 2025

View reviewed changes

This was referenced Aug 17, 2025

图片序列化问题未完全解决 - #171修复不彻底 #179

Closed

Image Serialization Issue Not Fully Resolved - Fix #171 Incomplete #180

Open

kunlunpoxiao approved these changes Sep 24, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: 修复图片序列化错误，解决 FastMCP Image 类型兼容性问题 #171

fix: 修复图片序列化错误，解决 FastMCP Image 类型兼容性问题 #171

hexonal commented Aug 3, 2025

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot left a comment

Uh oh!

gemini-code-assist bot Aug 3, 2025

Uh oh!

eugene-info-stw commented Aug 4, 2025

Uh oh!

hgcode1130 commented Sep 22, 2025

Uh oh!

HaoweiChan commented Oct 20, 2025

Uh oh!

hgcode1130 commented Oct 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

fix: 修复图片序列化错误，解决 FastMCP Image 类型兼容性问题 #171

Are you sure you want to change the base?

fix: 修复图片序列化错误，解决 FastMCP Image 类型兼容性问题 #171

Conversation

hexonal commented Aug 3, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Aug 3, 2025

Choose a reason for hiding this comment

Uh oh!

eugene-info-stw commented Aug 4, 2025

Uh oh!

hgcode1130 commented Sep 22, 2025

Uh oh!

HaoweiChan commented Oct 20, 2025

Uh oh!

hgcode1130 commented Oct 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants