mirascope 1.21.6__tar.gz → 1.22.0__tar.gz

{mirascope-1.21.6 → mirascope-1.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mirascope
-Version: 1.21.6
+Version: 1.22.0
 Summary: LLM abstractions that aren't obstructions
 Project-URL: Homepage, https://mirascope.com
 Project-URL: Documentation, https://mirascope.com/WELCOME
@@ -79,7 +79,7 @@ Requires-Dist: litellm<2,>=1.42.12; extra == 'litellm'
 Provides-Extra: logfire
 Requires-Dist: logfire<4,>=1.0.0; extra == 'logfire'
 Provides-Extra: mcp
-Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Requires-Dist: mcp>=1.3.0; extra == 'mcp'
 Provides-Extra: mistral
 Requires-Dist: mistralai<2,>=1.0.0; extra == 'mistral'
 Provides-Extra: openai

{mirascope-1.21.6 → mirascope-1.22.0}/docs/learn/mcp/client.md

@@ -3,7 +3,7 @@
 !!! mira ""
 
     <div align="center">
-        If you haven't already, we recommend first reading the section on [MCP Server](./server.md)
+        If you haven't already, we recommend first reading and learning about [Model Context Protocol](https://github.com/modelcontextprotocol)
     </div>
 
 MCP Client in Mirascope enables you to interact with MCP servers through a standardized protocol. The client provides methods to access resources, tools, and prompts exposed by MCP servers.
@@ -12,59 +12,83 @@ MCP Client in Mirascope enables you to interact with MCP servers through a stand
 
 Let's connect to our book recommendation server using the MCP client:
 
-```python hl_lines="11-15 19-26 28-33 35 39 44-47"
---8<-- "examples/learn/mcp/client.py"
-```
+!!! mira ""
+
+    ```python hl_lines="10-14 18"
+    --8<-- "examples/learn/mcp/client.py:1:20"
+    --8<-- "examples/learn/mcp/client.py:48:50"
+    ```
 
 This example demonstrates:
 
 1. Creating server parameters with `StdioServerParameters`
-2. Using the `create_mcp_client` context manager to connect to the server
-3. Accessing server components:
-   - Listing and using prompts
-   - Reading resources 
-   - Using tools with Mirascope calls
+2. Using the `stdio_client` context manager to connect to the server
+3. Accessing the list of available prompts
 
 ## Client Components
 
-### Server Connection
+### Standard In/Out (stdio) Server Connection
 
-To connect to an MCP server, use the `create_mcp_client` context manager with appropriate server parameters:
+To connect to an MCP server, use the `stdio_client` context manager with appropriate server parameters:
 
-```python hl_lines="3-7 11"
---8<-- "examples/learn/mcp/client.py:9:19"
-```
+!!! mira ""
+
+    ```python hl_lines="1 3-7 11"
+    --8<-- "examples/learn/mcp/client.py:8:20"
+    ```
 
 The `StdioServerParameters` specify how to launch and connect to the server process.
 
+### Server Side Events (sse) Server Connection
+
+You can also use the `sse_client` instead to connect to an MCP server side event endpoint:
+
+!!! mira ""
+
+    ```python hl_lines="4"
+    from mirascope.mcp import sse_client
+
+
+    async with sse_client("http://localhost:8000") as client:
+        prompts = await client.list_prompts()
+        print(prompts[0])
+    ```
+
 ### Prompts
 
 You can list available prompts and get prompt templates from the server:
 
-```python
---8<-- "examples/learn/mcp/client.py:20:26"
-```
+!!! mira ""
+
+    ```python
+    --8<-- "examples/learn/mcp/client.py:19:25"
+    ```
 
-The client automatically converts server prompts into Mirascope-compatible prompt templates that return `BaseMessageParam` instances.
+The client automatically converts server prompts into Mirascope-compatible prompt templates that return `BaseMessageParam` instances. This makes it easy to consume these prompts downstream in your Mirascope code.
 
 ### Resources
 
 Resources can be listed and read from the server:
 
-```python
---8<-- "examples/learn/mcp/client.py:28:33"
-```
+!!! mira ""
+
+    ```python
+    --8<-- "examples/learn/mcp/client.py:27:32"
+    ```
 
 The client provides methods to:
+
 - `list_resources()`: Get available resources
 - `read_resource(uri)`: Read resource content by URI
 
+If the resource is text, it will be converted into a `TextPart` instance. Otherwise it will be the MCP `BlobResourceContents` type where the data contained is the original bytes encoded as a base64 string.
+
 ### Tools
 
 Tools from the server can be used with Mirascope's standard call decorators:
 
-```python hl_lines="1 5 10-13"
---8<-- "examples/learn/mcp/client.py:35:47"
+```python hl_lines="1 6 11-14"
+--8<-- "examples/learn/mcp/client.py:34:47"
 ```
 
 The client automatically converts server tools into Mirascope-compatible tool types that can be used with any provider's call decorator.
@@ -79,7 +103,6 @@ The MCP client preserves type information from the server:
 
 This enables full editor support and type checking when using server components.
 
-
 ## Next Steps
 
 By using the MCP client with Mirascope's standard features like [Calls](../calls.md), [Tools](../tools.md), and [Prompts](../prompts.md), you can build powerful applications that leverage local services through MCP servers.

{mirascope-1.21.6 → mirascope-1.22.0}/docs/learn/mcp/server.md

@@ -1,10 +1,12 @@
 # MCP Server
 
-!!! mira ""
+!!! warning "This interface is deprecated!"
 
-    <div align="center">
-        If you haven't already, we recommend first reading the section on [Tools](../tools.md)
-    </div>
+    We have updated the Mirascope MCP Client module such that the `sse_client` and `stdio_client` properly handle connecting to any MCP server.
+
+    Given the introduction of `FastMCP` into the official MCP SDK, there's no reason to use this interface.
+
+    Instead, we recommend using the official SDK to build your servers (to which you can easily connect your Mirascope code now).
 
 MCP (Model Context Protocol) Server in Mirascope enables you to expose resources, tools, and prompts to LLM clients through a standardized protocol. This allows for secure and controlled interactions between host applications (like Claude Desktop) and local services.
 

{mirascope-1.21.6 → mirascope-1.22.0}/examples/learn/mcp/client.py

@@ -1,10 +1,9 @@
 import asyncio
-
 from pathlib import Path
 
-from mirascope.core import openai
-from mirascope.mcp.client import create_mcp_client, StdioServerParameters
-
+from mcp.client.stdio import StdioServerParameters
+from mirascope import llm
+from mirascope.mcp import stdio_client
 
 server_file = Path(__file__).parent / "server.py"
 
@@ -16,7 +15,7 @@ server_params = StdioServerParameters(
 
 
 async def main() -> None:
-    async with create_mcp_client(server_params) as client:
+    async with stdio_client(server_params) as client:
         prompts = await client.list_prompts()
         print(prompts[0])
         # name='recommend_book' description='Get book recommendations by genre.' arguments=[PromptArgument(name='genre', description='Genre of book to recommend (fantasy, mystery, sci-fi, etc.)', required=True)]
@@ -34,8 +33,9 @@ async def main() -> None:
 
         tools = await client.list_tools()
 
-        @openai.call(
-            "gpt-4o-mini",
+        @llm.call(
+            provider="openai",
+            model="gpt-4o-mini",
             tools=tools,
         )
         def recommend_book(genre: str) -> str:

{mirascope-1.21.6 → mirascope-1.22.0}/mirascope/llm/__init__.py

@@ -4,6 +4,7 @@ from ._context import context
 from ._override import override
 from .call_response import CallResponse
 from .stream import Stream
+from .tool import Tool
 
 __all__ = [
     "CallResponse",
@@ -11,6 +12,7 @@ __all__ = [
     "LocalProvider",
     "Provider",
     "Stream",
+    "Tool",
     "calculate_cost",
     "call",
     "context",

mirascope-1.22.0/mirascope/mcp/__init__.py

@@ -0,0 +1,7 @@
+"""Mirascope Model Context Protocol (MCP) implementation."""
+
+from .client import MCPClient, sse_client, stdio_client
+from .server import MCPServer  # DEPRECATED
+from .tools import MCPTool  # DEPRECATED
+
+__all__ = ["MCPClient", "MCPServer", "MCPTool", "sse_client", "stdio_client"]

mirascope-1.21.6/mirascope/mcp/client.py → mirascope-1.22.0/mirascope/mcp/_utils.py

@@ -1,48 +1,46 @@
+"""MCP client utility functions."""
+
 import base64
 import string
 from collections.abc import AsyncGenerator, Awaitable, Callable
 from contextlib import asynccontextmanager
-from typing import Any, TypeVar
+from typing import Any
 
 from anyio import create_memory_object_stream, create_task_group
 from anyio.streams.memory import MemoryObjectReceiveStream
-from mcp import ClientSession
-from mcp.client.stdio import StdioServerParameters, stdio_client
 from mcp.types import (
-    BlobResourceContents,
-    CallToolResult,
     EmbeddedResource,
     ImageContent,
     JSONRPCMessage,
-    Prompt,
     PromptMessage,
-    Resource,
     TextContent,
     TextResourceContents,
-    Tool,
 )
-from pydantic import AnyUrl, BaseModel, ConfigDict, Field, create_model
-
-from mirascope.core import BaseMessageParam, BaseTool
-from mirascope.core.base import AudioPart, DocumentPart, ImagePart
+from mcp.types import Tool as MCPTool
+from pydantic import BaseModel, ConfigDict, Field, create_model
 
-_BaseToolT = TypeVar("_BaseToolT", bound=BaseTool)
+from ..core import BaseMessageParam, BaseTool
+from ..core.base import AudioPart, DocumentPart, ImagePart
 
 
-def _create_tool_call(
+def create_tool_call(
     name: str,
-    call_tool: Callable[[str, dict | None], Awaitable[CallToolResult]],
+    call_tool: Callable[[str, dict | None], Awaitable[Any]],
 ) -> Callable[..., Awaitable[list[str | ImageContent | EmbeddedResource]]]:
+    """Create a tool call function for a Mirascope Tool.
+
+    Args:
+        name: The name of the tool
+        call_tool: The function to call the tool
+
+    Returns:
+        A function that can be used as the call method for a Tool
+    """
+
     async def call(self: BaseTool) -> list[str | ImageContent | EmbeddedResource]:
         result = await call_tool(name, self.args)  # pyright: ignore [reportOptionalCall]
         if result.isError:
             raise RuntimeError(f"MCP Server returned error: {self._name()}")
-        parsed_results = []
-        for content in result.content:
-            if isinstance(content, TextContent):
-                parsed_results.append(content.text)
-            else:
-                parsed_results.append(content)
         return [
             content.text if isinstance(content, TextContent) else content
             for content in result.content
@@ -51,7 +49,7 @@ def _create_tool_call(
     return call
 
 
-def _convert_prompt_message_to_base_message_params(
+def convert_prompt_message_to_base_message_params(
     prompt_message: PromptMessage,
 ) -> BaseMessageParam:
     """
@@ -93,6 +91,7 @@ def _convert_prompt_message_to_base_message_params(
     elif isinstance(content, EmbeddedResource):
         resource = content.resource
         if isinstance(resource, TextResourceContents):
+            # For text content embedded resources, just return the text
             return BaseMessageParam(role=prompt_message.role, content=resource.text)
         else:
             mime_type = resource.mimeType
@@ -131,12 +130,30 @@ def _convert_prompt_message_to_base_message_params(
 
 
 def snake_to_pascal(snake: str) -> str:
+    """Convert a snake_case string to PascalCase.
+
+    Args:
+        snake: A snake_case string
+
+    Returns:
+        The string converted to PascalCase
+    """
     return string.capwords(snake.replace("_", " ")).replace(" ", "")
 
 
 def build_object_type(
     properties: dict[str, Any], required: list[str], name: str
 ) -> type[BaseModel]:
+    """Build a Pydantic model from JSON Schema properties.
+
+    Args:
+        properties: JSON Schema properties dictionary
+        required: List of required property names
+        name: Name for the generated model
+
+    Returns:
+        A dynamically created Pydantic model class
+    """
     fields = {}
     for prop_name, prop_schema in properties.items():
         class_name = snake_to_pascal(prop_name)
@@ -158,6 +175,13 @@ def build_object_type(
 def json_schema_to_python_type(schema: dict[str, Any], name: str = "Model") -> Any:  # noqa: ANN401
     """
     Recursively convert a JSON Schema snippet into a Python type annotation or a dynamically generated pydantic model.
+
+    Args:
+        schema: JSON Schema to convert
+        name: Name for any generated models
+
+    Returns:
+        Corresponding Python type or Pydantic model
     """
     json_type = schema.get("type", "any")
 
@@ -184,9 +208,15 @@ def json_schema_to_python_type(schema: dict[str, Any], name: str = "Model") -> A
         return Any
 
 
-def create_model_from_tool(tool: Tool) -> type[BaseModel]:
+def create_tool_from_mcp_tool(tool: MCPTool) -> type[BaseTool]:
     """
-    Create a dynamic pydantic model from the given Tool instance based on its inputSchema.
+    Create a `BaseTool` type definition from the given MCP Tool instance.
+
+    Args:
+        tool: MCP tool instance.
+
+    Returns:
+        A dynamically created `Tool` schema.
     """
     schema = tool.inputSchema
     properties = schema.get("properties", {})
@@ -205,59 +235,7 @@ def create_model_from_tool(tool: Tool) -> type[BaseModel]:
 
         fields[field_name] = (annotation, default)
 
-    return create_model(
-        snake_to_pascal(tool.name), __config__=ConfigDict(extra="allow"), **fields
-    )
-
-
-class MCPClient:
-    def __init__(self, session: ClientSession) -> None:
-        self.session: ClientSession = session
-
-    async def list_resources(self) -> list[Resource]:
-        result = await self.session.list_resources()
-        return result.resources
-
-    async def read_resource(
-        self, uri: str | AnyUrl
-    ) -> list[str | BlobResourceContents]:
-        result = await self.session.read_resource(
-            uri if isinstance(uri, AnyUrl) else AnyUrl(uri)
-        )
-        parsed_results = []
-        for content in result.contents:
-            if isinstance(content, TextResourceContents):
-                parsed_results.append(content.text)
-            else:
-                parsed_results.append(content)
-        return parsed_results
-
-    async def list_prompts(self) -> list[Prompt]:
-        result = await self.session.list_prompts()
-        return result.prompts
-
-    async def get_prompt_template(
-        self, name: str
-    ) -> Callable[..., Awaitable[list[BaseMessageParam]]]:
-        async def async_prompt(**kwargs: str) -> list[BaseMessageParam]:
-            result = await self.session.get_prompt(name, kwargs)
-
-            return [
-                _convert_prompt_message_to_base_message_params(prompt_message)
-                for prompt_message in result.messages
-            ]
-
-        return async_prompt
-
-    async def list_tools(self) -> list[type[BaseModel]]:
-        list_tool_result = await self.session.list_tools()
-
-        converted_tools = []
-        for tool in list_tool_result.tools:
-            model = create_model_from_tool(tool)
-            model.call = _create_tool_call(tool.name, self.session.call_tool)  # pyright: ignore [reportAttributeAccessIssue]
-            converted_tools.append(model)
-        return converted_tools
+    return create_model(snake_to_pascal(tool.name), __base__=BaseTool, **fields)
 
 
 @asynccontextmanager
@@ -267,10 +245,14 @@ async def read_stream_exception_filer(
 ) -> AsyncGenerator[MemoryObjectReceiveStream[JSONRPCMessage], None]:
     """
     Handle exceptions in the original stream.
-    default handler is to ignore read stream exception for invalid JSON lines and log them.
+    Default handler is to ignore read stream exception for invalid JSON lines and log them.
+
     Args:
         original_read: The original stream to read from.
         exception_handler: An optional handler for exception.
+
+    Yields:
+        A filtered stream with exceptions removed
     """
     read_stream_writer, filtered_read = create_memory_object_stream(0)
 
@@ -293,29 +275,3 @@ async def read_stream_exception_filer(
         finally:
             await filtered_read.aclose()
             tg.cancel_scope.cancel()
-
-
-@asynccontextmanager
-async def create_mcp_client(
-    server_parameters: StdioServerParameters,
-    read_stream_exception_handler: Callable[[Exception], None] | None = None,
-) -> AsyncGenerator[MCPClient, None]:
-    """
-    Create a MCPClient instance with the given server parameters and exception handler.
-
-    Args:
-        server_parameters:
-        read_stream_exception_handler:
-
-    Returns:
-
-    """
-    async with (
-        stdio_client(server_parameters) as (read, write),
-        read_stream_exception_filer(
-            read, read_stream_exception_handler
-        ) as filtered_read,
-        ClientSession(filtered_read, write) as session,
-    ):
-        await session.initialize()
-        yield MCPClient(session)

mirascope-1.22.0/mirascope/mcp/client.py

@@ -0,0 +1,167 @@
+"""The `MCPServer` Class and context managers."""
+
+import contextlib
+from collections.abc import AsyncIterator, Awaitable, Callable
+from datetime import timedelta
+from typing import Any
+
+from mcp import ClientSession
+from mcp.client.session import ListRootsFnT, SamplingFnT
+from mcp.client.sse import sse_client as mcp_sse_client
+from mcp.client.stdio import StdioServerParameters
+from mcp.client.stdio import stdio_client as mcp_stdio_client
+from mcp.types import (
+    BlobResourceContents,
+    Resource,
+)
+from pydantic import AnyUrl
+
+from mirascope.core import BaseMessageParam, BaseTool, TextPart
+from mirascope.mcp import _utils
+
+
+class MCPClient(ClientSession):
+    """The SSE client session that connects to the MCP server.
+
+    All of the results from the server are converted into Mirascope-friendly types.
+    """
+
+    _session: ClientSession
+
+    def __init__(self, session: ClientSession) -> None:
+        """Initializes an instance of `MCPClient`.
+
+        Args:
+            session: The original MCP `ClientSession`.
+        """
+        self._session = session
+
+    async def list_resources(self) -> list[Resource]:  # pyright: ignore [reportIncompatibleMethodOverride]
+        """List all resources available on the MCP server.
+
+        Returns:
+            A list of Resource objects
+        """
+        result = await self._session.list_resources()
+        return result.resources
+
+    async def read_resource(  # pyright: ignore [reportIncompatibleMethodOverride]
+        self, uri: str | AnyUrl
+    ) -> list[TextPart | BlobResourceContents]:
+        """Read a resource from the MCP server.
+
+        Args:
+            uri: URI of the resource to read
+
+        Returns:
+            Contents of the resource, either as string or BlobResourceContents
+        """
+        result = await self._session.read_resource(
+            uri if isinstance(uri, AnyUrl) else AnyUrl(uri)
+        )
+        parsed_results: list[TextPart | BlobResourceContents] = []
+        for content in result.contents:
+            if isinstance(content, BlobResourceContents):
+                parsed_results.append(content)
+            else:
+                parsed_results.append(TextPart(type="text", text=content.text))
+        return parsed_results
+
+    async def list_prompts(self) -> list[Any]:  # pyright: ignore [reportIncompatibleMethodOverride]
+        """List all prompts available on the MCP server.
+
+        Returns:
+            A list of Prompt objects
+        """
+        result = await self._session.list_prompts()
+        return result.prompts
+
+    async def get_prompt_template(
+        self, name: str
+    ) -> Callable[..., Awaitable[list[BaseMessageParam]]]:
+        """Get a prompt template from the MCP server.
+
+        Args:
+            name: Name of the prompt template
+
+        Returns:
+            A callable that accepts keyword arguments and returns a list of BaseMessageParam
+        """
+
+        # TODO: wrap this with `llm.prompt` once it's implemented so that they prompts
+        # can be run super easily inside of an `llm.context` block.
+        async def async_prompt(**kwargs: str) -> list[BaseMessageParam]:
+            result = await self._session.get_prompt(name, kwargs)  # type: ignore
+
+            return [
+                _utils.convert_prompt_message_to_base_message_params(prompt_message)
+                for prompt_message in result.messages
+            ]
+
+        return async_prompt
+
+    async def list_tools(self) -> list[type[BaseTool]]:  # pyright: ignore [reportIncompatibleMethodOverride]
+        """List all tools available on the MCP server.
+
+        Returns:
+            A list of dynamically created `BaseTool` types.
+        """
+        list_tool_result = await self._session.list_tools()
+
+        converted_tools = []
+        for tool in list_tool_result.tools:
+            model = _utils.create_tool_from_mcp_tool(tool)
+            tool_call_method = _utils.create_tool_call(
+                tool.name, self._session.call_tool
+            )
+            model.call = tool_call_method  # pyright: ignore [reportAttributeAccessIssue]
+            converted_tools.append(model)
+        return converted_tools
+
+
+@contextlib.asynccontextmanager
+async def sse_client(
+    url: str,
+    list_roots_callback: ListRootsFnT | None = None,
+    read_timeout_seconds: timedelta | None = None,
+    sampling_callback: SamplingFnT | None = None,
+    session: ClientSession | None = None,
+) -> AsyncIterator[MCPClient]:
+    async with (
+        mcp_sse_client(url) as (read, write),
+        ClientSession(
+            read,
+            write,
+            read_timeout_seconds=read_timeout_seconds,
+            sampling_callback=sampling_callback,
+            list_roots_callback=list_roots_callback,
+        ) as session,
+    ):
+        await session.initialize()
+        yield MCPClient(session)
+
+
+@contextlib.asynccontextmanager
+async def stdio_client(
+    server_parameters: StdioServerParameters,
+    read_stream_exception_handler: Callable[[Exception], None] | None = None,
+) -> AsyncIterator[MCPClient]:
+    """
+    Create a MCPClient instance with the given server parameters and exception handler.
+
+    Args:
+        server_parameters:
+        read_stream_exception_handler:
+
+    Returns:
+
+    """
+    async with (
+        mcp_stdio_client(server_parameters) as (read, write),
+        _utils.read_stream_exception_filer(
+            read, read_stream_exception_handler
+        ) as filtered_read,
+        ClientSession(filtered_read, write) as session,  # pyright: ignore [reportArgumentType]
+    ):
+        await session.initialize()
+        yield MCPClient(session)

{mirascope-1.21.6 → mirascope-1.22.0}/mirascope/mcp/server.py

@@ -1,6 +1,7 @@
-"""MCP server implementation."""
+"""The `MCPServer` Class and context managers."""
 
 import inspect
+import warnings
 from collections.abc import Awaitable, Callable, Iterable
 from typing import Literal, ParamSpec, cast, overload
 
@@ -117,7 +118,12 @@ def _generate_prompt_from_function(fn: Callable) -> Prompt:
 
 
 class MCPServer:
-    """MCP server implementation."""
+    """MCP server implementation.
+
+    DEPRECATED: The MCPServer implementation is deprecated and will be removed in a future version.
+    Mirascope will only implement the client-side of MCP in the future, allowing it to connect to any
+    MCP server implementation, even if not built with Mirascope.
+    """
 
     def __init__(
         self,
@@ -134,6 +140,13 @@ class MCPServer:
         ]
         | None = None,
     ) -> None:
+        warnings.warn(
+            "MCPServer is deprecated and will be removed in a future version. "
+            "Mirascope will only implement the client-side of MCP in the future. "
+            "We recommend using the official MCP SDK (e.g. `FastMCP`) for server-side implementations.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self.name: str = name
         self.version: str = version
         self.server: Server = Server(name)