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

fastmcp/resources/resource_manager.py

@@ -1,12 +1,16 @@
 """Resource manager functionality."""
 
+import inspect
+import re
 from collections.abc import Callable
 from typing import Any
 
 from pydantic import AnyUrl
 
-from fastmcp.resources.base import Resource
-from fastmcp.resources.templates import ResourceTemplate
+from fastmcp.exceptions import ResourceError
+from fastmcp.resources import FunctionResource, Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.settings import DuplicateBehavior
 from fastmcp.utilities.logging import get_logger
 
 logger = get_logger(__name__)
@@ -15,21 +19,91 @@ logger = get_logger(__name__)
 class ResourceManager:
     """Manages FastMCP resources."""
 
-    def __init__(self, warn_on_duplicate_resources: bool = True):
+    def __init__(self, duplicate_behavior: DuplicateBehavior = DuplicateBehavior.WARN):
         self._resources: dict[str, Resource] = {}
         self._templates: dict[str, ResourceTemplate] = {}
-        self.warn_on_duplicate_resources = warn_on_duplicate_resources
+        self.duplicate_behavior = duplicate_behavior
 
-    def add_resource(self, resource: Resource) -> Resource:
-        """Add a resource to the manager.
+    def add_resource_or_template_from_fn(
+        self,
+        fn: Callable[..., Any],
+        uri: str,
+        name: str | None = None,
+        description: str | None = None,
+        mime_type: str | None = None,
+        tags: set[str] | None = None,
+    ) -> Resource | ResourceTemplate:
+        """Add a resource or template to the manager from a function.
 
         Args:
