fastmcp 2.10.5__py3-none-any.whl → 2.11.0__py3-none-any.whl

fastmcp/mcp_config.py

@@ -7,33 +7,47 @@ The configuration format supports both stdio and remote (HTTP/SSE) transports, w
 field definitions for server metadata, authentication, and execution parameters.
 
 Example configuration:
-    {
-        "mcpServers": {
-            "my-server": {
-                "command": "npx",
-                "args": ["-y", "@my/mcp-server"],
-                "env": {"API_KEY": "secret"},
-                "timeout": 30000,
-                "description": "My MCP server"
-            }
+```json
+{
+    "mcpServers": {
+        "my-server": {
+            "command": "npx",
+            "args": ["-y", "@my/mcp-server"],
+            "env": {"API_KEY": "secret"},
+            "timeout": 30000,
+            "description": "My MCP server"
         }
     }
+}
+```
 """
 
 from __future__ import annotations
 
 import datetime
-import json
 import re
 from pathlib import Path
 from typing import TYPE_CHECKING, Annotated, Any, Literal
 from urllib.parse import urlparse
 
 import httpx
-from pydantic import AnyUrl, BaseModel, ConfigDict, Field
+from pydantic import (
+    AnyUrl,
+    BaseModel,
+    ConfigDict,
+    Field,
+    ValidationInfo,
+    model_validator,
+)
+from typing_extensions import Self, override
+
+from fastmcp.tools.tool_transform import ToolTransformConfig
+from fastmcp.utilities.types import FastMCPBaseModel
 
 if TYPE_CHECKING:
     from fastmcp.client.transports import (
+        ClientTransport,
+        FastMCPTransport,
         SSETransport,
         StdioTransport,
         StreamableHttpTransport,
@@ -60,6 +74,39 @@ def infer_transport_type_from_url(
         return "http"
 
 
+class _TransformingMCPServerMixin(FastMCPBaseModel):
+    """A mixin that enables wrapping an MCP Server with tool transforms."""
+
+    tools: dict[str, ToolTransformConfig] = Field(...)
+    """The multi-tool transform to apply to the tools."""
+
+    include_tags: set[str] | None = Field(
+        default=None,
+        description="The tags to include in the proxy.",
+    )
+
+    exclude_tags: set[str] | None = Field(
+        default=None,
+        description="The tags to exclude in the proxy.",
+    )
+
+    def to_transport(self) -> FastMCPTransport:
+        """Get the transport for the server."""
+        from fastmcp.client.transports import FastMCPTransport
+        from fastmcp.server.server import FastMCP
+
+        transport: ClientTransport = super().to_transport()  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue, reportUnknownVariableType]
+
+        wrapped_mcp_server = FastMCP.as_proxy(
+            transport,
+            tool_transformations=self.tools,
+            include_tags=self.include_tags,
+            exclude_tags=self.exclude_tags,
+        )
+
+        return FastMCPTransport(wrapped_mcp_server)
+
+
 class StdioMCPServer(BaseModel):
     """MCP server configuration for stdio transport.
 
@@ -101,6 +148,10 @@ class StdioMCPServer(BaseModel):
         )
 
 
+class TransformingStdioMCPServer(_TransformingMCPServerMixin, StdioMCPServer):
+    """A Stdio server with tool transforms."""
+
+
 class RemoteMCPServer(BaseModel):
     """MCP server configuration for HTTP/SSE transport.
 
@@ -162,120 +213,106 @@ class RemoteMCPServer(BaseModel):
             )
 
 
+class TransformingRemoteMCPServer(_TransformingMCPServerMixin, RemoteMCPServer):
+    """A Remote server with tool transforms."""
+
+
+TransformingMCPServerTypes = TransformingStdioMCPServer | TransformingRemoteMCPServer
+
+CanonicalMCPServerTypes = StdioMCPServer | RemoteMCPServer
+
+MCPServerTypes = TransformingMCPServerTypes | CanonicalMCPServerTypes
+
+
 class MCPConfig(BaseModel):
-    """Canonical MCP configuration format.
+    """A configuration object for MCP Servers that conforms to the canonical MCP configuration format
+    while adding additional fields for enabling FastMCP-specific features like tool transformations
+    and filtering by tags.
 
-    This defines the standard configuration format for Model Context Protocol servers.
-    The format is designed to be client-agnostic and extensible for future use cases.
+    For an MCPConfig that is strictly canonical, see the `CanonicalMCPConfig` class.
     """
 
-    mcpServers: dict[str, StdioMCPServer | RemoteMCPServer]
+    mcpServers: dict[str, MCPServerTypes]
 
     model_config = ConfigDict(extra="allow")  # Preserve unknown top-level fields
 
+    @model_validator(mode="before")
+    def validate_mcp_servers(self, info: ValidationInfo) -> dict[str, Any]:
+        """Validate the MCP servers."""
+        if not isinstance(self, dict):
+            raise ValueError("MCPConfig format requires a dictionary of servers.")
+
+        if "mcpServers" not in self:
+            self = {"mcpServers": self}
+
+        return self
+
+    def add_server(self, name: str, server: MCPServerTypes) -> None:
+        """Add or update a server in the configuration."""
+        self.mcpServers[name] = server
+
     @classmethod
-    def from_dict(cls, config: dict[str, Any]) -> MCPConfig:
+    def from_dict(cls, config: dict[str, Any]) -> Self:
         """Parse MCP configuration from dictionary format."""
-        # Handle case where config is just the mcpServers object
-        if "mcpServers" not in config and any(
-            isinstance(v, dict) and ("command" in v or "url" in v)
-            for v in config.values()
-        ):
-            # This looks like a bare mcpServers object
-            servers_dict = config
-        else:
-            # Standard format with mcpServers wrapper
-            servers_dict = config.get("mcpServers", {})
-
-        # Parse each server configuration
-        parsed_servers = {}
-        for name, server_config in servers_dict.items():
-            if not isinstance(server_config, dict):
-                continue
-
-            # Determine if this is stdio or remote based on fields
-            if "command" in server_config:
-                parsed_servers[name] = StdioMCPServer.model_validate(server_config)
-            elif "url" in server_config:
-                parsed_servers[name] = RemoteMCPServer.model_validate(server_config)
-            else:
-                # Skip invalid server configs but preserve them as raw dicts
-                # This allows for forward compatibility with unknown server types
-                continue
-
-        # Create config with any extra top-level fields preserved
-        config_data = {k: v for k, v in config.items() if k != "mcpServers"}
-        config_data["mcpServers"] = parsed_servers
-
-        return cls.model_validate(config_data)
+        return cls.model_validate(config)
 
     def to_dict(self) -> dict[str, Any]:
         """Convert MCPConfig to dictionary format, preserving all fields."""
-        # Start with all extra fields at the top level
-        result = self.model_dump(exclude={"mcpServers"}, exclude_none=True)
-
-        # Add mcpServers with all fields preserved
-        result["mcpServers"] = {
-            name: server.model_dump(exclude_none=True)
-            for name, server in self.mcpServers.items()
-        }
-
-        return result
+        return self.model_dump(exclude_none=True)
 
     def write_to_file(self, file_path: Path) -> None:
         """Write configuration to JSON file."""
         file_path.parent.mkdir(parents=True, exist_ok=True)
-        with open(file_path, "w") as f:
-            json.dump(self.to_dict(), f, indent=2)
+        file_path.write_text(self.model_dump_json(indent=2))
 
     @classmethod
-    def from_file(cls, file_path: Path) -> MCPConfig:
+    def from_file(cls, file_path: Path) -> Self:
         """Load configuration from JSON file."""
-        if not file_path.exists():
-            return cls(mcpServers={})
-        with open(file_path) as f:
-            content = f.read().strip()
-            if not content:
-                return cls(mcpServers={})
-            data = json.loads(content)
-        return cls.from_dict(data)
-
-    def add_server(self, name: str, server: StdioMCPServer | RemoteMCPServer) -> None:
+        if file_path.exists():
+            if content := file_path.read_text().strip():
+                return cls.model_validate_json(content)
+
+        raise ValueError(f"No MCP servers defined in the config: {file_path}")
+
+
+class CanonicalMCPConfig(MCPConfig):
+    """Canonical MCP configuration format.
+
+    This defines the standard configuration format for Model Context Protocol servers.
+    The format is designed to be client-agnostic and extensible for future use cases.
+    """
+
+    mcpServers: dict[str, CanonicalMCPServerTypes]
+
+    @override
+    def add_server(self, name: str, server: CanonicalMCPServerTypes) -> None:
         """Add or update a server in the configuration."""
         self.mcpServers[name] = server
 
-    def remove_server(self, name: str) -> None:
-        """Remove a server from the configuration."""
-        if name in self.mcpServers:
-            del self.mcpServers[name]
-
 
 def update_config_file(
     file_path: Path,
     server_name: str,
-    server_config: StdioMCPServer | RemoteMCPServer,
+    server_config: CanonicalMCPServerTypes,
 ) -> None:
-    """Update MCP configuration file with new server, preserving existing fields."""
+    """Update an MCP configuration file from a server object, preserving existing fields.
+
+    This is used for updating the mcpServer configurations of third-party tools so we do not
+    worry about transforming server objects here."""
     config = MCPConfig.from_file(file_path)
 
     # If updating an existing server, merge with existing configuration
     # to preserve any unknown fields
-    if server_name in config.mcpServers:
-        existing_server = config.mcpServers[server_name]
+    if existing_server := config.mcpServers.get(server_name):
         # Get the raw dict representation of both servers
         existing_dict = existing_server.model_dump()
+
         new_dict = server_config.model_dump(exclude_none=True)
 
         # Merge, with new values taking precedence
-        merged_dict = {**existing_dict, **new_dict}
-
-        # Create new server instance with merged data
-        if "command" in merged_dict:
-            merged_server = StdioMCPServer.model_validate(merged_dict)
-        else:
-            merged_server = RemoteMCPServer.model_validate(merged_dict)
+        merged_config = server_config.model_validate({**existing_dict, **new_dict})
 
-        config.add_server(server_name, merged_server)
+        config.add_server(server_name, merged_config)
     else:
         config.add_server(server_name, server_config)
 

fastmcp/prompts/prompt.py

@@ -85,7 +85,12 @@ class Prompt(FastMCPComponent, ABC):
         except RuntimeError:
             pass  # No context available
 
-    def to_mcp_prompt(self, **overrides: Any) -> MCPPrompt:
+    def to_mcp_prompt(
+        self,
+        *,
+        include_fastmcp_meta: bool | None = None,
+        **overrides: Any,
+    ) -> MCPPrompt:
         """Convert the prompt to an MCP prompt."""
         arguments = [
             MCPPromptArgument(
@@ -100,6 +105,7 @@ class Prompt(FastMCPComponent, ABC):
             "description": self.description,
             "arguments": arguments,
             "title": self.title,
+            "_meta": self.get_meta(include_fastmcp_meta=include_fastmcp_meta),
         }
         return MCPPrompt(**kwargs | overrides)
 
@@ -111,6 +117,7 @@ class Prompt(FastMCPComponent, ABC):
         description: str | None = None,
         tags: set[str] | None = None,
         enabled: bool | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> FunctionPrompt:
         """Create a Prompt from a function.
 
@@ -127,6 +134,7 @@ class Prompt(FastMCPComponent, ABC):
             description=description,
             tags=tags,
             enabled=enabled,
+            meta=meta,
         )
 
     @abstractmethod
@@ -152,6 +160,7 @@ class FunctionPrompt(Prompt):
         description: str | None = None,
         tags: set[str] | None = None,
         enabled: bool | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> FunctionPrompt:
         """Create a Prompt from a function.
 
@@ -246,6 +255,7 @@ class FunctionPrompt(Prompt):
             tags=tags or set(),
             enabled=enabled if enabled is not None else True,
             fn=fn,
+            meta=meta,
         )
 
     def _convert_string_arguments(self, kwargs: dict[str, Any]) -> dict[str, Any]:

fastmcp/prompts/prompt_manager.py

@@ -78,7 +78,7 @@ class PromptManager:
             except Exception as e:
                 # Skip failed mounts silently, matches existing behavior
                 logger.warning(
-                    f"Failed to get prompts from mounted server '{mounted.prefix}': {e}"
+                    f"Failed to get prompts from server: {mounted.server.name!r}, mounted at: {mounted.prefix!r}: {e}"
                 )
                 continue
 

fastmcp/resources/resource.py

@@ -8,6 +8,7 @@ from collections.abc import Callable
 from typing import TYPE_CHECKING, Annotated, Any
 
 import pydantic_core
+from mcp.types import Annotations
 from mcp.types import Resource as MCPResource
 from pydantic import (
     AnyUrl,
@@ -43,6 +44,10 @@ class Resource(FastMCPComponent, abc.ABC):
         description="MIME type of the resource content",
         pattern=r"^[a-zA-Z0-9]+/[a-zA-Z0-9\-+.]+$",
     )
+    annotations: Annotated[
+        Annotations | None,
+        Field(description="Optional annotations about the resource's behavior"),
+    ] = None
 
     def enable(self) -> None:
         super().enable()
@@ -70,6 +75,8 @@ class Resource(FastMCPComponent, abc.ABC):
         mime_type: str | None = None,
         tags: set[str] | None = None,
         enabled: bool | None = None,
+        annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> FunctionResource:
         return FunctionResource.from_function(
             fn=fn,
@@ -80,6 +87,8 @@ class Resource(FastMCPComponent, abc.ABC):
             mime_type=mime_type,
             tags=tags,
             enabled=enabled,
+            annotations=annotations,
+            meta=meta,
         )
 
     @field_validator("mime_type", mode="before")
@@ -106,7 +115,12 @@ class Resource(FastMCPComponent, abc.ABC):
         """Read the resource content."""
         pass
 
-    def to_mcp_resource(self, **overrides: Any) -> MCPResource:
+    def to_mcp_resource(
+        self,
+        *,
+        include_fastmcp_meta: bool | None = None,
+        **overrides: Any,
+    ) -> MCPResource:
         """Convert the resource to an MCPResource."""
         kwargs = {
             "uri": self.uri,
@@ -114,6 +128,8 @@ class Resource(FastMCPComponent, abc.ABC):
             "description": self.description,
             "mimeType": self.mime_type,
             "title": self.title,
+            "annotations": self.annotations,
+            "_meta": self.get_meta(include_fastmcp_meta=include_fastmcp_meta),
         }
         return MCPResource(**kwargs | overrides)
 
@@ -157,6 +173,8 @@ class FunctionResource(Resource):
         mime_type: str | None = None,
         tags: set[str] | None = None,
         enabled: bool | None = None,
+        annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> FunctionResource:
         """Create a FunctionResource from a function."""
         if isinstance(uri, str):
@@ -170,6 +188,8 @@ class FunctionResource(Resource):
             mime_type=mime_type or "text/plain",
             tags=tags or set(),
             enabled=enabled if enabled is not None else True,
+            annotations=annotations,
+            meta=meta,
         )
 
     async def read(self) -> str | bytes:

