fix(mcp): preserve image content blocks

[danielz1z]

What does this PR do?

Preserves MCP ImageContent blocks returned from tools/call results instead of silently dropping them.

Hermes already preserved text content and structuredContent, but MCP servers that return images (for example design/reference tools) could send valid image blocks that never reached the agent. This change materializes image blocks under $HERMES_HOME/cache/mcp/<server>/ and includes JSON-safe metadata in the tool result, while keeping the existing text-first result shape unchanged.

Related Issue

N/A — found while testing an MCP server that returns screen-search metadata plus image content.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• tools/mcp_tool.py
  • Detects MCP content blocks with data + mimeType.
  • Base64-decodes and writes images to $HERMES_HOME/cache/mcp/<server>/.
  • Adds a content_blocks array with image mimeType, local path, and size_bytes metadata.
  • Preserves existing result and structuredContent behavior for text-only and structured responses.
• tests/tools/test_mcp_structured_content.py
  • Adds regression coverage proving image content blocks are materialized and surfaced.

How to Test

1. Run the regression test before the fix and confirm it fails because content_blocks is missing.
2. Run the targeted test suite:
   • scripts/run_tests.sh tests/tools/test_mcp_structured_content.py tests/tools/test_mcp_tool.py
3. Run the MCP tool suite:
   • scripts/run_tests.sh tests/tools/test_mcp_*.py

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Linux / Ubuntu-compatible environment

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

Regression test fails on main before the fix:

KeyError: 'content_blocks'

Validation after the fix:

scripts/run_tests.sh tests/tools/test_mcp_structured_content.py::TestStructuredContentPreservation::test_image_content_blocks_are_preserved
1 passed

scripts/run_tests.sh tests/tools/test_mcp_structured_content.py tests/tools/test_mcp_tool.py
188 passed

scripts/run_tests.sh tests/tools/test_mcp_*.py
317 passed, 1 warning

python -m py_compile tools/mcp_tool.py tests/tools/test_mcp_structured_content.py
passed

git diff --check
passed

The one warning is pre-existing in tests/tools/test_mcp_probe.py::TestProbeMcpServerTools::test_skips_disabled_servers (coroutine ... was never awaited) and is unrelated to this change.

[alt-glitch]

Duplicate of #10848 (and related to #9570, #17915, #20701). This is the 5th PR fixing the same MCP ImageContent block dropping issue. #10848 appears to be the canonical fix PR for #10759.