-            resource: A Resource instance to add
+            fn: The function to register as a resource or template
+            uri: The URI for the resource or template
+            name: Optional name for the resource or template
+            description: Optional description of the resource or template
+            mime_type: Optional MIME type for the resource or template
+            tags: Optional set of tags for categorizing the resource or template
+
+        Returns:
+            The added resource or template. If a resource or template with the same URI already exists,
+            returns the existing resource or template.
+        """
+        # Check if this should be a template
+        has_uri_params = "{" in uri and "}" in uri
+        has_func_params = bool(inspect.signature(fn).parameters)
+
+        if has_uri_params and has_func_params:
+            return self.add_template_from_fn(
+                fn, uri, name, description, mime_type, tags
+            )
+        elif not has_uri_params and not has_func_params:
+            return self.add_resource_from_fn(
+                fn, uri, name, description, mime_type, tags
+            )
+        else:
+            raise ValueError(
+                "Invalid resource or template definition due to a "
+                "mismatch between URI parameters and function parameters."
+            )
+
+    def add_resource_from_fn(
+        self,
+        fn: Callable[..., Any],
+        uri: str,
+        name: str | None = None,
+        description: str | None = None,
+        mime_type: str | None = None,
+        tags: set[str] | None = None,
+    ) -> Resource:
+        """Add a resource to the manager from a function.
+
+        Args:
+            fn: The function to register as a resource
+            uri: The URI for the resource
+            name: Optional name for the resource
+            description: Optional description of the resource
+            mime_type: Optional MIME type for the resource
+            tags: Optional set of tags for categorizing the resource
 
         Returns:
             The added resource. If a resource with the same URI already exists,
             returns the existing resource.
         """
+        resource = FunctionResource(
+            uri=AnyUrl(uri),
+            name=name,
+            description=description,
+            mime_type=mime_type or "text/plain",
+            fn=fn,
+            tags=tags or set(),
+        )
+        return self.add_resource(resource)
+
+    def add_resource(self, resource: Resource) -> Resource:
+        """Add a resource to the manager.
+
+        Args:
+            resource: A Resource instance to add
+        """
         logger.debug(
             "Adding resource",
             extra={
@@ -40,28 +114,78 @@ class ResourceManager:
         )
         existing = self._resources.get(str(resource.uri))
         if existing:
-            if self.warn_on_duplicate_resources:
+            if self.duplicate_behavior == DuplicateBehavior.WARN:
                 logger.warning(f"Resource already exists: {resource.uri}")
-            return existing
+                self._resources[str(resource.uri)] = resource
+            elif self.duplicate_behavior == DuplicateBehavior.REPLACE:
+                self._resources[str(resource.uri)] = resource
+            elif self.duplicate_behavior == DuplicateBehavior.ERROR:
+                raise ValueError(f"Resource already exists: {resource.uri}")
+            elif self.duplicate_behavior == DuplicateBehavior.IGNORE:
+                pass
         self._resources[str(resource.uri)] = resource
         return resource
 
-    def add_template(
+    def add_template_from_fn(
         self,
         fn: Callable[..., Any],
         uri_template: str,
         name: str | None = None,
         description: str | None = None,
         mime_type: str | None = None,
+        tags: set[str] | None = None,
     ) -> ResourceTemplate:
-        """Add a template from a function."""
+        """Create a template from a function."""
+
+        # Validate that URI params match function params
+        uri_params = set(re.findall(r"{(\w+)}", uri_template))
+        func_params = set(inspect.signature(fn).parameters.keys())
+
+        if uri_params != func_params:
+            raise ValueError(
+                f"Mismatch between URI parameters {uri_params} "
+                f"and function parameters {func_params}"
+            )
+
         template = ResourceTemplate.from_function(
             fn,
             uri_template=uri_template,
             name=name,
             description=description,
             mime_type=mime_type,
+            tags=tags,
+        )
+        return self.add_template(template)
+
+    def add_template(self, template: ResourceTemplate) -> ResourceTemplate:
+        """Add a template to the manager.
+
+        Args:
+            template: A ResourceTemplate instance to add
+
+        Returns:
+            The added template. If a template with the same URI already exists,
+            returns the existing template.
+        """
+        logger.debug(
+            "Adding resource",
+            extra={
+                "uri": template.uri_template,
+                "type": type(template).__name__,
+                "resource_name": template.name,
+            },
         )
+        existing = self._templates.get(str(template.uri_template))
+        if existing:
+            if self.duplicate_behavior == DuplicateBehavior.WARN:
+                logger.warning(f"Resource already exists: {template.uri_template}")
+                self._templates[str(template.uri_template)] = template
+            elif self.duplicate_behavior == DuplicateBehavior.REPLACE:
+                self._templates[str(template.uri_template)] = template
+            elif self.duplicate_behavior == DuplicateBehavior.ERROR:
+                raise ValueError(f"Resource already exists: {template.uri_template}")
+            elif self.duplicate_behavior == DuplicateBehavior.IGNORE:
+                pass
         self._templates[template.uri_template] = template
         return template
 
@@ -82,7 +206,7 @@ class ResourceManager:
                 except Exception as e:
                     raise ValueError(f"Error creating resource from template: {e}")
 
-        raise ValueError(f"Unknown resource: {uri}")
+        raise ResourceError(f"Unknown resource: {uri}")
 
     def list_resources(self) -> list[Resource]:
         """List all registered resources."""
@@ -114,11 +238,11 @@ class ResourceManager:
             # 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}")
+            new_resource = resource.copy(updates=dict(uri=prefixed_uri))
 
             # Store directly in resources dictionary
-            self._resources[prefixed_uri] = resource
+            self.add_resource(new_resource)
+            logger.debug(f'Imported resource "{uri}" as "{prefixed_uri}"')
 
     def import_templates(
         self, manager: "ResourceManager", prefix: str | None = None
@@ -142,10 +266,12 @@ class ResourceManager:
                 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}"
+            new_template = template.copy(
+                updates=dict(uri_template=prefixed_uri_template)
             )
 
             # Store directly in templates dictionary
-            self._templates[prefixed_uri_template] = template
+            self.add_template(new_template)
+            logger.debug(
+                f'Imported template "{uri_template}" as "{prefixed_uri_template}"'
+            )

fastmcp/resources/{templates.py → template.py}

@@ -5,11 +5,13 @@ from __future__ import annotations
 import inspect
 import re
 from collections.abc import Callable
-from typing import Any
+from typing import Annotated, Any
 
-from pydantic import BaseModel, Field, TypeAdapter, validate_call
+from pydantic import BaseModel, BeforeValidator, Field, TypeAdapter, validate_call
+from typing_extensions import Self
 
 from fastmcp.resources.types import FunctionResource, Resource
+from fastmcp.utilities.types import _convert_set_defaults
 
 
 class ResourceTemplate(BaseModel):
@@ -20,10 +22,13 @@ class ResourceTemplate(BaseModel):
     )
     name: str = Field(description="Name of the resource")
     description: str | None = Field(description="Description of what the resource does")
+    tags: Annotated[set[str], BeforeValidator(_convert_set_defaults)] = Field(
+        default_factory=set, description="Tags for the resource"
+    )
     mime_type: str = Field(
         default="text/plain", description="MIME type of the resource content"
     )
-    fn: Callable[..., Any] = Field(exclude=True)
+    fn: Callable[..., Any]
     parameters: dict[str, Any] = Field(
         description="JSON schema for function parameters"
     )
@@ -36,6 +41,7 @@ class ResourceTemplate(BaseModel):
         name: str | None = None,
         description: str | None = None,
         mime_type: str | None = None,
+        tags: set[str] | None = None,
     ) -> ResourceTemplate:
         """Create a template from a function."""
         func_name = name or fn.__name__
@@ -55,6 +61,7 @@ class ResourceTemplate(BaseModel):
             mime_type=mime_type or "text/plain",
             fn=fn,
             parameters=parameters,
+            tags=tags or set(),
         )
 
     def matches(self, uri: str) -> dict[str, Any] | None:
@@ -80,6 +87,19 @@ class ResourceTemplate(BaseModel):
                 description=self.description,
                 mime_type=self.mime_type,
                 fn=lambda: result,  # Capture result in closure
+                tags=self.tags,
             )
         except Exception as e:
             raise ValueError(f"Error creating resource from template: {e}")
+
+    def copy(self, updates: dict[str, Any] | None = None) -> Self:
+        """Copy the resource template with optional updates."""
+        data = self.model_dump()
+        if updates:
+            data.update(updates)
+        return type(self)(**data)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, ResourceTemplate):
+            return False
+        return self.model_dump() == other.model_dump()

fastmcp/resources/types.py

@@ -13,7 +13,7 @@ import pydantic.json
 import pydantic_core
 from pydantic import Field, ValidationInfo
 
-from fastmcp.resources.base import Resource
+from fastmcp.resources.resource import Resource
 
 
 class TextResource(Resource):
@@ -49,7 +49,7 @@ class FunctionResource(Resource):
     - other types will be converted to JSON
     """
 
