fastmcp 2.14.4__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

fastmcp/server/transforms/prompts_as_tools.py

@@ -0,0 +1,175 @@
+"""Transform that exposes prompts as tools.
+
+This transform generates tools for listing and getting prompts, enabling
+clients that only support tools to access prompt functionality.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.transforms import PromptsAsTools
+
+    mcp = FastMCP("Server")
+    mcp.add_transform(PromptsAsTools(mcp))
+    # Now has list_prompts and get_prompt tools
+    ```
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Annotated, Any
+
+from mcp.types import TextContent
+
+from fastmcp.server.transforms import GetToolNext, Transform
+from fastmcp.tools.tool import Tool
+from fastmcp.utilities.versions import VersionSpec
+
+if TYPE_CHECKING:
+    from fastmcp.server.providers.base import Provider
+
+# Note: FastMCP imported inside tools to avoid circular import
+
+
+class PromptsAsTools(Transform):
+    """Transform that adds tools for listing and getting prompts.
+
+    Generates two tools:
+    - `list_prompts`: Lists all prompts from the provider
+    - `get_prompt`: Gets a specific prompt with optional arguments
+
+    The transform captures a provider reference at construction and queries it
+    for prompts when the generated tools are called. When used with FastMCP,
+    the provider's auth and visibility filtering is automatically applied.
+
+    Example:
+        ```python
+        mcp = FastMCP("Server")
+        mcp.add_transform(PromptsAsTools(mcp))
+        # Now has list_prompts and get_prompt tools
+        ```
+    """
+
+    def __init__(self, provider: Provider) -> None:
+        """Initialize the transform with a provider reference.
+
+        Args:
+            provider: The provider to query for prompts. Typically this is
+                the same FastMCP server the transform is added to.
+        """
+        self._provider = provider
+
+    def __repr__(self) -> str:
+        return f"PromptsAsTools({self._provider!r})"
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        """Add prompt tools to the tool list."""
+        return [
+            *tools,
+            self._make_list_prompts_tool(),
+            self._make_get_prompt_tool(),
+        ]
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get a tool by name, including generated prompt tools."""
+        # Check if it's one of our generated tools
+        if name == "list_prompts":
+            return self._make_list_prompts_tool()
+        if name == "get_prompt":
+            return self._make_get_prompt_tool()
+
+        # Otherwise delegate to downstream
+        return await call_next(name, version=version)
+
+    def _make_list_prompts_tool(self) -> Tool:
+        """Create the list_prompts tool."""
+        provider = self._provider
+
+        async def list_prompts() -> str:
+            """List all available prompts.
+
+            Returns JSON with prompt metadata including name, description,
+            and optional arguments.
+            """
+            prompts = await provider.list_prompts()
+
+            result: list[dict[str, Any]] = []
+            for p in prompts:
+                result.append(
+                    {
+                        "name": p.name,
+                        "description": p.description,
+                        "arguments": [
+                            {
+                                "name": arg.name,
+                                "description": arg.description,
+                                "required": arg.required,
+                            }
+                            for arg in (p.arguments or [])
+                        ],
+                    }
+                )
+
+            return json.dumps(result, indent=2)
+
+        return Tool.from_function(fn=list_prompts)
+
+    def _make_get_prompt_tool(self) -> Tool:
+        """Create the get_prompt tool."""
+        provider = self._provider
+
+        async def get_prompt(
+            name: Annotated[str, "The name of the prompt to get"],
+            arguments: Annotated[
+                dict[str, Any] | None,
+                "Optional arguments for the prompt",
+            ] = None,
+        ) -> str:
+            """Get a prompt by name with optional arguments.
+
+            Returns the rendered prompt as JSON with a messages array.
+            Arguments should be provided as a dict mapping argument names to values.
+            """
+            from fastmcp.server.server import FastMCP
+
+            # Use FastMCP.render_prompt() if available - runs middleware chain
+            if isinstance(provider, FastMCP):
+                result = await provider.render_prompt(name, arguments=arguments or {})
+                return _format_prompt_result(result)
+
+            # Fallback for plain providers - no middleware
+            prompt = await provider.get_prompt(name)
+            if prompt is None:
+                raise ValueError(f"Prompt not found: {name}")
+
+            result = await prompt._render(arguments or {})
+            return _format_prompt_result(result)
+
+        return Tool.from_function(fn=get_prompt)
+
+
+def _format_prompt_result(result: Any) -> str:
+    """Format PromptResult for tool output.
+
+    Returns JSON with the messages array. Preserves embedded resources
+    as structured JSON objects.
+    """
+    messages = []
+    for msg in result.messages:
+        if isinstance(msg.content, TextContent):
+            content = msg.content.text
+        else:
+            # Preserve structured content (e.g., EmbeddedResource) as dict
+            content = msg.content.model_dump(mode="json", exclude_none=True)
+
+        messages.append(
+            {
+                "role": msg.role,
+                "content": content,
+            }
+        )
+
+    return json.dumps({"messages": messages}, indent=2)

