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

fastmcp/utilities/inspect.py

@@ -26,7 +26,6 @@ class ToolInfo:
     output_schema: dict[str, Any] | None = None
     annotations: dict[str, Any] | None = None
     tags: list[str] | None = None
-    enabled: bool | None = None
     title: str | None = None
     icons: list[dict[str, Any]] | None = None
     meta: dict[str, Any] | None = None
@@ -41,7 +40,6 @@ class PromptInfo:
     description: str | None
     arguments: list[dict[str, Any]] | None = None
     tags: list[str] | None = None
-    enabled: bool | None = None
     title: str | None = None
     icons: list[dict[str, Any]] | None = None
     meta: dict[str, Any] | None = None
@@ -58,7 +56,6 @@ class ResourceInfo:
     mime_type: str | None = None
     annotations: dict[str, Any] | None = None
     tags: list[str] | None = None
-    enabled: bool | None = None
     title: str | None = None
     icons: list[dict[str, Any]] | None = None
     meta: dict[str, Any] | None = None
@@ -76,7 +73,6 @@ class TemplateInfo:
     parameters: dict[str, Any] | None = None
     annotations: dict[str, Any] | None = None
     tags: list[str] | None = None
-    enabled: bool | None = None
     title: str | None = None
     icons: list[dict[str, Any]] | None = None
     meta: dict[str, Any] | None = None
@@ -110,16 +106,16 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
     Returns:
         FastMCPInfo dataclass containing the extracted information
     """
-    # Get all components via middleware to respect filtering and preserve metadata
-    tools_list = await mcp._list_tools_middleware()
-    prompts_list = await mcp._list_prompts_middleware()
-    resources_list = await mcp._list_resources_middleware()
-    templates_list = await mcp._list_resource_templates_middleware()
+    # Get all components (list_* includes middleware, enabled/auth filtering)
+    tools_list = await mcp.list_tools()
+    prompts_list = await mcp.list_prompts()
+    resources_list = await mcp.list_resources()
+    templates_list = await mcp.list_resource_templates()
 
     # Extract detailed tool information
     tool_infos = []
     for tool in tools_list:
-        mcp_tool = tool.to_mcp_tool(name=tool.key)
+        mcp_tool = tool.to_mcp_tool(name=tool.name)
         tool_infos.append(
             ToolInfo(
                 key=tool.key,
@@ -129,7 +125,6 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
                 output_schema=tool.output_schema,
                 annotations=tool.annotations.model_dump() if tool.annotations else None,
                 tags=list(tool.tags) if tool.tags else None,
-                enabled=tool.enabled,
                 title=tool.title,
                 icons=[icon.model_dump() for icon in tool.icons]
                 if tool.icons
@@ -150,7 +145,6 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
                 if prompt.arguments
                 else None,
                 tags=list(prompt.tags) if prompt.tags else None,
-                enabled=prompt.enabled,
                 title=prompt.title,
                 icons=[icon.model_dump() for icon in prompt.icons]
                 if prompt.icons
@@ -165,7 +159,7 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
         resource_infos.append(
             ResourceInfo(
                 key=resource.key,
-                uri=resource.key,
+                uri=str(resource.uri),
                 name=resource.name,
                 description=resource.description,
                 mime_type=resource.mime_type,
@@ -173,7 +167,6 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
                 if resource.annotations
                 else None,
                 tags=list(resource.tags) if resource.tags else None,
-                enabled=resource.enabled,
                 title=resource.title,
                 icons=[icon.model_dump() for icon in resource.icons]
                 if resource.icons
@@ -188,7 +181,7 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
         template_infos.append(
             TemplateInfo(
                 key=template.key,
-                uri_template=template.key,
+                uri_template=template.uri_template,
                 name=template.name,
                 description=template.description,
                 mime_type=template.mime_type,
@@ -197,7 +190,6 @@ async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
                 if template.annotations
                 else None,
                 tags=list(template.tags) if template.tags else None,
-                enabled=template.enabled,
                 title=template.title,
                 icons=[icon.model_dump() for icon in template.icons]
                 if template.icons
@@ -275,7 +267,6 @@ async def inspect_fastmcp_v1(mcp: FastMCP1x) -> FastMCPInfo:
                     output_schema=None,  # v1 doesn't have output_schema
                     annotations=None,  # v1 doesn't have annotations
                     tags=None,  # v1 doesn't have tags
-                    enabled=None,  # v1 doesn't have enabled field
                     title=None,  # v1 doesn't have title
                     icons=[icon.model_dump() for icon in mcp_tool.icons]
                     if hasattr(mcp_tool, "icons") and mcp_tool.icons
@@ -299,7 +290,6 @@ async def inspect_fastmcp_v1(mcp: FastMCP1x) -> FastMCPInfo:
                     description=mcp_prompt.description,
                     arguments=arguments,
                     tags=None,  # v1 doesn't have tags
-                    enabled=None,  # v1 doesn't have enabled field
                     title=None,  # v1 doesn't have title
                     icons=[icon.model_dump() for icon in mcp_prompt.icons]
                     if hasattr(mcp_prompt, "icons") and mcp_prompt.icons
@@ -320,7 +310,6 @@ async def inspect_fastmcp_v1(mcp: FastMCP1x) -> FastMCPInfo:
                     mime_type=mcp_resource.mimeType,
                     annotations=None,  # v1 doesn't have annotations
                     tags=None,  # v1 doesn't have tags
-                    enabled=None,  # v1 doesn't have enabled field
                     title=None,  # v1 doesn't have title
                     icons=[icon.model_dump() for icon in mcp_resource.icons]
                     if hasattr(mcp_resource, "icons") and mcp_resource.icons
@@ -342,7 +331,6 @@ async def inspect_fastmcp_v1(mcp: FastMCP1x) -> FastMCPInfo:
                     parameters=None,  # v1 doesn't expose template parameters
                     annotations=None,  # v1 doesn't have annotations
                     tags=None,  # v1 doesn't have tags
-                    enabled=None,  # v1 doesn't have enabled field
                     title=None,  # v1 doesn't have title
                     icons=[icon.model_dump() for icon in mcp_template.icons]
                     if hasattr(mcp_template, "icons") and mcp_template.icons

fastmcp/utilities/json_schema.py

@@ -364,31 +364,38 @@ def _single_pass_optimize(
 def compress_schema(
     schema: dict[str, Any],
     prune_params: list[str] | None = None,
-    prune_defs: bool = True,
     prune_additional_properties: bool = True,
     prune_titles: bool = False,
 ) -> dict[str, Any]:
     """