fastmcp/resources/resource_manager.py

@@ -109,7 +109,7 @@ class ResourceManager:
             except Exception as e:
                 # Skip failed mounts silently, matches existing behavior
                 logger.warning(
-                    f"Failed to get resources from mounted server '{mounted.prefix}': {e}"
+                    f"Failed to get resources from server: {mounted.server.name!r}, mounted at: {mounted.prefix!r}: {e}"
                 )
                 continue
 
@@ -157,7 +157,7 @@ class ResourceManager:
             except Exception as e:
                 # Skip failed mounts silently, matches existing behavior
                 logger.warning(
-                    f"Failed to get templates from mounted server '{mounted.prefix}': {e}"
+                    f"Failed to get templates from server: {mounted.server.name!r}, mounted at: {mounted.prefix!r}: {e}"
                 )
                 continue
 

fastmcp/resources/template.py

@@ -8,6 +8,7 @@ from collections.abc import Callable
 from typing import Any
 from urllib.parse import unquote
 
+from mcp.types import Annotations
 from mcp.types import ResourceTemplate as MCPResourceTemplate
 from pydantic import (
     Field,
@@ -61,6 +62,9 @@ class ResourceTemplate(FastMCPComponent):
     parameters: dict[str, Any] = Field(
         description="JSON schema for function parameters"
     )
+    annotations: Annotations | None = Field(
+        default=None, description="Optional annotations about the resource's behavior"
+    )
 
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}(uri_template={self.uri_template!r}, name={self.name!r}, description={self.description!r}, tags={self.tags})"
@@ -91,6 +95,8 @@ class ResourceTemplate(FastMCPComponent):
         mime_type: str | None = None,
         tags: set[str] | None = None,
         enabled: bool | None = None,
