fastmcp 2.10.2__py3-none-any.whl → 2.10.4__py3-none-any.whl

fastmcp/mcp_config.py

@@ -0,0 +1,282 @@
+"""Canonical MCP Configuration Format.
+
+This module defines the standard configuration format for Model Context Protocol (MCP) servers.
+It provides a client-agnostic, extensible format that can be used across all MCP implementations.
+
+The configuration format supports both stdio and remote (HTTP/SSE) transports, with comprehensive
+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"
+            }
+        }
+    }
+"""
+
+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
+
+if TYPE_CHECKING:
+    from fastmcp.client.transports import (
+        SSETransport,
+        StdioTransport,
+        StreamableHttpTransport,
+    )
+
+
+def infer_transport_type_from_url(
+    url: str | AnyUrl,
+) -> Literal["http", "sse"]:
+    """
+    Infer the appropriate transport type from the given URL.
+    """
+    url = str(url)
+    if not url.startswith("http"):
+        raise ValueError(f"Invalid URL: {url}")
+
+    parsed_url = urlparse(url)
+    path = parsed_url.path
+
+    # Match /sse followed by /, ?, &, or end of string
+    if re.search(r"/sse(/|\?|&|$)", path):
+        return "sse"
+    else:
+        return "http"
+
+
+class StdioMCPServer(BaseModel):
+    """MCP server configuration for stdio transport.
+
+    This is the canonical configuration format for MCP servers using stdio transport.
+    """
+
+    # Required fields
+    command: str
+
+    # Common optional fields
+    args: list[str] = Field(default_factory=list)
+    env: dict[str, Any] = Field(default_factory=dict)
+
+    # Transport specification
+    transport: Literal["stdio"] = "stdio"
+    type: Literal["stdio"] | None = None  # Alternative transport field name
+
+    # Execution context
+    cwd: str | None = None  # Working directory for command execution
+    timeout: int | None = None  # Maximum response time in milliseconds
+
+    # Metadata
+    description: str | None = None  # Human-readable server description
+    icon: str | None = None  # Icon path or URL for UI display
+
+    # Authentication configuration
+    authentication: dict[str, Any] | None = None  # Auth configuration object
+
+    model_config = ConfigDict(extra="allow")  # Preserve unknown fields
+
+    def to_transport(self) -> StdioTransport:
+        from fastmcp.client.transports import StdioTransport
+
+        return StdioTransport(
+            command=self.command,
+            args=self.args,
+            env=self.env,
+            cwd=self.cwd,
+        )
+
+
+class RemoteMCPServer(BaseModel):
+    """MCP server configuration for HTTP/SSE transport.
+
+    This is the canonical configuration format for MCP servers using remote transports.
+    """
+
+    # Required fields
+    url: str
+
+    # Transport configuration
+    transport: Literal["http", "streamable-http", "sse"] | None = None
+    headers: dict[str, str] = Field(default_factory=dict)
+
+    # Authentication
+    auth: Annotated[
+        str | Literal["oauth"] | httpx.Auth | None,
+        Field(
+            description='Either a string representing a Bearer token, the literal "oauth" to use OAuth authentication, or an httpx.Auth instance for custom authentication.',
+        ),
+    ] = None
+
+    # Timeout configuration
+    sse_read_timeout: datetime.timedelta | int | float | None = None
+    timeout: int | None = None  # Maximum response time in milliseconds
+
+    # Metadata
+    description: str | None = None  # Human-readable server description
+    icon: str | None = None  # Icon path or URL for UI display
+
+    # Authentication configuration
+    authentication: dict[str, Any] | None = None  # Auth configuration object
+
+    model_config = ConfigDict(
+        extra="allow", arbitrary_types_allowed=True
+    )  # Preserve unknown fields
+
+    def to_transport(self) -> StreamableHttpTransport | SSETransport:
+        from fastmcp.client.transports import SSETransport, StreamableHttpTransport
+
+        if self.transport is None:
+            transport = infer_transport_type_from_url(self.url)
+        else:
+            transport = self.transport
+
+        if transport == "sse":
+            return SSETransport(
+                self.url,
+                headers=self.headers,
+                auth=self.auth,
+                sse_read_timeout=self.sse_read_timeout,
+            )
+        else:
+            # Both "http" and "streamable-http" map to StreamableHttpTransport
+            return StreamableHttpTransport(
+                self.url,
+                headers=self.headers,
+                auth=self.auth,
+                sse_read_timeout=self.sse_read_timeout,
+            )
+
+
+class MCPConfig(BaseModel):
+    """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, StdioMCPServer | RemoteMCPServer]
+
+    model_config = ConfigDict(extra="allow")  # Preserve unknown top-level fields
+
+    @classmethod
+    def from_dict(cls, config: dict[str, Any]) -> MCPConfig:
+        """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)
+
+    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
+
+    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)
+
+    @classmethod
+    def from_file(cls, file_path: Path) -> MCPConfig:
+        """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:
+        """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,
+) -> None:
+    """Update MCP configuration file with new server, preserving existing fields."""
+    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]
+        # 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)
+
+        config.add_server(server_name, merged_server)
+    else:
+        config.add_server(server_name, server_config)
+
+    config.write_to_file(file_path)

fastmcp/prompts/prompt.py

@@ -329,7 +329,7 @@ class FunctionPrompt(Prompt):
 
             # Call function and check if result is a coroutine
             result = self.fn(**kwargs)
-            if inspect.iscoroutine(result):
+            if inspect.isawaitable(result):
                 result = await result
 
             # Validate messages
@@ -350,9 +350,7 @@ class FunctionPrompt(Prompt):
                             )
                         )
                     else:
