pyagentic-core 2.3.0a12__tar.gz → 2.4.0a3__tar.gz

{pyagentic_core-2.3.0a12/pyagentic_core.egg-info → pyagentic_core-2.4.0a3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagentic-core
-Version: 2.3.0a12
+Version: 2.4.0a3
 Summary: Build LLM Agents in a Pythonic way
 Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
 License: MIT
@@ -23,12 +23,16 @@ Requires-Dist: google-generativeai>=0.8.0
 Requires-Dist: transitions>=0.9.3
 Requires-Dist: ty>=0.0.15
 Requires-Dist: jinja2>=3.1.6
+Requires-Dist: fastmcp>=3.4.0
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0.0; extra == "mcp"
 Provides-Extra: deploy
 Requires-Dist: typer>=0.15.0; extra == "deploy"
 Requires-Dist: fastapi>=0.115.0; extra == "deploy"
 Requires-Dist: uvicorn>=0.34.0; extra == "deploy"
 Requires-Dist: sse-starlette>=2.0.0; extra == "deploy"
 Requires-Dist: httpx>=0.28.0; extra == "deploy"
+Requires-Dist: fastmcp>=2.0.0; extra == "deploy"
 Dynamic: license-file
 
 # PyAgentic

{pyagentic_core-2.3.0a12 → pyagentic_core-2.4.0a3}/mkdocs.yml

@@ -15,6 +15,7 @@ nav:
     - Agent Linking: agent-linking.md
     - Responses: responses.md
     - Structured Outputs: structured-output.md
+    - MCP: mcp.md
     - Inheritance: inheritance.md
     - Observability: observability.md
   - Deploy:

{pyagentic_core-2.3.0a12 → pyagentic_core-2.4.0a3}/pyagentic/__init__.py

@@ -38,9 +38,10 @@ Main Components:
 from pyagentic._base._spec import spec
 from pyagentic._base._agent._agent import BaseAgent, AgentExtension
 from pyagentic._base._agent._agent_linking import Link
+from pyagentic._base._mcp import MCPLink
 from pyagentic._base._tool import tool
 
 from pyagentic._base._state import State
 from pyagentic._base._ref import ref
 
-__all__ = ["BaseAgent", "AgentExtension", "tool", "spec", "State", "Link", "ref"]
+__all__ = ["BaseAgent", "AgentExtension", "tool", "spec", "State", "Link", "MCPLink", "ref"]

{pyagentic_core-2.3.0a12 → pyagentic_core-2.4.0a3}/pyagentic/_base/_agent/_agent.py

@@ -27,6 +27,7 @@ from pyagentic._base._agent._agent_state import _AgentState
 
 if TYPE_CHECKING:
     from pyagentic._base._agent._agent_linking import _LinkedAgentDefinition
+    from pyagentic._base._mcp import _MCPDefinition
 
 from pyagentic.models.response import ToolResponse, AgentResponse
 from pyagentic.models.llm import Message, ToolCall, LLMResponse
@@ -161,6 +162,7 @@ class BaseAgent(metaclass=AgentMeta):
     __tool_defs__: ClassVar[dict[str, _ToolDefinition]]  # Registered @tool methods
     __state_defs__: ClassVar[dict[str, _StateDefinition]]  # State field definitions
     __linked_agents__: ClassVar[dict[str, "_LinkedAgentDefinition"]]  # Linked agent definitions
+    __mcp_defs__: ClassVar[dict[str, "_MCPDefinition"]]  # MCP server definitions
 
     # User-set Class Attributes (defined in subclass)
     __system_message__: ClassVar[str]  # Required: system prompt for the agent
@@ -234,6 +236,126 @@ class BaseAgent(metaclass=AgentMeta):
         if self.__tool_defs__ and not self.provider.__supports_tool_calls__:
             raise Exception("Tools are not supported with this provider")
 
+    async def _ensure_mcp_connected(self):
+        """Lazily connect to all configured MCP servers and merge their tools.
+
+        Called once at the top of ``_get_tool_defs()``.  On first invocation
+        it connects to each MCP server, fetches available tools, applies
+        whitelist/blacklist filtering, converts them to ``_MCPToolDefinition``
+        instances, and shadows the class-level ``__tool_defs__`` and
+        ``__tool_response_models__`` with instance-level merged dicts.
+
+        Populates ``_mcp_tool_routing`` for dispatching tool calls to the
+        correct MCP client.
+        """
+        if getattr(self, "_mcp_connected", False):
+            return
+
+        if not self.__mcp_defs__:
+            self._mcp_connected = True
+            self._mcp_clients = {}
+            self._mcp_tool_routing = {}
+            return
+
+        try:
+            from fastmcp import Client as MCPClient
+        except ImportError:
+            raise ImportError(
+                "fastmcp is required for MCP support. "
+                "Install it with: pip install pyagentic-core[mcp]"
+            )
+
+        from pyagentic._base._mcp import (
+            _MCPToolDefinition,
+            mcp_tool_to_tool_def,
+            _json_schema_to_parameters,
+        )
+        from pyagentic.models.response import ToolResponse
+
+        self._mcp_clients = {}
+        self._mcp_tool_routing = {}
+        mcp_tool_defs = {}
+        mcp_response_models = {}
+
+        for field_name, mcp_def in self.__mcp_defs__.items():
+            info = mcp_def.info
+            server = info.server
+
+            # Auto-detect transport
+            if isinstance(server, str) and server.startswith(("http://", "https://")):
+                client = MCPClient(server)
+            elif isinstance(server, str) and info.args is not None:
+                from fastmcp.client.transports import StdioTransport
+
+                transport = StdioTransport(command=server, args=info.args)
+                client = MCPClient(transport)
+            else:
+                # In-process FastMCP server object
+                client = MCPClient(server)
+
+            # Connect and fetch tools
+            await client.__aenter__()
+            self._mcp_clients[field_name] = client
+
+            tools = await client.list_tools()
+
+            # Apply whitelist/blacklist filtering
+            if info.tools is not None:
+                allowed = set(info.tools)
+                tools = [t for t in tools if t.name in allowed]
+            if info.exclude_tools is not None:
+                excluded = set(info.exclude_tools)
+                tools = [t for t in tools if t.name not in excluded]
+
+            # Convert to _MCPToolDefinition and register routing
+            for mcp_tool in tools:
+                tool_def = mcp_tool_to_tool_def(
+                    mcp_tool, field_name, info.prefix
+                )
+                # Apply phases from MCPInfo to each tool definition
+                if info.phases:
+                    tool_def.phases = info.phases
+                mcp_tool_defs[tool_def.name] = tool_def
+                self._mcp_tool_routing[tool_def.name] = (
+                    client,
+                    tool_def.mcp_original_name,
+                )
+
+                # Build a simple response model for MCP tools
+                params = _json_schema_to_parameters(tool_def.json_schema)
+                simple_def = _ToolDefinition(
+                    name=tool_def.name,
+                    description=tool_def.description,
+                    parameters=params,
+                    return_type=str,
+                )
+                mcp_response_models[tool_def.name] = ToolResponse.from_tool_def(
+                    simple_def
+                )
+
+        # Shadow class-level dicts with instance-level merged versions
+        self.__tool_defs__ = {**self.__class__.__tool_defs__, **mcp_tool_defs}
+        self.__tool_response_models__ = {
+            **self.__class__.__tool_response_models__,
+            **mcp_response_models,
+        }
+        self._mcp_connected = True
+
+    async def close(self):
+        """Tear down all MCP client connections.
+
+        Should be called when the agent is no longer needed to clean up
+        any open connections or subprocesses.
+        """
+        for client in getattr(self, "_mcp_clients", {}).values():
+            try:
+                await client.__aexit__(None, None, None)
+            except Exception:
+                pass
+        self._mcp_clients = {}
+        self._mcp_tool_routing = {}
+        self._mcp_connected = False
+
     def __post_init__(self):
         """
         Post-initialization hook called after agent instance is created.
@@ -312,8 +434,9 @@ class BaseAgent(metaclass=AgentMeta):
                 response_format=self.__response_format__,
                 **kwargs,
             )
+            usage_details = response.usage.model_dump() if response.usage else {}
             self.tracer.set_attributes(
-                usage_details=response.usage.model_dump(), model=self.provider._model
+                usage_details=usage_details, model=self.provider._model
             )
             return response
         except Exception as e:
@@ -393,11 +516,17 @@ class BaseAgent(metaclass=AgentMeta):
         Returns:
             ToolResponse: The response from the tool execution
         """
-        # Add tool call message to conversation history
-        self.state._messages.append(self.provider.to_tool_call_message(tool_call))
         self.tracer.set_attributes(**tool_call.__dict__)
         logger.info(f"Calling {tool_call.name} with kwargs: {tool_call.arguments}")
 
+        # Check if this is an MCP-routed tool (before appending provider-specific message)
+        mcp_routing = getattr(self, "_mcp_tool_routing", {})
+        if tool_call.name in mcp_routing:
+            return await self._process_mcp_tool_call(tool_call, call_depth)
+
+        # Add tool call message to conversation history
+        self.state._messages.append(self.provider.to_tool_call_message(tool_call))
+
         # Look up the tool definition and bound method
         try:
             tool_def = self.__tool_defs__[tool_call.name]
@@ -413,11 +542,11 @@ class BaseAgent(metaclass=AgentMeta):
         except ValidationError as e:
             # Handle validation errors for tool arguments
             result = f"Function Args were invalid: {str(e)}"
-            compiled_args = {}
+            compiled_args = None
             self.tracer.record_exception(str(e))
             logger.exception(e)
         try:
-            if compiled_args:
+            if compiled_args is not None:
                 result = await _safe_run(handler, **compiled_args)
                 self.tracer.set_attributes(result=result)
         except TypeError as e:
@@ -451,16 +580,65 @@ class BaseAgent(metaclass=AgentMeta):
             raw_kwargs=tool_call.arguments, call_depth=call_depth, output=result, **compiled_args
         )
 
