fastmcp 2.1.2__py3-none-any.whl → 2.2.0__py3-none-any.whl

fastmcp/resources/resource_manager.py

@@ -1,16 +1,18 @@
 """Resource manager functionality."""
 
-import copy
 import inspect
-import re
 from collections.abc import Callable
 from typing import Any
 
 from pydantic import AnyUrl
 
-from fastmcp.exceptions import ResourceError
-from fastmcp.resources import FunctionResource, Resource
-from fastmcp.resources.template import ResourceTemplate
+from fastmcp.exceptions import NotFoundError
+from fastmcp.resources import FunctionResource
+from fastmcp.resources.resource import Resource
+from fastmcp.resources.template import (
+    ResourceTemplate,
+    match_uri_template,
+)
 from fastmcp.settings import DuplicateBehavior
 from fastmcp.utilities.logging import get_logger
 
@@ -20,9 +22,20 @@ logger = get_logger(__name__)
 class ResourceManager:
     """Manages FastMCP resources."""
 
-    def __init__(self, duplicate_behavior: DuplicateBehavior = DuplicateBehavior.WARN):
+    def __init__(self, duplicate_behavior: DuplicateBehavior | None = None):
         self._resources: dict[str, Resource] = {}
         self._templates: dict[str, ResourceTemplate] = {}
+
+        # Default to "warn" if None is provided
+        if duplicate_behavior is None:
+            duplicate_behavior = "warn"
+
+        if duplicate_behavior not in DuplicateBehavior.__args__:
+            raise ValueError(
+                f"Invalid duplicate_behavior: {duplicate_behavior}. "
+                f"Must be one of: {', '.join(DuplicateBehavior.__args__)}"
+            )
+
         self.duplicate_behavior = duplicate_behavior
 
     def add_resource_or_template_from_fn(
@@ -52,7 +65,7 @@ class ResourceManager:
         has_uri_params = "{" in uri and "}" in uri
         has_func_params = bool(inspect.signature(fn).parameters)
 
-        if has_uri_params and has_func_params:
+        if has_uri_params or has_func_params:
             return self.add_template_from_fn(
                 fn, uri, name, description, mime_type, tags
             )
@@ -99,32 +112,35 @@ class ResourceManager:
         )
         return self.add_resource(resource)
 
-    def add_resource(self, resource: Resource) -> Resource:
+    def add_resource(self, resource: Resource, key: str | None = None) -> Resource:
         """Add a resource to the manager.
 
         Args:
             resource: A Resource instance to add
+            key: Optional URI to use as the storage key (if different from resource.uri)
         """
+        storage_key = key or str(resource.uri)
         logger.debug(
             "Adding resource",
             extra={
                 "uri": resource.uri,
+                "storage_key": storage_key,
                 "type": type(resource).__name__,
                 "resource_name": resource.name,
             },
         )
-        existing = self._resources.get(str(resource.uri))
+        existing = self._resources.get(storage_key)
         if existing:
-            if self.duplicate_behavior == DuplicateBehavior.WARN:
-                logger.warning(f"Resource already exists: {resource.uri}")
-                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
+            if self.duplicate_behavior == "warn":
+                logger.warning(f"Resource already exists: {storage_key}")
+                self._resources[storage_key] = resource
+            elif self.duplicate_behavior == "replace":
+                self._resources[storage_key] = resource
+            elif self.duplicate_behavior == "error":
+                raise ValueError(f"Resource already exists: {storage_key}")
+            elif self.duplicate_behavior == "ignore":
+                return existing
+        self._resources[storage_key] = resource
         return resource
 
     def add_template_from_fn(
@@ -138,16 +154,6 @@ class ResourceManager:
     ) -> ResourceTemplate:
         """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,
@@ -158,40 +164,60 @@ class ResourceManager:
         )
         return self.add_template(template)
 
-    def add_template(self, template: ResourceTemplate) -> ResourceTemplate:
+    def add_template(
+        self, template: ResourceTemplate, key: str | None = None
+    ) -> ResourceTemplate:
         """Add a template to the manager.
 
         Args:
             template: A ResourceTemplate instance to add
