MCP (Model Context Protocol)¶

MCP integration for AI-Parrot.

MCPToolAdapter ¶

MCPToolAdapter(tool: AbstractTool)

Adapts AI-Parrot AbstractTool to MCP tool format.

Tools marked routing_meta["requires_confirmation"] (e.g. the destructive members of a toolkit's confirming_tools) get an MCP-side guard: a required confirm boolean is injected into their input schema and the call is rejected unless confirm=true is passed — the stdio transport has no interactive HITL channel, so the explicit argument is the confirmation record.

Source code in packages/ai-parrot/src/parrot/mcp/adapter.py

def __init__(self, tool: AbstractTool):
    self.tool = tool
    self.logger = logging.getLogger(f"MCPToolAdapter.{tool.name}")

to_mcp_tool_definition ¶

to_mcp_tool_definition() -> dict[str, Any]

Convert AbstractTool to MCP tool definition.

Source code in packages/ai-parrot/src/parrot/mcp/adapter.py

def to_mcp_tool_definition(self) -> dict[str, Any]:
    """Convert AbstractTool to MCP tool definition."""
    # Extract schema from the tool's args_schema
    input_schema = {}
    if hasattr(self.tool, 'args_schema') and self.tool.args_schema:
        try:
            # Get the JSON schema from the Pydantic model
            input_schema = self.tool.args_schema.model_json_schema()
        except Exception as e:  # noqa: BLE001
            self.logger.warning("Could not extract schema for %s: %s", self.tool.name, e)
            input_schema = {"type": "object", "properties": {}}

    if self._requires_confirmation():
        input_schema.setdefault("type", "object")
        input_schema.setdefault("properties", {})["confirm"] = {
            "type": "boolean",
            "description": (
                "This operation is destructive. Set true ONLY after the "
                "user has explicitly approved it; the call is rejected "
                "otherwise."
            ),
        }
        required = input_schema.setdefault("required", [])
        if "confirm" not in required:
            required.append("confirm")

    return {
        "name": self.tool.name or "unknown_tool",
        "description": self.tool.description or f"Tool: {self.tool.name}",
        "inputSchema": input_schema
    }

execute `async` ¶

execute(arguments: dict[str, Any]) -> dict[str, Any]

Execute the AI-Parrot tool and convert result to MCP format.

Source code in packages/ai-parrot/src/parrot/mcp/adapter.py

async def execute(self, arguments: dict[str, Any]) -> dict[str, Any]:
    """Execute the AI-Parrot tool and convert result to MCP format."""
    # The guard argument never reaches the tool itself.
    confirm = arguments.pop("confirm", None)
    if self._requires_confirmation() and confirm is not True:
        return {
            "content": [
                {
                    "type": "text",
                    "text": (
                        f"Error: '{self.tool.name}' is a destructive "
                        "operation and was not confirmed. Ask the user "
                        "for approval, then re-invoke with confirm=true."
                    ),
                }
            ],
            "isError": True,
        }
    try:
        # Execute the tool
        result = await self.tool._execute(**arguments)

        # Convert ToolResult to MCP response format
        if isinstance(result, ToolResult):
            return self._toolresult_to_mcp(result)
        else:
            # Handle direct results (for backward compatibility)
            return {
                "content": [
                    {
                        "type": "text",
                        "text": str(result)
                    }
                ],
                "isError": False
            }

    except Exception as e:  # noqa: BLE001
        self.logger.error("Tool execution failed: %s", e)
        return {
            "content": [
                {
                    "type": "text",
                    "text": f"Error executing tool: {e!s}"
                }
            ],
            "isError": True
        }

MCPResource `dataclass` ¶

MCPResource(uri: str, name: str, description: str | None = None, mime_type: str | None = None)

Represents an MCP Resource.

Resources are read-only data sources exposed by the server.

to_dict ¶

to_dict() -> dict[str, Any]

Convert to MCP protocol dictionary.

Source code in packages/ai-parrot/src/parrot/mcp/resources.py

def to_dict(self) -> dict[str, Any]:
    """Convert to MCP protocol dictionary."""
    data = {
        "uri": self.uri,
        "name": self.name,
    }
    if self.description:
        data["description"] = self.description
    if self.mime_type:
        data["mimeType"] = self.mime_type
    return data