+    @traced(SpanKind.TOOL)
+    async def _process_mcp_tool_call(self, tool_call: ToolCall, call_depth: int) -> ToolResponse:
+        """Processes a tool call routed to an MCP server.
+
+        Args:
+            tool_call (ToolCall): The tool call to execute via MCP.
+            call_depth (int): Current depth in the tool calling loop.
+
+        Returns:
+            ToolResponse: The response from the MCP tool execution.
+        """
+        # Add tool call to conversation history (provider-specific format)
+        self.state._messages.append(self.provider.to_tool_call_message(tool_call))
+
+        client, original_name = self._mcp_tool_routing[tool_call.name]
+        kwargs = json.loads(tool_call.arguments)
+
+        try:
+            mcp_result = await client.call_tool(original_name, kwargs)
+            # CallToolResult has .content (list of content blocks)
+            parts = []
+            for block in mcp_result.content:
+                if hasattr(block, "text"):
+                    parts.append(block.text)
+                else:
+                    parts.append(str(block))
+            result = "\n".join(parts)
+            self.tracer.set_attributes(result=result)
+        except Exception as e:
+            self.tracer.record_exception(str(e))
+            logger.exception(e)
+            result = f"MCP tool `{tool_call.name}` failed: {e}. Please kindly state to the user that it failed, provide state, and ask if they want to try again."  # noqa E501
+
+        # Add result to conversation history
+        self.state._messages.append(
+            self.provider.to_tool_call_result_message(result=result, id_=tool_call.id)
+        )
+
+        if self.phases:
+            self.state._update_state_machine(phases=self.phases)
+
+        # Return a base ToolResponse (not a class-time typed subclass,
+        # since MCP tools are discovered at runtime)
+        return ToolResponse(
+            raw_kwargs=tool_call.arguments, call_depth=call_depth, output=result
+        )
+
     async def _get_tool_defs(self) -> list[_ToolDefinition]:
         """
-        Builds a list of tool definitions from @tool methods and linked agents.
+        Builds a list of tool definitions from @tool methods, linked agents, and MCP servers.
 
         Resolves any StateRef references in tool parameters using the current agent_reference,
-        allowing tools to dynamically reference state values.
+        allowing tools to dynamically reference state values. Lazily connects to MCP servers
+        on first call.
 
         Returns:
             list[_ToolDefinition]: List of resolved tool definitions ready for LLM
         """
