fastmcp 0.4.1__py3-none-any.whl → 2.0.0__py3-none-any.whl

fastmcp/resources/resource_manager.py

@@ -1,6 +1,7 @@
 """Resource manager functionality."""
 
-from typing import Callable, Dict, Optional, Union
+from collections.abc import Callable
+from typing import Any
 
 from pydantic import AnyUrl
 
@@ -15,8 +16,8 @@ class ResourceManager:
     """Manages FastMCP resources."""
 
     def __init__(self, warn_on_duplicate_resources: bool = True):
-        self._resources: Dict[str, Resource] = {}
-        self._templates: Dict[str, ResourceTemplate] = {}
+        self._resources: dict[str, Resource] = {}
+        self._templates: dict[str, ResourceTemplate] = {}
         self.warn_on_duplicate_resources = warn_on_duplicate_resources
 
     def add_resource(self, resource: Resource) -> Resource:
@@ -34,7 +35,7 @@ class ResourceManager:
             extra={
                 "uri": resource.uri,
                 "type": type(resource).__name__,
-                "name": resource.name,
+                "resource_name": resource.name,
             },
         )
         existing = self._resources.get(str(resource.uri))
@@ -47,11 +48,11 @@ class ResourceManager:
 
     def add_template(
         self,
-        fn: Callable,
+        fn: Callable[..., Any],
         uri_template: str,
-        name: Optional[str] = None,
-        description: Optional[str] = None,
-        mime_type: Optional[str] = None,
+        name: str | None = None,
+        description: str | None = None,
+        mime_type: str | None = None,
     ) -> ResourceTemplate:
         """Add a template from a function."""
         template = ResourceTemplate.from_function(
@@ -64,7 +65,7 @@ class ResourceManager:
         self._templates[template.uri_template] = template
         return template
 
-    async def get_resource(self, uri: Union[AnyUrl, str]) -> Optional[Resource]:
+    async def get_resource(self, uri: AnyUrl | str) -> Resource | None:
         """Get resource by URI, checking concrete resources first, then templates."""
         uri_str = str(uri)
         logger.debug("Getting resource", extra={"uri": uri_str})
@@ -92,3 +93,59 @@ class ResourceManager:
         """List all registered templates."""
         logger.debug("Listing templates", extra={"count": len(self._templates)})
         return list(self._templates.values())
+
+    def import_resources(
+        self, manager: "ResourceManager", prefix: str | None = None
+    ) -> None:
+        """Import resources from another resource manager.
+
+        Resources are imported with a prefixed URI if a prefix is provided. For example,
+        if a resource has URI "data://users" and you import it with prefix "app+", the
+        imported resource will have URI "app+data://users". If no prefix is provided,
+        the original URI is used.
+
+        Args:
+            manager: The ResourceManager to import from
+            prefix: A prefix to apply to the resource URIs, including the delimiter.
+                   For example, "app+" would result in URIs like "app+data://users".
+                   If None, the original URI is used.
+        """
+        for uri, resource in manager._resources.items():
+            # Create prefixed URI and copy the resource with the new URI
+            prefixed_uri = f"{prefix}{uri}" if prefix else uri
+
+            # Log the import
+            logger.debug(f"Importing resource with URI {uri} as {prefixed_uri}")
+
+            # Store directly in resources dictionary
+            self._resources[prefixed_uri] = resource
+
+    def import_templates(
+        self, manager: "ResourceManager", prefix: str | None = None
+    ) -> None:
+        """Import resource templates from another resource manager.
+
+        Templates are imported with a prefixed URI template if a prefix is provided.
+        For example, if a template has URI template "data://users/{id}" and you import
+        it with prefix "app+", the imported template will have URI template
+        "app+data://users/{id}". If no prefix is provided, the original URI template is used.
+
+        Args:
+            manager: The ResourceManager to import templates from
+            prefix: A prefix to apply to the template URIs, including the delimiter.
+                   For example, "app+" would result in URI templates like "app+data://users/{id}".
+                   If None, the original URI template is used.
+        """
+        for uri_template, template in manager._templates.items():
+            # Create prefixed URI template and copy the template with the new URI template
+            prefixed_uri_template = (
+                f"{prefix}{uri_template}" if prefix else uri_template
+            )
+
+            # Log the import
+            logger.debug(
+                f"Importing resource template with URI {uri_template} as {prefixed_uri_template}"
+            )
+
+            # Store directly in templates dictionary
+            self._templates[prefixed_uri_template] = template

fastmcp/resources/templates.py

@@ -1,8 +1,11 @@
 """Resource template functionality."""
 
+from __future__ import annotations
+
 import inspect
 import re
-from typing import Any, Callable, Dict, Optional
+from collections.abc import Callable
+from typing import Any
 
 from pydantic import BaseModel, Field, TypeAdapter, validate_call
 
@@ -20,18 +23,20 @@ class ResourceTemplate(BaseModel):
     mime_type: str = Field(
         default="text/plain", description="MIME type of the resource content"
     )
-    fn: Callable = Field(exclude=True)
-    parameters: dict = Field(description="JSON schema for function parameters")
+    fn: Callable[..., Any] = Field(exclude=True)
+    parameters: dict[str, Any] = Field(
+        description="JSON schema for function parameters"
+    )
 
     @classmethod
     def from_function(
         cls,
-        fn: Callable,
+        fn: Callable[..., Any],
         uri_template: str,
-        name: Optional[str] = None,
-        description: Optional[str] = None,
-        mime_type: Optional[str] = None,
-    ) -> "ResourceTemplate":
+        name: str | None = None,
+        description: str | None = None,
+        mime_type: str | None = None,
+    ) -> ResourceTemplate:
         """Create a template from a function."""
         func_name = name or fn.__name__
         if func_name == "<lambda>":
