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

fastmcp/cli/install/claude_desktop.py

@@ -0,0 +1,186 @@
+"""Claude Desktop integration for FastMCP install using Cyclopts."""
+
+import os
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+from rich import print
+
+from fastmcp.mcp_config import StdioMCPServer, update_config_file
+from fastmcp.utilities.logging import get_logger
+
+from .shared import process_common_args
+
+logger = get_logger(__name__)
+
+
+def get_claude_config_path() -> Path | None:
+    """Get the Claude config directory based on platform."""
+    if sys.platform == "win32":
+        path = Path(Path.home(), "AppData", "Roaming", "Claude")
+    elif sys.platform == "darwin":
+        path = Path(Path.home(), "Library", "Application Support", "Claude")
+    elif sys.platform.startswith("linux"):
+        path = Path(
+            os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"), "Claude"
+        )
+    else:
+        return None
+
+    if path.exists():
+        return path
+    return None
+
+
+def install_claude_desktop(
+    file: Path,
+    server_object: str | None,
+    name: str,
+    *,
+    with_editable: Path | None = None,
+    with_packages: list[str] | None = None,
+    env_vars: dict[str, str] | None = None,
+) -> bool:
+    """Install FastMCP server in Claude Desktop.
+
+    Args:
+        file: Path to the server file
+        server_object: Optional server object name (for :object suffix)
+        name: Name for the server in Claude's config
+        with_editable: Optional directory to install in editable mode
+        with_packages: Optional list of additional packages to install
+        env_vars: Optional dictionary of environment variables
+
+    Returns:
+        True if installation was successful, False otherwise
+    """
+    config_dir = get_claude_config_path()
+    if not config_dir:
+        print(
+            "[red]Claude Desktop config directory not found.[/red]\n"
+            "[blue]Please ensure Claude Desktop is installed and has been run at least once to initialize its config.[/blue]"
+        )
+        return False
+
+    config_file = config_dir / "claude_desktop_config.json"
+
+    # Build uv run command
+    args = ["run"]
+
+    # Collect all packages in a set to deduplicate
+    packages = {"fastmcp"}
+    if with_packages:
+        packages.update(pkg for pkg in with_packages if pkg)
+
+    # Add all packages with --with
+    for pkg in sorted(packages):
+        args.extend(["--with", pkg])
+
+    if with_editable:
+        args.extend(["--with-editable", str(with_editable)])
+
+    # Build server spec from parsed components
+    if server_object:
+        server_spec = f"{file.resolve()}:{server_object}"
+    else:
+        server_spec = str(file.resolve())
+
+    # Add fastmcp run command
+    args.extend(["fastmcp", "run", server_spec])
+
+    # Create server configuration
+    server_config = StdioMCPServer(
+        command="uv",
+        args=args,
+        env=env_vars or {},
+    )
+
+    try:
+        # Handle environment variable merging manually since we need to preserve existing config
+        if config_file.exists():
+            import json
+
+            content = config_file.read_text().strip()
+            if content:
+                config = json.loads(content)
+                if "mcpServers" in config and name in config["mcpServers"]:
+                    existing_env = config["mcpServers"][name].get("env", {})
+                    if env_vars:
+                        # New vars take precedence over existing ones
+                        merged_env = {**existing_env, **env_vars}
+                    else:
+                        merged_env = existing_env
+                    server_config.env = merged_env
+
+        # Update configuration with correct function signature
+        update_config_file(config_file, name, server_config)
+        print(f"[green]Successfully installed '{name}' in Claude Desktop[/green]")
+        return True
+    except Exception as e:
+        print(f"[red]Failed to install server: {e}[/red]")
+        return False
+
+
+def claude_desktop_command(
+    server_spec: str,
+    *,
+    server_name: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--server-name", "-n"],
+            help="Custom name for the server in Claude Desktop's config",
+        ),
+    ] = None,
+    with_editable: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            name=["--with-editable", "-e"],
+            help="Directory with pyproject.toml to install in editable mode",
+        ),
+    ] = None,
+    with_packages: Annotated[
+        list[str],
+        cyclopts.Parameter(
+            "--with",
+            help="Additional packages to install",
+            negative=False,
+        ),
+    ] = [],
+    env_vars: Annotated[
+        list[str],
+        cyclopts.Parameter(
+            "--env",
+            help="Environment variables in KEY=VALUE format",
+            negative=False,
+        ),
+    ] = [],
+    env_file: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--env-file",
+            help="Load environment variables from .env file",
+        ),
+    ] = None,
+) -> None:
+    """Install an MCP server in Claude Desktop.
+
+    Args:
+        server_spec: Python file to install, optionally with :object suffix
+    """
+    file, server_object, name, with_packages, env_dict = process_common_args(
+        server_spec, server_name, with_packages, env_vars, env_file
+    )
+
+    success = install_claude_desktop(
+        file=file,
+        server_object=server_object,
+        name=name,
+        with_editable=with_editable,
+        with_packages=with_packages,
+        env_vars=env_dict,
+    )
+
+    if not success:
+        sys.exit(1)

