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

fastmcp/tools/__init__.py

@@ -0,0 +1,4 @@
+from .base import Tool
+from .tool_manager import ToolManager
+
+__all__ = ["Tool", "ToolManager"]

fastmcp/tools/base.py

@@ -0,0 +1,79 @@
+import fastmcp
+from fastmcp.exceptions import ToolError
+
+
+from pydantic import BaseModel, Field, TypeAdapter, validate_call
+
+
+import inspect
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+if TYPE_CHECKING:
+    from fastmcp.server import Context
+
+
+class Tool(BaseModel):
+    """Internal tool registration info."""
+
+    fn: 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")
+    context_kwarg: Optional[str] = Field(
+        None, description="Name of the kwarg that should receive context"
+    )
+
+    @classmethod
+    def from_function(
+        cls,
+        fn: Callable,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        context_kwarg: Optional[str] = None,
+    ) -> "Tool":
+        """Create a Tool from a function."""
+        func_name = name or fn.__name__
+
+        if func_name == "<lambda>":
+            raise ValueError("You must provide a name for lambda functions")
+
+        func_doc = description or fn.__doc__ or ""
+        is_async = inspect.iscoroutinefunction(fn)
+
+        # Get schema from TypeAdapter - will fail if function isn't properly typed
+        parameters = TypeAdapter(fn).json_schema()
+
+        # Find context parameter if it exists
+        if context_kwarg is None:
+            sig = inspect.signature(fn)
+            for param_name, param in sig.parameters.items():
+                if param.annotation is fastmcp.Context:
+                    context_kwarg = param_name
+                    break
+
+        # ensure the arguments are properly cast
+        fn = validate_call(fn)
+
+        return cls(
+            fn=fn,
+            name=func_name,
+            description=func_doc,
+            parameters=parameters,
+            is_async=is_async,
+            context_kwarg=context_kwarg,
+        )
+
+    async def run(self, arguments: dict, context: Optional["Context"] = None) -> Any:
+        """Run the tool with arguments."""
+        try:
+            # Inject context if needed
+            if self.context_kwarg:
+                arguments[self.context_kwarg] = context
+
+            # Call function with proper async handling
+            if self.is_async:
+                return await self.fn(**arguments)
+            return self.fn(**arguments)
+        except Exception as e:
+            raise ToolError(f"Error executing tool {self.name}: {e}") from e

fastmcp/tools/tool_manager.py

@@ -0,0 +1,55 @@
+from fastmcp.exceptions import ToolError
+
+from fastmcp.tools.base import Tool
+
+
+from typing import Any, Callable, Dict, Optional, TYPE_CHECKING
+
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from fastmcp.server import Context
+
+logger = get_logger(__name__)
+
+
+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,
+        fn: Callable,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+    ) -> Tool:
+        """Add a tool to the server."""
+        tool = Tool.from_function(fn, 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, context: Optional["Context"] = None
+    ) -> 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, context=context)

fastmcp/utilities/types.py

@@ -0,0 +1,53 @@
+"""Common types used across FastMCP."""
+
+import base64
+from pathlib import Path
+from typing import Optional, Union
+
+from mcp.types import ImageContent
+
+
+class Image:
+    """Helper class for returning images from tools."""
+
+    def __init__(
+        self,
+        path: Optional[Union[str, Path]] = None,
+        data: Optional[bytes] = None,
+        format: Optional[str] = None,
+    ):
+        if path is None and data is None:
+            raise ValueError("Either path or data must be provided")
+        if path is not None and data is not None:
+            raise ValueError("Only one of path or data can be provided")
+
+        self.path = Path(path) if path else None
+        self.data = data
+        self._format = format
+        self._mime_type = self._get_mime_type()
+
+    def _get_mime_type(self) -> str:
+        """Get MIME type from format or guess from file extension."""
+        if self._format:
+            return f"image/{self._format.lower()}"
+
+        if self.path:
+            suffix = self.path.suffix.lower()
+            return {
+                ".png": "image/png",
+                ".jpg": "image/jpeg",
+                ".jpeg": "image/jpeg",
+                ".gif": "image/gif",
+                ".webp": "image/webp",
+            }.get(suffix, "application/octet-stream")
+        return "image/png"  # default for raw binary data
+
+    def to_image_content(self) -> ImageContent:
+        """Convert to MCP ImageContent."""
+        if self.path:
+            with open(self.path, "rb") as f:
+                data = base64.b64encode(f.read()).decode()
+        else:
+            data = base64.b64encode(self.data).decode()
+
+        return ImageContent(type="image", data=data, mimeType=self._mime_type)