+            key: Optional URI template to use as the storage key (if different from template.uri_template)
 
         Returns:
             The added template. If a template with the same URI already exists,
             returns the existing template.
         """
+        uri_template_str = str(template.uri_template)
+        storage_key = key or uri_template_str
         logger.debug(
-            "Adding resource",
+            "Adding template",
             extra={
-                "uri": template.uri_template,
+                "uri_template": uri_template_str,
+                "storage_key": storage_key,
                 "type": type(template).__name__,
-                "resource_name": template.name,
+                "template_name": template.name,
             },
         )
-        existing = self._templates.get(str(template.uri_template))
+        existing = self._templates.get(storage_key)
         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
+            if self.duplicate_behavior == "warn":
+                logger.warning(f"Template already exists: {storage_key}")
+                self._templates[storage_key] = template
+            elif self.duplicate_behavior == "replace":
+                self._templates[storage_key] = template
+            elif self.duplicate_behavior == "error":
+                raise ValueError(f"Template already exists: {storage_key}")
+            elif self.duplicate_behavior == "ignore":
+                return existing
+        self._templates[storage_key] = template
         return template
 
-    async def get_resource(self, uri: AnyUrl | str) -> Resource | None:
-        """Get resource by URI, checking concrete resources first, then templates."""
+    def has_resource(self, uri: AnyUrl | str) -> bool:
+        """Check if a resource exists."""
+        uri_str = str(uri)
+        if uri_str in self._resources:
+            return True
+        for template_key in self._templates.keys():
+            if match_uri_template(uri_str, template_key):
+                return True
+        return False
+
+    async def get_resource(self, uri: AnyUrl | str) -> Resource:
+        """Get resource by URI, checking concrete resources first, then templates.
+
+        Raises:
+            NotFoundError: If no resource or template matching the URI is found.
+        """
         uri_str = str(uri)
         logger.debug("Getting resource", extra={"uri": uri_str})
 
@@ -199,80 +225,21 @@ class ResourceManager:
         if resource := self._resources.get(uri_str):
             return resource
 
-        # Then check templates
-        for template in self._templates.values():
-            if params := template.matches(uri_str):
+        # Then check templates - use the utility function to match against storage keys
+        for storage_key, template in self._templates.items():
+            # Try to match against the storage key (which might be a custom key)
+            if params := match_uri_template(uri_str, storage_key):
                 try:
                     return await template.create_resource(uri_str, params)
                 except Exception as e:
                     raise ValueError(f"Error creating resource from template: {e}")
 
-        raise ResourceError(f"Unknown resource: {uri}")
-
-    def list_resources(self) -> list[Resource]:
-        """List all registered resources."""
-        logger.debug("Listing resources", extra={"count": len(self._resources)})
-        return list(self._resources.values())
-
-    def list_templates(self) -> list[ResourceTemplate]:
-        """List all registered templates."""
-        logger.debug("Listing templates", extra={"count": len(self._templates)})
-        return list(self._templates.values())
+        raise NotFoundError(f"Unknown resource: {uri_str}")
 
-    def import_resources(
-        self, manager: "ResourceManager", prefix: str | None = None
-    ) -> None:
-        """Import resources from another resource manager.
+    def get_resources(self) -> dict[str, Resource]:
+        """Get all registered resources, keyed by URI."""
+        return self._resources
 
-        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
-
-            new_resource = copy.copy(resource)
-            new_resource.uri = AnyUrl(prefixed_uri)
-
-            # Store directly in resources dictionary
-            self.add_resource(new_resource)
-            logger.debug(f'Imported resource "{uri}" as "{prefixed_uri}"')
-
-    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
-            )
-
-            new_template = copy.copy(template)
-            new_template.uri_template = prefixed_uri_template
-
-            # Store directly in templates dictionary
-            self.add_template(new_template)
-            logger.debug(
-                f'Imported template "{uri_template}" as "{prefixed_uri_template}"'
-            )
+    def get_templates(self) -> dict[str, ResourceTemplate]:
+        """Get all registered templates, keyed by URI template."""
+        return self._templates

fastmcp/resources/template.py

@@ -6,13 +6,49 @@ import inspect
 import re
 from collections.abc import Callable
 from typing import Annotated, Any
+from urllib.parse import unquote
 
-from pydantic import BaseModel, BeforeValidator, Field, TypeAdapter, validate_call
+from mcp.types import ResourceTemplate as MCPResourceTemplate
+from pydantic import (
+    AnyUrl,
+    BaseModel,
+    BeforeValidator,
+    Field,
+    TypeAdapter,
+    field_validator,
+    validate_call,
+)
 
 from fastmcp.resources.types import FunctionResource, Resource
 from fastmcp.utilities.types import _convert_set_defaults
 
 
+def build_regex(template: str) -> re.Pattern:
+    # Escape all non-brace characters, then restore {var} placeholders
+    parts = re.split(r"(\{[^}]+\})", template)
+    pattern = ""
+    for part in parts:
+        if part.startswith("{") and part.endswith("}"):
+            name = part[1:-1]
+            pattern += f"(?P<{name}>[^/]+)"
+        else:
+            pattern += re.escape(part)
+    return re.compile(f"^{pattern}$")
+
+
+def match_uri_template(uri: str, uri_template: str) -> dict[str, str] | None:
+    regex = build_regex(uri_template)
+    match = regex.match(uri)
+    if match:
+        return {k: unquote(v) for k, v in match.groupdict().items()}
+    return None
+
+
+class MyModel(BaseModel):
+    key: str
+    value: int
+
+
 class ResourceTemplate(BaseModel):
     """A template for dynamically creating resources."""
 