fastmcp/cli/install/cursor.py

@@ -0,0 +1,196 @@
+"""Cursor integration for FastMCP install using Cyclopts."""
+
+import base64
+import subprocess
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+from rich import print
+
+from fastmcp.mcp_config import StdioMCPServer
+from fastmcp.utilities.logging import get_logger
+
+from .shared import process_common_args
+
+logger = get_logger(__name__)
+
+
+def generate_cursor_deeplink(
+    server_name: str,
+    server_config: StdioMCPServer,
+) -> str:
+    """Generate a Cursor deeplink for installing the MCP server.
+
+    Args:
+        server_name: Name of the server
+        server_config: Server configuration
+
+    Returns:
+        Deeplink URL that can be clicked to install the server
+    """
+    # Create the configuration structure expected by Cursor
+    # Base64 encode the configuration (URL-safe for query parameter)
+    config_json = server_config.model_dump_json(exclude_none=True)
+    config_b64 = base64.urlsafe_b64encode(config_json.encode()).decode()
+
+    # Generate the deeplink URL
+    deeplink = f"cursor://anysphere.cursor-deeplink/mcp/install?name={server_name}&config={config_b64}"
+
+    return deeplink
+
+
+def open_deeplink(deeplink: str) -> bool:
+    """Attempt to open a deeplink URL using the system's default handler.
+
+    Args:
+        deeplink: The deeplink URL to open
+
+    Returns:
+        True if the command succeeded, False otherwise
+    """
+    try:
+        if sys.platform == "darwin":  # macOS
+            subprocess.run(["open", deeplink], check=True, capture_output=True)
+        elif sys.platform == "win32":  # Windows
+            subprocess.run(
+                ["start", deeplink], shell=True, check=True, capture_output=True
+            )
+        else:  # Linux and others
+            subprocess.run(["xdg-open", deeplink], check=True, capture_output=True)
+        return True
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return False
+
+
+def install_cursor(
+    file: Path,
+    server_object: str | None,
+    name: str,
+    *,
+    with_editable: Path | None = None,
+    with_packages: list[str] | None = None,
+    env_vars: dict[str, str] | None = None,
+) -> bool:
+    """Install FastMCP server in Cursor.
+
+    Args:
+        file: Path to the server file
+        server_object: Optional server object name (for :object suffix)
+        name: Name for the server in Cursor
+        with_editable: Optional directory to install in editable mode
+        with_packages: Optional list of additional packages to install
+        env_vars: Optional dictionary of environment variables
+
+    Returns:
+        True if installation was successful, False otherwise
+    """
+    # Build uv run command
+    args = ["run"]
+
+    # Collect all packages in a set to deduplicate
+    packages = {"fastmcp"}
+    if with_packages:
+        packages.update(pkg for pkg in with_packages if pkg)
+
+    # Add all packages with --with
+    for pkg in sorted(packages):
+        args.extend(["--with", pkg])
+
+    if with_editable:
+        args.extend(["--with-editable", str(with_editable)])
+
+    # Build server spec from parsed components
+    if server_object:
+        server_spec = f"{file.resolve()}:{server_object}"
+    else:
+        server_spec = str(file.resolve())
+
+    # Add fastmcp run command
+    args.extend(["fastmcp", "run", server_spec])
+
+    # Create server configuration
+    server_config = StdioMCPServer(
+        command="uv",
+        args=args,
+        env=env_vars or {},
+    )
+
+    # Generate deeplink
+    deeplink = generate_cursor_deeplink(name, server_config)
+
+    print(f"[blue]Opening Cursor to install '{name}'[/blue]")
+
+    if open_deeplink(deeplink):
+        print("[green]Cursor should now open with the installation dialog[/green]")
+        return True
+    else:
+        print(
+            "[red]Could not open Cursor automatically.[/red]\n"
+            f"[blue]Please copy this link and open it in Cursor: {deeplink}[/blue]"
+        )
+        return False
+
+
+def cursor_command(
+    server_spec: str,
+    *,
+    server_name: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--server-name", "-n"],
+            help="Custom name for the server in Cursor",
+        ),
+    ] = None,
+    with_editable: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            name=["--with-editable", "-e"],
+            help="Directory with pyproject.toml to install in editable mode",
+        ),
+    ] = None,
+    with_packages: Annotated[
+        list[str],
+        cyclopts.Parameter(
+            "--with",
+            help="Additional packages to install",
+            negative=False,
+        ),
+    ] = [],
+    env_vars: Annotated[
+        list[str],
+        cyclopts.Parameter(
+            "--env",
+            help="Environment variables in KEY=VALUE format",
+            negative=False,
+        ),
+    ] = [],
+    env_file: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--env-file",
+            help="Load environment variables from .env file",
+        ),
+    ] = None,
+) -> None:
+    """Install an MCP server in Cursor.
+
+    Args:
+        server_spec: Python file to install, optionally with :object suffix
+    """
+    file, server_object, name, with_packages, env_dict = process_common_args(
+        server_spec, server_name, with_packages, env_vars, env_file
+    )
+
+    success = install_cursor(
+        file=file,
+        server_object=server_object,
+        name=name,
+        with_editable=with_editable,
+        with_packages=with_packages,
+        env_vars=env_dict,
+    )
+
+    if not success:
+        sys.exit(1)

