fastmcp 2.11.2__py3-none-any.whl → 2.12.0rc1__py3-none-any.whl

fastmcp/utilities/mcp_server_config/v1/schema.json

@@ -0,0 +1,361 @@
+{
+  "$defs": {
+    "Deployment": {
+      "description": "Configuration for server deployment and runtime settings.",
+      "properties": {
+        "transport": {
+          "anyOf": [
+            {
+              "enum": [
+                "stdio",
+                "http",
+                "sse"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Transport protocol to use",
+          "title": "Transport"
+        },
+        "host": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Host to bind to when using HTTP transport",
+          "examples": [
+            "127.0.0.1",
+            "0.0.0.0",
+            "localhost"
+          ],
+          "title": "Host"
+        },
+        "port": {
+          "anyOf": [
+            {
+              "type": "integer"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Port to bind to when using HTTP transport",
+          "examples": [
+            8000,
+            3000,
+            5000
+          ],
+          "title": "Port"
+        },
+        "path": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "URL path for the server endpoint",
+          "examples": [
+            "/mcp/",
+            "/api/mcp/",
+            "/sse/"
+          ],
+          "title": "Path"
+        },
+        "log_level": {
+          "anyOf": [
+            {
+              "enum": [
+                "DEBUG",
+                "INFO",
+                "WARNING",
+                "ERROR",
+                "CRITICAL"
+              ],
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Log level for the server",
+          "title": "Log Level"
+        },
+        "cwd": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Working directory for the server process",
+          "examples": [
+            ".",
+            "./src",
+            "/app"
+          ],
+          "title": "Cwd"
+        },
+        "env": {
+          "anyOf": [
+            {
+              "additionalProperties": {
+                "type": "string"
+              },
+              "type": "object"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Environment variables to set when running the server",
+          "examples": [
+            {
+              "API_KEY": "secret",
+              "DEBUG": "true"
+            }
+          ],
+          "title": "Env"
+        },
+        "args": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Arguments to pass to the server (after --)",
+          "examples": [
+            [
+              "--config",
+              "config.json",
+              "--debug"
+            ]
+          ],
+          "title": "Args"
+        }
+      },
+      "title": "Deployment",
+      "type": "object"
+    },
+    "FileSystemSource": {
+      "description": "Source for local Python files.",
+      "properties": {
+        "type": {
+          "const": "filesystem",
+          "default": "filesystem",
+          "title": "Type",
+          "type": "string"
+        },
+        "path": {
+          "description": "Path to Python file containing the server",
+          "title": "Path",
+          "type": "string"
+        },
+        "entrypoint": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Name of server instance or factory function (a no-arg function that returns a FastMCP server)",
+          "title": "Entrypoint"
+        }
+      },
+      "required": [
+        "path"
+      ],
+      "title": "FileSystemSource",
+      "type": "object"
+    },
+    "UVEnvironment": {
+      "description": "Configuration for Python environment setup.",
+      "properties": {
+        "type": {
+          "const": "uv",
+          "default": "uv",
+          "title": "Type",
+          "type": "string"
+        },
+        "python": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Python version constraint",
+          "examples": [
+            "3.10",
+            "3.11",
+            "3.12"
+          ],
+          "title": "Python"
+        },
+        "dependencies": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Python packages to install with PEP 508 specifiers",
+          "examples": [
+            [
+              "fastmcp>=2.0,<3",
+              "httpx",
+              "pandas>=2.0"
+            ]
+          ],
+          "title": "Dependencies"
+        },
+        "requirements": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Path to requirements.txt file",
+          "examples": [
+            "requirements.txt",
+            "../requirements/prod.txt"
+          ],
+          "title": "Requirements"
+        },
+        "project": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Path to project directory containing pyproject.toml",
+          "examples": [
+            ".",
+            "../my-project"
+          ],
+          "title": "Project"
+        },
+        "editable": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Directories to install in editable mode",
+          "examples": [
+            [
+              ".",
+              "../my-package"
+            ],
+            [
+              "/path/to/package"
+            ]
+          ],
+          "title": "Editable"
+        }
+      },
+      "title": "UVEnvironment",
+      "type": "object"
+    }
+  },
+  "description": "Configuration file for FastMCP servers",
+  "properties": {
+    "$schema": {
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "default": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
+      "description": "JSON schema for IDE support and validation",
+      "title": "$Schema"
+    },
+    "source": {
+      "$ref": "#/$defs/FileSystemSource",
+      "description": "Source configuration for the server",
+      "examples": [
+        {
+          "path": "server.py"
+        },
+        {
+          "entrypoint": "app",
+          "path": "server.py"
+        },
+        {
+          "entrypoint": "mcp",
+          "path": "src/server.py",
+          "type": "filesystem"
+        }
+      ]
+    },
+    "environment": {
+      "$ref": "#/$defs/UVEnvironment",
+      "description": "Python environment setup configuration"
+    },
+    "deployment": {
+      "$ref": "#/$defs/Deployment",
+      "description": "Server deployment and runtime settings"
+    }
+  },
+  "required": [
+    "source"
+  ],
+  "title": "FastMCP Configuration",
+  "type": "object",
+  "$id": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json"
+}

