fastmcp 2.0.0__tar.gz → 2.1.0__tar.gz

fastmcp-2.1.0/.cursor/rules/core-mcp-objects.mdc

@@ -0,0 +1,13 @@
+---
+description: 
+globs: 
+alwaysApply: true
+---
+There are four major MCP object types:
+
+- Tools (src/tools/)
+- Resources (src/resources/)
+- Resource Templates (src/resources/)
+- Prompts (src/prompts)
+
+While these have slightly different semantics and implementations, in general changes that affect interactions with any one (like adding tags, importing, etc.) will need to be adopted, applied, and tested on all others. Be sure to look at not only the object definition but also the related `Manager` (e.g. `ToolManager`, `ResourceManager`, and `PromptManager`). Also note that while resources and resource templates are different objects, they both are handled by the `ResourceManager`.

{fastmcp-2.0.0 → fastmcp-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.0.0
+Version: 2.1.0
 Summary: An ergonomic MCP interface
 Author: Jeremiah Lowin
 License: Apache-2.0

{fastmcp-2.0.0 → fastmcp-2.1.0}/examples/mount_example.py

@@ -64,10 +64,11 @@ def check_app_status() -> dict[str, str]:
 
 # Mount sub-applications
 app.mount("weather", weather_app)
+
 app.mount("news", news_app)
 
 
-async def start_server():
+async def get_server_details():
     """Print information about mounted resources."""
     # Print available tools
     tools = app._tool_manager.list_tools()
@@ -105,7 +106,7 @@ async def start_server():
 
 if __name__ == "__main__":
     # First run our async function to display info
-    asyncio.run(start_server())
+    asyncio.run(get_server_details())
 
     # Then start the server (uncomment to run the server)
     # app.run()

{fastmcp-2.0.0 → fastmcp-2.1.0}/src/fastmcp/cli/cli.py

@@ -65,7 +65,7 @@ def _build_uv_command(
     """Build the uv run command that runs a MCP server through mcp run."""
     cmd = ["uv"]
 
-    cmd.extend(["run", "--with", "mcp"])
+    cmd.extend(["run", "--with", "fastmcp"])
 
     if with_editable:
         cmd.extend(["--with-editable", str(with_editable)])
@@ -76,7 +76,7 @@ def _build_uv_command(
                 cmd.extend(["--with", pkg])
 
     # Add mcp run command
-    cmd.extend(["mcp", "run", file_spec])
+    cmd.extend(["fastmcp", "run", file_spec])
     return cmd
 
 

{fastmcp-2.0.0 → fastmcp-2.1.0}/src/fastmcp/client/client.py

@@ -1,7 +1,7 @@
 import datetime
 from contextlib import AbstractAsyncContextManager
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal, cast, overload
 
 import mcp.types
 from mcp import ClientSession
@@ -24,6 +24,10 @@ from .transports import ClientTransport, SessionKwargs, infer_transport
 __all__ = ["Client", "RootsHandler", "RootsList"]
 
 
+class ClientError(ValueError):
+    """Base class for errors raised by the client."""
+
+
 class Client:
     """
     MCP client that delegates connection management to a Transport instance.
@@ -122,60 +126,101 @@ class Client:
         """Send a logging/setLevel request."""
         await self.session.set_logging_level(level)
 
-    async def list_resources(self) -> mcp.types.ListResourcesResult:
+    async def send_roots_list_changed(self) -> None:
+        """Send a roots/list_changed notification."""
+        await self.session.send_roots_list_changed()
+
+    async def list_resources(self) -> list[mcp.types.Resource]:
         """Send a resources/list request."""
-        return await self.session.list_resources()
+        result = await self.session.list_resources()
+        return result.resources
 
-    async def list_resource_templates(self) -> mcp.types.ListResourceTemplatesResult:
+    async def list_resource_templates(self) -> list[mcp.types.ResourceTemplate]:
         """Send a resources/listResourceTemplates request."""
-        return await self.session.list_resource_templates()
+        result = await self.session.list_resource_templates()
+        return result.resourceTemplates
 
-    async def read_resource(self, uri: AnyUrl | str) -> mcp.types.ReadResourceResult:
+    async def read_resource(
+        self, uri: AnyUrl | str
+    ) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]:
         """Send a resources/read request."""
         if isinstance(uri, str):
             uri = AnyUrl(uri)  # Ensure AnyUrl
-        return await self.session.read_resource(uri)
-
-    async def subscribe_resource(self, uri: AnyUrl | str) -> None:
-        """Send a resources/subscribe request."""
-        if isinstance(uri, str):
-            uri = AnyUrl(uri)
-        await self.session.subscribe_resource(uri)
-
-    async def unsubscribe_resource(self, uri: AnyUrl | str) -> None:
-        """Send a resources/unsubscribe request."""
-        if isinstance(uri, str):
-            uri = AnyUrl(uri)
-        await self.session.unsubscribe_resource(uri)
-
-    async def list_prompts(self) -> mcp.types.ListPromptsResult:
+        result = await self.session.read_resource(uri)
+        return result.contents
+
+    # async def subscribe_resource(self, uri: AnyUrl | str) -> None:
+    #     """Send a resources/subscribe request."""
+    #     if isinstance(uri, str):
+    #         uri = AnyUrl(uri)
+    #     await self.session.subscribe_resource(uri)
+
+    # async def unsubscribe_resource(self, uri: AnyUrl | str) -> None:
+    #     """Send a resources/unsubscribe request."""
+    #     if isinstance(uri, str):
+    #         uri = AnyUrl(uri)
+    #     await self.session.unsubscribe_resource(uri)
+
+    async def list_prompts(self) -> list[mcp.types.Prompt]:
         """Send a prompts/list request."""
-        return await self.session.list_prompts()
+        result = await self.session.list_prompts()
+        return result.prompts
 
     async def get_prompt(
         self, name: str, arguments: dict[str, str] | None = None
     ) -> mcp.types.GetPromptResult:
         """Send a prompts/get request."""
-        return await self.session.get_prompt(name, arguments)
+        result = await self.session.get_prompt(name, arguments)
+        return result
 
     async def complete(
         self,
         ref: mcp.types.ResourceReference | mcp.types.PromptReference,
         argument: dict[str, str],
-    ) -> mcp.types.CompleteResult:
-        """Send a completion/complete request."""
-        return await self.session.complete(ref, argument)
+    ) -> mcp.types.Completion:
+        """Send a completion request."""
+        result = await self.session.complete(ref, argument)
+        return result.completion
 
-    async def list_tools(self) -> mcp.types.ListToolsResult:
+    async def list_tools(self) -> list[mcp.types.Tool]:
         """Send a tools/list request."""
-        return await self.session.list_tools()
+        result = await self.session.list_tools()
+        return result.tools
 
+    @overload
     async def call_tool(
-        self, name: str, arguments: dict[str, Any] | None = None
-    ) -> mcp.types.CallToolResult:
-        """Send a tools/call request."""
-        return await self.session.call_tool(name, arguments)
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        _return_raw_result: Literal[False] = False,
+    ) -> list[
+        mcp.types.TextContent | mcp.types.ImageContent | mcp.types.EmbeddedResource
+    ]: ...
+
+    @overload
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        _return_raw_result: Literal[True] = True,
+    ) -> mcp.types.CallToolResult: ...
 
-    async def send_roots_list_changed(self) -> None:
-        """Send a roots/list_changed notification."""
-        await self.session.send_roots_list_changed()
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        _return_raw_result: bool = False,
+    ) -> (
+        list[
+            mcp.types.TextContent | mcp.types.ImageContent | mcp.types.EmbeddedResource
+        ]
+        | mcp.types.CallToolResult
+    ):
+        """Send a tools/call request."""
+        result = await self.session.call_tool(name, arguments)
+        if _return_raw_result:
+            return result
+        elif result.isError:
+            msg = cast(mcp.types.TextContent, result.content[0]).text
+            raise ClientError(msg)
+        return result.content

{fastmcp-2.0.0 → fastmcp-2.1.0}/src/fastmcp/prompts/__init__.py

@@ -1,4 +1,4 @@
-from .base import Prompt
+from .prompt import Prompt
 from .prompt_manager import PromptManager
 
 __all__ = ["Prompt", "PromptManager"]

fastmcp-2.0.0/src/fastmcp/prompts/base.py → fastmcp-2.1.0/src/fastmcp/prompts/prompt.py

@@ -3,11 +3,14 @@
 import inspect
 import json
 from collections.abc import Awaitable, Callable, Sequence
-from typing import Any, Literal
+from typing import Annotated, Any, Literal
 
 import pydantic_core
 from mcp.types import EmbeddedResource, ImageContent, TextContent
-from pydantic import BaseModel, Field, TypeAdapter, validate_call
+from pydantic import BaseModel, BeforeValidator, Field, TypeAdapter, validate_call
+from typing_extensions import Self
+
+from fastmcp.utilities.types import _convert_set_defaults
 
 CONTENT_TYPES = TextContent | ImageContent | EmbeddedResource
 
@@ -71,10 +74,13 @@ class Prompt(BaseModel):
     description: str | None = Field(
         None, description="Description of what the prompt does"
     )
+    tags: Annotated[set[str], BeforeValidator(_convert_set_defaults)] = Field(
+        default_factory=set, description="Tags for the prompt"
+    )
     arguments: list[PromptArgument] | None = Field(
         None, description="Arguments that can be passed to the prompt"
     )
-    fn: Callable[..., PromptResult | Awaitable[PromptResult]] = Field(exclude=True)
+    fn: Callable[..., PromptResult | Awaitable[PromptResult]]
 
     @classmethod
     def from_function(
@@ -82,6 +88,7 @@ class Prompt(BaseModel):
         fn: Callable[..., PromptResult | Awaitable[PromptResult]],
         name: str | None = None,
         description: str | None = None,
+        tags: set[str] | None = None,
     ) -> "Prompt":
         """Create a Prompt from a function.
 
@@ -120,6 +127,7 @@ class Prompt(BaseModel):
             description=description or fn.__doc__ or "",
             arguments=arguments,
             fn=fn,
+            tags=tags or set(),
         )
 
     async def render(self, arguments: dict[str, Any] | None = None) -> list[Message]:
@@ -164,3 +172,15 @@ class Prompt(BaseModel):
             return messages
         except Exception as e:
             raise ValueError(f"Error rendering prompt {self.name}: {e}")
+
+    def copy(self, updates: dict[str, Any] | None = None) -> Self:
+        """Copy the prompt 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, Prompt):
+            return False
+        return self.model_dump() == other.model_dump()

{fastmcp-2.0.0 → fastmcp-2.1.0}/src/fastmcp/prompts/prompt_manager.py

@@ -1,8 +1,10 @@
 """Prompt management functionality."""
 
+from collections.abc import Awaitable, Callable
 from typing import Any
 
-from fastmcp.prompts.base import Message, Prompt
+from fastmcp.prompts.prompt import Message, Prompt, PromptResult
+from fastmcp.settings import DuplicateBehavior
 from fastmcp.utilities.logging import get_logger
 
 logger = get_logger(__name__)
@@ -11,9 +13,9 @@ logger = get_logger(__name__)
 class PromptManager:
     """Manages FastMCP prompts."""
 
-    def __init__(self, warn_on_duplicate_prompts: bool = True):
+    def __init__(self, duplicate_behavior: DuplicateBehavior = DuplicateBehavior.WARN):
         self._prompts: dict[str, Prompt] = {}
-        self.warn_on_duplicate_prompts = warn_on_duplicate_prompts
+        self.duplicate_behavior = duplicate_behavior
 
     def get_prompt(self, name: str) -> Prompt | None:
         """Get prompt by name."""
@@ -23,18 +25,32 @@ class PromptManager:
         """List all registered prompts."""
         return list(self._prompts.values())
 
-    def add_prompt(
+    def add_prompt_from_fn(
         self,
-        prompt: Prompt,
+        fn: Callable[..., PromptResult | Awaitable[PromptResult]],
+        name: str | None = None,
+        description: str | None = None,
+        tags: set[str] | None = None,
     ) -> Prompt:
+        """Create a prompt from a function."""
+        prompt = Prompt.from_function(fn, name=name, description=description, tags=tags)
+        return self.add_prompt(prompt)
+
+    def add_prompt(self, prompt: Prompt) -> Prompt:
         """Add a prompt to the manager."""
 
         # Check for duplicates
         existing = self._prompts.get(prompt.name)
         if existing:
-            if self.warn_on_duplicate_prompts:
+            if self.duplicate_behavior == DuplicateBehavior.WARN:
                 logger.warning(f"Prompt already exists: {prompt.name}")
-            return existing
+                self._prompts[prompt.name] = prompt
+            elif self.duplicate_behavior == DuplicateBehavior.REPLACE:
+                self._prompts[prompt.name] = prompt
+            elif self.duplicate_behavior == DuplicateBehavior.ERROR:
+                raise ValueError(f"Prompt already exists: {prompt.name}")
+            elif self.duplicate_behavior == DuplicateBehavior.IGNORE:
+                pass
 
         self._prompts[prompt.name] = prompt
         return prompt
@@ -64,11 +80,11 @@ class PromptManager:
                    the imported prompt would be available as "weather/forecast_prompt"
         """
         for name, prompt in manager._prompts.items():
-            # Create prefixed name - we keep the original name in the Prompt object
+            # Create prefixed name
             prefixed_name = f"{prefix}{name}" if prefix else name
 
-            # Log the import
-            logger.debug(f"Importing prompt with name {name} as {prefixed_name}")
+            new_prompt = prompt.copy(updates=dict(name=prefixed_name))
 
             # Store the prompt with the prefixed name
-            self._prompts[prefixed_name] = prompt
+            self.add_prompt(new_prompt)
+            logger.debug(f'Imported prompt "{name}" as "{prefixed_name}"')

{fastmcp-2.0.0 → fastmcp-2.1.0}/src/fastmcp/resources/__init__.py

@@ -1,6 +1,6 @@
-from .base import Resource
+from .resource import Resource
 from .resource_manager import ResourceManager
-from .templates import ResourceTemplate
+from .template import ResourceTemplate
 from .types import (
     BinaryResource,
     DirectoryResource,

fastmcp-2.0.0/src/fastmcp/resources/base.py → fastmcp-2.1.0/src/fastmcp/resources/resource.py

@@ -1,17 +1,21 @@
 """Base classes and interfaces for FastMCP resources."""
 
 import abc
-from typing import Annotated
+from typing import Annotated, Any
 
 from pydantic import (
     AnyUrl,
     BaseModel,
+    BeforeValidator,
     ConfigDict,
     Field,
     UrlConstraints,
     ValidationInfo,
     field_validator,
 )
+from typing_extensions import Self
+
+from fastmcp.utilities.types import _convert_set_defaults
 
 
 class Resource(BaseModel, abc.ABC):
@@ -26,6 +30,9 @@ class Resource(BaseModel, abc.ABC):
     description: str | None = Field(
         description="Description of the resource", default=None
     )
+    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",
@@ -46,3 +53,15 @@ class Resource(BaseModel, abc.ABC):
     async def read(self) -> str | bytes:
         """Read the resource content."""
         pass
+
+    def copy(self, updates: dict[str, Any] | None = None) -> Self:
+        """Copy the resource 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, Resource):
+            return False
+        return self.model_dump() == other.model_dump()

{fastmcp-2.0.0 → fastmcp-2.1.0}/src/fastmcp/resources/resource_manager.py

@@ -5,8 +5,9 @@ from typing import Any
 
 from pydantic import AnyUrl
 
-from fastmcp.resources.base import Resource
-from fastmcp.resources.templates import ResourceTemplate
+from fastmcp.resources.resource import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.settings import DuplicateBehavior
 from fastmcp.utilities.logging import get_logger
 
 logger = get_logger(__name__)
@@ -15,10 +16,10 @@ 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.
@@ -40,28 +41,67 @@ 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."""
         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
 
@@ -114,11 +154,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 +182,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-2.0.0/src/fastmcp/resources/templates.py → fastmcp-2.1.0/src/fastmcp/resources/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-2.0.0 → fastmcp-2.1.0}/src/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."""