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

fastmcp/server/telemetry.py

@@ -0,0 +1,131 @@
+"""Server-side telemetry helpers."""
+
+from collections.abc import Generator
+from contextlib import contextmanager
+
+from mcp.server.lowlevel.server import request_ctx
+from opentelemetry.context import Context
+from opentelemetry.trace import Span, SpanKind, Status, StatusCode
+
+from fastmcp.telemetry import extract_trace_context, get_tracer
+
+
+def get_auth_span_attributes() -> dict[str, str]:
+    """Get auth attributes for the current request, if authenticated."""
+    from fastmcp.server.dependencies import get_access_token
+
+    attrs: dict[str, str] = {}
+    try:
+        token = get_access_token()
+        if token:
+            if token.client_id:
+                attrs["enduser.id"] = token.client_id
+            if token.scopes:
+                attrs["enduser.scope"] = " ".join(token.scopes)
+    except RuntimeError:
+        pass
+    return attrs
+
+
+def get_session_span_attributes() -> dict[str, str]:
+    """Get session attributes for the current request."""
+    from fastmcp.server.dependencies import get_context
+
+    attrs: dict[str, str] = {}
+    try:
+        ctx = get_context()
+        if ctx.request_context is not None and ctx.session_id is not None:
+            attrs["mcp.session.id"] = ctx.session_id
+    except RuntimeError:
+        pass
+    return attrs
+
+
+def _get_parent_trace_context() -> Context | None:
+    """Get parent trace context from request meta for distributed tracing."""
+    try:
+        req_ctx = request_ctx.get()
+        if req_ctx and hasattr(req_ctx, "meta") and req_ctx.meta:
+            return extract_trace_context(dict(req_ctx.meta))
+    except LookupError:
+        pass
+    return None
+
+
+@contextmanager
+def server_span(
+    name: str,
+    method: str,
+    server_name: str,
+    component_type: str,
+    component_key: str,
+    resource_uri: str | None = None,
+) -> Generator[Span, None, None]:
+    """Create a SERVER span with standard MCP attributes and auth context.
+
+    Automatically records any exception on the span and sets error status.
+    """
+    tracer = get_tracer()
+    with tracer.start_as_current_span(
+        name,
+        context=_get_parent_trace_context(),
+        kind=SpanKind.SERVER,
+    ) as span:
+        attrs: dict[str, str] = {
+            # RPC semantic conventions
+            "rpc.system": "mcp",
+            "rpc.service": server_name,
+            "rpc.method": method,
+            # MCP semantic conventions
+            "mcp.method.name": method,
+            # FastMCP-specific attributes
+            "fastmcp.server.name": server_name,
+            "fastmcp.component.type": component_type,
+            "fastmcp.component.key": component_key,
+            **get_auth_span_attributes(),
+            **get_session_span_attributes(),
+        }
+        if resource_uri is not None:
+            attrs["mcp.resource.uri"] = resource_uri
+        span.set_attributes(attrs)
+        try:
+            yield span
+        except Exception as e:
+            span.record_exception(e)
+            span.set_status(Status(StatusCode.ERROR))
+            raise
+
+
+@contextmanager
+def delegate_span(
+    name: str,
+    provider_type: str,
+    component_key: str,
+) -> Generator[Span, None, None]:
+    """Create an INTERNAL span for provider delegation.
+
+    Used by FastMCPProvider when delegating to mounted servers.
+    Automatically records any exception on the span and sets error status.
+    """
+    tracer = get_tracer()
+    with tracer.start_as_current_span(f"delegate {name}") as span:
+        span.set_attributes(
+            {
+                "fastmcp.provider.type": provider_type,
+                "fastmcp.component.key": component_key,
+            }
+        )
+        try:
+            yield span
+        except Exception as e:
+            span.record_exception(e)
+            span.set_status(Status(StatusCode.ERROR))
+            raise
+
+
+__all__ = [
+    "delegate_span",
+    "get_auth_span_attributes",
+    "get_session_span_attributes",
+    "server_span",
+]