fastmcp/cli/install/mcp_config.py

@@ -0,0 +1,165 @@
+"""MCP configuration JSON generation for FastMCP install using Cyclopts."""
+
+import json
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import cyclopts
+import pyperclip
+from rich import print
+
+from fastmcp.utilities.logging import get_logger
+
+from .shared import process_common_args
+
+logger = get_logger(__name__)
+
+
+def install_mcp_config(
+    file: Path,
+    server_object: str | None,
+    name: str,
+    *,
+    with_editable: Path | None = None,
+    with_packages: list[str] | None = None,
+    env_vars: dict[str, str] | None = None,
+    copy: bool = False,
+) -> bool:
+    """Generate MCP configuration JSON for manual installation.
+
+    Args:
+        file: Path to the server file
+        server_object: Optional server object name (for :object suffix)
+        name: Name for the server in MCP config
+        with_editable: Optional directory to install in editable mode
+        with_packages: Optional list of additional packages to install
+        env_vars: Optional dictionary of environment variables
+        copy: If True, copy to clipboard instead of printing to stdout
+
+    Returns:
+        True if generation was successful, False otherwise
+    """
+    try:
+        # Build uv run command
+        args = ["run"]
+
+        # Collect all packages in a set to deduplicate
+        packages = {"fastmcp"}
+        if with_packages:
+            packages.update(pkg for pkg in with_packages if pkg)
+
+        # Add all packages with --with
+        for pkg in sorted(packages):
+            args.extend(["--with", pkg])
+
+        if with_editable:
+            args.extend(["--with-editable", str(with_editable)])
+
+        # Build server spec from parsed components
+        if server_object:
+            server_spec = f"{file.resolve()}:{server_object}"
+        else:
+            server_spec = str(file.resolve())
+
+        # Add fastmcp run command
+        args.extend(["fastmcp", "run", server_spec])
+
+        # Build MCP server configuration (just the server object, not the wrapper)
+        config = {
+            "command": "uv",
+            "args": args,
+        }
+
+        # Add environment variables if provided
+        if env_vars:
+            config["env"] = env_vars
+
+        # Convert to JSON
+        json_output = json.dumps(config, indent=2)
+
+        # Handle output
+        if copy:
+            pyperclip.copy(json_output)
+            print(f"[green]MCP configuration for '{name}' copied to clipboard[/green]")
+        else:
+            # Print to stdout (for piping)
+            print(json_output)
+
+        return True
+
+    except Exception as e:
+        print(f"[red]Failed to generate MCP configuration: {e}[/red]")
+        return False
+
+
+def mcp_config_command(
+    server_spec: str,
+    *,
+    server_name: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--server-name", "-n"],
+            help="Custom name for the server in MCP config",
+        ),
+    ] = None,
+    with_editable: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            name=["--with-editable", "-e"],
+            help="Directory with pyproject.toml to install in editable mode",
+        ),
+    ] = None,
+    with_packages: Annotated[
+        list[str],
+        cyclopts.Parameter(
+            "--with",
+            help="Additional packages to install",
+            negative=False,
+        ),
+    ] = [],
+    env_vars: Annotated[
+        list[str],
+        cyclopts.Parameter(
+            "--env",
+            help="Environment variables in KEY=VALUE format",
+            negative=False,
+        ),
+    ] = [],
+    env_file: Annotated[
+        Path | None,
+        cyclopts.Parameter(
+            "--env-file",
+            help="Load environment variables from .env file",
+        ),
+    ] = None,
+    copy: Annotated[
+        bool,
+        cyclopts.Parameter(
+            "--copy",
+            help="Copy configuration to clipboard instead of printing to stdout",
+            negative=False,
+        ),
+    ] = False,
+) -> None:
+    """Generate MCP configuration JSON for manual installation.
+
+    Args:
+        server_spec: Python file to install, optionally with :object suffix
+    """
+    file, server_object, name, packages, env_dict = process_common_args(
+        server_spec, server_name, with_packages, env_vars, env_file
+    )
+
+    success = install_mcp_config(
+        file=file,
+        server_object=server_object,
+        name=name,
+        with_editable=with_editable,
+        with_packages=packages,
+        env_vars=env_dict,
+        copy=copy,
+    )
+
+    if not success:
+        sys.exit(1)

