coco-framework 0.1.0__py3-none-any.whl

coco/mcp/elicitation.py

@@ -0,0 +1,394 @@
+"""Answer MCP elicitation requests with a CocoGraph interrupt.
+
+A server needing input mid-call returns an `InputRequiredResult` and expects the
+`tools/call` to be retried with answers. This module drives that loop, sourcing
+each answer from `interrupt()` so the human reviewing the agent answers too.
+
+We drive the loop here rather than via the SDK's `run_input_required_driver`
+because that driver answers from callbacks run concurrently in a task group:
+CocoGraph matches resume values to `interrupt()` calls by order, so concurrent
+firing scrambles the matching, and FastMCP would swallow the `GraphInterrupt` as
+an MCP error. Calling `interrupt()` from this frame keeps one per round.
+
+Only elicitation is answered. Sampling, roots, and continuation rounds are
+refused rather than half-served.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import TYPE_CHECKING, Any, Final, Literal, TypeAlias, TypedDict, TypeVar
+
+from fastmcp.client.group import ClientGroup
+from coco_graph.types import interrupt
+from mcp.types import (
+    CallToolResult,
+    ElicitRequest,
+    ElicitRequestFormParams,
+    ElicitResult,
+    InputRequiredResult,
+    InputResponses,
+)
+from mcp.types.version import LATEST_MODERN_VERSION, is_version_at_least
+from typing_extensions import NotRequired
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine
+
+    from fastmcp.client import Client
+    from mcp.client.session import ClientSession
+    from mcp.types import InputRequest
+
+
+_ResultT = TypeVar("_ResultT")
+
+
+ELICITATION_INTERRUPT_TYPE: Final = "mcp_elicitation"
+"""Discriminator on the interrupt payload, so a handler can recognize it."""
+
+_ACTIONS: Final = ("accept", "decline", "cancel")
+"""Actions the wire accepts, for validating a resumed answer."""
+
+MCPFormContent: TypeAlias = dict[str, str | int | float | bool | list[str] | None]
+"""Values a form answer may carry, as narrow as `mcp.types.ElicitResult.content`."""
+
+
+class MCPElicitationFormRequest(TypedDict):
+    """A request for data matching a schema.
+
+    Attributes:
+        key: The server's identifier for this request. An answer must be
+            returned under the same key.
+        message: The server's prompt, intended for a human to read.
+        mode: Always `'form'`.
+        requested_schema: JSON schema the answer's `content` must satisfy.
+    """
+
+    key: str
+    message: str
+    mode: Literal["form"]
+    requested_schema: dict[str, Any]
+
+
+class MCPElicitationUrlRequest(TypedDict):
+    """A request for the human to visit an address.
+
+    Attributes:
+        key: The server's identifier for this request. An answer must be
+            returned under the same key.
+        message: The server's prompt, intended for a human to read.
+        mode: Always `'url'`.
+        url: The address the human should visit.
+    """
+
+    key: str
+    message: str
+    mode: Literal["url"]
+    url: str
+
+
+MCPElicitationRequest: TypeAlias = MCPElicitationFormRequest | MCPElicitationUrlRequest
+"""One question an MCP server asks before finishing a tool call. Narrow on `mode`."""
+
+
+class MCPElicitationInterrupt(TypedDict):
+    """Interrupt payload raised while an MCP tool call waits on input.
+
+    Attributes:
+        type: Always `'mcp_elicitation'`.
+        tool_name: The MCP tool whose call is waiting.
+        requests: Every question this round, in the order they should be asked.
+    """
+
+    type: Literal["mcp_elicitation"]
+    tool_name: str
+    requests: list[MCPElicitationRequest]
+
+
+class MCPElicitationAccept(TypedDict):
+    """An answer to an `MCPElicitationRequest`.
+
+    Attributes:
+        action: Always `'accept'`.
+        content: The answer itself, matching the request's `requested_schema`.
+            Expected for a `'form'` request; a `'url'` request carries none.
+    """
+
+    action: Literal["accept"]
+    content: NotRequired[MCPFormContent | None]
+
+
+class MCPElicitationDecline(TypedDict):
+    """A refusal to answer an `MCPElicitationRequest`, leaving the call to go on.
+
+    Attributes:
+        action: Always `'decline'`.
+    """
+
+    action: Literal["decline"]
+
+
+class MCPElicitationCancel(TypedDict):
+    """A refusal that abandons the tool call rather than just the question.
+
+    Attributes:
+        action: Always `'cancel'`.
+    """
+
+    action: Literal["cancel"]
+
+
+MCPElicitationResponse: TypeAlias = (
+    MCPElicitationAccept | MCPElicitationDecline | MCPElicitationCancel
+)
+"""One answer to an `MCPElicitationRequest`. Narrow on `action`; only accept carries content."""
+
+
+class MCPElicitationResume(TypedDict):
+    """Value used to resume a run interrupted by an MCP elicitation.
+
+    Attributes:
+        responses: One answer per request, keyed by the request's `key`.
+    """
+
+    responses: dict[str, MCPElicitationResponse]
+
+
+def _describe_request(key: str, request: ElicitRequest) -> MCPElicitationRequest:
+    """Render one server request as a payload a human can act on."""
+    params = request.params
+    if isinstance(params, ElicitRequestFormParams):
+        return MCPElicitationFormRequest(
+            key=key,
+            message=params.message,
+            mode="form",
+            requested_schema=params.requested_schema,
+        )
+    return MCPElicitationUrlRequest(
+        key=key,
+        message=params.message,
+        mode="url",
+        url=str(params.url),
+    )
+
+
+def _elicit_requests(
+    requests: dict[str, InputRequest],
+    tool_name: str,
+) -> dict[str, ElicitRequest]:
+    """Narrow a round's requests to elicitations, raising on sampling or roots."""
+    unsupported = sorted(
+        f"{key} ({request.method})"
+        for key, request in requests.items()
+        if not isinstance(request, ElicitRequest)
+    )
+    if unsupported:
+        msg = (
+            f"The MCP tool {tool_name!r} asked for input that interrupt-based "
+            f"elicitation cannot answer: {', '.join(unsupported)}. Only "
+            "elicitation requests are supported."
+        )
+        raise NotImplementedError(msg)
+    return {key: request for key, request in requests.items() if isinstance(request, ElicitRequest)}
+
+
+def _build_responses(
+    requests: dict[str, ElicitRequest],
+    answers: dict[str, MCPElicitationResponse],
+    tool_name: str,
+) -> InputResponses:
+    """Turn resumed answers into the server's responses, raising on any missing or malformed."""
+    missing = sorted(set(requests) - set(answers))
+    if missing:
+        msg = (
+            f"Resuming the MCP tool {tool_name!r} needs an answer for every "
+            f"elicitation request, but these had none: {', '.join(missing)}."
+        )
+        raise ValueError(msg)
+
+    responses: InputResponses = {}
+    for key in requests:
+        answer = answers[key]
+        action = answer.get("action")
+        if action not in _ACTIONS:
+            msg = (
+                f"Elicitation answer for {key!r} has action {action!r}; expected "
+                "'accept', 'decline', or 'cancel'."
+            )
+            raise ValueError(msg)
+        content = answer.get("content") if action == "accept" else None
+        responses[key] = ElicitResult(action=action, content=content)
+    return responses
+
+
+_ARMED_MARKER: Final = "_coco_mcp_interrupt_armed"
+"""Attribute stamped on a client the adapter armed for interrupt elicitation."""
+
+
+async def _declare_elicitation_capability(*_: object) -> dict[str, Any]:
+    """Elicitation handler that only exists to advertise the capability.
+
+    FastMCP advertises `elicitation` only when a handler is set, so a client
+    that should drive the interrupt loop needs one. The loop answers from the
+    tool call, not this handler, so it never runs on a modern server. It only
+    fires when a legacy server initiates elicitation the old way — which the
+    interrupt loop cannot answer, hence the error.
+    """
+    msg = (
+        "This MCP server asked for input over the legacy server-initiated "
+        "elicitation path, which interrupt-based elicitation cannot answer. It "
+        "needs a server that returns its requests as an `InputRequiredResult`, "
+        "or a pre-built client with your own `elicitation_handler`."
+    )
+    raise NotImplementedError(msg)
+
+
+def _arm_for_interrupts(client: Client[Any]) -> None:
+    """Set the sentinel handler and mark the client as adapter-armed."""
+    client.set_elicitation_callback(_declare_elicitation_capability)
+    setattr(client, _ARMED_MARKER, True)
+
+
+def _drives_interrupts(client: Client[Any]) -> bool:
+    """Report whether a call through `client` should drive the interrupt loop.
+
+    True only for a client the adapter armed (not one carrying a caller's own
+    handler) that is connected to a modern-era server. The `InputRequiredResult`
+    the loop answers is a modern feature (SEP-2322); a legacy server never
+    returns one, so the call falls back to a plain `call_tool` there.
+    """
+    if not getattr(client, _ARMED_MARKER, False):
+        return False
+    version = getattr(client, "protocol_version", None)
+    return version is not None and is_version_at_least(version, LATEST_MODERN_VERSION)
+
+
+async def _await_monitored(client: Client[Any], coro: Coroutine[Any, Any, _ResultT]) -> _ResultT:
+    """Race a session request against the session task so an error can't hang it.
+
+    On HTTP transports a server error surfaces in the background session task,
+    not in the awaiting coroutine. FastMCP's guard for this is private, so warn
+    and fall back if it ever moves.
+    """
+    monitored = getattr(client, "_await_with_session_monitoring", None)
+    if monitored is None:
+        warnings.warn(
+            "This version of FastMCP does not expose "
+            "`Client._await_with_session_monitoring`, so an MCP elicitation "
+            "round cannot be raced against the session task. A transport "
+            "failure mid-elicitation may hang instead of raising.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return await coro
+    result: _ResultT = await monitored(coro)
+    return result
+
+
+async def _resolve_session(
+    client: Client[Any] | ClientGroup, tool_name: str
+) -> tuple[Client[Any], ClientSession, str]:
+    """Resolve the member client, its session, and the server's name for a tool.
+
+    For a group, `list_tools` namespaces the catalog as `{server}_{tool}` but the
+    serving client only knows the tool by its own name; `resolve_tool` maps the
+    namespaced name back to that member and its upstream name. For a single
+    client the tool is already addressed by its own name.
+
+    Args:
+        client: The armed client or group serving the tool.
+        tool_name: The tool's name as this adapter published it.
+
+    Returns:
+        The member client, its connected session, and the name the member's
+        server knows the tool by.
+    """
+    if isinstance(client, ClientGroup):
+        route = await client.resolve_tool(tool_name)
+        return route.client, route.client.session, route.upstream_name
+    return client, client.session, tool_name
+
+
+async def _call_tool_with_interrupts(
+    client: Client[Any] | ClientGroup,
+    tool_name: str,
+    arguments: dict[str, Any],
+) -> CallToolResult:
+    """Call an MCP tool, answering each round of requested input with an interrupt.
+
+    `interrupt()` unwinds the whole call, so on resume it is re-issued from the
+    first round. A server that asks before doing work repeats nothing; one that
+    works first repeats that work once per round.
+
+    Args:
+        client: A connected client armed to advertise the elicitation capability.
+        tool_name: The MCP tool to call.
+        arguments: Arguments for the tool.
+
+    Returns:
+        The tool's terminal result.
+
+    Raises:
+        GraphInterrupt: For each unanswered round. This is the mechanism.
+        NotImplementedError: On a sampling/roots request or a continuation round.
+        ValueError: If a resumed answer is missing or malformed.
+    """
+    # FastMCP's public `call_tool` no longer forwards `allow_input_required`; it
+    # drives the input-required loop itself via a concurrent driver, which is the
+    # exact behavior this module replaces with one `interrupt()` per round. So
+    # drive it against the member session, whose `call_tool` still returns the
+    # `InputRequiredResult` for us to answer.
+    member, session, upstream_name = await _resolve_session(client, tool_name)
+
+    result = await _await_monitored(
+        member, session.call_tool(upstream_name, arguments, allow_input_required=True)
+    )
+
+    while isinstance(result, InputRequiredResult):
+        if not result.input_requests:
+            # A round with only `request_state` is a continuation: the server is
+            # still working, with no question to interrupt on. Refused like sampling.
+            msg = (
+                f"The MCP tool {tool_name!r} returned a continuation round with "
+                "no input requests. Interrupt-based elicitation only answers "
+                "elicitation requests, not long-running work that resumes over "
+                "several round trips."
+            )
+            raise NotImplementedError(msg)
+
+        requests = _elicit_requests(result.input_requests, tool_name)
+        request: MCPElicitationInterrupt = {
+            "type": ELICITATION_INTERRUPT_TYPE,
+            "tool_name": tool_name,
+            "requests": [_describe_request(key, req) for key, req in requests.items()],
+        }
+        resume: MCPElicitationResume = interrupt(request)
+        responses = _build_responses(requests, resume["responses"], tool_name)
+
+        result = await _await_monitored(
+            member,
+            session.call_tool(
+                upstream_name,
+                arguments,
+                input_responses=responses,
+                request_state=result.request_state,  # opaque; echoed back verbatim
+                allow_input_required=True,
+            ),
+        )
+
+    return result
+
+
+__all__ = [
+    "ELICITATION_INTERRUPT_TYPE",
+    "MCPElicitationAccept",
+    "MCPElicitationCancel",
+    "MCPElicitationDecline",
+    "MCPElicitationFormRequest",
+    "MCPElicitationInterrupt",
+    "MCPElicitationRequest",
+    "MCPElicitationResponse",
+    "MCPElicitationResume",
+    "MCPElicitationUrlRequest",
+    "MCPFormContent",
+]

coco/mcp/tools.py

@@ -0,0 +1,307 @@
+"""Convert MCP tools and tool results into Coco-native values.
+
+Tool results follow `trustcoco-mcp-adapters`, so a call made through
+`coco.mcp` reaches a model in the same shape as one loaded by that
+package. Tool *metadata* is richer here: it is grouped under a single `mcp`
+namespace with the tool's annotations and `_meta` under `mcp.tool` and the
+serving server's identity under `mcp.server`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, TypedDict
+
+from fastmcp.client.group import ClientGroup
+from coco_core.messages.content import (
+    FileContentBlock,
+    ImageContentBlock,
+    TextContentBlock,
+    create_file_block,
+    create_image_block,
+    create_text_block,
+)
+from coco_core.tools import BaseTool, StructuredTool, ToolException
+from mcp.types import (
+    AudioContent,
+    BlobResourceContents,
+    ContentBlock,
+    EmbeddedResource,
+    ImageContent,
+    ResourceLink,
+    TextContent,
+    TextResourceContents,
+)
+
+from coco.mcp.elicitation import _call_tool_with_interrupts, _drives_interrupts
+
+if TYPE_CHECKING:
+    from fastmcp.client import Client
+    from mcp.types import Tool
+
+
+class _ToolCallResult(Protocol):
+    """The result fields this module reads.
+
+    FastMCP's `CallToolResult` dataclass and the MCP SDK's own pydantic
+    `CallToolResult` both satisfy this, and elicitation-driven calls return the
+    latter.
+    """
+
+    content: list[ContentBlock]
+    structured_content: dict[str, Any] | None
+    is_error: bool
+
+
+ToolMessageContentBlock = TextContentBlock | ImageContentBlock | FileContentBlock
+"""Coco content blocks an MCP tool result can convert into."""
+
+
+class MCPToolArtifact(TypedDict):
+    """Artifact attached to the `ToolMessage` produced by an MCP tool call.
+
+    Wrapping the structured content in a `TypedDict` leaves room for further
+    MCP result fields without changing the artifact's shape.
+
+    Attributes:
+        structured_content: The `structuredContent` of the MCP tool result.
+    """
+
+    structured_content: Any
+
+
+def _summarize_tool_error(tool_content: list[ToolMessageContentBlock]) -> str:
+    """Build a readable message from the content blocks of a failed tool call.
+
+    Image and file blocks are summarized by count rather than interpolated, so a
+    base64 payload never lands in an exception message.
+    """
+    error_parts = [block["text"] for block in tool_content if block["type"] == "text"]
+    if error_parts:
+        return "\n".join(error_parts)
+    if tool_content:
+        return (
+            "The MCP tool reported an error with no text content "
+            f"({len(tool_content)} non-text content block(s))."
+        )
+    return "The MCP tool reported an error with empty content."
+
+
+class _MCPToolExecutionError(ToolException):
+    """An MCP tool that ran and reported failure, as `isError=True`.
+
+    Carries the converted content blocks so `_handle_mcp_tool_error` can hand the
+    server's own error detail to the model instead of ending the run.
+
+    Deliberately narrow: only `isError=True` results raise this. Transport and
+    conversion failures are not `ToolException`s, so they bypass error handling.
+    """
+
+    def __init__(self, tool_content: list[ToolMessageContentBlock]) -> None:
+        super().__init__(_summarize_tool_error(tool_content))
+        self.tool_content = tool_content
+
+
+def _handle_mcp_tool_error(error: ToolException) -> list[ToolMessageContentBlock]:
+    """Surface an MCP execution error to the model as failed tool output.
+
+    Wired as `handle_tool_error`, so what this returns becomes a `ToolMessage`
+    with `status="error"` carrying the server's own detail. Any other
+    `ToolException` is re-raised.
+    """
+    if isinstance(error, _MCPToolExecutionError):
+        if error.tool_content:
+            return error.tool_content
+        # An empty `ToolMessage` is a fragile shape for some providers, so
+        # substitute a placeholder rather than pass no content at all.
+        return [create_text_block(text=str(error))]
+    raise error
+
+
+def _convert_content_block(content: ContentBlock) -> ToolMessageContentBlock:
+    """Convert one MCP content block into its Coco equivalent."""
+    if isinstance(content, TextContent):
+        return create_text_block(text=content.text)
+
+    if isinstance(content, ImageContent):
+        return create_image_block(base64=content.data, mime_type=content.mime_type)
+
+    if isinstance(content, AudioContent):
+        msg = (
+            "Converting MCP audio content to a Coco content block is not yet "
+            f"supported. Received audio with mime type: {content.mime_type}"
+        )
+        raise NotImplementedError(msg)
+
+    if isinstance(content, ResourceLink):
+        mime_type = content.mime_type or None
+        if mime_type and mime_type.startswith("image/"):
+            return create_image_block(url=content.uri, mime_type=mime_type)
+        return create_file_block(url=content.uri, mime_type=mime_type)
+
+    if isinstance(content, EmbeddedResource):
+        resource = content.resource
+        if isinstance(resource, TextResourceContents):
+            return create_text_block(text=resource.text)
+        if isinstance(resource, BlobResourceContents):
+            mime_type = resource.mime_type or None
+            if mime_type and mime_type.startswith("image/"):
+                return create_image_block(base64=resource.blob, mime_type=mime_type)
+            return create_file_block(base64=resource.blob, mime_type=mime_type)
+        # Unreachable while the SDK's resource union holds; see the note below.
+        msg = f"Unknown embedded resource type: {type(resource).__name__}"  # type: ignore[unreachable]
+        raise ValueError(msg)
+
+    # Both unions are closed at type-check time, so mypy proves these two lines
+    # unreachable — and the `unreachable` ignores become unused-ignore errors the
+    # moment the SDK grows a member, which is what keeps this exhaustive.
+    #
+    # The runtime guards still earn their place: a union is only as closed as the
+    # installed `mcp`, and a caller on a newer SDK is better served by a named
+    # type than by the bare `AssertionError` an `assert_never` would raise.
+    msg = (  # type: ignore[unreachable]
+        f"Unknown MCP content type: {type(content).__name__}. This usually means "
+        "the installed `mcp` is newer than the version this adapter supports."
+    )
+    raise ValueError(msg)
+
+
+def _convert_call_tool_result(
+    result: _ToolCallResult,
+) -> tuple[list[ToolMessageContentBlock], MCPToolArtifact | None]:
+    """Split an MCP tool result into model-visible content and an artifact."""
+    tool_content = [_convert_content_block(block) for block in result.content]
+
+    if result.is_error:
+        raise _MCPToolExecutionError(tool_content)
+
+    artifact: MCPToolArtifact | None = None
+    if result.structured_content is not None:
+        artifact = MCPToolArtifact(structured_content=result.structured_content)
+    return tool_content, artifact
+
+
+def _tool_metadata(tool: Tool, client: Client[Any] | None) -> dict[str, Any] | None:
+    """Collect the MCP tool- and server-level metadata worth keeping.
+
+    Everything lives under a single `mcp` namespace so a consumer can tell an
+    MCP tool's provenance from any other metadata on the Coco tool, and so
+    tool-level fields (`annotations`, `_meta`) stay distinct from the identity
+    of the server that served the tool.
+    """
+    tool_meta: dict[str, Any] = {}
+    if tool.annotations is not None:
+        # Snake_case (no `by_alias`) reads naturally from Python, and matches
+        # what `trustcoco-mcp-adapters` produces.
+        tool_meta["annotations"] = tool.annotations.model_dump(exclude_none=True)
+    if tool.meta is not None:
+        # `_meta` is the MCP wire field name; keep it so the key matches the
+        # protocol and the server's payload stays in one nested place.
+        tool_meta["_meta"] = tool.meta
+
+    mcp: dict[str, Any] = {}
+    if tool_meta:
+        mcp["tool"] = tool_meta
+    # Server identity comes off the connection, not the tool — a `Tool` carries
+    # no server field. It is populated while the client is connected, which is
+    # the case at conversion time.
+    if client is not None and client.server_info is not None:
+        mcp["server"] = client.server_info.model_dump(exclude_none=True)
+    return {"mcp": mcp} if mcp else None
+
+
+def _normalize_mcp_schema(schema: dict[str, Any]) -> dict[str, Any]:
+    """Keep open object arguments open during provider schema conversion."""
+    normalized = dict(schema)
+    properties = schema.get("properties")
+    if not isinstance(properties, dict):
+        return normalized
+    normalized["properties"] = dict(properties)
+    for name, value in properties.items():
+        if not isinstance(value, dict):
+            continue
+        types = value.get("type")
+        is_object = types == "object" or (isinstance(types, list) and "object" in types)
+        if (
+            is_object
+            and not value.get("properties")
+            and "additionalProperties" not in value
+            and "unevaluatedProperties" not in value
+        ):
+            normalized["properties"][name] = {**value, "additionalProperties": True}
+    return normalized
+
+
+async def as_coco_tool(
+    tool: Tool,
+    client: Client[Any] | ClientGroup,
+) -> BaseTool:
+    """Convert one MCP tool into a Coco tool.
+
+    The returned tool calls the MCP tool through `client` on every invocation.
+    FastMCP clients are reentrant, so the tool can open the client itself
+    whether or not a connection is already held elsewhere.
+
+    A server that needs input mid-call is answered with a CocoGraph
+    `interrupt()` when `client` carries the interrupt-driving sentinel handler
+    that `MCPAdapter` installs — so a human answers and the call resumes, see
+    `coco.mcp.elicitation`. A client that carries a different handler (a
+    caller's own) uses that handler instead, and one with no handler simply
+    never gets asked. Which path a call takes is read off the client, so the
+    behavior matches whatever it was armed with.
+
+    An MCP tool that runs and reports failure reaches the model as a
+    `ToolMessage` with `status="error"`, carrying the server's own error
+    content, so an agent can correct itself and retry. Transport failures and
+    unconvertible content propagate instead, since a model cannot act on them.
+
+    Args:
+        tool: An MCP tool, as returned by `fastmcp.Client.list_tools`.
+        client: The FastMCP client to call the tool through.
+
+    Returns:
+        A Coco tool that invokes the MCP tool asynchronously.
+
+    Example:
+        ```python
+        from fastmcp import Client
+
+        from coco.mcp import as_coco_tool
+
+        client = Client("https://example.com/mcp")
+        async with client:
+            mcp_tools = await client.list_tools()
+        tools = [await as_coco_tool(t, client) for t in mcp_tools]
+        ```
+    """
+    if isinstance(client, ClientGroup):
+        tool_route = await client.resolve_tool(tool.name)
+        requesting_client = tool_route.client
+    else:
+        requesting_client = client
+    drives_interrupts = _drives_interrupts(requesting_client)
+
+    async def call_tool(
+        **arguments: Any,
+    ) -> tuple[list[ToolMessageContentBlock], MCPToolArtifact | None]:
+        """Call the captured MCP tool and convert its result."""
+        result: _ToolCallResult
+        async with client:
+            if drives_interrupts:
+                result = await _call_tool_with_interrupts(client, tool.name, arguments)
+            else:
+                # Preserve MCP error results for conversion into failed tool messages.
+                result = await client.call_tool(tool.name, arguments, raise_on_error=False)
+        return _convert_call_tool_result(result)
+
+    return StructuredTool(
+        name=tool.name,
+        description=tool.description or "",
+        args_schema=_normalize_mcp_schema(tool.input_schema),
+        coroutine=call_tool,
+        response_format="content_and_artifact",
+        metadata=_tool_metadata(tool, requesting_client),
+        handle_tool_error=_handle_mcp_tool_error,
+    )
+
+
+__all__ = ["MCPToolArtifact", "as_coco_tool"]