-                        content = pydantic_core.to_json(
-                            msg, fallback=str, indent=2
-                        ).decode()
+                        content = pydantic_core.to_json(msg, fallback=str).decode()
                         messages.append(
                             PromptMessage(
                                 role="user",

fastmcp/resources/resource.py

@@ -182,7 +182,7 @@ class FunctionResource(Resource):
             kwargs[context_kwarg] = get_context()
 
         result = self.fn(**kwargs)
-        if inspect.iscoroutinefunction(self.fn):
+        if inspect.isawaitable(result):
             result = await result
 
         if isinstance(result, Resource):
@@ -192,4 +192,4 @@ class FunctionResource(Resource):
         elif isinstance(result, str):
             return result
         else:
-            return pydantic_core.to_json(result, fallback=str, indent=2).decode()
+            return pydantic_core.to_json(result, fallback=str).decode()

fastmcp/resources/template.py

@@ -190,7 +190,7 @@ class FunctionResourceTemplate(ResourceTemplate):
             kwargs[context_kwarg] = get_context()
 
         result = self.fn(**kwargs)
-        if inspect.iscoroutine(result):
+        if inspect.isawaitable(result):
             result = await result
         return result
 

fastmcp/server/openapi.py

@@ -27,6 +27,7 @@ from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.openapi import (
     HTTPRoute,
     _combine_schemas,
+    extract_output_schema_from_responses,
     format_array_parameter,
     format_description_with_responses,
 )
@@ -234,6 +235,7 @@ class OpenAPITool(Tool):
         name: str,
         description: str,
         parameters: dict[str, Any],
+        output_schema: dict[str, Any] | None = None,
         tags: set[str] | None = None,
         timeout: float | None = None,
         annotations: ToolAnnotations | None = None,
@@ -243,6 +245,7 @@ class OpenAPITool(Tool):
             name=name,
             description=description,
             parameters=parameters,
+            output_schema=output_schema,
             tags=tags or set(),
             annotations=annotations,
             serializer=serializer,
@@ -392,9 +395,22 @@ class OpenAPITool(Tool):
             # Try to parse as JSON first
             try:
                 result = response.json()
-                if not isinstance(result, dict):
-                    result = {"result": result}
-                return ToolResult(structured_content=result)
+
+                # Handle structured content based on output schema, if any
+                structured_output = None
+                if self.output_schema is not None:
+                    if self.output_schema.get("x-fastmcp-wrap-result"):
+                        # Schema says wrap - always wrap in result key
+                        structured_output = {"result": result}
+                    else:
+                        structured_output = result
+                # If no output schema, use fallback logic for backward compatibility
+                elif not isinstance(result, dict):
+                    structured_output = {"result": result}
+                else:
+                    structured_output = result
+
+                return ToolResult(structured_content=structured_output)
             except json.JSONDecodeError:
                 return ToolResult(content=response.text)
 
@@ -787,6 +803,11 @@ class FastMCPOpenAPI(FastMCP):
         """Creates and registers an OpenAPITool with enhanced description."""
         combined_schema = _combine_schemas(route)
 
+        # Extract output schema from OpenAPI responses
+        output_schema = extract_output_schema_from_responses(
+            route.responses, route.schema_definitions
+        )
+
         # Get a unique tool name
         tool_name = self._get_unique_name(name, "tool")
 
@@ -810,6 +831,7 @@ class FastMCPOpenAPI(FastMCP):
             name=tool_name,
             description=enhanced_description,
             parameters=combined_schema,
+            output_schema=output_schema,
             tags=set(route.tags or []) | tags,
             timeout=self._timeout,
         )
@@ -825,10 +847,13 @@ class FastMCPOpenAPI(FastMCP):
                     f"Using component as-is."
                 )
 
+        # Use the potentially modified tool name as the registration key
+        final_tool_name = tool.name
+
         # Register the tool by directly assigning to the tools dictionary
-        self._tool_manager._tools[tool_name] = tool
+        self._tool_manager._tools[final_tool_name] = tool
         logger.debug(
-            f"Registered TOOL: {tool_name} ({route.method} {route.path}) with tags: {route.tags}"
+            f"Registered TOOL: {final_tool_name} ({route.method} {route.path}) with tags: {route.tags}"
         )
 
     def _create_openapi_resource(
@@ -875,10 +900,13 @@ class FastMCPOpenAPI(FastMCP):
                     f"Using component as-is."
                 )
 
+        # Use the potentially modified resource URI as the registration key
+        final_resource_uri = str(resource.uri)
+
         # Register the resource by directly assigning to the resources dictionary
-        self._resource_manager._resources[str(resource.uri)] = resource
+        self._resource_manager._resources[final_resource_uri] = resource
         logger.debug(
-            f"Registered RESOURCE: {resource_uri} ({route.method} {route.path}) with tags: {route.tags}"
+            f"Registered RESOURCE: {final_resource_uri} ({route.method} {route.path}) with tags: {route.tags}"
         )
 
     def _create_openapi_template(
@@ -954,8 +982,11 @@ class FastMCPOpenAPI(FastMCP):
                     f"Using component as-is."
                 )
 
+        # Use the potentially modified template URI as the registration key
+        final_template_uri = template.uri_template
+
         # Register the template by directly assigning to the templates dictionary
-        self._resource_manager._templates[uri_template_str] = template
+        self._resource_manager._templates[final_template_uri] = template
         logger.debug(
-            f"Registered TEMPLATE: {uri_template_str} ({route.method} {route.path}) with tags: {route.tags}"
+            f"Registered TEMPLATE: {final_template_uri} ({route.method} {route.path}) with tags: {route.tags}"
         )