+        annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> FunctionResourceTemplate:
         return FunctionResourceTemplate.from_function(
             fn=fn,
@@ -101,6 +107,8 @@ class ResourceTemplate(FastMCPComponent):
             mime_type=mime_type,
             tags=tags,
             enabled=enabled,
+            annotations=annotations,
+            meta=meta,
         )
 
     @field_validator("mime_type", mode="before")
@@ -139,7 +147,12 @@ class ResourceTemplate(FastMCPComponent):
             enabled=self.enabled,
         )
 
-    def to_mcp_template(self, **overrides: Any) -> MCPResourceTemplate:
+    def to_mcp_template(
+        self,
+        *,
+        include_fastmcp_meta: bool | None = None,
+        **overrides: Any,
+    ) -> MCPResourceTemplate:
         """Convert the resource template to an MCPResourceTemplate."""
         kwargs = {
             "uriTemplate": self.uri_template,
@@ -147,6 +160,8 @@ class ResourceTemplate(FastMCPComponent):
             "description": self.description,
             "mimeType": self.mime_type,
             "title": self.title,
+            "annotations": self.annotations,
+            "_meta": self.get_meta(include_fastmcp_meta=include_fastmcp_meta),
         }
         return MCPResourceTemplate(**kwargs | overrides)
 