@@ -32,6 +68,14 @@ class ResourceTemplate(BaseModel):
         description="JSON schema for function parameters"
     )
 
+    @field_validator("mime_type", mode="before")
+    @classmethod
+    def set_default_mime_type(cls, mime_type: str | None) -> str:
+        """Set default MIME type if not provided."""
+        if mime_type:
+            return mime_type
+        return "text/plain"
+
     @classmethod
     def from_function(
         cls,
@@ -47,6 +91,30 @@ class ResourceTemplate(BaseModel):
         if func_name == "<lambda>":
             raise ValueError("You must provide a name for lambda functions")
 
+        # Validate that URI params match function params
+        uri_params = set(re.findall(r"{(\w+)}", uri_template))
+        if not uri_params:
+            raise ValueError("URI template must contain at least one parameter")
+
+        func_params = set(inspect.signature(fn).parameters.keys())
+
+        # get the parameters that are required
+        required_params = {
+            p
+            for p in func_params
+            if inspect.signature(fn).parameters[p].default is inspect.Parameter.empty
+        }
+
+        if not required_params.issubset(uri_params):
+            raise ValueError(
+                f"URI parameters {uri_params} must be a subset of the required function arguments: {required_params}"
+            )
+
+        if not uri_params.issubset(func_params):
+            raise ValueError(
+                f"URI parameters {uri_params} must be a subset of the function arguments: {func_params}"
+            )
+
         # Get schema from TypeAdapter - will fail if function isn't properly typed
         parameters = TypeAdapter(fn).json_schema()
 
@@ -65,12 +133,7 @@ class ResourceTemplate(BaseModel):
 
     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("}", ">[^/]+)")
-        match = re.match(f"^{pattern}$", uri)
-        if match:
-            return match.groupdict()
-        return None
+        return match_uri_template(uri, self.uri_template)
 
     async def create_resource(self, uri: str, params: dict[str, Any]) -> Resource:
         """Create a resource from the template with the given parameters."""
@@ -81,7 +144,7 @@ class ResourceTemplate(BaseModel):
                 result = await result
 
             return FunctionResource(
-                uri=uri,  # type: ignore
+                uri=AnyUrl(uri),  # Explicitly convert to AnyUrl
                 name=self.name,
                 description=self.description,
                 mime_type=self.mime_type,
@@ -95,3 +158,13 @@ class ResourceTemplate(BaseModel):
         if not isinstance(other, ResourceTemplate):
             return False
         return self.model_dump() == other.model_dump()
+
+    def to_mcp_template(self, **overrides: Any) -> MCPResourceTemplate:
+        """Convert the resource template to an MCPResourceTemplate."""
+        kwargs = {
+            "uriTemplate": self.uri_template,
+            "name": self.name,
+            "description": self.description,
+            "mimeType": self.mime_type,
+        }
+        return MCPResourceTemplate(**kwargs | overrides)

fastmcp/server/openapi.py

@@ -8,6 +8,7 @@ from re import Pattern
 from typing import Any, Literal
 
 import httpx
+from mcp.types import TextContent
 from pydantic.networks import AnyUrl
 
 from fastmcp.resources import Resource, ResourceTemplate
@@ -613,25 +614,18 @@ class FastMCPOpenAPI(FastMCP):
             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:
-        """Override the call_tool method to return the raw result without converting to content.
+    async def _mcp_call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
+        """Override the call_tool method to return the raw result without converting to content."""
 
-        For testing purposes, if specific tools are called, we convert the result to the expected object.
-        """
         context = self.get_context()
         result = await self._tool_manager.call_tool(name, arguments, context=context)
 
-        # For testing purposes, convert result to expected model based on tool name
-        if name == "create_user_users_post":
-            # Try to import User class from test module
-            try:
-                from tests.server.test_openapi import User
-
-                # Convert dict to User object
-                if isinstance(result, dict):
-                    return User(**result)
-            except ImportError:
-                # If User class not found, just return the raw result
-                pass
+        # For other tools, ensure the response is wrapped in TextContent
+        if isinstance(result, dict | str):
+            if isinstance(result, dict):
+                result_text = json.dumps(result)
+            else:
+                result_text = result
+            return [TextContent(text=result_text, type="text")]
 
         return result