fastmcp/server/transforms/__init__.py

@@ -0,0 +1,244 @@
+"""Transform system for component transformations.
+
+Transforms modify components (tools, resources, prompts). List operations use a pure
+function pattern where transforms receive sequences and return transformed sequences.
+Get operations use a middleware pattern with `call_next` to chain lookups.
+
+Unlike middleware (which operates on requests), transforms are observable by the
+system for task registration, tag filtering, and component introspection.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.transforms import Namespace
+
+    server = FastMCP("Server")
+    mount = server.mount(other_server)
+    mount.add_transform(Namespace("api"))  # Tools become api_toolname
+    ```
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Sequence
+from typing import TYPE_CHECKING, Protocol
+
+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
+
+
+# Get methods use Protocol to express keyword-only version parameter
+class GetToolNext(Protocol):
+    """Protocol for get_tool call_next functions."""
+
+    def __call__(
+        self, name: str, *, version: VersionSpec | None = None
+    ) -> Awaitable[Tool | None]: ...
+
+
+class GetResourceNext(Protocol):
+    """Protocol for get_resource call_next functions."""
+
+    def __call__(
+        self, uri: str, *, version: VersionSpec | None = None
+    ) -> Awaitable[Resource | None]: ...
+
+
+class GetResourceTemplateNext(Protocol):
+    """Protocol for get_resource_template call_next functions."""
+
+    def __call__(
+        self, uri: str, *, version: VersionSpec | None = None
+    ) -> Awaitable[ResourceTemplate | None]: ...
+
+
+class GetPromptNext(Protocol):
+    """Protocol for get_prompt call_next functions."""
+
+    def __call__(
+        self, name: str, *, version: VersionSpec | None = None
+    ) -> Awaitable[Prompt | None]: ...
+
+
+class Transform:
+    """Base class for component transformations.
+
+    List operations use a pure function pattern: transforms receive sequences
+    and return transformed sequences. Get operations use a middleware pattern
+    with `call_next` to chain lookups.
+
+    Example:
+        ```python
+        class MyTransform(Transform):
+            async def list_tools(self, tools):
+                return [transform(t) for t in tools]  # Transform sequence
+
+            async def get_tool(self, name, call_next, *, version=None):
+                original = self.reverse_name(name)  # Map to original name
+                tool = await call_next(original, version=version)  # Get from downstream
+                return transform(tool) if tool else None
+        ```
+    """
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}()"
+
+    # -------------------------------------------------------------------------
+    # Tools
+    # -------------------------------------------------------------------------
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        """List tools with transformation applied.
+
+        Args:
+            tools: Sequence of tools to transform.
+
+        Returns:
+            Transformed sequence of tools.
+        """
+        return tools
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get a tool by name.
+
+        Args:
+            name: The requested tool name (may be transformed).
+            call_next: Callable to get tool from downstream.
+            version: Optional version filter to apply.
+
+        Returns:
+            The tool if found, None otherwise.
+        """
+        return await call_next(name, version=version)
+
+    # -------------------------------------------------------------------------
+    # Resources
+    # -------------------------------------------------------------------------
+
+    async def list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource]:
+        """List resources with transformation applied.
+
+        Args:
+            resources: Sequence of resources to transform.
+
+        Returns:
+            Transformed sequence of resources.
+        """
+        return resources
+
+    async def get_resource(
+        self,
+        uri: str,
+        call_next: GetResourceNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> Resource | None:
+        """Get a resource by URI.
+
+        Args:
+            uri: The requested resource URI (may be transformed).
+            call_next: Callable to get resource from downstream.
+            version: Optional version filter to apply.
+
+        Returns:
+            The resource if found, None otherwise.
+        """
+        return await call_next(uri, version=version)
+
+    # -------------------------------------------------------------------------
+    # Resource Templates
+    # -------------------------------------------------------------------------
+
+    async def list_resource_templates(
+        self, templates: Sequence[ResourceTemplate]
+    ) -> Sequence[ResourceTemplate]:
+        """List resource templates with transformation applied.
+
+        Args:
+            templates: Sequence of resource templates to transform.
+
+        Returns:
+            Transformed sequence of resource templates.
+        """
+        return templates
+
+    async def get_resource_template(
+        self,
+        uri: str,
+        call_next: GetResourceTemplateNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> ResourceTemplate | None:
+        """Get a resource template by URI.
+
+        Args:
+            uri: The requested template URI (may be transformed).
+            call_next: Callable to get template from downstream.
+            version: Optional version filter to apply.
+
+        Returns:
+            The resource template if found, None otherwise.
+        """
+        return await call_next(uri, version=version)
+
+    # -------------------------------------------------------------------------
+    # Prompts
+    # -------------------------------------------------------------------------
+
+    async def list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt]:
+        """List prompts with transformation applied.
+
+        Args:
+            prompts: Sequence of prompts to transform.
+
+        Returns:
+            Transformed sequence of prompts.
+        """
+        return prompts
+
+    async def get_prompt(
+        self, name: str, call_next: GetPromptNext, *, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Get a prompt by name.
+
+        Args:
+            name: The requested prompt name (may be transformed).
+            call_next: Callable to get prompt from downstream.
+            version: Optional version filter to apply.
+
+        Returns:
+            The prompt if found, None otherwise.
+        """
+        return await call_next(name, version=version)
+
+
+# Re-export built-in transforms (must be after Transform class to avoid circular imports)
+from fastmcp.server.transforms.visibility import Visibility, is_enabled  # noqa: E402
+from fastmcp.server.transforms.namespace import Namespace  # noqa: E402
+from fastmcp.server.transforms.prompts_as_tools import PromptsAsTools  # noqa: E402
+from fastmcp.server.transforms.resources_as_tools import ResourcesAsTools  # noqa: E402
+from fastmcp.server.transforms.tool_transform import ToolTransform  # noqa: E402
+from fastmcp.server.transforms.version_filter import VersionFilter  # noqa: E402
+
+__all__ = [
+    "GetPromptNext",
+    "GetResourceNext",
+    "GetResourceTemplateNext",
+    "GetToolNext",
+    "Namespace",
+    "PromptsAsTools",
+    "ResourcesAsTools",
+    "ToolTransform",
+    "Transform",
+    "VersionFilter",
+    "VersionSpec",
+    "Visibility",
+    "is_enabled",
+]

fastmcp/server/transforms/namespace.py

@@ -0,0 +1,193 @@
+"""Namespace transform for prefixing component names."""
+
+from __future__ import annotations
+
+import re
+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
+
+# Pattern for matching URIs: protocol://path
+_URI_PATTERN = re.compile(r"^([^:]+://)(.*?)$")
+
+
+class Namespace(Transform):
+    """Prefixes component names with a namespace.
+
+    - Tools: name → namespace_name
+    - Prompts: name → namespace_name
+    - Resources: protocol://path → protocol://namespace/path
+    - Resource Templates: same as resources
+
+    Example:
+        ```python
+        transform = Namespace("math")
+        # Tool "add" becomes "math_add"
+        # Resource "file://data.txt" becomes "file://math/data.txt"
+        ```
+    """
+
+    def __init__(self, prefix: str) -> None:
+        """Initialize Namespace transform.
+
+        Args:
+            prefix: The namespace prefix to apply.
+        """
+        self._prefix = prefix
+        self._name_prefix = f"{prefix}_"
+
+    def __repr__(self) -> str:
+        return f"Namespace({self._prefix!r})"
+
+    # -------------------------------------------------------------------------
+    # Name transformation helpers
+    # -------------------------------------------------------------------------
+
+    def _transform_name(self, name: str) -> str:
+        """Apply namespace prefix to a name."""
+        return f"{self._name_prefix}{name}"
+
+    def _reverse_name(self, name: str) -> str | None:
+        """Remove namespace prefix from a name, or None if no match."""
+        if name.startswith(self._name_prefix):
+            return name[len(self._name_prefix) :]
+        return None
+
+    # -------------------------------------------------------------------------
+    # URI transformation helpers
+    # -------------------------------------------------------------------------
+
+    def _transform_uri(self, uri: str) -> str:
+        """Apply namespace to a URI: protocol://path → protocol://namespace/path."""
+        match = _URI_PATTERN.match(uri)
+        if match:
+            protocol, path = match.groups()
+            return f"{protocol}{self._prefix}/{path}"
+        return uri
+
+    def _reverse_uri(self, uri: str) -> str | None:
+        """Remove namespace from a URI, or None if no match."""
+        match = _URI_PATTERN.match(uri)
+        if match:
+            protocol, path = match.groups()
+            prefix = f"{self._prefix}/"
+            if path.startswith(prefix):
+                return f"{protocol}{path[len(prefix) :]}"
+            return None
+        return None
+
+    # -------------------------------------------------------------------------
+    # Tools
+    # -------------------------------------------------------------------------
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        """Prefix tool names with namespace."""
+        return [
+            t.model_copy(update={"name": self._transform_name(t.name)}) for t in tools
+        ]
+
+    async def get_tool(
+        self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
+    ) -> Tool | None:
+        """Get tool by namespaced name."""
+        original = self._reverse_name(name)
+        if original is None:
+            return None
+        tool = await call_next(original, version=version)
+        if tool:
+            return tool.model_copy(update={"name": name})
+        return None
+
+    # -------------------------------------------------------------------------
+    # Resources
+    # -------------------------------------------------------------------------
+
+    async def list_resources(self, resources: Sequence[Resource]) -> Sequence[Resource]:
+        """Add namespace path segment to resource URIs."""
+        return [
+            r.model_copy(update={"uri": self._transform_uri(str(r.uri))})
+            for r in resources
+        ]
+
+    async def get_resource(
+        self,
+        uri: str,
+        call_next: GetResourceNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> Resource | None:
+        """Get resource by namespaced URI."""
+        original = self._reverse_uri(uri)
+        if original is None:
+            return None
+        resource = await call_next(original, version=version)
+        if resource:
+            return resource.model_copy(update={"uri": uri})
+        return None
+
+    # -------------------------------------------------------------------------
+    # Resource Templates
+    # -------------------------------------------------------------------------
+
+    async def list_resource_templates(
+        self, templates: Sequence[ResourceTemplate]
+    ) -> Sequence[ResourceTemplate]:
+        """Add namespace path segment to template URIs."""
+        return [
+            t.model_copy(update={"uri_template": self._transform_uri(t.uri_template)})
+            for t in templates
+        ]
+
+    async def get_resource_template(
+        self,
+        uri: str,
+        call_next: GetResourceTemplateNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> ResourceTemplate | None:
+        """Get resource template by namespaced URI."""
+        original = self._reverse_uri(uri)
+        if original is None:
+            return None
+        template = await call_next(original, version=version)
+        if template:
+            return template.model_copy(
+                update={"uri_template": self._transform_uri(template.uri_template)}
+            )
+        return None
+
+    # -------------------------------------------------------------------------
+    # Prompts
+    # -------------------------------------------------------------------------
+
+    async def list_prompts(self, prompts: Sequence[Prompt]) -> Sequence[Prompt]:
+        """Prefix prompt names with namespace."""
+        return [
+            p.model_copy(update={"name": self._transform_name(p.name)}) for p in prompts
+        ]
+
+    async def get_prompt(
+        self, name: str, call_next: GetPromptNext, *, version: VersionSpec | None = None
+    ) -> Prompt | None:
+        """Get prompt by namespaced name."""
+        original = self._reverse_name(name)
+        if original is None:
+            return None
+        prompt = await call_next(original, version=version)
+        if prompt:
+            return prompt.model_copy(update={"name": name})
+        return None