fastmcp/server/transforms/resources_as_tools.py

@@ -0,0 +1,190 @@
+"""Transform that exposes resources as tools.
+
+This transform generates tools for listing and reading resources, enabling
+clients that only support tools to access resource functionality.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.transforms import ResourcesAsTools
+
+    mcp = FastMCP("Server")
+    mcp.add_transform(ResourcesAsTools(mcp))
+    # Now has list_resources and read_resource tools
+    ```
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Annotated, Any
+
+from fastmcp.server.transforms import GetToolNext, Transform
+from fastmcp.tools.tool import Tool
+from fastmcp.utilities.versions import VersionSpec
+
+if TYPE_CHECKING:
+    from fastmcp.server.providers.base import Provider
+
+
+class ResourcesAsTools(Transform):
+    """Transform that adds tools for listing and reading resources.
+
+    Generates two tools:
+    - `list_resources`: Lists all resources and templates from the provider
+    - `read_resource`: Reads a resource by URI
+
+    The transform captures a provider reference at construction and queries it
+    for resources when the generated tools are called. When used with FastMCP,
+    the provider's auth and visibility filtering is automatically applied.
+
+    Example:
+        ```python
+        mcp = FastMCP("Server")
+        mcp.add_transform(ResourcesAsTools(mcp))
+        # Now has list_resources and read_resource tools
+        ```
+    """
+
+    def __init__(self, provider: Provider) -> None:
+        """Initialize the transform with a provider reference.
+
+        Args:
+            provider: The provider to query for resources. Typically this is
+                the same FastMCP server the transform is added to.
+        """
+        self._provider = provider
+
+    def __repr__(self) -> str:
+        return f"ResourcesAsTools({self._provider!r})"
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        """Add resource tools to the tool list."""
+        return [
+            *tools,
+            self._make_list_resources_tool(),
+            self._make_read_resource_tool(),
+        ]
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get a tool by name, including generated resource tools."""
+        # Check if it's one of our generated tools
+        if name == "list_resources":
+            return self._make_list_resources_tool()
+        if name == "read_resource":
+            return self._make_read_resource_tool()
+
+        # Otherwise delegate to downstream
+        return await call_next(name, version=version)
+
+    def _make_list_resources_tool(self) -> Tool:
+        """Create the list_resources tool."""
+        provider = self._provider
+
+        async def list_resources() -> str:
+            """List all available resources and resource templates.
+
+            Returns JSON with resource metadata. Static resources have a 'uri' field,
+            while templates have a 'uri_template' field with placeholders like {name}.
+            """
+            resources = await provider.list_resources()
+            templates = await provider.list_resource_templates()
+
+            result: list[dict[str, Any]] = []
+
+            # Static resources
+            for r in resources:
+                result.append(
+                    {
+                        "uri": str(r.uri),
+                        "name": r.name,
+                        "description": r.description,
+                        "mime_type": r.mime_type,
+                    }
+                )
+
+            # Resource templates (URI contains placeholders like {name})
+            for t in templates:
+                result.append(
+                    {
+                        "uri_template": t.uri_template,
+                        "name": t.name,
+                        "description": t.description,
+                    }
+                )
+
+            return json.dumps(result, indent=2)
+
+        return Tool.from_function(fn=list_resources)
+
+    def _make_read_resource_tool(self) -> Tool:
+        """Create the read_resource tool."""
+        provider = self._provider
+
+        async def read_resource(
+            uri: Annotated[str, "The URI of the resource to read"],
+        ) -> str:
+            """Read a resource by its URI.
+
+            For static resources, provide the exact URI. For templated resources,
+            provide the URI with template parameters filled in.
+
+            Returns the resource content as a string. Binary content is
+            base64-encoded.
+            """
+            from fastmcp import FastMCP
+
+            # Use FastMCP.read_resource() if available - runs middleware chain
+            if isinstance(provider, FastMCP):
+                result = await provider.read_resource(uri)
+                return _format_result(result)
+
+            # Fallback for plain providers - no middleware
+            resource = await provider.get_resource(uri)
+            if resource is not None:
+                result = await resource._read()
+                return _format_result(result)
+
+            template = await provider.get_resource_template(uri)
+            if template is not None:
+                params = template.matches(uri)
+                if params is not None:
+                    result = await template._read(uri, params)
+                    return _format_result(result)
+
+            raise ValueError(f"Resource not found: {uri}")
+
+        return Tool.from_function(fn=read_resource)
+
+
+def _format_result(result: Any) -> str:
+    """Format ResourceResult for tool output.
+
+    Single text content is returned as-is. Single binary content is base64-encoded.
+    Multiple contents are JSON-encoded with each item containing content and mime_type.
+    """
+    # result is a ResourceResult with .contents list
+    if len(result.contents) == 1:
+        content = result.contents[0].content
+        if isinstance(content, bytes):
+            return base64.b64encode(content).decode()
+        return content
+
+    # Multiple contents - JSON encode
+    return json.dumps(
+        [
+            {
+                "content": (
+                    c.content
+                    if isinstance(c.content, str)
+                    else base64.b64encode(c.content).decode()
+                ),
+                "mime_type": c.mime_type,
+            }
+            for c in result.contents
+        ]
+    )