fastmcp-0.3.0.dist-info/METADATA

@@ -0,0 +1,385 @@
+Metadata-Version: 2.3
+Name: fastmcp
+Version: 0.3.0
+Summary: A more ergonomic interface for MCP servers
+Author: Jeremiah Lowin
+License: Apache-2.0
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: mcp<2.0.0,>=1.0.0
+Requires-Dist: pydantic-settings>=2.6.1
+Requires-Dist: pydantic<3.0.0,>=2.5.3
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: copychat>=0.5.2; extra == 'dev'
+Requires-Dist: ipython>=8.12.3; extra == 'dev'
+Requires-Dist: pdbpp>=0.10.3; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.5; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.6.1; extra == 'dev'
+Requires-Dist: pytest>=8.3.3; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<!-- omit in toc -->
+# FastMCP 
+
+<div align="center">
+
+[![PyPI - Version](https://img.shields.io/pypi/v/fastmcp.svg)](https://pypi.org/project/fastmcp)
+[![Tests](https://github.com/jlowin/fastmcp/actions/workflows/run-tests.yml/badge.svg)](https://github.com/jlowin/fastmcp/actions/workflows/run-tests.yml)
+[![License](https://img.shields.io/github/license/jlowin/fastmcp.svg)](https://github.com/jlowin/fastmcp/blob/main/LICENSE)
+
+</div>
+
+FastMCP is a high-level, intuitive framework for building [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers with Python. While MCP is a powerful protocol that enables LLMs to interact with local data and tools in a secure, standardized way, the specification can be cumbersome to implement directly. FastMCP lets you build fully compliant MCP servers in the most Pythonic way possible - in many cases, simply decorating a function is all that's required.
+
+🚧 *Note: FastMCP is under active development, as is the low-level MCP Python SDK* 🏗️
+
+Key features:
+* **Intuitive**: Designed to feel familiar to Python developers, with powerful type hints and editor support
+* **Simple**: Build compliant MCP servers with minimal boilerplate
+* **Fast**: High-performance async implementation
+* **Full-featured**: Complete implementation of the MCP specification
+
+<!-- omit in toc -->
+## Table of Contents
+
+- [Installation](#installation)
+- [Quickstart](#quickstart)
+- [What is MCP?](#what-is-mcp)
+- [Core Concepts](#core-concepts)
+  - [Server](#server)
+  - [Resources](#resources)
+  - [Tools](#tools)
+  - [Prompts](#prompts)
+  - [Images](#images)
+  - [Context](#context)
+- [Deployment](#deployment)
+  - [Development](#development)
+  - [Claude Desktop](#claude-desktop)
+- [Examples](#examples)
+  - [Echo Server](#echo-server)
+  - [SQLite Explorer](#sqlite-explorer)
+
+## Installation
+
+```bash
+# We strongly recommend installing with uv
+brew install uv  # on macOS
+uv pip install fastmcp
+```
+
+Or with pip:
+```bash
+pip install fastmcp
+```
+
+## Quickstart
+
+Let's create a simple MCP server that exposes a calculator tool and some data:
+
+```python
+from fastmcp import FastMCP
+
+
+# Create an MCP server
+mcp = FastMCP("Demo")
+
+
+# Add an addition tool
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+
+# Add a dynamic greeting resource
+@mcp.resource("greeting://{name}")
+def get_greeting(name: str) -> str:
+    """Get a personalized greeting"""
+    return f"Hello, {name}!"
+```
+
+To use this server, you have two options:
+
+1. Install it in [Claude Desktop](https://claude.ai/download):
+```bash
+fastmcp install server.py
+```
+
+2. Test it with the MCP Inspector:
+```bash
+fastmcp dev server.py
+```
+
+![MCP Inspector](docs/images/mcp-inspector.png)
+
+## What is MCP?
+
+The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but specifically designed for LLM interactions. MCP servers can:
+
+- Expose data through **Resources** (like GET endpoints)
+- Provide functionality through **Tools** (like POST endpoints)
+- Define interaction patterns through **Prompts** (reusable templates for LLM interactions)
+
+## Core Concepts
+
+*Note: All code examples below assume you've created a FastMCP server instance called `mcp`.*
+
+### Server
+
+The FastMCP server is your core interface to the MCP protocol. It handles connection management, protocol compliance, and message routing:
+
+```python
+from fastmcp import FastMCP
+
+# Create a named server
+mcp = FastMCP("My App")
+
+# Configure host/port for HTTP transport (optional)
+mcp = FastMCP("My App", host="localhost", port=8000)
+```
+
+### Resources
+
+Resources are how you expose data to LLMs. They're similar to GET endpoints in a REST API - they provide data but shouldn't perform significant computation or have side effects. Some examples:
+
+- File contents
+- Database schemas
+- API responses
+- System information
+
+Resources can be static:
+```python
+@mcp.resource("config://app")
+def get_config() -> str:
+    """Static configuration data"""
+    return "App configuration here"
+```
+
+Or dynamic with parameters (FastMCP automatically handles these as MCP templates):
+```python
+@mcp.resource("users://{user_id}/profile")
+def get_user_profile(user_id: str) -> str:
+    """Dynamic user data"""
+    return f"Profile data for user {user_id}"
+```
+
+### Tools
+
+Tools let LLMs take actions through your server. Unlike resources, tools are expected to perform computation and have side effects. They're similar to POST endpoints in a REST API.
+
+Simple calculation example:
+```python
+@mcp.tool()
+def calculate_bmi(weight_kg: float, height_m: float) -> float:
+    """Calculate BMI given weight in kg and height in meters"""
+    return weight_kg / (height_m ** 2)
+```
+
+HTTP request example:
+```python
+import httpx
+
+@mcp.tool()
+async def fetch_weather(city: str) -> str:
+    """Fetch current weather for a city"""
+    async with httpx.AsyncClient() as client:
+        response = await client.get(
+            f"https://api.weather.com/{city}"
+        )
+        return response.text
+```
+
+### Prompts
+
+Prompts are reusable templates that help LLMs interact with your server effectively. They're like "best practices" encoded into your server. A prompt can be as simple as a string:
+
+```python
+@mcp.prompt()
+def review_code(code: str) -> str:
+    return f"Please review this code:\n\n{code}"
+```
+
+Or a more structured sequence of messages:
+```python
+from fastmcp.prompts.base import UserMessage, AssistantMessage
+
+@mcp.prompt()
+def debug_error(error: str) -> list[Message]:
+    return [
+        UserMessage("I'm seeing this error:"),
+        UserMessage(error),
+        AssistantMessage("I'll help debug that. What have you tried so far?")
+    ]
+```
+
+
+### Images
+
+FastMCP provides an `Image` class that automatically handles image data in your server:
+
+```python
+from fastmcp import FastMCP, Image
+from PIL import Image as PILImage
+
+@mcp.tool()
+def create_thumbnail(image_path: str) -> Image:
+    """Create a thumbnail from an image"""
+    img = PILImage.open(image_path)
+    img.thumbnail((100, 100))
+    
+    # FastMCP automatically handles conversion and MIME types
+    return Image(data=img.tobytes(), format="png")
+
+@mcp.tool()
+def load_image(path: str) -> Image:
+    """Load an image from disk"""
+    # FastMCP handles reading and format detection
+    return Image(path=path)
+```
+
+Images can be used as the result of both tools and resources.
+
+### Context
+
+The Context object gives your tools and resources access to MCP capabilities. To use it, add a parameter annotated with `fastmcp.Context`:
+
+```python
+from fastmcp import FastMCP, Context
+
+@mcp.tool()
+async def long_task(files: list[str], ctx: Context) -> str:
+    """Process multiple files with progress tracking"""
+    for i, file in enumerate(files):
+        ctx.info(f"Processing {file}")
+        await ctx.report_progress(i, len(files))
+        
+        # Read another resource if needed
+        data = await ctx.read_resource(f"file://{file}")
+        
+    return "Processing complete"
+```
+
+The Context object provides:
+- Progress reporting through `report_progress()`
+- Logging via `debug()`, `info()`, `warning()`, and `error()`
+- Resource access through `read_resource()`
+- Request metadata via `request_id` and `client_id`
+
+## Deployment
+
+The FastMCP CLI helps you develop and deploy MCP servers.
+
+Note that for all deployment commands, you are expected to provide the fully qualified path to your server object. For example, if you have a file `server.py` that contains a FastMCP server named `my_server`, you would provide `path/to/server.py:my_server`.
+
+If your server variable has one of the standard names (`mcp`, `server`, or `app`), you can omit the server name from the path and just provide the file: `path/to/server.py`.
+
+### Development
+
+Test and debug your server with the MCP Inspector:
+```bash
+# Provide the fully qualified path to your server
+fastmcp dev server.py:my_mcp_server
+
+# Or just the file if your server is named 'mcp', 'server', or 'app'
+fastmcp dev server.py
+```
+
+Your server is run in an isolated environment, so you'll need to indicate any dependencies with the `--with` flag. FastMCP is automatically included. If you are working on a uv project, you can use the `--with-editable` flag to mount your current directory:   
+
+```bash
+# With additional packages
+fastmcp dev server.py --with pandas --with numpy
+
+# Using your project's dependencies and up-to-date code
+fastmcp dev server.py --with-editable .
+```
+
+### Claude Desktop
+
+Install your server in Claude Desktop:
+```bash
+# Basic usage (name is taken from your FastMCP instance)
+fastmcp install server.py
+
+# With a custom name
+fastmcp install server.py --name "My Server"
+
+# With dependencies
+fastmcp install server.py --with pandas --with numpy
+
+# Replace an existing server
+fastmcp install server.py --force
+```
+
+The server name in Claude will be:
+1. The `--name` parameter if provided
+2. The `name` from your FastMCP instance
+3. The filename if the server can't be imported
+
+## Examples
+
+### Echo Server
+A simple server demonstrating resources, tools, and prompts:
+
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("Echo")
+
+@mcp.resource("echo://{message}")
+def echo_resource(message: str) -> str:
+    """Echo a message as a resource"""
+    return f"Resource echo: {message}"
+
+@mcp.tool()
+def echo_tool(message: str) -> str:
+    """Echo a message as a tool"""
+    return f"Tool echo: {message}"
+
+@mcp.prompt()
+def echo_prompt(message: str) -> str:
+    """Create an echo prompt"""
+    return f"Please process this message: {message}"
+```
+
+### SQLite Explorer
+A more complex example showing database integration:
+
+```python
+from fastmcp import FastMCP
+import sqlite3
+
+mcp = FastMCP("SQLite Explorer")
+
+@mcp.resource("schema://main")
+def get_schema() -> str:
+    """Provide the database schema as a resource"""
+    conn = sqlite3.connect("database.db")
+    schema = conn.execute(
+        "SELECT sql FROM sqlite_master WHERE type='table'"
+    ).fetchall()
+    return "\n".join(sql[0] for sql in schema if sql[0])
+
+@mcp.tool()
+def query_data(sql: str) -> str:
+    """Execute SQL queries safely"""
+    conn = sqlite3.connect("database.db")
+    try:
+        result = conn.execute(sql).fetchall()
+        return "\n".join(str(row) for row in result)
+    except Exception as e:
+        return f"Error: {str(e)}"
+
+@mcp.prompt()
+def analyze_table(table: str) -> str:
+    """Create a prompt template for analyzing tables"""
+    return f"""Please analyze this database table:
+Table: {table}
+Schema: 
+{get_schema()}
+
+What insights can you provide about the structure and relationships?"""
+```

fastmcp-0.3.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+fastmcp/__init__.py,sha256=Y5dHGBwyQPgNP5gzOyNIItefvMZ3vJLdom1oV8A1u_k,248
+fastmcp/exceptions.py,sha256=K0rCgXsUVlws39hz98Tb4BBf_BzIql_zXFZgqbkNTiE,348
+fastmcp/server.py,sha256=gZCl4ppLWYjM4L6MXJxr-jh9ngjHjaFSFTLpofmgtmA,21987
+fastmcp/cli/__init__.py,sha256=7hrwtCHX9nMd9qcz7R_JFSoqbL71fC35cBLXBS430mg,88
+fastmcp/cli/claude.py,sha256=hId0cTmAfCrav72Hg5LeO0SPPNyEVtIOcoKVAy8gD3k,3390
+fastmcp/cli/cli.py,sha256=Mru5j0_apXBnLBEd6DMICGPUk52DN3eyjSc1B973M2M,10028
+fastmcp/prompts/__init__.py,sha256=4BsMxoYolpoxg74xkkkzCFL8vvdkLVJ5cIPNs1ND1Jo,99
+fastmcp/prompts/base.py,sha256=WaSsfyFSsUPUbcApkGy3Pm-Ne-Gk-5ZwU3efqRYn1mQ,4996
+fastmcp/prompts/manager.py,sha256=EkexOB_N4QNtC-UlZmIcWcau91ceO2O1K4_kD75pA_A,1485
+fastmcp/prompts/prompt_manager.py,sha256=5uR14gsi7l0YHwbxFH7N5b_ACHHRWyTtBAH3R0-G5rk,1129
+fastmcp/resources/__init__.py,sha256=9QShop6ckX3Khh3BQLZNkB6R2ZhwskAcnh7-sIuX-W8,464
+fastmcp/resources/base.py,sha256=glGLpHp8Eq-LKq7YLJx3LRDiCktLlLaTTmltNcdWzHg,1818
+fastmcp/resources/resource_manager.py,sha256=b0PKpG-pKi7x2Yx-qaeknjv0mqL17zixSIYOz2V5G6o,3271
+fastmcp/resources/templates.py,sha256=EmLlI-ddBBzSTAUiA6-knFnHCE3MPMW2ZoH9WswPKvI,2868
+fastmcp/resources/types.py,sha256=ofE6bfeQQfPSmaWrLGDf3qjCP0kGjKmvupsHDYkSrj0,5658
+fastmcp/tools/__init__.py,sha256=ZboxhyMJDl87Svjov8YwNYwNZi55P9VhmpTjBZLesnk,96
+fastmcp/tools/base.py,sha256=JPdTx8SAl5pKsHyIVxnsLG88f3fbjnopDTOAZ_PoVQE,2585
+fastmcp/tools/tool_manager.py,sha256=PT6XHcQWzhdC6kfdsJaddRn7VLps4nAs5FMG8l1j8Zc,1617
+fastmcp/utilities/__init__.py,sha256=-imJ8S-rXmbXMWeDamldP-dHDqAPg_wwmPVz-LNX14E,31
+fastmcp/utilities/logging.py,sha256=t2w5bwtrkxHxioWSy5vY8esxLQxyxN8tfFZ1FI3Cb6E,704
+fastmcp/utilities/types.py,sha256=jFlZMZsKrJg4NWc1vTBIILLoHpTVwSd-vxO7ycoRuig,1718
+fastmcp-0.3.0.dist-info/METADATA,sha256=Nu76qWE1nxUHiHF4pczCTMUl8C2hKpXfIeo2Sp1UHxo,11452
+fastmcp-0.3.0.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+fastmcp-0.3.0.dist-info/entry_points.txt,sha256=ff8bMtKX1JvXyurMibAacMSKbJEPmac9ffAKU9mLnM8,44
+fastmcp-0.3.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+fastmcp-0.3.0.dist-info/RECORD,,

{fastmcp-0.2.0.dist-info → fastmcp-0.3.0.dist-info}/WHEEL

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