fastmcp 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

fastmcp/__init__.py

@@ -1 +1,8 @@
-from .server import FastMCP
+"""FastMCP - A more ergonomic interface for MCP servers."""
+
+from importlib.metadata import version
+from .server import FastMCP, Context
+from .utilities.types import Image
+
+__version__ = version("fastmcp")
+__all__ = ["FastMCP", "Context", "Image"]

fastmcp/cli/__init__.py

@@ -2,4 +2,6 @@
 
 from .cli import app
 
-__all__ = ["app"]
+
+if __name__ == "__main__":
+    app()

fastmcp/cli/claude.py

@@ -25,18 +25,21 @@ def get_claude_config_path() -> Path | None:
 
 
 def update_claude_config(
-    file: Path,
-    server_name: Optional[str] = None,
+    file_spec: str,
+    server_name: str,
     *,
-    uv_directory: Optional[Path] = None,
+    with_editable: Optional[Path] = None,
+    with_packages: Optional[list[str]] = None,
+    force: bool = False,
 ) -> bool:
     """Add the MCP server to Claude's configuration.
 
     Args:
-        file: Path to the server file
-        server_name: Optional custom name for the server. If not provided,
-                    defaults to the file stem
-        uv_directory: Optional directory containing pyproject.toml
+        file_spec: Path to the server file, optionally with :object suffix
+        server_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
+        force: If True, replace existing server with same name
     """
     config_dir = get_claude_config_path()
     if not config_dir:
@@ -51,29 +54,49 @@ def update_claude_config(
         if "mcpServers" not in config:
             config["mcpServers"] = {}
 
-        # Use provided server_name or fall back to file stem
-        name = server_name or file.stem
-        if name in config["mcpServers"]:
-            logger.warning(
-                f"Server '{name}' already exists in Claude config",
+        if server_name in config["mcpServers"]:
+            if not force:
+                logger.warning(
+                    f"Server '{server_name}' already exists in Claude config. "
+                    "Use `--force` to replace.",
+                    extra={"config_file": str(config_file)},
+                )
+                return False
+            logger.info(
+                f"Replacing existing server '{server_name}' in Claude config",
                 extra={"config_file": str(config_file)},
             )
-            return False
 
         # Build uv run command
-        args = []
-        if uv_directory:
-            args.extend(["--directory", str(uv_directory)])
-        args.extend(["run", str(file)])
+        args = ["run", "--with", "fastmcp"]
 
-        config["mcpServers"][name] = {
+        if with_editable:
+            args.extend(["--with-editable", str(with_editable)])
+
+        if with_packages:
+            for pkg in with_packages:
+                if pkg:
+                    args.extend(["--with", pkg])
+
+        # Convert file path to absolute before adding to command
+        # Split off any :object suffix first
+        if ":" in file_spec:
+            file_path, server_object = file_spec.rsplit(":", 1)
+            file_spec = f"{Path(file_path).resolve()}:{server_object}"
+        else:
+            file_spec = str(Path(file_spec).resolve())
+
+        # Add fastmcp run command
+        args.extend(["fastmcp", "run", file_spec])
+
+        config["mcpServers"][server_name] = {
             "command": "uv",
             "args": args,
         }
 
         config_file.write_text(json.dumps(config, indent=2))
         logger.info(
-            f"Added server '{name}' to Claude config",
+            f"Added server '{server_name}' to Claude config",
             extra={"config_file": str(config_file)},
         )
         return True

fastmcp/cli/cli.py

@@ -24,16 +24,25 @@ app = typer.Typer(
 
 
 def _build_uv_command(
-    file: Path,
-    uv_directory: Optional[Path] = None,
+    file_spec: str,
+    with_editable: Optional[Path] = None,
+    with_packages: Optional[list[str]] = None,
 ) -> list[str]:
-    """Build the uv run command."""
+    """Build the uv run command that runs a FastMCP server through fastmcp run."""
     cmd = ["uv"]
 
-    if uv_directory:
-        cmd.extend(["--directory", str(uv_directory)])
+    cmd.extend(["run", "--with", "fastmcp"])
 
-    cmd.extend(["run", str(file)])
+    if with_editable:
+        cmd.extend(["--with-editable", str(with_editable)])
+
+    if with_packages:
+        for pkg in with_packages:
+            if pkg:
+                cmd.extend(["--with", pkg])
+
+    # Add fastmcp run command
+    cmd.extend(["fastmcp", "run", file_spec])
     return cmd
 
 
@@ -81,7 +90,7 @@ def _import_server(file: Path, server_object: Optional[str] = None):
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
 
-    # If no object specified, try __main__ block
+    # If no object specified, try common server names
     if not server_object:
         # Look for the most common server object names
         for name in ["mcp", "server", "app"]:
@@ -89,7 +98,9 @@ def _import_server(file: Path, server_object: Optional[str] = None):
                 return getattr(module, name)
 
         logger.error(
-            f"No server object found in {file}. Please specify the object name with file:object syntax.",
+            f"No server object found in {file}. Please either:\n"
+            "1. Use a standard variable name (mcp, server, or app)\n"
+            "2. Specify the object name with file:object syntax",
             extra={"file": str(file)},
         )
         sys.exit(1)
@@ -137,17 +148,24 @@ def dev(
         ...,
         help="Python file to run, optionally with :object suffix",
     ),
-    uv_directory: Annotated[
+    with_editable: Annotated[
         Optional[Path],
         typer.Option(
-            "--uv-directory",
-            "-d",
-            help="Directory containing pyproject.toml (defaults to current directory)",
+            "--with-editable",
+            "-e",
+            help="Directory containing pyproject.toml to install in editable mode",
             exists=True,
             file_okay=False,
             resolve_path=True,
         ),
     ] = None,
+    with_packages: Annotated[
+        list[str],
+        typer.Option(
+            "--with",
+            help="Additional packages to install",
+        ),
+    ] = [],
 ) -> None:
     """Run a FastMCP server with the MCP Inspector."""
     file, server_object = _parse_file_path(file_spec)
@@ -157,12 +175,13 @@ def dev(
         extra={
             "file": str(file),
             "server_object": server_object,
-            "uv_directory": str(uv_directory) if uv_directory else None,
+            "with_editable": str(with_editable) if with_editable else None,
+            "with_packages": with_packages,
         },
     )
 
     try:
-        uv_cmd = _build_uv_command(file, uv_directory)
+        uv_cmd = _build_uv_command(file_spec, with_editable, with_packages)
         # Run the MCP Inspector command
         process = subprocess.run(
             ["npx", "@modelcontextprotocol/inspector"] + uv_cmd,
@@ -201,19 +220,24 @@ def run(
             help="Transport protocol to use (stdio or sse)",
         ),
     ] = None,
-    uv_directory: Annotated[
+    with_editable: Annotated[
         Optional[Path],
         typer.Option(
-            "--uv-directory",
-            "-d",
-            help="Directory containing pyproject.toml (defaults to current directory)",
+            "--with-editable",
+            "-e",
+            help="Directory containing pyproject.toml to install in editable mode",
             exists=True,
             file_okay=False,
             resolve_path=True,
         ),
     ] = None,
 ) -> None:
-    """Run a FastMCP server."""
+    """Run a FastMCP server.
+
+    The server can be specified in two ways:
+    1. Module approach: server.py - runs the module directly, expecting a server.run() call
+    2. Import approach: server.py:app - imports and runs the specified server object
+    """
     file, server_object = _parse_file_path(file_spec)
 
     logger.debug(
@@ -222,13 +246,11 @@ def run(
             "file": str(file),
             "server_object": server_object,
             "transport": transport,
-            "uv_directory": str(uv_directory) if uv_directory else None,
+            "with_editable": str(with_editable) if with_editable else None,
         },
     )
 
     try:
-        uv_cmd = _build_uv_command(file, uv_directory)
-
         # Import and get server object
         server = _import_server(file, server_object)
 
@@ -261,20 +283,35 @@ def install(
         typer.Option(
             "--name",
             "-n",
-            help="Custom name for the server (defaults to file name)",
+            help="Custom name for the server (defaults to server's name attribute or file name)",
         ),
     ] = None,
-    uv_directory: Annotated[
+    with_editable: Annotated[
         Optional[Path],
         typer.Option(
-            "--uv-directory",
-            "-d",
-            help="Directory containing pyproject.toml (defaults to current directory)",
+            "--with-editable",
+            "-e",
+            help="Directory containing pyproject.toml to install in editable mode",
             exists=True,
             file_okay=False,
             resolve_path=True,
         ),
     ] = None,
+    with_packages: Annotated[
+        list[str],
+        typer.Option(
+            "--with",
+            help="Additional packages to install",
+        ),
+    ] = [],
+    force: Annotated[
+        bool,
+        typer.Option(
+            "--force",
+            "-f",
+            help="Replace existing server if one exists with the same name",
+        ),
+    ] = False,
 ) -> None:
     """Install a FastMCP server in the Claude desktop app."""
     file, server_object = _parse_file_path(file_spec)
@@ -285,7 +322,9 @@ def install(
             "file": str(file),
             "server_name": server_name,
             "server_object": server_object,
-            "uv_directory": str(uv_directory) if uv_directory else None,
+            "with_editable": str(with_editable) if with_editable else None,
+            "with_packages": with_packages,
+            "force": force,
         },
     )
 
@@ -293,14 +332,27 @@ def install(
         logger.error("Claude app not found")
         sys.exit(1)
 
-    if claude.update_claude_config(file, server_name, uv_directory=uv_directory):
-        name = server_name or file.stem
+    # Try to import server to get its name, but fall back to file name if dependencies missing
+    name = server_name
+    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
+
+    if claude.update_claude_config(
+        file_spec,
+        name,
+        with_editable=with_editable,
+        with_packages=with_packages,
+        force=force,
+    ):
         print(f"Successfully installed {name} in Claude app")
     else:
-        name = server_name or file.stem
         print(f"Failed to install {name} in Claude app")
         sys.exit(1)
-
-
-if __name__ == "__main__":
-    app()

fastmcp/prompts/__init__.py

@@ -0,0 +1,4 @@
+from .base import Prompt
+from .manager import PromptManager
+
+__all__ = ["Prompt", "PromptManager"]

fastmcp/prompts/base.py

@@ -0,0 +1,149 @@
+"""Base classes for FastMCP prompts."""
+
+import json
+from typing import Any, Callable, Dict, Literal, Optional, Sequence, Union
+import inspect
+
+from pydantic import BaseModel, Field, TypeAdapter, field_validator, validate_call
+from mcp.types import TextContent, ImageContent, EmbeddedResource
+import pydantic_core
+
+
+class Message(BaseModel):
+    """Base class for all prompt messages."""
+
+    role: Literal["user", "assistant"]
+    content: Union[TextContent, ImageContent, EmbeddedResource]
+
+    def __init__(self, content, **kwargs):
+        super().__init__(content=content, **kwargs)
+
+    @field_validator("content", mode="before")
+    def validate_content(cls, v):
+        if isinstance(v, str):
+            return TextContent(type="text", text=v)
+        return v
+
+
+class UserMessage(Message):
+    """A message from the user."""
+
+    role: Literal["user"] = "user"
+
+
+class AssistantMessage(Message):
+    """A message from the assistant."""
+
+    role: Literal["assistant"] = "assistant"
+
+
+message_validator = TypeAdapter(Union[UserMessage, AssistantMessage])
+
+
+class PromptArgument(BaseModel):
+    """An argument that can be passed to a prompt."""
+
+    name: str = Field(description="Name of the argument")
+    description: str | None = Field(
+        None, description="Description of what the argument does"
+    )
+    required: bool = Field(
+        default=False, description="Whether the argument is required"
+    )
+
+
+class Prompt(BaseModel):
+    """A prompt template that can be rendered with parameters."""
+
+    name: str = Field(description="Name of the prompt")
+    description: str | None = Field(
+        None, description="Description of what the prompt does"
+    )
+    arguments: list[PromptArgument] | None = Field(
+        None, description="Arguments that can be passed to the prompt"
+    )
+    fn: Callable = Field(exclude=True)
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: Callable[..., Sequence[Message]],
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> "Prompt":
+        """Create a Prompt from a function."""
+        func_name = name or fn.__name__
+
+        if func_name == "<lambda>":
+            raise ValueError("You must provide a name for lambda functions")
+
+        # Get schema from TypeAdapter - will fail if function isn't properly typed
+        parameters = TypeAdapter(fn).json_schema()
+
+        # Convert parameters to PromptArguments
+        arguments = []
+        if "properties" in parameters:
+            for param_name, param in parameters["properties"].items():
+                required = param_name in parameters.get("required", [])
+                arguments.append(
+                    PromptArgument(
+                        name=param_name,
+                        description=param.get("description"),
+                        required=required,
+                    )
+                )
+
+        # ensure the arguments are properly cast
+        fn = validate_call(fn)
+
+        return cls(
+            name=func_name,
+            description=description or fn.__doc__ or "",
+            arguments=arguments,
+            fn=fn,
+        )
+
+    async def render(self, arguments: Optional[Dict[str, Any]] = None) -> list[Message]:
+        """Render the prompt with arguments."""
+        # Validate required arguments
+        if self.arguments:
+            required = {arg.name for arg in self.arguments if arg.required}
+            provided = set(arguments or {})
+            missing = required - provided
+            if missing:
+                raise ValueError(f"Missing required arguments: {missing}")
+
+        try:
+            # Call function and check if result is a coroutine
+            result = self.fn(**(arguments or {}))
+            if inspect.iscoroutine(result):
+                result = await result
+
+            # Validate messages
+            if not isinstance(result, (list, tuple)):
+                result = [result]
+
+            # Convert result to messages
+            messages = []
+            for msg in result:
+                try:
+                    if isinstance(msg, Message):
+                        messages.append(msg)
+                    elif isinstance(msg, dict):
+                        msg = message_validator.validate_python(msg)
+                        messages.append(msg)
+                    elif isinstance(msg, str):
+                        messages.append(
+                            UserMessage(content=TextContent(type="text", text=msg))
+                        )
+                    else:
+                        msg = json.dumps(pydantic_core.to_jsonable_python(msg))
+                        messages.append(Message(role="user", content=msg))
+                except Exception:
+                    raise ValueError(
+                        f"Could not convert prompt result to message: {msg}"
+                    )
+
+            return messages
+        except Exception as e:
+            raise ValueError(f"Error rendering prompt {self.name}: {e}")

fastmcp/prompts/manager.py

@@ -0,0 +1,50 @@
+"""Prompt management functionality."""
+
+from typing import Any, Dict, Optional
+
+from fastmcp.prompts.base import Message, Prompt
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class PromptManager:
+    """Manages FastMCP prompts."""
+
+    def __init__(self, warn_on_duplicate_prompts: bool = True):
+        self._prompts: Dict[str, Prompt] = {}
+        self.warn_on_duplicate_prompts = warn_on_duplicate_prompts
+
+    def get_prompt(self, name: str) -> Optional[Prompt]:
+        """Get prompt by name."""
+        return self._prompts.get(name)
+
+    def list_prompts(self) -> list[Prompt]:
+        """List all registered prompts."""
+        return list(self._prompts.values())
+
+    def add_prompt(
+        self,
+        prompt: Prompt,
+    ) -> Prompt:
+        """Add a prompt to the manager."""
+
+        # Check for duplicates
+        existing = self._prompts.get(prompt.name)
+        if existing:
+            if self.warn_on_duplicate_prompts:
+                logger.warning(f"Prompt already exists: {prompt.name}")
+            return existing
+
+        self._prompts[prompt.name] = prompt
+        return prompt
+
+    async def render_prompt(
+        self, name: str, arguments: Optional[Dict[str, Any]] = None
+    ) -> list[Message]:
+        """Render a prompt by name with arguments."""
+        prompt = self.get_prompt(name)
+        if not prompt:
+            raise ValueError(f"Unknown prompt: {name}")
+
+        return await prompt.render(arguments)

fastmcp/prompts/prompt_manager.py

@@ -0,0 +1,36 @@
+"""Prompt management functionality."""
+
+from typing import Dict, Optional
+
+
+from fastmcp.prompts.base import Prompt
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class PromptManager:
+    """Manages FastMCP prompts."""
+
+    def __init__(self, warn_on_duplicate_prompts: bool = True):
+        self._prompts: Dict[str, Prompt] = {}
+        self.warn_on_duplicate_prompts = warn_on_duplicate_prompts
+
+    def add_prompt(self, prompt: Prompt) -> Prompt:
+        """Add a prompt to the manager."""
+        logger.debug(f"Adding prompt: {prompt.name}")
+        existing = self._prompts.get(prompt.name)
+        if existing:
+            if self.warn_on_duplicate_prompts:
+                logger.warning(f"Prompt already exists: {prompt.name}")
+            return existing
+        self._prompts[prompt.name] = prompt
+        return prompt
+
+    def get_prompt(self, name: str) -> Optional[Prompt]:
+        """Get prompt by name."""
+        return self._prompts.get(name)
+
+    def list_prompts(self) -> list[Prompt]:
+        """List all registered prompts."""
+        return list(self._prompts.values())

fastmcp/resources/__init__.py

@@ -0,0 +1,23 @@
+from .base import Resource
+from .types import (
+    TextResource,
+    BinaryResource,
+    FunctionResource,
+    FileResource,
+    HttpResource,
+    DirectoryResource,
+)
+from .templates import ResourceTemplate
+from .resource_manager import ResourceManager
+
+__all__ = [
+    "Resource",
+    "TextResource",
+    "BinaryResource",
+    "FunctionResource",
+    "FileResource",
+    "HttpResource",
+    "DirectoryResource",
+    "ResourceTemplate",
+    "ResourceManager",
+]

fastmcp/resources/base.py

@@ -0,0 +1,63 @@
+"""Base classes and interfaces for FastMCP resources."""
+
+import abc
+from typing import Annotated, Union
+
+from pydantic import (
+    AnyUrl,
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+    Field,
+    FileUrl,
+    ValidationInfo,
+    field_validator,
+)
+from pydantic.networks import _BaseUrl  # TODO: remove this once pydantic is updated
+
+
+def maybe_cast_str_to_any_url(x) -> AnyUrl:
+    if isinstance(x, FileUrl):
+        return x
+    elif isinstance(x, AnyUrl):
+        return x
+    elif isinstance(x, str):
+        if x.startswith("file://"):
+            return FileUrl(x)
+        return AnyUrl(x)
+    raise ValueError(f"Expected str or AnyUrl, got {type(x)}")
+
+
+LaxAnyUrl = Annotated[_BaseUrl | str, BeforeValidator(maybe_cast_str_to_any_url)]
+
+
+class Resource(BaseModel, abc.ABC):
+    """Base class for all resources."""
+
+    model_config = ConfigDict(validate_default=True)
+
+    uri: LaxAnyUrl = Field(default=..., description="URI of the resource")
+    name: str | None = Field(description="Name of the resource", default=None)
+    description: str | None = Field(
+        description="Description of the resource", default=None
+    )
+    mime_type: str = Field(
+        default="text/plain",
+        description="MIME type of the resource content",
+        pattern=r"^[a-zA-Z0-9]+/[a-zA-Z0-9\-+.]+$",
+    )
+
+    @field_validator("name", mode="before")
+    @classmethod
+    def set_default_name(cls, name: str | None, info: ValidationInfo) -> str:
+        """Set default name from URI if not provided."""
+        if name:
+            return name
+        if uri := info.data.get("uri"):
+            return str(uri)
+        raise ValueError("Either name or uri must be provided")
+
+    @abc.abstractmethod
+    async def read(self) -> Union[str, bytes]:
+        """Read the resource content."""
+        pass