-    fn: Callable[[], Any] = Field(exclude=True)
+    fn: Callable[[], Any]
 
     async def read(self) -> str | bytes:
         """Read the resource by calling the wrapped function."""

fastmcp/server/context.py

@@ -118,7 +118,7 @@ class Context(BaseModel, Generic[ServerSessionT, LifespanContextT]):
         assert self._fastmcp is not None, (
             "Context is not available outside of a request"
         )
-        return await self._fastmcp.read_resource(uri)
+        return await self._fastmcp._mcp_read_resource(uri)
 
     async def log(
         self,

fastmcp/server/openapi.py

@@ -12,7 +12,7 @@ from pydantic.networks import AnyUrl
 
 from fastmcp.resources import Resource, ResourceTemplate
 from fastmcp.server.server import FastMCP
-from fastmcp.tools.base import Tool
+from fastmcp.tools.tool import Tool
 from fastmcp.utilities import openapi
 from fastmcp.utilities.func_metadata import func_metadata
 from fastmcp.utilities.logging import get_logger
@@ -115,6 +115,7 @@ class OpenAPITool(Tool):
         parameters: dict[str, Any],
         fn_metadata: Any,
         is_async: bool = True,
+        tags: set[str] = set(),
     ):
         super().__init__(
             name=name,
@@ -124,6 +125,7 @@ class OpenAPITool(Tool):
             fn_metadata=fn_metadata,
             is_async=is_async,
             context_kwarg="context",  # Default context keyword argument
+            tags=tags,
         )
         self._client = client
         self._route = route
@@ -242,12 +244,14 @@ class OpenAPIResource(Resource):
         name: str,
         description: str,
         mime_type: str = "application/json",
+        tags: set[str] = set(),
     ):
         super().__init__(
             uri=AnyUrl(uri),  # Convert string to AnyUrl
             name=name,
             description=description,
             mime_type=mime_type,
+            tags=tags,
         )
         self._client = client
         self._route = route
