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

fastmcp/__init__.py

@@ -1,2 +1,8 @@
-from .server import FastMCP
-from .tools import Image
+"""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,8 +25,8 @@ def get_claude_config_path() -> Path | None:
 
 
 def update_claude_config(
-    file: Path,
-    server_name: Optional[str] = None,
+    file_spec: str,
+    server_name: str,
     *,
     with_editable: Optional[Path] = None,
     with_packages: Optional[list[str]] = None,
@@ -35,9 +35,8 @@ def update_claude_config(
     """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
+        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
@@ -55,46 +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"]:
+        if server_name in config["mcpServers"]:
             if not force:
                 logger.warning(
-                    f"Server '{name}' already exists in Claude config. "
+                    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 '{name}' in Claude config",
+                f"Replacing existing server '{server_name}' in Claude config",
                 extra={"config_file": str(config_file)},
             )
 
         # Build uv run command
-        args = ["run"]
+        args = ["run", "--with", "fastmcp"]
 
         if with_editable:
             args.extend(["--with-editable", str(with_editable)])
 
-        # Always include fastmcp
-        args.extend(["--with", "fastmcp"])
-
-        # Add additional packages
         if with_packages:
             for pkg in with_packages:
                 if pkg:
                     args.extend(["--with", pkg])
 
-        args.append(str(file))
+        # 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"][name] = {
+        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,11 +24,11 @@ app = typer.Typer(
 
 
 def _build_uv_command(
-    file: Path,
+    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"]
 
     cmd.extend(["run", "--with", "fastmcp"])
@@ -41,7 +41,8 @@ def _build_uv_command(
             if pkg:
                 cmd.extend(["--with", pkg])
 
-    cmd.append(str(file))
+    # Add fastmcp run command
+    cmd.extend(["fastmcp", "run", file_spec])
     return cmd
 
 
@@ -89,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"]:
@@ -97,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)
@@ -178,7 +181,7 @@ def dev(
     )
 
     try:
-        uv_cmd = _build_uv_command(file, with_editable, with_packages)
+        uv_cmd = _build_uv_command(file_spec, with_editable, with_packages)
         # Run the MCP Inspector command
         process = subprocess.run(
             ["npx", "@modelcontextprotocol/inspector"] + uv_cmd,
@@ -229,7 +232,12 @@ def run(
         ),
     ] = 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(
@@ -338,7 +346,7 @@ def install(
             name = file.stem
 
     if claude.update_claude_config(
-        file,
+        file_spec,
         name,
         with_editable=with_editable,
         with_packages=with_packages,
@@ -348,7 +356,3 @@ def install(
     else:
         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

fastmcp/resources/resource_manager.py

@@ -0,0 +1,94 @@
+"""Resource manager functionality."""
+
+from typing import Callable, Dict, Optional, Union
+
+from pydantic import AnyUrl
+
+from fastmcp.resources.base import Resource
+from fastmcp.resources.templates import ResourceTemplate
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class ResourceManager:
+    """Manages FastMCP resources."""
+
+    def __init__(self, warn_on_duplicate_resources: bool = True):
+        self._resources: Dict[str, Resource] = {}
+        self._templates: Dict[str, ResourceTemplate] = {}
+        self.warn_on_duplicate_resources = warn_on_duplicate_resources
+
+    def add_resource(self, resource: Resource) -> Resource:
+        """Add a resource to the manager.
+
+        Args:
+            resource: A Resource instance to add
+
+        Returns:
+            The added resource. If a resource with the same URI already exists,
+            returns the existing resource.
+        """
+        logger.debug(
+            "Adding resource",
+            extra={
+                "uri": resource.uri,
+                "type": type(resource).__name__,
+                "name": resource.name,
+            },
+        )
+        existing = self._resources.get(str(resource.uri))
+        if existing:
+            if self.warn_on_duplicate_resources:
+                logger.warning(f"Resource already exists: {resource.uri}")
+            return existing
+        self._resources[str(resource.uri)] = resource
+        return resource
+
+    def add_template(
+        self,
+        fn: Callable,
+        uri_template: str,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        mime_type: Optional[str] = None,
+    ) -> ResourceTemplate:
+        """Add a template from a function."""
+        template = ResourceTemplate.from_function(
+            fn,
+            uri_template=uri_template,
+            name=name,
+            description=description,
+            mime_type=mime_type,
+        )
+        self._templates[template.uri_template] = template
+        return template
+
+    async def get_resource(self, uri: Union[AnyUrl, str]) -> Optional[Resource]:
+        """Get resource by URI, checking concrete resources first, then templates."""
+        uri_str = str(uri)
+        logger.debug("Getting resource", extra={"uri": uri_str})
+
+        # First check concrete resources
+        if resource := self._resources.get(uri_str):
+            return resource
+
+        # Then check templates
+        for template in self._templates.values():
+            if params := template.matches(uri_str):
+                try:
+                    return await template.create_resource(uri_str, params)
+                except Exception as e:
+                    raise ValueError(f"Error creating resource from template: {e}")
+
+        raise ValueError(f"Unknown resource: {uri}")
+
+    def list_resources(self) -> list[Resource]:
+        """List all registered resources."""
+        logger.debug("Listing resources", extra={"count": len(self._resources)})
+        return list(self._resources.values())
+
+    def list_templates(self) -> list[ResourceTemplate]:
+        """List all registered templates."""
+        logger.debug("Listing templates", extra={"count": len(self._templates)})
+        return list(self._templates.values())