fastmcp/utilities/mcp_server_config/v1/sources/base.py

@@ -0,0 +1,30 @@
+from abc import ABC, abstractmethod
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class Source(BaseModel, ABC):
+    """Abstract base class for all source types."""
+
+    type: str = Field(description="Source type identifier")
+
+    async def prepare(self) -> None:
+        """Prepare the source (download, clone, install, etc).
+
+        For sources that need preparation (e.g., git clone, download),
+        this method performs that preparation. For sources that don't
+        need preparation (e.g., local files), this is a no-op.
+        """
+        # Default implementation for sources that don't need preparation
+        pass
+
+    @abstractmethod
+    async def load_server(self) -> Any:
+        """Load and return the FastMCP server instance.
+
+        Must be called after prepare() if the source requires preparation.
+        All information needed to load the server should be available
+        as attributes on the source instance.
+        """
+        ...

fastmcp/utilities/mcp_server_config/v1/sources/filesystem.py

@@ -0,0 +1,216 @@
+import importlib.util
+import inspect
+import sys
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import Field, field_validator
+
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config.v1.sources.base import Source
+
+logger = get_logger(__name__)
+
+
+class FileSystemSource(Source):
+    """Source for local Python files."""
+
+    type: Literal["filesystem"] = "filesystem"
+
+    path: str = Field(description="Path to Python file containing the server")
+    entrypoint: str | None = Field(
+        default=None,
+        description="Name of server instance or factory function (a no-arg function that returns a FastMCP server)",
+    )
+
+    @field_validator("path", mode="before")
+    @classmethod
+    def parse_path_with_object(cls, v: str) -> str:
+        """Parse path:object syntax and extract the object name.
+
+        This validator runs before the model is created, allowing us to
+        handle the "file.py:object" syntax at the model boundary.
+        """
+        if isinstance(v, str) and ":" in v:
+            # Check if it's a Windows path (e.g., C:\...)
+            has_windows_drive = len(v) > 1 and v[1] == ":"
+
+            # Only split if colon is not part of Windows drive
+            if ":" in (v[2:] if has_windows_drive else v):
+                # This path has an object specification
+                # We'll handle it in __init__ by setting entrypoint
+                return v
+        return v
+
+    def __init__(self, **data: Any) -> None:
+        """Initialize FileSystemSource, handling path:object syntax."""
+        # Check if path contains an object specification
+        if "path" in data and isinstance(data["path"], str) and ":" in data["path"]:
+            path_str = data["path"]
+            # Check if it's a Windows path (e.g., C:\...)
+            has_windows_drive = len(path_str) > 1 and path_str[1] == ":"
+
+            # Only split if colon is not part of Windows drive
+            if ":" in (path_str[2:] if has_windows_drive else path_str):
+                file_str, obj = path_str.rsplit(":", 1)
+                data["path"] = file_str
+                # Only set entrypoint if not already provided
+                if "entrypoint" not in data or data["entrypoint"] is None:
+                    data["entrypoint"] = obj
+
+        super().__init__(**data)
+
+    async def load_server(self) -> Any:
+        """Load server from filesystem."""
+        # Resolve the file path
+        file_path = Path(self.path).expanduser().resolve()
+        if not file_path.exists():
+            logger.error(f"File not found: {file_path}")
+            sys.exit(1)
+        if not file_path.is_file():
+            logger.error(f"Not a file: {file_path}")
+            sys.exit(1)
+
+        # Import the module
+        module = self._import_module(file_path)
+
+        # Find the server object
+        server = await self._find_server_object(module, file_path)
+
+        return server
+
+    def _import_module(self, file_path: Path) -> Any:
+        """Import a Python module from a file path.
+
+        Args:
+            file_path: Path to the Python file
+
+        Returns:
+            The imported module
+        """
+        # Add parent directory to Python path so imports can be resolved
+        file_dir = str(file_path.parent)
+        if file_dir not in sys.path:
+            sys.path.insert(0, file_dir)
+
+        # Import the module
+        spec = importlib.util.spec_from_file_location("server_module", file_path)
+        if not spec or not spec.loader:
+            logger.error("Could not load module", extra={"file": str(file_path)})
+            sys.exit(1)
+
+        module = importlib.util.module_from_spec(spec)  # type: ignore[arg-type]
+        sys.modules["server_module"] = module  # Register in sys.modules
+        spec.loader.exec_module(module)  # type: ignore[union-attr]
+
+        return module
+
+    async def _find_server_object(self, module: Any, file_path: Path) -> Any:
+        """Find the server object in the module.
+
+        Args:
+            module: The imported Python module
+            file_path: Path to the file (for error messages)
+
+        Returns:
+            The server object (or result of calling a factory function)
+        """
+        # Avoid circular import by importing here
+        from mcp.server.fastmcp import FastMCP as FastMCP1x
+
+        from fastmcp.server.server import FastMCP
+
+        # If entrypoint is specified, use it
+        if self.entrypoint:
+            # Handle module:object syntax (though this is legacy)
+            if ":" in self.entrypoint:
+                module_name, object_name = self.entrypoint.split(":", 1)
+                try:
+                    import importlib
+
+                    server_module = importlib.import_module(module_name)
+                    obj = getattr(server_module, object_name, None)
+                except ImportError:
+                    logger.error(
+                        f"Could not import module '{module_name}'",
+                        extra={"file": str(file_path)},
+                    )
+                    sys.exit(1)
+            else:
+                # Just object name
+                obj = getattr(module, self.entrypoint, None)
+
+            if obj is None:
+                logger.error(
+                    f"Server object '{self.entrypoint}' not found",
+                    extra={"file": str(file_path)},
+                )
+                sys.exit(1)
+
+            return await self._resolve_factory(obj, file_path, self.entrypoint)
+
+        # No entrypoint specified, try common server names
+        for name in ["mcp", "server", "app"]:
+            if hasattr(module, name):
+                obj = getattr(module, name)
+                if isinstance(obj, FastMCP | FastMCP1x):
+                    return await self._resolve_factory(obj, file_path, name)
+
+        # No server found
+        logger.error(
+            f"No server object found in {file_path}. Please either:\n"
+            "1. Use a standard variable name (mcp, server, or app)\n"
+            "2. Specify the entrypoint name in fastmcp.json or use `file.py:object` syntax as your path.",
+            extra={"file": str(file_path)},
+        )
+        sys.exit(1)
+
+    async def _resolve_factory(self, obj: Any, file_path: Path, name: str) -> Any:
+        """Resolve a server object or factory function to a server instance.
+
+        Args:
+            obj: The object that might be a server or factory function
+            file_path: Path to the file for error messages
+            name: Name of the object for error messages
+
+        Returns:
+            A server instance
+        """
+        # Avoid circular import by importing here
+        from mcp.server.fastmcp import FastMCP as FastMCP1x
+
+        from fastmcp.server.server import FastMCP
+
+        # Check if it's a function or coroutine function
+        if inspect.isfunction(obj) or inspect.iscoroutinefunction(obj):
+            logger.debug(f"Found factory function '{name}' in {file_path}")
+
+            try:
+                if inspect.iscoroutinefunction(obj):
+                    # Async factory function
+                    server = await obj()
+                else:
+                    # Sync factory function
+                    server = obj()
+
+                # Validate the result is a FastMCP server
+                if not isinstance(server, FastMCP | FastMCP1x):
+                    logger.error(
+                        f"Factory function '{name}' must return a FastMCP server instance, "
+                        f"got {type(server).__name__}",
+                        extra={"file": str(file_path)},
+                    )
+                    sys.exit(1)
+
+                logger.debug(f"Factory function '{name}' created server: {server.name}")
+                return server
+
+            except Exception as e:
+                logger.error(
+                    f"Failed to call factory function '{name}': {e}",
+                    extra={"file": str(file_path)},
+                )
+                sys.exit(1)
+
+        # Not a function, return as-is (should be a server instance)
+        return obj

