fix(mcp): report non-text error results without their payload (#8327)

* fix(mcp): report non-text error results without their payload

When an MCP tool returns isError with no text content, the local conversion
fell back to stringifying the LangChain content blocks. That put the whole
base64 payload into the ToolException message, and the middleware's
500-character cap still left a base64 prefix in the model-visible ToolMessage
and the checkpoint.

Describe the blocks by kind and MIME type instead; text results keep their
existing message unchanged. Applies to stdio tools, which use this conversion;
sse/http tools keep the adapter's conversion (tracked separately).

* fix(mcp): name empty binary error payloads instead of raising

An error result whose embedded file or image had a zero-byte payload hit
create_file_block/create_image_block before the isError branch, so the
model saw ValueError('Must provide one of: url, base64, or file_id')
instead of the server's diagnostic. Skip empty binary payloads on error
results, name their shape in the no-text fallback, and keep normal
results unchanged (audio still raises NotImplementedError).
This commit is contained in:
哈基米 2026-11-19 11:38:39 +08:00 committed by GitHub
parent c9ecf577c4
commit 90ca57e97b
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 152 additions and 2 deletions

View File

@ -59,7 +59,9 @@ make test-blocking-io
## Results
- **Never put base64 payloads in text.** Unsupported content (inline audio) raises
a recoverable tool error.
a recoverable tool error, and the stdio conversion reports an error result with
no text block by content shape, never the payload. sse/http tools keep
`langchain-mcp-adapters`' conversion, which still stringifies that fallback.
- **`ResourceLink` items do not become URL-sourced `file` blocks.** Chat
Completions serialization rejects them, and a checkpointed block would break
every later turn of the thread.

View File

@ -473,6 +473,23 @@ def _extract_thread_id(runtime: Runtime | None) -> str:
return "default"
def _describe_non_text_result(blocks: list[dict[str, Any]]) -> str:
"""Name the non-text blocks of an error result without their payloads.
The tool error reported to the model is built from the result's text
blocks. An error result that carries only images or files has none, and
stringifying the blocks instead would put their base64 payload into the
model-visible message (and into the checkpointed ToolMessage). Report the
block kinds and MIME types, which is all the model can act on anyway.
"""
parts: list[str] = []
for block in blocks:
kind = block.get("type", "unknown")
mime_type = block.get("mime_type")
parts.append(f"{kind} ({mime_type})" if mime_type else str(kind))
return ", ".join(parts)
def _convert_call_tool_result(
call_tool_result: Any,
*,
@ -549,10 +566,18 @@ def _convert_call_tool_result(
# Convert MCP content blocks to LangChain content blocks.
lc_content = []
resource_links: list[dict[str, Any]] = []
is_error = bool(call_tool_result.isError)
# Empty binary payloads cannot become LangChain blocks (``create_file_block``
# rejects an empty base64 string). On an error result that would hide the
# server's diagnostics, so name the shape in the fallback message instead.
empty_binary_shapes: list[str] = []
for item in call_tool_result.content:
if isinstance(item, TextContent):
lc_content.append(create_text_block(text=_resolve_text(item.text)))
elif isinstance(item, ImageContent):
if is_error and not item.data:
empty_binary_shapes.append(f"image ({item.mimeType})")
continue
lc_content.append(create_image_block(base64=item.data, mime_type=item.mimeType))
elif isinstance(item, AudioContent):
raise NotImplementedError(f"AudioContent conversion to LangChain content blocks is not yet supported. Received audio with mime type: {item.mimeType}")
@ -601,6 +626,10 @@ def _convert_call_tool_result(
lc_content.append(create_text_block(text=_resolve_text(res.text)))
elif isinstance(res, BlobResourceContents):
mime = res.mimeType or None
if is_error and not res.blob:
kind = "image" if mime and mime.startswith("image/") else "file"
empty_binary_shapes.append(f"{kind} ({mime or 'application/octet-stream'})")
continue
if mime and mime.startswith("image/"):
lc_content.append(create_image_block(base64=res.blob, mime_type=mime))
else:
@ -622,7 +651,18 @@ def _convert_call_tool_result(
if call_tool_result.isError:
error_parts = [item["text"] for item in lc_content if isinstance(item, dict) and item.get("type") == "text"]
raise ToolException("\n".join(error_parts) if error_parts else str(lc_content))
if error_parts:
raise ToolException("\n".join(error_parts))
# No text block to report: describe the payload shapes instead of
# stringifying the blocks, which would put image/file base64 into the
# model-visible error message.
described = _describe_non_text_result(lc_content)
if empty_binary_shapes:
described = ", ".join(filter(None, [described, ", ".join(empty_binary_shapes)]))
message = "MCP tool returned an error result without text content"
if described:
message += f" ({described}); the payload is not shown"
raise ToolException(message + ".")
artifact = None
if call_tool_result.structuredContent is not None:

View File

@ -0,0 +1,108 @@
"""An MCP error result without text blocks reports shapes, not base64 payloads.
The tool error a model sees is built from the result's text blocks. Before this
case was handled, an error result carrying only images or files fell back to
stringifying the LangChain content blocks, putting the whole base64 payload into
the ToolException message; the middleware's 500-character cap still left a
base64 prefix in the model-visible ToolMessage and the checkpoint. The MCP guide
forbids that.
"""
import base64
import pytest
from langchain_core.tools import ToolException
from mcp.types import BlobResourceContents, CallToolResult, EmbeddedResource, ImageContent, TextContent
from deerflow.mcp.tools import _convert_call_tool_result
PAYLOAD = base64.b64encode(b"\x89PNG\r\n\x1a\nbinary image payload").decode("ascii")
def _image() -> ImageContent:
return ImageContent(type="image", data=PAYLOAD, mimeType="image/png")
def _file(mime_type: str | None) -> EmbeddedResource:
return EmbeddedResource(
type="resource",
resource=BlobResourceContents(uri="file:///tmp/report.pdf", blob=PAYLOAD, mimeType=mime_type),
)
def test_image_only_error_result_keeps_the_payload_out_of_the_message():
with pytest.raises(ToolException) as excinfo:
_convert_call_tool_result(CallToolResult(content=[_image()], isError=True))
message = str(excinfo.value)
assert PAYLOAD not in message
assert "without text content" in message
assert "image (image/png)" in message
def test_file_only_error_result_names_its_mime_type_without_the_payload():
with pytest.raises(ToolException) as excinfo:
_convert_call_tool_result(CallToolResult(content=[_file("application/pdf")], isError=True))
message = str(excinfo.value)
assert PAYLOAD not in message
assert "file (application/pdf)" in message
def test_error_result_with_no_content_reports_that_no_text_was_sent():
with pytest.raises(ToolException) as excinfo:
_convert_call_tool_result(CallToolResult(content=[], isError=True))
assert str(excinfo.value) == "MCP tool returned an error result without text content."
def test_error_result_text_blocks_are_reported_unchanged():
with pytest.raises(ToolException) as excinfo:
_convert_call_tool_result(
CallToolResult(
content=[TextContent(type="text", text="server refused: bad token"), _image()],
isError=True,
)
)
message = str(excinfo.value)
assert message == "server refused: bad token"
assert PAYLOAD not in message
def _empty_file(mime_type: str | None = "application/pdf") -> EmbeddedResource:
return EmbeddedResource(
type="resource",
resource=BlobResourceContents(uri="file:///tmp/empty.pdf", blob="", mimeType=mime_type),
)
def test_zero_byte_file_error_result_keeps_the_server_diagnostic():
with pytest.raises(ToolException) as excinfo:
_convert_call_tool_result(
CallToolResult(
content=[_empty_file(), TextContent(type="text", text="upload rejected: empty file")],
isError=True,
)
)
assert str(excinfo.value) == "upload rejected: empty file"
def test_zero_byte_file_only_error_result_names_its_shape():
with pytest.raises(ToolException) as excinfo:
_convert_call_tool_result(CallToolResult(content=[_empty_file()], isError=True))
message = str(excinfo.value)
assert "without text content" in message
assert "file (application/pdf)" in message
def test_zero_byte_image_error_result_names_its_shape():
empty_image = ImageContent(type="image", data="", mimeType="image/png")
with pytest.raises(ToolException) as excinfo:
_convert_call_tool_result(CallToolResult(content=[empty_image], isError=True))
message = str(excinfo.value)
assert "without text content" in message
assert "image (image/png)" in message