@@ -52,7 +57,7 @@ class ResourceTemplate(BaseModel):
             parameters=parameters,
         )
 
-    def matches(self, uri: str) -> Optional[Dict[str, Any]]:
+    def matches(self, uri: str) -> dict[str, Any] | None:
         """Check if URI matches template and extract parameters."""
         # Convert template to regex pattern
         pattern = self.uri_template.replace("{", "(?P<").replace("}", ">[^/]+)")
@@ -61,7 +66,7 @@ class ResourceTemplate(BaseModel):
             return match.groupdict()
         return None
 
-    async def create_resource(self, uri: str, params: Dict[str, Any]) -> Resource:
+    async def create_resource(self, uri: str, params: dict[str, Any]) -> Resource:
         """Create a resource from the template with the given parameters."""
         try:
             # Call function and check if result is a coroutine

fastmcp/resources/types.py

@@ -1,10 +1,13 @@
 """Concrete resource implementations."""
 
-import asyncio
+import inspect
 import json
+from collections.abc import Callable
 from pathlib import Path
-from typing import Any, Callable, Union
+from typing import Any
 
+import anyio
+import anyio.to_thread
 import httpx
 import pydantic.json
 import pydantic_core
@@ -48,10 +51,12 @@ class FunctionResource(Resource):
 
     fn: Callable[[], Any] = Field(exclude=True)
 
-    async def read(self) -> Union[str, bytes]:
+    async def read(self) -> str | bytes:
         """Read the resource by calling the wrapped function."""
         try:
-            result = self.fn()
+            result = (
+                await self.fn() if inspect.iscoroutinefunction(self.fn) else self.fn()
+            )
             if isinstance(result, Resource):
                 return await result.read()
             if isinstance(result, bytes):
@@ -100,12 +105,12 @@ class FileResource(Resource):
         mime_type = info.data.get("mime_type", "text/plain")
         return not mime_type.startswith("text/")
 
-    async def read(self) -> Union[str, bytes]:
+    async def read(self) -> str | bytes:
         """Read the file content."""
         try:
             if self.is_binary:
-                return await asyncio.to_thread(self.path.read_bytes)
-            return await asyncio.to_thread(self.path.read_text)
+                return await anyio.to_thread.run_sync(self.path.read_bytes)
+            return await anyio.to_thread.run_sync(self.path.read_text)
         except Exception as e:
             raise ValueError(f"Error reading file {self.path}: {e}")
 
@@ -114,11 +119,11 @@ class HttpResource(Resource):
     """A resource that reads from an HTTP endpoint."""
 
     url: str = Field(description="URL to fetch content from")
-    mime_type: str | None = Field(
+    mime_type: str = Field(
         default="application/json", description="MIME type of the resource content"
     )
 
-    async def read(self) -> Union[str, bytes]:
+    async def read(self) -> str | bytes:
         """Read the HTTP content."""
         async with httpx.AsyncClient() as client:
             response = await client.get(self.url)
@@ -136,7 +141,7 @@ class DirectoryResource(Resource):
     pattern: str | None = Field(
         default=None, description="Optional glob pattern to filter files"
     )
-    mime_type: str | None = Field(
+    mime_type: str = Field(
         default="application/json", description="MIME type of the resource content"
     )
 
@@ -173,7 +178,7 @@ class DirectoryResource(Resource):
     async def read(self) -> str:  # Always returns JSON string
         """Read the directory listing."""
         try:
-            files = await asyncio.to_thread(self.list_files)
+            files = await anyio.to_thread.run_sync(self.list_files)
             file_list = [str(f.relative_to(self.path)) for f in files if f.is_file()]
             return json.dumps({"files": file_list}, indent=2)
         except Exception as e:

fastmcp/server/__init__.py

@@ -0,0 +1,5 @@
+from .server import FastMCP
+from .context import Context
+
+
+__all__ = ["FastMCP", "Context"]

fastmcp/server/context.py

@@ -0,0 +1,222 @@
+from __future__ import annotations as _annotations
+
+from typing import Any, Generic, Literal
+
+from mcp.server.lowlevel.helper_types import ReadResourceContents
+from mcp.server.session import ServerSessionT
+from mcp.shared.context import LifespanContextT, RequestContext
+from mcp.types import (
+    CreateMessageResult,
+    ImageContent,
+    Root,
+    SamplingMessage,
+    TextContent,
+)
+from pydantic import BaseModel
+from pydantic.networks import AnyUrl
+
+from fastmcp.server.server import FastMCP
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class Context(BaseModel, Generic[ServerSessionT, LifespanContextT]):
+    """Context object providing access to MCP capabilities.
+
+    This provides a cleaner interface to MCP's RequestContext functionality.
+    It gets injected into tool and resource functions that request it via type hints.
+
+    To use context in a tool function, add a parameter with the Context type annotation:
+
+    ```python
+    @server.tool()
+    def my_tool(x: int, ctx: Context) -> str:
+        # Log messages to the client
+        ctx.info(f"Processing {x}")
+        ctx.debug("Debug info")
+        ctx.warning("Warning message")
+        ctx.error("Error message")
+
+        # Report progress
+        ctx.report_progress(50, 100)
+
+        # Access resources
+        data = ctx.read_resource("resource://data")
+
+        # Get request info
+        request_id = ctx.request_id
+        client_id = ctx.client_id
+
+        return str(x)
+    ```
+
+    The context parameter name can be anything as long as it's annotated with Context.
+    The context is optional - tools that don't need it can omit the parameter.
+    """
+
+    _request_context: RequestContext[ServerSessionT, LifespanContextT] | None
+    _fastmcp: FastMCP | None
+
+    def __init__(
+        self,
+        *,
+        request_context: RequestContext[ServerSessionT, LifespanContextT] | None = None,
+        fastmcp: FastMCP | None = None,
+        **kwargs: Any,
+    ):
+        super().__init__(**kwargs)
+        self._request_context = request_context
+        self._fastmcp = fastmcp
+
+    @property
+    def fastmcp(self) -> FastMCP:
+        """Access to the FastMCP server."""
+        if self._fastmcp is None:
+            raise ValueError("Context is not available outside of a request")
+        return self._fastmcp
+
+    @property
+    def request_context(self) -> RequestContext[ServerSessionT, LifespanContextT]:
+        """Access to the underlying request context."""
+        if self._request_context is None:
+            raise ValueError("Context is not available outside of a request")
+        return self._request_context
+
+    async def report_progress(
+        self, progress: float, total: float | None = None
+    ) -> None:
+        """Report progress for the current operation.
+
+        Args:
+            progress: Current progress value e.g. 24
+            total: Optional total value e.g. 100
+        """
+
+        progress_token = (
+            self.request_context.meta.progressToken
+            if self.request_context.meta
+            else None
+        )
+
+        if progress_token is None:
+            return
+
+        await self.request_context.session.send_progress_notification(
+            progress_token=progress_token, progress=progress, total=total
+        )
+
+    async def read_resource(self, uri: str | AnyUrl) -> list[ReadResourceContents]:
+        """Read a resource by URI.
+
+        Args:
+            uri: Resource URI to read
+
+        Returns:
+            The resource content as either text or bytes
+        """
+        assert self._fastmcp is not None, (
+            "Context is not available outside of a request"
+        )
+        return await self._fastmcp.read_resource(uri)
+
+    async def log(
+        self,
+        level: Literal["debug", "info", "warning", "error"],
+        message: str,
+        *,
+        logger_name: str | None = None,
+    ) -> None:
+        """Send a log message to the client.
+
+        Args:
+            level: Log level (debug, info, warning, error)
+            message: Log message
+            logger_name: Optional logger name
+            **extra: Additional structured data to include
+        """
+        await self.request_context.session.send_log_message(
+            level=level, data=message, logger=logger_name
+        )
+
+    @property
+    def client_id(self) -> str | None:
+        """Get the client ID if available."""
+        return (
+            getattr(self.request_context.meta, "client_id", None)
+            if self.request_context.meta
+            else None
+        )
+
+    @property
+    def request_id(self) -> str:
+        """Get the unique ID for this request."""
+        return str(self.request_context.request_id)
+
+    @property
+    def session(self):
+        """Access to the underlying session for advanced usage."""
+        return self.request_context.session
+
+    # Convenience methods for common log levels
+    async def debug(self, message: str, **extra: Any) -> None:
+        """Send a debug log message."""
+        await self.log("debug", message, **extra)
+
+    async def info(self, message: str, **extra: Any) -> None:
+        """Send an info log message."""
+        await self.log("info", message, **extra)
+
+    async def warning(self, message: str, **extra: Any) -> None:
+        """Send a warning log message."""
+        await self.log("warning", message, **extra)
+
+    async def error(self, message: str, **extra: Any) -> None:
+        """Send an error log message."""
+        await self.log("error", message, **extra)
+
+    async def list_roots(self) -> list[Root]:
+        """List the roots available to the server, as indicated by the client."""
+        result = await self.request_context.session.list_roots()
+        return result.roots
+
+    async def sample(
+        self,
+        messages: str | list[str | SamplingMessage],
+        system_prompt: str | None = None,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+    ) -> TextContent | ImageContent:
+        """
+        Send a sampling request to the client and await the response.
+
+        Call this method at any time to have the server request an LLM
+        completion from the client. The client must be appropriately configured,
+        or the request will error.
+        """
+
+        if max_tokens is None:
+            max_tokens = 512
+
+        if isinstance(messages, str):
+            sampling_messages = [
+                SamplingMessage(
+                    content=TextContent(text=messages, type="text"), role="user"
+                )
+            ]
+        elif isinstance(messages, list):
+            sampling_messages = [
+                SamplingMessage(content=TextContent(text=m, type="text"), role="user")
+                if isinstance(m, str)
+                else m
+                for m in messages
+            ]
+
+        result: CreateMessageResult = await self.request_context.session.create_message(
+            messages=sampling_messages,
+            system_prompt=system_prompt,
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+
+        return result.content