fastmcp/server/transforms/tool_transform.py

@@ -0,0 +1,96 @@
+"""Transform for applying tool transformations."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from fastmcp.server.transforms import GetToolNext, Transform
+from fastmcp.tools.tool_transform import ToolTransformConfig
+from fastmcp.utilities.versions import VersionSpec
+
+if TYPE_CHECKING:
+    from fastmcp.tools.tool import Tool
+
+
+class ToolTransform(Transform):
+    """Applies tool transformations to modify tool schemas.
+
+    Wraps ToolTransformConfig to apply argument renames, schema changes,
+    hidden arguments, and other transformations at the transform level.
+
+    Example:
+        ```python
+        transform = ToolTransform({
+            "my_tool": ToolTransformConfig(
+                name="renamed_tool",
+                arguments={"old_arg": ArgTransformConfig(name="new_arg")}
+            )
+        })
+        ```
+    """
+
+    def __init__(self, transforms: dict[str, ToolTransformConfig]) -> None:
+        """Initialize ToolTransform.
+
+        Args:
+            transforms: Map of original tool name → transform config.
+        """
+        self._transforms = transforms
+
+        # Build reverse mapping: final_name → original_name
+        self._name_reverse: dict[str, str] = {}
+        for original_name, config in transforms.items():
+            final_name = config.name if config.name else original_name
+            self._name_reverse[final_name] = original_name
+
+        # Validate no duplicate target names
+        seen_targets: dict[str, str] = {}
+        for original_name, config in transforms.items():
+            target = config.name if config.name else original_name
+            if target in seen_targets:
+                raise ValueError(
+                    f"ToolTransform has duplicate target name {target!r}: "
+                    f"both {seen_targets[target]!r} and {original_name!r} map to it"
+                )
+            seen_targets[target] = original_name
+
+    def __repr__(self) -> str:
+        names = list(self._transforms.keys())
+        if len(names) <= 3:
+            return f"ToolTransform({names!r})"
+        return f"ToolTransform({names[:3]!r}... +{len(names) - 3} more)"
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        """Apply transforms to matching tools."""
+        result: list[Tool] = []
+        for tool in tools:
+            if tool.name in self._transforms:
+                transformed = self._transforms[tool.name].apply(tool)
+                result.append(transformed)
+            else:
+                result.append(tool)
+        return result
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get tool by transformed name."""
+        # Check if this name is a transformed name
+        original_name = self._name_reverse.get(name, name)
+
+        # Get the original tool
+        tool = await call_next(original_name, version=version)
+        if tool is None:
+            return None
+
+        # Apply transform if applicable
+        if original_name in self._transforms:
+            transformed = self._transforms[original_name].apply(tool)
+            # Only return if requested name matches transformed name
+            if transformed.name == name:
+                return transformed
+            return None
+
+        # No transform, return as-is only if name matches
+        return tool if tool.name == name else None