-    Remove the given parameters from the schema.
+    Compress and optimize a JSON schema for MCP compatibility.
+
+    This function dereferences all $ref entries (inlining definitions) to ensure
+    compatibility with MCP clients that don't properly handle $ref in schemas
+    (e.g., VS Code Copilot). It also applies various optimizations to reduce
+    schema size.
 
     Args:
         schema: The schema to compress
         prune_params: List of parameter names to remove from properties
-        prune_defs: Whether to remove unused definitions
         prune_additional_properties: Whether to remove additionalProperties: false
         prune_titles: Whether to remove title fields from the schema
     """
+    # Dereference $ref - this inlines all definitions and removes $defs
+    # Required for MCP client compatibility
+    schema = dereference_refs(schema)
+
     # Remove specific parameters if requested
     for param in prune_params or []:
         schema = _prune_param(schema, param=param)
 
     # Apply combined optimizations in a single tree traversal
-    if prune_titles or prune_additional_properties or prune_defs:
+    if prune_titles or prune_additional_properties:
         schema = _single_pass_optimize(
             schema,
             prune_titles=prune_titles,
             prune_additional_properties=prune_additional_properties,
-            prune_defs=prune_defs,
+            prune_defs=False,
         )
 
     return schema

fastmcp/utilities/json_schema_type.py

@@ -47,6 +47,7 @@ from typing import (
     ForwardRef,
     Literal,
     Union,
+    cast,
 )
 
 from pydantic import (
@@ -171,14 +172,15 @@ def json_schema_to_type(
         if not schema.get("properties") and schema.get("additionalProperties"):
             additional_props = schema["additionalProperties"]
             if additional_props is True:
-                return dict[str, Any]  # type: ignore - additionalProperties: true means dict[str, Any]
+                return dict[str, Any]
             else:
                 # Handle typed dictionaries like dict[str, str]
                 value_type = _schema_to_type(additional_props, schemas=schema)
-                return dict[str, value_type]  # type: ignore
+                # value_type might be ForwardRef or type - cast to Any for dynamic type construction
+                return cast(type[Any], dict[str, value_type])  # type: ignore[valid-type]
         # If no properties and no additionalProperties, default to dict[str, Any] for safety
         elif not schema.get("properties") and not schema.get("additionalProperties"):
-            return dict[str, Any]  # type: ignore
+            return dict[str, Any]
         # If has properties AND additionalProperties is True, use Pydantic BaseModel
         elif schema.get("properties") and schema.get("additionalProperties") is True:
             return _create_pydantic_model(schema, name, schemas=schema)
@@ -265,13 +267,13 @@ def _create_array_type(
     if isinstance(items, list):
         # Handle positional item schemas
         item_types = [_schema_to_type(s, schemas) for s in items]
-        combined = Union[tuple(item_types)]  # type: ignore[arg-type] # noqa: UP007
+        combined = Union[tuple(item_types)]  # noqa: UP007
         base = list[combined]  # type: ignore[valid-type]
     else:
         # Handle single item schema
         item_type = _schema_to_type(items, schemas)
         base_class = set if schema.get("uniqueItems") else list
-        base = base_class[item_type]  # type: ignore[misc]
+        base = base_class[item_type]
 
     constraints = {
         k: v
@@ -295,17 +297,17 @@ def _get_from_type_handler(
     """Get the appropriate type handler for the schema."""
 
     type_handlers: dict[str, Callable[..., Any]] = {  # TODO
-        "string": lambda s: _create_string_type(s),  # type: ignore
-        "integer": lambda s: _create_numeric_type(int, s),  # type: ignore
-        "number": lambda s: _create_numeric_type(float, s),  # type: ignore
-        "boolean": lambda _: bool,  # type: ignore
-        "null": lambda _: type(None),  # type: ignore
-        "array": lambda s: _create_array_type(s, schemas),  # type: ignore
+        "string": lambda s: _create_string_type(s),
+        "integer": lambda s: _create_numeric_type(int, s),
+        "number": lambda s: _create_numeric_type(float, s),
+        "boolean": lambda _: bool,
+        "null": lambda _: type(None),
+        "array": lambda s: _create_array_type(s, schemas),
         "object": lambda s: (
             _create_pydantic_model(s, s.get("title"), schemas)
             if s.get("properties") and s.get("additionalProperties") is True
             else _create_dataclass(s, s.get("title"), schemas)
-        ),  # type: ignore
+        ),
     }
     return type_handlers.get(schema.get("type", None), _return_Any)
 
@@ -326,7 +328,7 @@ def _schema_to_type(
         ref = schema["$ref"]
         # Handle self-reference
         if ref == "#":
-            return ForwardRef(schema.get("title", "Root"))  # type: ignore[return-value]
+            return ForwardRef(schema.get("title", "Root"))
         return _schema_to_type(_resolve_ref(ref, schemas), schemas)
 
     if "const" in schema:
@@ -348,7 +350,7 @@ def _schema_to_type(
                 # This is a dict type, handle it directly
                 additional_props = subschema["additionalProperties"]
                 if additional_props is True:
-                    types.append(dict[str, Any])  # type: ignore
+                    types.append(dict[str, Any])
                 else:
                     value_type = _schema_to_type(additional_props, schemas)
                     types.append(dict[str, value_type])  # type: ignore
@@ -374,7 +376,7 @@ def _schema_to_type(
 
     schema_type = schema.get("type")
     if not schema_type:
-        return Any  # type: ignore[return-value]
+        return Any
 
     if isinstance(schema_type, list):
         # Create a copy of the schema for each type, but keep all constraints

fastmcp/utilities/lifespan.py

@@ -0,0 +1,56 @@
+"""Lifespan utilities for combining async context manager lifespans."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+from contextlib import AbstractAsyncContextManager, AsyncExitStack, asynccontextmanager
+from typing import Any, TypeVar
+
+AppT = TypeVar("AppT")
+
+
+def combine_lifespans(
+    *lifespans: Callable[[AppT], AbstractAsyncContextManager[dict[str, Any] | None]],
+) -> Callable[[AppT], AbstractAsyncContextManager[dict[str, Any]]]:
+    """Combine multiple lifespans into a single lifespan.
+
+    Useful when mounting FastMCP into FastAPI and you need to run
+    both your app's lifespan and the MCP server's lifespan.
+
+    Works with both FastAPI-style lifespans (yield None) and FastMCP-style
+    lifespans (yield dict). Results are merged; later lifespans override
+    earlier ones on key conflicts.
+
+    Lifespans are entered in order and exited in reverse order (LIFO).
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.utilities.lifespan import combine_lifespans
+        from fastapi import FastAPI
+
+        mcp = FastMCP("Tools")
+        mcp_app = mcp.http_app()
+
+        app = FastAPI(lifespan=combine_lifespans(app_lifespan, mcp_app.lifespan))
+        app.mount("/mcp", mcp_app)  # MCP endpoint at /mcp
+        ```
+
+    Args:
+        *lifespans: Lifespan context manager factories to combine.
+
+    Returns:
+        A combined lifespan context manager factory.
+    """
+
+    @asynccontextmanager
+    async def combined(app: AppT) -> AsyncIterator[dict[str, Any]]:
+        merged: dict[str, Any] = {}
+        async with AsyncExitStack() as stack:
+            for ls in lifespans:
+                result = await stack.enter_async_context(ls(app))
+                if result is not None:
+                    merged.update(result)
+            yield merged
+
+    return combined