@@ -332,6 +336,7 @@ class OpenAPIResourceTemplate(ResourceTemplate):
         name: str,
         description: str,
         parameters: dict[str, Any],
+        tags: set[str] = set(),
     ):
         super().__init__(
             uri_template=uri_template,
@@ -339,6 +344,7 @@ class OpenAPIResourceTemplate(ResourceTemplate):
             description=description,
             fn=self._create_resource_fn,
             parameters=parameters,
+            tags=tags,
         )
         self._client = client
         self._route = route
@@ -405,6 +411,7 @@ class OpenAPIResourceTemplate(ResourceTemplate):
             description=self.description
             or f"Resource for {self._route.path}",  # Provide default if None
             mime_type="application/json",  # Default, will be updated when read
+            tags=set(self._route.tags or []),
         )
 
 
@@ -525,10 +532,13 @@ class FastMCPOpenAPI(FastMCP):
             parameters=combined_schema,
             fn_metadata=func_metadata(_openapi_passthrough),
             is_async=True,
+            tags=set(route.tags or []),
         )
         # Register the tool by directly assigning to the tools dictionary
         self._tool_manager._tools[tool_name] = tool
-        logger.debug(f"Registered TOOL: {tool_name} ({route.method} {route.path})")
+        logger.debug(
+            f"Registered TOOL: {tool_name} ({route.method} {route.path}) with tags: {route.tags}"
+        )
 
     def _create_openapi_resource(self, route: openapi.HTTPRoute, operation_id: str):
         """Creates and registers an OpenAPIResource with enhanced description."""
@@ -550,11 +560,12 @@ class FastMCPOpenAPI(FastMCP):
             uri=resource_uri,
             name=resource_name,
             description=enhanced_description,
+            tags=set(route.tags or []),
         )
         # Register the resource by directly assigning to the resources dictionary
         self._resource_manager._resources[str(resource.uri)] = resource
         logger.debug(
-            f"Registered RESOURCE: {resource_uri} ({route.method} {route.path})"
+            f"Registered RESOURCE: {resource_uri} ({route.method} {route.path}) with tags: {route.tags}"
         )
 
     def _create_openapi_template(self, route: openapi.HTTPRoute, operation_id: str):
@@ -594,11 +605,12 @@ class FastMCPOpenAPI(FastMCP):
             name=template_name,
             description=enhanced_description,
             parameters=template_params_schema,
+            tags=set(route.tags or []),
         )
         # Register the template by directly assigning to the templates dictionary
         self._resource_manager._templates[uri_template_str] = template
         logger.debug(
-            f"Registered TEMPLATE: {uri_template_str} ({route.method} {route.path})"
+            f"Registered TEMPLATE: {uri_template_str} ({route.method} {route.path}) with tags: {route.tags}"
         )
 
     async def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:

fastmcp/server/proxy.py

@@ -1,15 +1,15 @@
 from typing import Any, cast
 
 import mcp.types
-from mcp.types import BlobResourceContents, PromptMessage, TextResourceContents
+from mcp.types import BlobResourceContents, TextResourceContents
 
 import fastmcp
 from fastmcp.client import Client
-from fastmcp.prompts import Prompt
+from fastmcp.prompts import Message, Prompt
 from fastmcp.resources import Resource, ResourceTemplate
 from fastmcp.server.context import Context
 from fastmcp.server.server import FastMCP
-from fastmcp.tools.base import Tool
+from fastmcp.tools.tool import Tool
 from fastmcp.utilities.func_metadata import func_metadata
 from fastmcp.utilities.logging import get_logger
 
@@ -40,11 +40,15 @@ class ProxyTool(Tool):
     async def run(
         self, arguments: dict[str, Any], context: Context | None = None
     ) -> Any:
+        # the client context manager will swallow any exceptions inside a TaskGroup
+        # so we return the raw result and raise an exception ourselves
         async with self._client:
-            result = await self._client.call_tool(self.name, arguments)
+            result = await self._client.call_tool(
+                self.name, arguments, _return_raw_result=True
+            )
         if result.isError:
             raise ValueError(cast(mcp.types.TextContent, result.content[0]).text)