fastmcp/server/transforms/version_filter.py

@@ -0,0 +1,124 @@
+"""Version filter transform for filtering components by version range."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from fastmcp.server.transforms import (
+    GetPromptNext,
+    GetResourceNext,
+    GetResourceTemplateNext,
+    GetToolNext,
+    Transform,
+)
+from fastmcp.utilities.versions import VersionSpec
+
+if TYPE_CHECKING:
+    from fastmcp.prompts.prompt import Prompt
+    from fastmcp.resources.resource import Resource
+    from fastmcp.resources.template import ResourceTemplate
+    from fastmcp.tools.tool import Tool
+
+
+class VersionFilter(Transform):
+    """Filters components by version range.
+
+    When applied to a provider or server, only components within the version
+    range are visible. Within that filtered set, the highest version of each
+    component is exposed to clients (standard deduplication behavior).
+
+    Parameters mirror comparison operators for clarity:
+
+        # Versions < 3.0 (v1 and v2)
+        server.add_transform(VersionFilter(version_lt="3.0"))
+
+        # Versions >= 2.0 and < 3.0 (only v2.x)
+        server.add_transform(VersionFilter(version_gte="2.0", version_lt="3.0"))
+
+    Works with any version string - PEP 440 (1.0, 2.0) or dates (2025-01-01).
+
+    Args:
+        version_gte: Versions >= this value pass through.
+        version_lt: Versions < this value pass through.
+    """
+
+    def __init__(
+        self,
+        *,
+        version_gte: str | None = None,
+        version_lt: str | None = None,
+    ) -> None:
+        if version_gte is None and version_lt is None:
+            raise ValueError(
+                "At least one of version_gte or version_lt must be specified"
+            )
+        self.version_gte = version_gte
+        self.version_lt = version_lt
+        self._spec = VersionSpec(gte=version_gte, lt=version_lt)
+
+    def __repr__(self) -> str:
+        parts = []
+        if self.version_gte:
+            parts.append(f"version_gte={self.version_gte!r}")
+        if self.version_lt:
+            parts.append(f"version_lt={self.version_lt!r}")
+        return f"VersionFilter({', '.join(parts)})"
+
+    # -------------------------------------------------------------------------
+    # Tools
+    # -------------------------------------------------------------------------
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        return [t for t in tools if self._spec.matches(t.version)]
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        return await call_next(name, version=self._spec.intersect(version))
+
+    # -------------------------------------------------------------------------
+    # Resources
+    # -------------------------------------------------------------------------
+
+    async def list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource]:
+        return [r for r in resources if self._spec.matches(r.version)]
+
+    async def get_resource(
+        self,
+        uri: str,
+        call_next: GetResourceNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> Resource | None:
+        return await call_next(uri, version=self._spec.intersect(version))
+
+    # -------------------------------------------------------------------------
+    # Resource Templates
+    # -------------------------------------------------------------------------
+
+    async def list_resource_templates(
+        self, templates: Sequence[ResourceTemplate]
+    ) -> Sequence[ResourceTemplate]:
+        return [t for t in templates if self._spec.matches(t.version)]
+
+    async def get_resource_template(
+        self,
+        uri: str,
+        call_next: GetResourceTemplateNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> ResourceTemplate | None:
+        return await call_next(uri, version=self._spec.intersect(version))
+
+    # -------------------------------------------------------------------------
+    # Prompts
+    # -------------------------------------------------------------------------
+
+    async def list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt]:
+        return [p for p in prompts if self._spec.matches(p.version)]
+
+    async def get_prompt(
+        self, name: str, call_next: GetPromptNext, *, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        return await call_next(name, version=self._spec.intersect(version))