fastmcp 0.1.0__py3-none-any.whl

fastmcp/__init__.py

@@ -0,0 +1 @@
+from .server import FastMCP

fastmcp/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)

fastmcp/cli/__init__.py

@@ -0,0 +1,5 @@
+"""FastMCP CLI package."""
+
+from .cli import app
+
+__all__ = ["app"]

fastmcp/cli/claude.py

@@ -0,0 +1,88 @@
+"""Claude app integration utilities."""
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+from ..utilities.logging import get_logger
+
+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")
+    else:
+        return None
+
+    if path.exists():
+        return path
+    return None
+
+
+def update_claude_config(
+    file: Path,
+    server_name: Optional[str] = None,
+    *,
+    uv_directory: Optional[Path] = None,
+) -> 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
+    """
+    config_dir = get_claude_config_path()
+    if not config_dir:
+        return False
+
+    config_file = config_dir / "claude_desktop_config.json"
+    if not config_file.exists():
+        return False
+
+    try:
+        config = json.loads(config_file.read_text())
+        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",
+                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)])
+
+        config["mcpServers"][name] = {
+            "command": "uv",
+            "args": args,
+        }
+
+        config_file.write_text(json.dumps(config, indent=2))
+        logger.info(
+            f"Added server '{name}' to Claude config",
+            extra={"config_file": str(config_file)},
+        )
+        return True
+    except Exception as e:
+        logger.error(
+            "Failed to update Claude config",
+            extra={
+                "error": str(e),
+                "config_file": str(config_file),
+            },
+        )
+        return False

fastmcp/cli/cli.py

@@ -0,0 +1,306 @@
+"""FastMCP CLI tools."""
+
+import importlib.metadata
+import importlib.util
+import subprocess
+import sys
+from pathlib import Path
+from typing import Optional, Tuple
+
+import typer
+from typing_extensions import Annotated
+
+from ..utilities.logging import get_logger
+from . import claude
+
+logger = get_logger(__name__)
+
+app = typer.Typer(
+    name="fastmcp",
+    help="FastMCP development tools",
+    add_completion=False,
+    no_args_is_help=True,  # Show help if no args provided
+)
+
+
+def _build_uv_command(
+    file: Path,
+    uv_directory: Optional[Path] = None,
+) -> list[str]:
+    """Build the uv run command."""
+    cmd = ["uv"]
+
+    if uv_directory:
+        cmd.extend(["--directory", str(uv_directory)])
+
+    cmd.extend(["run", str(file)])
+    return cmd
+
+
+def _parse_file_path(file_spec: str) -> Tuple[Path, Optional[str]]:
+    """Parse a file path that may include a server object specification.
+
+    Args:
+        file_spec: Path to file, optionally with :object suffix
+
+    Returns:
+        Tuple of (file_path, server_object)
+    """
+    if ":" in file_spec:
+        file_str, server_object = file_spec.rsplit(":", 1)
+    else:
+        file_str, server_object = file_spec, None
+
+    file_path = Path(file_str).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)
+
+    return file_path, server_object
+
+
+def _import_server(file: Path, server_object: Optional[str] = None):
+    """Import a FastMCP server from a file.
+
+    Args:
+        file: Path to the file
+        server_object: Optional object name in format "module:object" or just "object"
+
+    Returns:
+        The server object
+    """
+    # Import the module
+    spec = importlib.util.spec_from_file_location("server_module", file)
+    if not spec or not spec.loader:
+        logger.error("Could not load module", extra={"file": str(file)})
+        sys.exit(1)
+
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    # If no object specified, try __main__ block
+    if not server_object:
+        # Look for the most common server object names
+        for name in ["mcp", "server", "app"]:
+            if hasattr(module, name):
+                return getattr(module, name)
+
+        logger.error(
+            f"No server object found in {file}. Please specify the object name with file:object syntax.",
+            extra={"file": str(file)},
+        )
+        sys.exit(1)
+
+    # Handle module:object syntax
+    if ":" in server_object:
+        module_name, object_name = server_object.split(":", 1)
+        try:
+            server_module = importlib.import_module(module_name)
+            server = getattr(server_module, object_name, None)
+        except ImportError:
+            logger.error(
+                f"Could not import module '{module_name}'",
+                extra={"file": str(file)},
+            )
+            sys.exit(1)
+    else:
+        # Just object name
+        server = getattr(module, server_object, None)
+
+    if server is None:
+        logger.error(
+            f"Server object '{server_object}' not found",
+            extra={"file": str(file)},
+        )
+        sys.exit(1)
+
+    return server
+
+
+@app.command()
+def version() -> None:
+    """Show the FastMCP version."""
+    try:
+        version = importlib.metadata.version("fastmcp")
+        print(f"FastMCP version {version}")
+    except importlib.metadata.PackageNotFoundError:
+        print("FastMCP version unknown (package not installed)")
+        sys.exit(1)
+
+
+@app.command()
+def dev(
+    file_spec: str = typer.Argument(
+        ...,
+        help="Python file to run, optionally with :object suffix",
+    ),
+    uv_directory: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--uv-directory",
+            "-d",
+            help="Directory containing pyproject.toml (defaults to current directory)",
+            exists=True,
+            file_okay=False,
+            resolve_path=True,
+        ),
+    ] = None,
+) -> None:
+    """Run a FastMCP server with the MCP Inspector."""
+    file, server_object = _parse_file_path(file_spec)
+
+    logger.debug(
+        "Starting dev server",
+        extra={
+            "file": str(file),
+            "server_object": server_object,
+            "uv_directory": str(uv_directory) if uv_directory else None,
+        },
+    )
+
+    try:
+        uv_cmd = _build_uv_command(file, uv_directory)
+        # Run the MCP Inspector command
+        process = subprocess.run(
+            ["npx", "@modelcontextprotocol/inspector"] + uv_cmd,
+            check=True,
+        )
+        sys.exit(process.returncode)
+    except subprocess.CalledProcessError as e:
+        logger.error(
+            "Dev server failed",
+            extra={
+                "file": str(file),
+                "error": str(e),
+                "returncode": e.returncode,
+            },
+        )
+        sys.exit(e.returncode)
+    except FileNotFoundError:
+        logger.error(
+            "npx not found. Please install Node.js and npm.",
+            extra={"file": str(file)},
+        )
+        sys.exit(1)
+
+
+@app.command()
+def run(
+    file_spec: str = typer.Argument(
+        ...,
+        help="Python file to run, optionally with :object suffix",
+    ),
+    transport: Annotated[
+        Optional[str],
+        typer.Option(
+            "--transport",
+            "-t",
+            help="Transport protocol to use (stdio or sse)",
+        ),
+    ] = None,
+    uv_directory: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--uv-directory",
+            "-d",
+            help="Directory containing pyproject.toml (defaults to current directory)",
+            exists=True,
+            file_okay=False,
+            resolve_path=True,
+        ),
+    ] = None,
+) -> None:
+    """Run a FastMCP server."""
+    file, server_object = _parse_file_path(file_spec)
+
+    logger.debug(
+        "Running server",
+        extra={
+            "file": str(file),
+            "server_object": server_object,
+            "transport": transport,
+            "uv_directory": str(uv_directory) if uv_directory else None,
+        },
+    )
+
+    try:
+        uv_cmd = _build_uv_command(file, uv_directory)
+
+        # Import and get server object
+        server = _import_server(file, server_object)
+
+        # Run the server
+        kwargs = {}
+        if transport:
+            kwargs["transport"] = transport
+
+        server.run(**kwargs)
+
+    except Exception as e:
+        logger.error(
+            "Failed to run server",
+            extra={
+                "file": str(file),
+                "error": str(e),
+            },
+        )
+        sys.exit(1)
+
+
+@app.command()
+def install(
+    file_spec: str = typer.Argument(
+        ...,
+        help="Python file to run, optionally with :object suffix",
+    ),
+    server_name: Annotated[
+        Optional[str],
+        typer.Option(
+            "--name",
+            "-n",
+            help="Custom name for the server (defaults to file name)",
+        ),
+    ] = None,
+    uv_directory: Annotated[
+        Optional[Path],
+        typer.Option(
+            "--uv-directory",
+            "-d",
+            help="Directory containing pyproject.toml (defaults to current directory)",
+            exists=True,
+            file_okay=False,
+            resolve_path=True,
+        ),
+    ] = None,
+) -> None:
+    """Install a FastMCP server in the Claude desktop app."""
+    file, server_object = _parse_file_path(file_spec)
+
+    logger.debug(
+        "Installing server",
+        extra={
+            "file": str(file),
+            "server_name": server_name,
+            "server_object": server_object,
+            "uv_directory": str(uv_directory) if uv_directory else None,
+        },
+    )
+
+    if not claude.get_claude_config_path():
+        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
+        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/cli.py

@@ -0,0 +1,6 @@
+"""FastMCP CLI tools."""
+
+from .cli.cli import app
+
+if __name__ == "__main__":
+    app()

fastmcp/exceptions.py

@@ -0,0 +1,17 @@
+"""Custom exceptions for FastMCP."""
+
+
+class FastMCPError(Exception):
+    """Base error for FastMCP."""
+
+
+class ValidationError(FastMCPError):
+    """Error in validating parameters or return values."""
+
+
+class ResourceError(FastMCPError):
+    """Error in resource operations."""
+
+
+class ToolError(FastMCPError):
+    """Error in tool operations."""

fastmcp/resources.py

@@ -0,0 +1,219 @@
+import pydantic.json
+
+import abc
+import asyncio
+import json
+from pathlib import Path
+from typing import Dict, Optional, Callable, Any, Union, Awaitable
+
+import httpx
+from pydantic import BaseModel, field_validator
+from pydantic.networks import _BaseUrl
+
+from .utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class Resource(BaseModel):
+    """Base class for all resources."""
+
+    uri: _BaseUrl
+    name: str
+    description: Optional[str] = None
+    mime_type: str = "text/plain"
+
+    @field_validator("name", mode="before")
+    @classmethod
+    def set_default_name(cls, name: str | None, info) -> str:
+        """Set default name from URI if not provided."""
+        if name is not None:
+            return name
+        # Extract everything after the protocol (e.g., "desktop" from "resource://desktop")
+        uri = info.data.get("uri")
+        if uri:
+            return str(uri).split("://", 1)[1]
+        raise ValueError("Either name or uri must be provided")
+
+    @abc.abstractmethod
+    async def read(self) -> str:
+        """Read the resource content."""
+        return ""
+
+
+class FunctionResource(Resource):
+    """A resource that is generated by a function call.
+
+    The function can be sync or async and must return a string
+    or another Resource.
+    """
+
+    func: Union[Callable[[], Any], Callable[[], Awaitable[Any]]]
+    is_async: bool = False
+
+    def __init__(self, **data):
+        super().__init__(**data)
+        self.is_async = asyncio.iscoroutinefunction(self.func)
+
+    async def read(self) -> str:
+        """Read the resource content by calling the function."""
+        try:
+            result = (
+                await self.func()
+                if self.is_async
+                else await asyncio.to_thread(self.func)
+            )
+
+            if isinstance(result, Resource):
+                return await result.read()
+            if isinstance(result, bytes):
+                return result.decode()
+            if not isinstance(result, str):
+                try:
+                    return json.dumps(result, default=pydantic.json.pydantic_encoder)
+                except json.JSONDecodeError:
+                    return str(result)
+            return result
+        except Exception as e:
+            raise ValueError(f"Error calling function {self.func.__name__}: {e}")
+
+
+class FileResource(Resource):
+    """A file resource."""
+
+    path: Path
+
+    @field_validator("path")
+    @classmethod
+    def validate_absolute_path(cls, path: Path) -> Path:
+        """Ensure path is absolute."""
+        if not path.is_absolute():
+            raise ValueError(f"Path must be absolute: {path}")
+        return path
+
+    async def read(self) -> str:
+        """Read the file content."""
+        try:
+            return await asyncio.to_thread(self.path.read_text)
+        except FileNotFoundError:
+            raise FileNotFoundError(f"File not found: {self.path}")
+        except PermissionError:
+            raise PermissionError(f"Permission denied: {self.path}")
+        except Exception as e:
+            raise ValueError(f"Error reading file {self.path}: {e}")
+
+
+class HttpResource(Resource):
+    """An HTTP resource."""
+
+    url: str
+    headers: Optional[Dict[str, str]] = None
+
+    async def read(self) -> str:
+        """Read the HTTP resource content."""
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.get(self.url, headers=self.headers)
+                response.raise_for_status()
+                return response.text
+        except httpx.HTTPStatusError as e:
+            raise ValueError(f"HTTP error {e.response.status_code}: {e}")
+        except httpx.RequestError as e:
+            raise ValueError(f"Request failed: {e}")
+
+
+class DirectoryResource(Resource):
+    """A directory resource."""
+
+    path: Path
+    recursive: bool = False
+    pattern: Optional[str] = None
+    mime_type: str = "application/json"
+
+    @field_validator("path")
+    @classmethod
+    def validate_absolute_path(cls, path: Path) -> Path:
+        """Ensure path is absolute."""
+        if not path.is_absolute():
+            raise ValueError(f"Path must be absolute: {path}")
+        return path
+
+    def list_files(self) -> list[Path]:
+        """List files in the directory."""
+        if not self.path.exists():
+            raise FileNotFoundError(f"Directory not found: {self.path}")
+        if not self.path.is_dir():
+            raise NotADirectoryError(f"Not a directory: {self.path}")
+
+        try:
+            if self.pattern:
+                return (
+                    list(self.path.glob(self.pattern))
+                    if not self.recursive
+                    else list(self.path.rglob(self.pattern))
+                )
+            return (
+                list(self.path.glob("*"))
+                if not self.recursive
+                else list(self.path.rglob("*"))
+            )
+        except Exception as e:
+            raise ValueError(f"Error listing directory {self.path}: {e}")
+
+    async def read(self) -> str:
+        """Read the directory listing."""
+        try:
+            files = await asyncio.to_thread(self.list_files)
+            file_list = [str(f.relative_to(self.path)) for f in files if f.is_file()]
+            return json.dumps({"files": file_list}, indent=2)
+        except Exception as e:
+            raise ValueError(f"Error reading directory {self.path}: {e}")
+
+
+class ResourceManager:
+    """Manages FastMCP resources."""
+
+    def __init__(self, warn_on_duplicate_resources: bool = True):
+        self._resources: Dict[str, Resource] = {}
+        self.warn_on_duplicate_resources = warn_on_duplicate_resources
+
+    def get_resource(self, uri: Union[_BaseUrl, str]) -> Optional[Resource]:
+        """Get resource by URI."""
+        uri = str(uri)
+        logger.debug("Getting resource", extra={"uri": uri})
+
+        if resource := self._resources.get(uri):
+            return resource
+
+        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 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

fastmcp/server.py

@@ -0,0 +1,275 @@
+"""FastMCP - A more ergonomic interface for MCP servers."""
+
+import asyncio
+import base64
+import functools
+import json
+from typing import Any, Callable, Optional, Sequence, Union, Literal
+
+from mcp.server import Server as MCPServer
+from mcp.server.stdio import stdio_server
+from mcp.server.sse import SseServerTransport
+from mcp.types import Resource as MCPResource
+from mcp.types import Tool, TextContent, ImageContent, EmbeddedResource
+from pydantic import BaseModel
+from pydantic_settings import BaseSettings
+from pydantic.networks import _BaseUrl
+from .exceptions import ResourceError
+from .resources import Resource, FunctionResource, ResourceManager
+from .tools import ToolManager
+from .utilities.logging import get_logger, configure_logging
+
+logger = get_logger(__name__)
+
+
+class Settings(BaseSettings):
+    """FastMCP server settings.
+
+    All settings can be configured via environment variables with the prefix FASTMCP_.
+    For example, FASTMCP_DEBUG=true will set debug=True.
+    """
+
+    model_config: dict = dict(env_prefix="FASTMCP_")
+
+    # Server settings
+    debug: bool = False
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "INFO"
+
+    # HTTP settings
+    host: str = "0.0.0.0"
+    port: int = 8000
+
+    # resource settings
+    warn_on_duplicate_resources: bool = True
+
+    # tool settings
+    warn_on_duplicate_tools: bool = True
+
+
+class FastMCP:
+    def __init__(self, name=None, **settings: Optional[Settings]):
+        self.settings = Settings(**settings)
+        self._mcp_server = MCPServer(name=name or "FastMCP")
+        self._tool_manager = ToolManager(
+            warn_on_duplicate_tools=self.settings.warn_on_duplicate_tools
+        )
+        self._resource_manager = ResourceManager(
+            warn_on_duplicate_resources=self.settings.warn_on_duplicate_resources
+        )
+
+        # Set up MCP protocol handlers
+        self._setup_handlers()
+
+        # Configure logging
+        configure_logging(self.settings.log_level)
+
+    @property
+    def name(self) -> str:
+        return self._mcp_server.name
+
+    def run(self, transport: Literal["stdio", "sse"] = "stdio") -> None:
+        """Run the FastMCP server. Note this is a synchronous function.
+
+        Args:
+            transport: Transport protocol to use ("stdio" or "sse")
+        """
+        if transport == "stdio":
+            asyncio.run(self.run_stdio_async())
+        elif transport == "sse":
+            asyncio.run(self.run_sse_async())
+        else:
+            raise ValueError(f"Unknown transport: {transport}")
+
+    def _setup_handlers(self) -> None:
+        """Set up core MCP protocol handlers."""
+        self._mcp_server.list_tools()(self.list_tools)
+        self._mcp_server.call_tool()(self.call_tool)
+        self._mcp_server.list_resources()(self.list_resources)
+        self._mcp_server.read_resource()(self.read_resource)
+
+    async def list_tools(self) -> list[Tool]:
+        """List all available tools."""
+        tools = self._tool_manager.list_tools()
+        return [
+            Tool(
+                name=info.name,
+                description=info.description,
+                inputSchema=info.parameters,
+            )
+            for info in tools
+        ]
+
+    async def call_tool(
+        self, name: str, arguments: dict
+    ) -> Sequence[Union[TextContent, ImageContent, EmbeddedResource]]:
+        """Call a tool by name with arguments."""
+        result = await self._tool_manager.call_tool(name, arguments)
+        return [self._convert_to_content(result)]
+
+    async def list_resources(self) -> list[MCPResource]:
+        """List all available resources."""
+        resources = self._resource_manager.list_resources()
+        return [
+            MCPResource(
+                uri=resource.uri,
+                name=resource.name,
+                description=resource.description,
+                mimeType=resource.mime_type,
+            )
+            for resource in resources
+        ]
+
+    async def read_resource(self, uri: _BaseUrl) -> Union[str, bytes]:
+        """Read a resource by URI."""
+        resource = self._resource_manager.get_resource(uri)
+        if not resource:
+            raise ResourceError(f"Unknown resource: {uri}")
+
+        try:
+            return await resource.read()
+        except Exception as e:
+            logger.error(f"Error reading resource {uri}: {e}")
+            raise ResourceError(str(e))
+
+    def _convert_to_content(
+        self, value: Any
+    ) -> Union[TextContent, ImageContent, EmbeddedResource]:
+        """Convert Python values to MCP content types."""
+        if isinstance(value, (dict, list)):
+            return TextContent(type="text", text=json.dumps(value, indent=2))
+        if isinstance(value, str):
+            return TextContent(type="text", text=value)
+        if isinstance(value, bytes):
+            return ImageContent(
+                type="image",
+                data=base64.b64encode(value).decode(),
+                mimeType="application/octet-stream",
+            )
+        if isinstance(value, BaseModel):
+            return TextContent(type="text", text=value.model_dump_json(indent=2))
+        return TextContent(type="text", text=str(value))
+
+    def add_tool(
+        self,
+        func: Callable,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> None:
+        """Add a tool to the server."""
+        self._tool_manager.add_tool(func, name=name, description=description)
+
+    def tool(
+        self, name: Optional[str] = None, description: Optional[str] = None
+    ) -> Callable:
+        """Decorator to register a tool."""
+        # Check if user passed function directly instead of calling decorator
+        if callable(name):
+            raise TypeError(
+                "The @tool decorator was used incorrectly. "
+                "Did you forget to call it? Use @tool() instead of @tool"
+            )
+
+        def decorator(func: Callable) -> Callable:
+            self.add_tool(func, name=name, description=description)
+            return func
+
+        return decorator
+
+    def add_resource(self, resource: Resource) -> None:
+        """Add a resource to the server.
+
+        Args:
+            resource: A Resource instance to add
+        """
+        self._resource_manager.add_resource(resource)
+
+    def resource(
+        self,
+        uri: str,
+        *,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        mime_type: Optional[str] = None,
+    ) -> Callable:
+        """Decorator to register a function as a resource.
+
+        The function will be called when the resource is read to generate its content.
+
+        Args:
+            uri: URI for the resource (e.g. "resource://my-resource")
+            description: Optional description of the resource
+            mime_type: Optional MIME type for the resource
+
+        Example:
+            @server.resource("resource://my-resource")
+            def get_data() -> str:
+                return "Hello, world!"
+        """
+        # Check if user passed function directly instead of calling decorator
+        if callable(uri):
+            raise TypeError(
+                "The @resource decorator was used incorrectly. "
+                "Did you forget to call it? Use @resource('uri') instead of @resource"
+            )
+
+        def decorator(func: Callable) -> Callable:
+            @functools.wraps(func)
+            def wrapper() -> Any:
+                return func()
+
+            resource = FunctionResource(
+                uri=uri,
+                name=name,
+                description=description,
+                mime_type=mime_type or "text/plain",
+                func=wrapper,
+            )
+            self.add_resource(resource)
+            return wrapper
+
+        return decorator
+
+    async def run_stdio_async(self) -> None:
+        """Run the server using stdio transport."""
+        async with stdio_server() as (read_stream, write_stream):
+            await self._mcp_server.run(
+                read_stream,
+                write_stream,
+                self._mcp_server.create_initialization_options(),
+            )
+
+    async def run_sse_async(self) -> None:
+        """Run the server using SSE transport."""
+        from starlette.applications import Starlette
+        from starlette.routing import Route
+        import uvicorn
+
+        sse = SseServerTransport("/messages")
+
+        async def handle_sse(request):
+            async with sse.connect_sse(
+                request.scope, request.receive, request._send
+            ) as streams:
+                await self._mcp_server.run(
+                    streams[0],
+                    streams[1],
+                    self._mcp_server.create_initialization_options(),
+                )
+
+        async def handle_messages(request):
+            await sse.handle_post_message(request.scope, request.receive, request._send)
+
+        starlette_app = Starlette(
+            debug=self.settings.debug,
+            routes=[
+                Route("/sse", endpoint=handle_sse),
+                Route("/messages", endpoint=handle_messages, methods=["POST"]),
+            ],
+        )
+
+        uvicorn.run(
+            starlette_app,
+            host=self.settings.host,
+            port=self.settings.port,
+            log_level=self.settings.log_level,
+        )

fastmcp/tools.py

@@ -0,0 +1,101 @@
+"""Tool management for FastMCP."""
+
+import inspect
+from typing import Any, Callable, Dict, Optional
+
+from pydantic import BaseModel, Field, TypeAdapter, validate_call
+
+from .exceptions import ToolError
+from .utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class Tool(BaseModel):
+    """Internal tool registration info."""
+
+    func: Callable = Field(exclude=True)
+    name: str = Field(description="Name of the tool")
+    description: str = Field(description="Description of what the tool does")
+    parameters: dict = Field(description="JSON schema for tool parameters")
+    is_async: bool = Field(description="Whether the tool is async")
+
+    @classmethod
+    def from_function(
+        cls,
+        func: Callable,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> "Tool":
+        """Create a Tool from a function."""
+        func_name = name or func.__name__
+
+        if func_name == "<lambda>":
+            raise ValueError("You must provide a name for lambda functions")
+
+        func_doc = description or func.__doc__ or ""
+        is_async = inspect.iscoroutinefunction(func)
+
+        # Get schema from TypeAdapter - will fail if function isn't properly typed
+        parameters = TypeAdapter(func).json_schema()
+
+        # ensure the arguments are properly cast
+        func = validate_call(func)
+
+        return cls(
+            func=func,
+            name=func_name,
+            description=func_doc,
+            parameters=parameters,
+            is_async=is_async,
+        )
+
+    async def run(self, arguments: dict) -> Any:
+        """Run the tool with arguments."""
+        try:
+            # Call function with proper async handling
+            if self.is_async:
+                return await self.func(**arguments)
+            return self.func(**arguments)
+        except Exception as e:
+            raise ToolError(f"Error executing tool {self.name}: {e}") from e
+
+
+class ToolManager:
+    """Manages FastMCP tools."""
+
+    def __init__(self, warn_on_duplicate_tools: bool = True):
+        self._tools: Dict[str, Tool] = {}
+        self.warn_on_duplicate_tools = warn_on_duplicate_tools
+
+    def get_tool(self, name: str) -> Optional[Tool]:
+        """Get tool by name."""
+        return self._tools.get(name)
+
+    def list_tools(self) -> list[Tool]:
+        """List all registered tools."""
+        return list(self._tools.values())
+
+    def add_tool(
+        self,
+        func: Callable,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> Tool:
+        """Add a tool to the server."""
+        tool = Tool.from_function(func, name=name, description=description)
+        existing = self._tools.get(tool.name)
+        if existing:
+            if self.warn_on_duplicate_tools:
+                logger.warning(f"Tool already exists: {tool.name}")
+            return existing
+        self._tools[tool.name] = tool
+        return tool
+
+    async def call_tool(self, name: str, arguments: dict) -> Any:
+        """Call a tool by name with arguments."""
+        tool = self.get_tool(name)
+        if not tool:
+            raise ToolError(f"Unknown tool: {name}")
+
+        return await tool.run(arguments)

fastmcp/utilities/__init__.py

@@ -0,0 +1 @@
+"""FastMCP utility modules."""

fastmcp/utilities/logging.py

@@ -0,0 +1,30 @@
+"""Logging utilities for FastMCP."""
+
+import logging
+from typing import Literal
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Get a logger nested under FastMCP namespace.
+
+    Args:
+        name: The name of the logger, which will be prefixed with 'FastMCP.'
+
+    Returns:
+        A configured logger instance
+    """
+    return logging.getLogger(f"FastMCP.{name}")
+
+
+def configure_logging(
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = "INFO",
+) -> None:
+    """Configure logging for FastMCP.
+
+    Args:
+        level: The log level to use
+    """
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )

fastmcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.1
+Name: fastmcp
+Version: 0.1.0
+Summary: A more ergonomic interface for MCP servers
+Author: Jeremiah Lowin
+License: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic-settings>=2.6.1
+Requires-Dist: pydantic>=2.5.3
+Requires-Dist: typer>=0.9.0
+
+# FastMCP
+
+> **Note**: This is experimental software. The Model Context Protocol itself is only a few days old and the specification is still evolving.
+
+A fast, pythonic way to build Model Context Protocol (MCP) servers.
+
+The Model Context Protocol is an extremely powerful way to give LLMs access to tools and resources. However, building MCP servers can be difficult and cumbersome. FastMCP provides a simple, intuitive interface for creating MCP servers in Python.
+
+## Installation
+
+MCP servers require you to use [uv](https://github.com/astral-sh/uv) as your dependency manager.
+
+
+Install uv with brew:
+```bash
+brew install uv
+```
+*(Editor's note: I was unable to get MCP servers working unless uv was installed with brew.)*
+
+Install FastMCP:
+```bash
+uv pip install fastmcp
+```
+
+
+
+## Quick Start
+
+Here's a simple example that exposes your desktop directory as a resource and provides a basic addition tool:
+
+```python
+from pathlib import Path
+from fastmcp import FastMCP
+
+# Create server
+mcp = FastMCP("Demo")
+
+@mcp.resource("dir://desktop")
+def desktop() -> list[str]:
+    """List the files in the user's desktop"""
+    desktop = Path.home() / "Desktop"
+    return [str(f) for f in desktop.iterdir()]
+
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+if __name__ == "__main__":
+    mcp.run()
+```
+
+## Features
+
+### Resources
+
+Resources are data sources that can be accessed by the LLM. They can be files, directories, or any other data source. Resources are defined using the `@resource` decorator:
+
+```python
+@mcp.resource("file://config.json")
+def get_config() -> str:
+    """Read the config file"""
+    return Path("config.json").read_text()
+```
+
+### Tools
+
+Tools are functions that can be called by the LLM. They are defined using the `@tool` decorator:
+
+```python
+@mcp.tool()
+def calculate(x: int, y: int) -> int:
+    """Perform a calculation"""
+    return x + y
+```
+
+## Development
+
+### Running the Dev Inspector
+
+FastMCP includes a development server with the MCP Inspector for testing your server:
+
+```bash
+fastmcp dev your_server.py
+```
+
+### Installing in Claude
+
+To use your server with Claude Desktop:
+
+```bash
+fastmcp install your_server.py --name "My Server"
+```
+
+
+## Configuration
+
+FastMCP can be configured via environment variables with the prefix `FASTMCP_`:
+
+- `FASTMCP_DEBUG`: Enable debug mode
+- `FASTMCP_LOG_LEVEL`: Set logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+- `FASTMCP_HOST`: HTTP server host (default: 0.0.0.0)
+- `FASTMCP_PORT`: HTTP server port (default: 8000)
+
+## License
+
+Apache 2.0

fastmcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+fastmcp/__init__.py,sha256=r_Qr4WYOFDNF1SSkJY9c3L3ZasYVKB7_U7EM31D5yfE,27
+fastmcp/_version.py,sha256=IMl2Pr_Sy4LVRKy_Sm4CdwUl1Gryous6ncL96EMYsnM,411
+fastmcp/cli.py,sha256=RjtnF_4ApkIjxWfQlRmshb03icP6_nlNVV0LKnZGA5w,89
+fastmcp/exceptions.py,sha256=K0rCgXsUVlws39hz98Tb4BBf_BzIql_zXFZgqbkNTiE,348
+fastmcp/resources.py,sha256=Y1VwYEU7xBl0brHNZarBAgFmDdOZf4Q7xdbYxK7osnU,7065
+fastmcp/server.py,sha256=oDIid6XLXhqUNVliMw2x_SN2QC0BEcjSDAdi3YRRWeM,9311
+fastmcp/tools.py,sha256=EAkST81hTkMch7IlEGl4WC7npIDjGICLMEaXjPbttSo,3210
+fastmcp/cli/__init__.py,sha256=RUaBw4rNUJ7CjHrzVazB2jl60E6KA0Wo0x4OqHByL6c,68
+fastmcp/cli/claude.py,sha256=_kkDTlFdqkhl1GElVWtCd15txyw1liTYpmBVl8CA2VE,2458
+fastmcp/cli/cli.py,sha256=4Ld9ohDmJMMaveDpe_Wm4RtlnFyLeKaU-4tPhX-CQRA,8276
+fastmcp/utilities/__init__.py,sha256=-imJ8S-rXmbXMWeDamldP-dHDqAPg_wwmPVz-LNX14E,31
+fastmcp/utilities/logging.py,sha256=t2w5bwtrkxHxioWSy5vY8esxLQxyxN8tfFZ1FI3Cb6E,704
+fastmcp-0.1.0.dist-info/METADATA,sha256=3oRrtc8oV24OH6GIjE0bxDBojjDpU95x_T8M1O2F5XM,2932
+fastmcp-0.1.0.dist-info/WHEEL,sha256=PZUExdf71Ui_so67QXpySuHtCi3-J3wvF4ORK6k_S8U,91
+fastmcp-0.1.0.dist-info/entry_points.txt,sha256=ff8bMtKX1JvXyurMibAacMSKbJEPmac9ffAKU9mLnM8,44
+fastmcp-0.1.0.dist-info/top_level.txt,sha256=9NvhdRmSJxxf5iTz58rYyea0DtTsKgvGQHMRZaa7NN4,8
+fastmcp-0.1.0.dist-info/RECORD,,

fastmcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.6.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fastmcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fastmcp = fastmcp.cli:app

fastmcp-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fastmcp