-        return result.content[0]
+        return result.content
 
 
 class ProxyResource(Resource):
@@ -73,12 +77,12 @@ class ProxyResource(Resource):
 
         async with self._client:
             result = await self._client.read_resource(self.uri)
-        if isinstance(result.contents[0], TextResourceContents):
-            return result.contents[0].text
-        elif isinstance(result.contents[0], BlobResourceContents):
-            return result.contents[0].blob
+        if isinstance(result[0], TextResourceContents):
+            return result[0].text
+        elif isinstance(result[0], BlobResourceContents):
+            return result[0].blob
         else:
-            raise ValueError(f"Unsupported content type: {type(result.contents[0])}")
+            raise ValueError(f"Unsupported content type: {type(result[0])}")
 
 
 class ProxyTemplate(ResourceTemplate):
@@ -103,20 +107,20 @@ class ProxyTemplate(ResourceTemplate):
         async with self._client:
             result = await self._client.read_resource(uri)
 
-        if isinstance(result.contents[0], TextResourceContents):
-            value = result.contents[0].text
-        elif isinstance(result.contents[0], BlobResourceContents):
-            value = result.contents[0].blob
+        if isinstance(result[0], TextResourceContents):
+            value = result[0].text
+        elif isinstance(result[0], BlobResourceContents):
+            value = result[0].blob
         else:
-            raise ValueError(f"Unsupported content type: {type(result.contents[0])}")
+            raise ValueError(f"Unsupported content type: {type(result[0])}")
 
         return ProxyResource(
             client=self._client,
             uri=uri,
             name=self.name,
             description=self.description,
-            mime_type=result.contents[0].mimeType,
-            contents=result.contents,
+            mime_type=result[0].mimeType,
+            contents=result,
             _value=value,
         )
 
@@ -138,10 +142,10 @@ class ProxyPrompt(Prompt):
             fn=_proxy_passthrough,
         )
 
-    async def render(self, arguments: dict[str, Any]) -> list[PromptMessage]:
+    async def render(self, arguments: dict[str, Any]) -> list[Message]:
         async with self._client:
             result = await self._client.get_prompt(self.name, arguments)
-        return result.messages
+        return [Message(role=m.role, content=m.content) for m in result.messages]
 
 
 class FastMCPProxy(FastMCP):
@@ -177,15 +181,15 @@ class FastMCPProxy(FastMCP):
 
         async with client:
             # Register proxies for client tools
-            tools_result = await client.list_tools()
-            for tool in tools_result.tools:
+            tools = await client.list_tools()
+            for tool in tools:
                 tool_proxy = await ProxyTool.from_client(client, tool)
                 server._tool_manager._tools[tool_proxy.name] = tool_proxy
                 logger.debug(f"Created proxy for tool: {tool_proxy.name}")
 
             # Register proxies for client resources
-            resources_result = await client.list_resources()
-            for resource in resources_result.resources:
+            resources = await client.list_resources()
+            for resource in resources:
                 resource_proxy = await ProxyResource.from_client(client, resource)
                 server._resource_manager._resources[str(resource_proxy.uri)] = (
                     resource_proxy
@@ -193,8 +197,8 @@ class FastMCPProxy(FastMCP):
                 logger.debug(f"Created proxy for resource: {resource_proxy.uri}")
 
             # Register proxies for client resource templates
-            templates_result = await client.list_resource_templates()
-            for template in templates_result.resourceTemplates:
+            templates = await client.list_resource_templates()
+            for template in templates:
                 template_proxy = await ProxyTemplate.from_client(client, template)
                 server._resource_manager._templates[template_proxy.uri_template] = (
                     template_proxy
@@ -204,8 +208,8 @@ class FastMCPProxy(FastMCP):
                 )
 
             # Register proxies for client prompts
-            prompts_result = await client.list_prompts()
-            for prompt in prompts_result.prompts:
+            prompts = await client.list_prompts()
+            for prompt in prompts:
                 prompt_proxy = await ProxyPrompt.from_client(client, prompt)
                 server._prompt_manager._prompts[prompt_proxy.name] = prompt_proxy
                 logger.debug(f"Created proxy for prompt: {prompt_proxy.name}")