@@ -205,6 +220,8 @@ class FunctionResourceTemplate(ResourceTemplate):
         mime_type: str | None = None,
         tags: set[str] | None = None,
         enabled: bool | None = None,
+        annotations: Annotations | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> FunctionResourceTemplate:
         """Create a template from a function."""
         from fastmcp.server.context import Context
@@ -289,4 +306,6 @@ class FunctionResourceTemplate(ResourceTemplate):
             parameters=parameters,
             tags=tags or set(),
             enabled=enabled if enabled is not None else True,
+            annotations=annotations,
+            meta=meta,
         )

fastmcp/server/auth/__init__.py

@@ -1,4 +1,19 @@
-from .providers.bearer import BearerAuthProvider
+from .auth import OAuthProvider, TokenVerifier
+from .providers.jwt import JWTVerifier, StaticTokenVerifier
 
 
-__all__ = ["BearerAuthProvider"]
+__all__ = [
+    "OAuthProvider",
+    "TokenVerifier",
+    "JWTVerifier",
+    "StaticTokenVerifier",
+]
+
+
+def __getattr__(name: str):
+    # Defer import because it raises a deprecation warning
+    if name == "BearerAuthProvider":
+        from .providers.bearer import BearerAuthProvider
+
+        return BearerAuthProvider
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")