fastmcp/utilities/openapi.py

@@ -212,7 +212,7 @@ def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRoute
         if openapi_version.startswith("3.0"):
             # Use OpenAPI 3.0 models
             openapi_30 = OpenAPI_30.model_validate(openapi_dict)
-            logger.info(
+            logger.debug(
                 f"Successfully parsed OpenAPI 3.0 schema version: {openapi_30.openapi}"
             )
             parser = OpenAPIParser(
@@ -230,7 +230,7 @@ def parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRoute
         else:
             # Default to OpenAPI 3.1 models
             openapi_31 = OpenAPI.model_validate(openapi_dict)
-            logger.info(
+            logger.debug(
                 f"Successfully parsed OpenAPI 3.1 schema version: {openapi_31.openapi}"
             )
             parser = OpenAPIParser(
@@ -713,7 +713,7 @@ class OpenAPIParser(
                             openapi_version=self.openapi_version,
                         )
                         routes.append(route)
-                        logger.info(
+                        logger.debug(
                             f"Successfully extracted route: {method_upper} {path_str}"
                         )
                     except ValueError as op_error:
@@ -734,7 +734,7 @@ class OpenAPIParser(
                             exc_info=True,
                         )
 
-        logger.info(f"Finished parsing. Extracted {len(routes)} HTTP routes.")
+        logger.debug(f"Finished parsing. Extracted {len(routes)} HTTP routes.")
         return routes
 
 

fastmcp/utilities/tests.py

@@ -76,6 +76,8 @@ def run_server_in_process(
     server_fn: Callable[..., None],
     *args,
     provide_host_and_port: bool = True,
+    host: str = "127.0.0.1",
+    port: int | None = None,
     **kwargs,
 ) -> Generator[str, None, None]:
     """
@@ -87,13 +89,16 @@ def run_server_in_process(
             not pickleable, so we need a function that creates and runs one.
         *args: Arguments to pass to the server function.
         provide_host_and_port: Whether to provide the host and port to the server function as kwargs.
+        host: Host to bind the server to (default: "127.0.0.1").
+        port: Port to bind the server to (default: find available port).
         **kwargs: Keyword arguments to pass to the server function.
 
     Returns:
         The server URL.
     """
-    host = "127.0.0.1"
-    port = find_available_port()
+    # Use provided port or find an available one
+    if port is None:
+        port = find_available_port()
 
     if provide_host_and_port:
         kwargs |= {"host": host, "port": port}