+        await self._ensure_mcp_connected()
         tool_defs = []
 
         # Add all @tool decorated methods
@@ -540,9 +718,6 @@ class BaseAgent(metaclass=AgentMeta):
             # Add user message to conversation state
             self.state.add_user_message(input_)
 
-            # Build tool definitions (including linked agents as tools)
-            tool_defs = await self._get_tool_defs()
-
             # Track responses and prevent duplicate processing
             tool_responses: list = []
             agent_responses: list = []
@@ -553,6 +728,10 @@ class BaseAgent(metaclass=AgentMeta):
             final_ai_output: str | None = None
 
             while depth < self.max_call_depth:
+                # Rebuild tool definitions each iteration so phase transitions
+                # that occurred during tool execution are reflected
+                tool_defs = await self._get_tool_defs()
+
                 # Ask the LLM what to do next (may return tool calls or final text)
                 response = await self._process_llm_inference(tool_defs=tool_defs)
                 yield response
@@ -610,6 +789,8 @@ class BaseAgent(metaclass=AgentMeta):
                 final_ai_output = response.parsed if response.parsed else response.text
 
             # Build the structured response
+            if final_ai_output is None:
+                final_ai_output = ""
             response_fields = {
                 "final_output": final_ai_output,
                 "state": self.state,

{pyagentic_core-2.3.0a12 → pyagentic_core-2.4.0a3}/pyagentic/_base/_info.py

@@ -83,3 +83,16 @@ class ParamInfo(_SpecInfo):
     description: MaybeRef[str] | None = None
     required: MaybeRef[bool] | None = False
     values: MaybeRef[list[str]] | None = None
+
+
+@dataclass
+class MCPInfo(_SpecInfo):
+    """Descriptor for configuring MCP server connections."""
+
+    server: Any = None
+    args: list[str] | None = None
+    tools: list[str] | None = None
+    exclude_tools: list[str] | None = None
+    prefix: bool | str = True
+    condition: Callable | None = None
+    phases: list[str] | None = None

pyagentic_core-2.4.0a3/pyagentic/_base/_mcp.py

@@ -0,0 +1,264 @@
+"""
+MCP (Model Context Protocol) integration types and helpers.
+
+Provides:
+  - ``MCPLink``: Type annotation marker for MCP server connections
+  - ``_MCPDefinition``: Pairs a field name with its ``MCPInfo`` config
+  - ``_MCPToolDefinition``: A ``_ToolDefinition`` subclass for MCP-sourced tools
+  - ``mcp_tool_to_tool_def()``: Converts a fastmcp ``Tool`` into ``_MCPToolDefinition``
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Self
+
+from pyagentic._base._info import MCPInfo, ParamInfo
+from pyagentic._base._tool import _ToolDefinition
+
+
+class MCPLink:
+    """Type annotation marker for MCP server connections.
+
+    Used as a type annotation on agent class fields so the metaclass can
+    detect MCP server configurations.  Paired with ``spec.MCPLink()`` which
+    returns an ``MCPInfo`` descriptor.
+
+    Example:
+        ```python
+        class MyAgent(BaseAgent):
+            __system_message__ = "You are helpful"
+
+            fs: MCPLink = spec.MCPLink(
+                "npx",
+                args=["@modelcontextprotocol/server-filesystem", "/tmp"],
+                tools=["read_file", "write_file"],
+                prefix=True,
+            )
+        ```
+    """
+
+    pass
+
+
+@dataclass
+class _MCPDefinition:
+    """Pairs an agent field name with its MCP configuration."""
+
+    field_name: str
+    info: MCPInfo
+
+
+@dataclass
+class _MCPToolDefinition(_ToolDefinition):
+    """A tool definition sourced from an MCP server.
+
+    Overrides the base ``_ToolDefinition`` to work with raw JSON Schema
+    from MCP instead of Python type introspection.
+
+    Attributes:
+        mcp_field_name: The agent field name (e.g. ``"fs"``).
+        mcp_original_name: The original tool name on the MCP server.
+        json_schema: Raw JSON Schema for the tool's input parameters.
+    """
+
+    mcp_field_name: str = ""
+    mcp_original_name: str = ""
+    json_schema: dict = field(default_factory=dict)
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        description: str,
+        json_schema: dict,
+        mcp_field_name: str,
+        mcp_original_name: str,
+    ):
+        super().__init__(
+            name=name,
+            description=description,
+            parameters={},
+            return_type=str,
+        )
+        self.mcp_field_name = mcp_field_name
+        self.mcp_original_name = mcp_original_name
+        self.json_schema = json_schema
+
+    # JSON Schema keywords not supported by Anthropic's strict tool mode
+    _UNSUPPORTED_SCHEMA_KEYS = frozenset({
+        "$schema", "exclusiveMaximum", "exclusiveMinimum",
+        "maxLength", "minLength", "maxItems", "minItems",
+        "uniqueItems", "pattern", "format",
+        "maximum", "minimum", "multipleOf",
+    })
+
+    @classmethod
+    def _strip_unsupported(cls, obj: dict) -> dict:
+        """Recursively strip unsupported JSON Schema keys and enforce strict mode.
+
+        Also injects ``additionalProperties: false`` on every ``object``
+        type node, as required by Anthropic's strict tool mode.
+        """
+        cleaned = {}
+        for key, value in obj.items():
+            if key in cls._UNSUPPORTED_SCHEMA_KEYS:
+                continue
+            if isinstance(value, dict):
+                cleaned[key] = cls._strip_unsupported(value)
+            else:
+                cleaned[key] = value
+        # Anthropic strict mode requires additionalProperties: false
+        # on every object-typed node in the schema
+        if cleaned.get("type") == "object":
+            cleaned["additionalProperties"] = False
+        return cleaned
+
+    def _clean_schema(self) -> dict:
+        """Return a cleaned copy of the MCP JSON Schema.
+
+        Strips meta-keys and unsupported validation keywords that LLM
+        APIs don't accept, and ensures ``type`` and ``properties`` are
+        present.
+        """
+        schema = self._strip_unsupported(
+            dict(self.json_schema) if self.json_schema else {}
+        )
+        if "type" not in schema:
+            schema["type"] = "object"
+        if "properties" not in schema:
+            schema["properties"] = {}
+        return schema
+
+    def to_openai_spec(self) -> dict:
+        """Emit the raw JSON Schema from the MCP server.
+
+        Returns:
+            dict: An OpenAI-compliant tool specification dictionary.
+        """
+        return {
+            "type": "function",
+            "name": self.name,
+            "description": self.description,
+            "parameters": self._clean_schema(),
+        }
+
+    def to_anthropic_spec(self) -> dict:
+        """Emit Anthropic-formatted tool spec with strict mode from MCP JSON Schema.
+
+        Uses ``strict: true`` and ``additionalProperties: false`` to guarantee
+        schema conformance via grammar-constrained sampling.
+
+        Returns:
+            dict: An Anthropic-compliant tool specification dictionary.
+        """
+        schema = self._clean_schema()
+        schema["additionalProperties"] = False
+
+        return {
+            "name": self.name,
+            "description": self.description,
+            "strict": True,
+            "input_schema": schema,
+        }
+
+    def compile_args(self, **kwargs) -> dict[str, Any]:
+        """Pass-through: MCP handles its own validation.
+
+        Args:
+            **kwargs: Raw keyword arguments from the LLM tool call.
+
+        Returns:
+            dict[str, Any]: The same kwargs, unmodified.
+        """
+        return kwargs
+
+    def resolve(self, agent_reference: dict) -> Self:
+        """MCP tools have no StateRefs to resolve.
+
+        Args:
+            agent_reference (dict): The agent reference dict (unused).
+
+        Returns:
+            Self: Returns self unchanged.
+        """
+        return self
+
+
+def _json_schema_to_parameters(
+    schema: dict,
+) -> dict[str, tuple[type, ParamInfo]]:
+    """Convert a JSON Schema properties dict to ``(type, ParamInfo)`` pairs.
+
+    This is a simple mapping used for response model compatibility. Complex
+    schemas fall back to ``str``.
+
+    Args:
+        schema (dict): JSON Schema with ``properties`` and optionally ``required``.
+
+    Returns:
+        dict[str, tuple[type, ParamInfo]]: Mapping of parameter names to
+            ``(python_type, ParamInfo)`` tuples.
+    """
+    _JSON_TYPE_MAP = {
+        "string": str,
+        "integer": int,
+        "number": float,
+        "boolean": bool,
+    }
+    properties = schema.get("properties", {})
+    required_fields = set(schema.get("required", []))
+    params: dict[str, tuple[type, ParamInfo]] = {}
+
+    for prop_name, prop_schema in properties.items():
+        json_type = prop_schema.get("type", "string")
+        py_type = _JSON_TYPE_MAP.get(json_type, str)
+        is_required = prop_name in required_fields
+        description = prop_schema.get("description")
+        params[prop_name] = (
+            py_type,
+            ParamInfo(required=is_required, description=description),
+        )
+
+    return params
+
+
+def mcp_tool_to_tool_def(
+    mcp_tool: Any,
+    field_name: str,
+    prefix: bool | str,
+) -> _MCPToolDefinition:
+    """Convert a fastmcp ``Tool`` object to an ``_MCPToolDefinition``.
+
+    Applies prefix logic: when *prefix* is ``True``, the tool name becomes
+    ``{field_name}__{original_name}``.  When *prefix* is a string, it is
+    used instead of *field_name*.
+
+    Args:
+        mcp_tool (Any): A fastmcp ``Tool`` object with ``name``,
+            ``description``, and ``inputSchema`` attributes.
+        field_name (str): The agent field name (e.g. ``"fs"``).
+        prefix (bool | str): Prefix mode — ``True`` uses *field_name*,
+            a string uses that value, ``False`` uses no prefix.
+
+    Returns:
+        _MCPToolDefinition: The converted tool definition.
+    """
+    original_name = mcp_tool.name
+    description = mcp_tool.description or ""
+    input_schema = mcp_tool.inputSchema if hasattr(mcp_tool, "inputSchema") else {}
+
+    if prefix is True:
+        prefixed_name = f"{field_name}__{original_name}"
+    elif isinstance(prefix, str) and prefix:
+        prefixed_name = f"{prefix}__{original_name}"
+    else:
+        prefixed_name = original_name
+
+    return _MCPToolDefinition(
+        name=prefixed_name,
+        description=description,
+        json_schema=input_schema,
+        mcp_field_name=field_name,
+        mcp_original_name=original_name,
+    )