fastmcp/cli/install/shared.py

@@ -0,0 +1,85 @@
+"""Shared utilities for install commands."""
+
+import sys
+from pathlib import Path
+
+from dotenv import dotenv_values
+from rich import print
+
+from fastmcp.cli.run import import_server, parse_file_path
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+def parse_env_var(env_var: str) -> tuple[str, str]:
+    """Parse environment variable string in format KEY=VALUE."""
+    if "=" not in env_var:
+        print(
+            f"[red]Invalid environment variable format: '[bold]{env_var}[/bold]'. Must be KEY=VALUE[/red]"
+        )
+        sys.exit(1)
+    key, value = env_var.split("=", 1)
+    return key.strip(), value.strip()
+
+
+def process_common_args(
+    server_spec: str,
+    server_name: str | None,
+    with_packages: list[str],
+    env_vars: list[str],
+    env_file: Path | None,
+) -> tuple[Path, str | None, str, list[str], dict[str, str] | None]:
+    """Process common arguments shared by all install commands."""
+    # Parse server spec
+    file, server_object = parse_file_path(server_spec)
+
+    logger.debug(
+        "Installing server",
+        extra={
+            "file": str(file),
+            "server_name": server_name,
+            "server_object": server_object,
+            "with_packages": with_packages,
+        },
+    )
+
+    # Try to import server to get its name and dependencies
+    name = server_name
+    server = None
+    if not name:
+        try:
+            server = import_server(file, server_object)
+            name = server.name
+        except (ImportError, ModuleNotFoundError) as e:
+            logger.debug(
+                "Could not import server (likely missing dependencies), using file name",
+                extra={"error": str(e)},
+            )
+            name = file.stem
+
+    # Get server dependencies if available
+    server_dependencies = getattr(server, "dependencies", []) if server else []
+    if server_dependencies:
+        with_packages = list(set(with_packages + server_dependencies))
+
+    # Process environment variables if provided
+    env_dict: dict[str, str] | None = None
+    if env_file or env_vars:
+        env_dict = {}
+        # Load from .env file if specified
+        if env_file:
+            try:
+                env_dict |= {
+                    k: v for k, v in dotenv_values(env_file).items() if v is not None
+                }
+            except Exception as e:
+                print(f"[red]Failed to load .env file: {e}[/red]")
+                sys.exit(1)
+
+        # Add command line environment variables
+        for env_var in env_vars:
+            key, value = parse_env_var(env_var)
+            env_dict[key] = value
+
+    return file, server_object, name, with_packages, env_dict

fastmcp/cli/run.py

@@ -1,15 +1,19 @@
-"""FastMCP run command implementation."""
+"""FastMCP run command implementation with enhanced type hints."""
 
 import importlib.util
 import re
 import sys
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 from fastmcp.utilities.logging import get_logger
 
 logger = get_logger("cli.run")
 
+# Type aliases for better type safety
+TransportType = Literal["stdio", "http", "sse", "streamable-http"]
+LogLevelType = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
 
 def is_url(path: str) -> bool:
     """Check if a string is a URL."""
@@ -164,10 +168,11 @@ def import_server_with_args(
 
 def run_command(
     server_spec: str,
-    transport: str | None = None,
+    transport: TransportType | None = None,
     host: str | None = None,
     port: int | None = None,
-    log_level: str | None = None,
+    path: str | None = None,
+    log_level: LogLevelType | None = None,
     server_args: list[str] | None = None,
     show_banner: bool = True,
 ) -> None:
@@ -178,8 +183,10 @@ def run_command(
         transport: Transport protocol to use
         host: Host to bind to when using http transport
         port: Port to bind to when using http transport
+        path: Path to bind to when using http transport
         log_level: Log level
         server_args: Additional arguments to pass to the server
+        show_banner: Whether to show the server banner
     """
     if is_url(server_spec):
         # Handle URL case
@@ -199,6 +206,8 @@ def run_command(
         kwargs["host"] = host
     if port:
         kwargs["port"] = port
+    if path:
+        kwargs["path"] = path
     if log_level:
         kwargs["log_level"] = log_level