fastmcp/utilities/logging.py

@@ -57,6 +57,18 @@ def configure_logging(
     logger.propagate = False
     logger.setLevel(level)
 
+    # Remove any existing handlers to avoid duplicates on reconfiguration
+    for hdlr in logger.handlers[:]:
+        logger.removeHandler(hdlr)
+
+    # Use standard logging handlers if rich logging is disabled
+    if not fastmcp.settings.enable_rich_logging:
+        # Create a standard StreamHandler for stderr
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("%(levelname)s: %(message)s"))
+        logger.addHandler(handler)
+        return
+
     # Configure the handler for normal logs
     handler = RichHandler(
         console=Console(stderr=True),
@@ -91,10 +103,6 @@ def configure_logging(
 
     traceback_handler.addFilter(lambda record: record.exc_info is not None)
 
-    # Remove any existing handlers to avoid duplicates on reconfiguration
-    for hdlr in logger.handlers[:]:
-        logger.removeHandler(hdlr)
-
     logger.addHandler(handler)
     logger.addHandler(traceback_handler)
 

fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py

@@ -216,7 +216,7 @@ class MCPServerConfig(BaseModel):
 
         """
         if isinstance(v, dict):
-            return Deployment(**v)  # type: ignore[arg-type]
+            return Deployment(**v)
         return cast(Deployment, v)  # type: ignore[return-value]
 
     @classmethod
@@ -301,9 +301,9 @@ class MCPServerConfig(BaseModel):
         if any([transport, host, port, path, log_level, env, cwd, args]):
             # Convert streamable-http to http for backward compatibility
             if transport == "streamable-http":
-                transport = "http"  # type: ignore[assignment]
+                transport = "http"
             deployment = Deployment(
-                transport=transport,  # type: ignore[arg-type]
+                transport=transport,
                 host=host,
                 port=port,
                 path=path,

fastmcp/utilities/openapi/parser.py

@@ -1,6 +1,6 @@
 """OpenAPI parsing logic for converting OpenAPI specs to HTTPRoute objects."""
 
-from typing import Any, Generic, TypeVar
+from typing import Any, Generic, TypeVar, cast
 
 from openapi_pydantic import (
     OpenAPI,
@@ -146,9 +146,9 @@ class OpenAPIParser(
     def _convert_to_parameter_location(self, param_in: str) -> ParameterLocation:
         """Convert string parameter location to our ParameterLocation type."""
         if param_in in ["path", "query", "header", "cookie"]:
-            return param_in  # type: ignore[return-value]  # Safe cast since we checked values
+            return cast(ParameterLocation, param_in)
         logger.warning(f"Unknown parameter location: {param_in}, defaulting to 'query'")
-        return "query"  # type: ignore[return-value]  # Safe cast to default value
+        return cast(ParameterLocation, "query")
 
     def _resolve_ref(self, item: Any) -> Any:
         """Resolves a reference to its target definition."""

fastmcp/utilities/pagination.py

@@ -0,0 +1,80 @@
+"""Pagination utilities for MCP list operations."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class CursorState:
+    """Internal representation of pagination cursor state.
+
+    The cursor encodes the offset into the result set. This is opaque to clients
+    per the MCP spec - they should not parse or modify cursors.
+    """
+
+    offset: int
+
+    def encode(self) -> str:
+        """Encode cursor state to an opaque string."""
+        data = json.dumps({"o": self.offset})
+        return base64.urlsafe_b64encode(data.encode()).decode()
+
+    @classmethod
+    def decode(cls, cursor: str) -> CursorState:
+        """Decode cursor from an opaque string.
+
+        Raises:
+            ValueError: If the cursor is invalid or malformed.
+        """
+        try:
+            data = json.loads(base64.urlsafe_b64decode(cursor.encode()).decode())
+            return cls(offset=data["o"])
+        except (
+            json.JSONDecodeError,
+            KeyError,
+            ValueError,
+            TypeError,
+            binascii.Error,
+        ) as e:
+            raise ValueError(f"Invalid cursor: {cursor}") from e
+
+
+def paginate_sequence(
+    items: Sequence[T],
+    cursor: str | None,
+    page_size: int,
+) -> tuple[list[T], str | None]:
+    """Paginate a sequence of items.
+
+    Args:
+        items: The full sequence to paginate.
+        cursor: Optional cursor from a previous request. None for first page.
+        page_size: Maximum number of items per page.
+
+    Returns:
+        Tuple of (page_items, next_cursor). next_cursor is None if no more pages.
+
+    Raises:
+        ValueError: If the cursor is invalid.
+    """
+    offset = 0
+    if cursor:
+        state = CursorState.decode(cursor)
+        offset = state.offset
+
+    end = offset + page_size
+    page = list(items[offset:end])
+
+    next_cursor = None
+    if end < len(items):
+        next_cursor = CursorState(offset=end).encode()
+
+    return page, next_cursor