fastmcp 0.3.2__py3-none-any.whl → 0.3.4__py3-none-any.whl

fastmcp/cli/claude.py

@@ -41,14 +41,31 @@ def update_claude_config(
         with_packages: Optional list of additional packages to install
         env_vars: Optional dictionary of environment variables. These are merged with
             any existing variables, with new values taking precedence.
+
+    Raises:
+        RuntimeError: If Claude Desktop's config directory is not found, indicating
+            Claude Desktop may not be installed or properly set up.
     """
     config_dir = get_claude_config_path()
     if not config_dir:
-        return False
+        raise RuntimeError(
+            "Claude Desktop config directory not found. Please ensure Claude Desktop "
+            "is installed and has been run at least once to initialize its configuration."
+        )
 
     config_file = config_dir / "claude_desktop_config.json"
     if not config_file.exists():
-        return False
+        try:
+            config_file.write_text("{}")
+        except Exception as e:
+            logger.error(
+                "Failed to create Claude config file",
+                extra={
+                    "error": str(e),
+                    "config_file": str(config_file),
+                },
+            )
+            return False
 
     try:
         config = json.loads(config_file.read_text())
@@ -68,16 +85,20 @@ def update_claude_config(
                 env_vars = existing_env
 
         # Build uv run command
-        args = ["run", "--with", "fastmcp"]
+        args = ["run"]
+
+        # Collect all packages in a set to deduplicate
+        packages = {"fastmcp"}
+        if with_packages:
+            packages.update(pkg for pkg in with_packages if pkg)
+
+        # Add all packages with --with
+        for pkg in sorted(packages):
+            args.extend(["--with", pkg])
 
         if with_editable:
             args.extend(["--with-editable", str(with_editable)])
 
-        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:

fastmcp/cli/cli.py

@@ -193,6 +193,11 @@ def dev(
     )
 
     try:
+        # Import server to get dependencies
+        server = _import_server(file, server_object)
+        if hasattr(server, "dependencies"):
+            with_packages = list(set(with_packages + server.dependencies))
+
         uv_cmd = _build_uv_command(file_spec, with_editable, with_packages)
         # Run the MCP Inspector command
         process = subprocess.run(
@@ -232,23 +237,16 @@ def run(
             help="Transport protocol to use (stdio or sse)",
         ),
     ] = None,
-    with_editable: Annotated[
-        Optional[Path],
-        typer.Option(
-            "--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.
 
     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
+
+    Note: This command runs the server directly. You are responsible for ensuring
+    all dependencies are available. For dependency management, use fastmcp install
+    or fastmcp dev instead.
     """
     file, server_object = _parse_file_path(file_spec)
 
@@ -258,7 +256,6 @@ def run(
             "file": str(file),
             "server_object": server_object,
             "transport": transport,
-            "with_editable": str(with_editable) if with_editable else None,
         },
     )
 
@@ -361,6 +358,7 @@ def install(
 
     # Try to import server to get its name, but fall back to file name if dependencies missing
     name = server_name
+    server = None
     if not name:
         try:
             server = _import_server(file, server_object)
@@ -372,6 +370,11 @@ def install(
             )
             name = file.stem
 
+    # Get server dependencies if available
+    server_dependencies = getattr(server, "dependencies", []) if server else []
+    if server_dependencies:
+        with_packages = list(set(with_packages + server_dependencies))
+
     # Process environment variables if provided
     env_dict: Optional[Dict[str, str]] = None
     if env_file or env_vars:

fastmcp/resources/base.py

@@ -1,34 +1,17 @@
 """Base classes and interfaces for FastMCP resources."""
 
 import abc
-from typing import Annotated, Union
+from typing import 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):
@@ -36,7 +19,8 @@ class Resource(BaseModel, abc.ABC):
 
     model_config = ConfigDict(validate_default=True)
 
-    uri: LaxAnyUrl = Field(default=..., description="URI of the resource")
+    # uri: Annotated[AnyUrl, BeforeValidator(maybe_cast_str_to_any_url)] = Field(
+    uri: AnyUrl = 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
@@ -47,6 +31,15 @@ class Resource(BaseModel, abc.ABC):
         pattern=r"^[a-zA-Z0-9]+/[a-zA-Z0-9\-+.]+$",
     )
 
+    @field_validator("uri", mode="before")
+    def validate_uri(cls, uri: AnyUrl | str) -> AnyUrl:
+        if isinstance(uri, str):
+            # AnyUrl doesn't support triple-slashes, but files do ("file:///absolute/path")
+            if uri.startswith("file://"):
+                return FileUrl(uri)
+            return AnyUrl(uri)
+        return uri
+
     @field_validator("name", mode="before")
     @classmethod
     def set_default_name(cls, name: str | None, info: ValidationInfo) -> str:

fastmcp/server.py

@@ -9,6 +9,7 @@ from itertools import chain
 from typing import Any, Callable, Dict, Literal, Sequence
 
 import pydantic_core
+from pydantic import Field
 import uvicorn
 from mcp.server import Server as MCPServer
 from mcp.server.sse import SseServerTransport
@@ -76,6 +77,11 @@ class Settings(BaseSettings):
     # prompt settings
     warn_on_duplicate_prompts: bool = True
 
+    dependencies: list[str] = Field(
+        default_factory=list,
+        description="List of dependencies to install in the server environment",
+    )
+
 
 class FastMCP:
     def __init__(self, name: str | None = None, **settings: Any):
@@ -90,6 +96,7 @@ class FastMCP:
         self._prompt_manager = PromptManager(
             warn_on_duplicate_prompts=self.settings.warn_on_duplicate_prompts
         )
+        self.dependencies = self.settings.dependencies
 
         # Set up MCP protocol handlers
         self._setup_handlers()

{fastmcp-0.3.2.dist-info → fastmcp-0.3.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastmcp
-Version: 0.3.2
+Version: 0.3.4
 Summary: A more ergonomic interface for MCP servers
 Author: Jeremiah Lowin
 License: Apache-2.0
@@ -27,11 +27,12 @@ Description-Content-Type: text/markdown
 
 <div align="center">
 
+<strong>The fast, Pythonic way to build MCP servers.</strong>
+
 [![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)
 
-The fast, Pythonic way to build MCP servers
 
 </div>
 
@@ -85,24 +86,33 @@ FastMCP handles all the complex protocol details and server management, so you c
   - [Prompts](#prompts)
   - [Images](#images)
   - [Context](#context)
-- [Deployment](#deployment)
-  - [Development](#development)
-    - [Environment Variables](#environment-variables)
-  - [Claude Desktop](#claude-desktop)
-    - [Environment Variables](#environment-variables-1)
+- [Running Your Server](#running-your-server)
+  - [Development Mode (Recommended for Building \& Testing)](#development-mode-recommended-for-building--testing)
+  - [Claude Desktop Integration (For Regular Use)](#claude-desktop-integration-for-regular-use)
+  - [Direct Execution (For Advanced Use Cases)](#direct-execution-for-advanced-use-cases)
+  - [Server Object Names](#server-object-names)
 - [Examples](#examples)
   - [Echo Server](#echo-server)
   - [SQLite Explorer](#sqlite-explorer)
+- [Contributing](#contributing)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation-1)
+  - [Testing](#testing)
+  - [Formatting](#formatting)
+  - [Opening a Pull Request](#opening-a-pull-request)
 
 ## Installation
 
+We strongly recommend installing FastMCP with [uv](https://docs.astral.sh/uv/), as it is required for deploying servers:
+
 ```bash
-# We strongly recommend installing with uv
-brew install uv  # on macOS
 uv pip install fastmcp
 ```
 
-Or with pip:
+Note: on macOS, uv may need to be installed with Homebrew (`brew install uv`) in order to make it available to the Claude Desktop app.
+
+Alternatively, to use the SDK without deploying, you may use pip:
+
 ```bash
 pip install fastmcp
 ```
@@ -112,6 +122,8 @@ pip install fastmcp
 Let's create a simple MCP server that exposes a calculator tool and some data:
 
 ```python
+# server.py
+
 from fastmcp import FastMCP
 
 
@@ -133,14 +145,12 @@ def get_greeting(name: str) -> str:
     return f"Hello, {name}!"
 ```
 
-To use this server, you have two options:
-
-1. Install it in [Claude Desktop](https://claude.ai/download):
+You can install this server in [Claude Desktop](https://claude.ai/download) and interact with it right away by running:
 ```bash
 fastmcp install server.py
 ```
 
-2. Test it with the MCP Inspector:
+Alternatively, you can test it with the MCP Inspector:
 ```bash
 fastmcp dev server.py
 ```
@@ -171,10 +181,9 @@ 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)
+# Specify dependencies for deployment and development
+mcp = FastMCP("My App", dependencies=["pandas", "numpy"])
 ```
-*Note: All of the following code examples assume you've created a FastMCP server instance called `mcp`, as shown above.*
 
 ### Resources
 
@@ -303,84 +312,101 @@ The Context object provides:
 - Resource access through `read_resource()`
 - Request metadata via `request_id` and `client_id`
 
-## Deployment
-
-The FastMCP CLI helps you develop and deploy MCP servers.
+## Running Your Server
 
-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`.
+There are three main ways to use your FastMCP server, each suited for different stages of development:
 
-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 Mode (Recommended for Building & Testing)
 
-### Development
+The fastest way to test and debug your server is with the MCP Inspector:
 
-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:   
+This launches a web interface where you can:
+- Test your tools and resources interactively
+- See detailed logs and error messages
+- Monitor server performance
+- Set environment variables for testing
 
-```bash
-# With additional packages
-fastmcp dev server.py --with pandas --with numpy
+During development, you can:
+- Add dependencies with `--with`: 
+  ```bash
+  fastmcp dev server.py --with pandas --with numpy
+  ```
+- Mount your local code for live updates:
+  ```bash
+  fastmcp dev server.py --with-editable .
+  ```
 
-# Using your project's dependencies and up-to-date code
-fastmcp dev server.py --with-editable .
-```
+### Claude Desktop Integration (For Regular Use)
 
-#### Environment Variables
+Once your server is ready, install it in Claude Desktop to use it with Claude:
 
-The MCP Inspector runs servers in an isolated environment. Environment variables must be set through the Inspector UI and are not inherited from your system. The Inspector does not currently support setting environment variables via command line (see [Issue #94](https://github.com/modelcontextprotocol/inspector/issues/94)).
-
-### 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"
+Your server will run in an isolated environment with:
+- Automatic installation of dependencies specified in your FastMCP instance:
+  ```python
+  mcp = FastMCP("My App", dependencies=["pandas", "numpy"])
+  ```
+- Custom naming via `--name`:
+  ```bash
+  fastmcp install server.py --name "My Analytics Server"
+  ```
+- Environment variable management:
+  ```bash
+  # Set variables individually
+  fastmcp install server.py -e API_KEY=abc123 -e DB_URL=postgres://...
+  
+  # Or load from a .env file
+  fastmcp install server.py -f .env
+  ```
+
+### Direct Execution (For Advanced Use Cases)
+
+For advanced scenarios like custom deployments or running without Claude, you can execute your server directly:
 
-# With dependencies
-fastmcp install server.py --with pandas --with numpy
+```python
+from fastmcp import FastMCP
+
+mcp = FastMCP("My App")
+
+if __name__ == "__main__":
+    mcp.run()
 ```
 
-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
+Run it with:
+```bash
+# Using the FastMCP CLI
+fastmcp run server.py
 
-#### Environment Variables
+# Or with Python/uv directly
+python server.py
+uv run python server.py
+```
 
-Claude Desktop runs servers in an isolated environment. Environment variables from your system are NOT automatically available to the server - you must explicitly provide them during installation:
 
-```bash
-# Single env var
-fastmcp install server.py -e API_KEY=abc123
+Note: When running directly, you are responsible for ensuring all dependencies are available in your environment. Any dependencies specified on the FastMCP instance are ignored.
 
-# Multiple env vars
-fastmcp install server.py -e API_KEY=abc123 -e OTHER_VAR=value
+Choose this method when you need:
+- Custom deployment configurations
+- Integration with other services
+- Direct control over the server lifecycle
 
-# Load from .env file
-fastmcp install server.py -f .env
-```
+### Server Object Names
 
-Environment variables persist across reinstalls and are only updated when new values are provided:
+All FastMCP commands will look for a server object called `mcp`, `app`, or `server` in your file. If you have a different object name or multiple servers in one file, use the syntax `server.py:my_server`:
 
 ```bash
-# First install
-fastmcp install server.py -e FOO=bar -e BAZ=123
+# Using a standard name
+fastmcp run server.py
 
-# Second install - FOO and BAZ are preserved
-fastmcp install server.py -e NEW=value
-
-# Third install - FOO gets new value, others preserved
-fastmcp install server.py -e FOO=newvalue
+# Using a custom name
+fastmcp run server.py:my_custom_server
 ```
 
 ## Examples
@@ -449,3 +475,85 @@ Schema:
 
 What insights can you provide about the structure and relationships?"""
 ```
+
+## Contributing
+
+<details>
+
+<summary><h3>Open Developer Guide</h3></summary>
+
+### Prerequisites
+
+FastMCP requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
+
+### Installation
+
+Create a fork of this repository, then clone it:
+
+```bash
+git clone https://github.com/YouFancyUserYou/fastmcp.git
+cd fastmcp
+```
+
+Next, create a virtual environment and install FastMCP:
+
+```bash
+uv venv
+source .venv/bin/activate
+uv sync --frozen --all-extras --dev
+```
+
+
+
+### Testing
+
+Please make sure to test any new functionality. Your tests should be simple and atomic and anticipate change rather than cement complex patterns.
+
+Run tests from the root directory:
+
+
+```bash
+pytest -vv
+```
+
+### Formatting
+
+FastMCP enforces a variety of required formats, which you can automatically enforce with pre-commit. 
+
+Install the pre-commit hooks:
+
+```bash
+pre-commit install
+```
+
+The hooks will now run on every commit (as well as on every PR). To run them manually:
+
+```bash
+pre-commit run --all-files
+```
+
+### Opening a Pull Request
+
+Fork the repository and create a new branch:
+
+```bash
+git checkout -b my-branch
+```
+
+Make your changes and commit them:
+
+
+```bash
+git add . && git commit -m "My changes"
+```
+
+Push your changes to your fork:
+
+
+```bash
+git push origin my-branch
+```
+
+Feel free to reach out in a GitHub issue or discussion if you have any questions!
+
+</details>

{fastmcp-0.3.2.dist-info → fastmcp-0.3.4.dist-info}/RECORD

@@ -1,15 +1,15 @@
 fastmcp/__init__.py,sha256=Y5dHGBwyQPgNP5gzOyNIItefvMZ3vJLdom1oV8A1u_k,248
 fastmcp/exceptions.py,sha256=K0rCgXsUVlws39hz98Tb4BBf_BzIql_zXFZgqbkNTiE,348
-fastmcp/server.py,sha256=JttRzt1bnJGBU8mL4Bo764WHFXQ09QqKc_CUT3390WM,21997
+fastmcp/server.py,sha256=V6BaciC5u9g_XzbvPkafjGO8OtEBPGy_KlV535Au0do,22234
 fastmcp/cli/__init__.py,sha256=7hrwtCHX9nMd9qcz7R_JFSoqbL71fC35cBLXBS430mg,88
-fastmcp/cli/claude.py,sha256=mepURIVhlwQQYgkjgmuJCS841QAs9Mu-xRxdLpfCO0o,3628
-fastmcp/cli/cli.py,sha256=gzpgUseCR5tkdyZumjjxyAIYJLMeAdyJ5zgRHC9EL_M,11407
+fastmcp/cli/claude.py,sha256=5SoVEsA_PnOyOe2bcItvfcCwuhfX6W99TP1nXahLIJE,4442
+fastmcp/cli/cli.py,sha256=Ub2iNwnCVRO4TbC6Rr_1xOeTKnDN-9XE1z1O1yZatbg,11664
 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/base.py,sha256=inm2uhaE6KPQEsMd4SyDLbRIOjQrXahSn84RNT3Y6MY,1723
 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
@@ -19,8 +19,8 @@ fastmcp/tools/tool_manager.py,sha256=PT6XHcQWzhdC6kfdsJaddRn7VLps4nAs5FMG8l1j8Zc
 fastmcp/utilities/__init__.py,sha256=-imJ8S-rXmbXMWeDamldP-dHDqAPg_wwmPVz-LNX14E,31
 fastmcp/utilities/logging.py,sha256=VLJdNc0tIYoQZmpobehLUnWrQz7NXnuwSqrDlFt2RF0,738
 fastmcp/utilities/types.py,sha256=jFlZMZsKrJg4NWc1vTBIILLoHpTVwSd-vxO7ycoRuig,1718
-fastmcp-0.3.2.dist-info/METADATA,sha256=R64QFKVKLfIVWjOFi-vmEL3At_Dx8rwHTBdjBOTLC30,13617
-fastmcp-0.3.2.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-fastmcp-0.3.2.dist-info/entry_points.txt,sha256=ff8bMtKX1JvXyurMibAacMSKbJEPmac9ffAKU9mLnM8,44
-fastmcp-0.3.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-fastmcp-0.3.2.dist-info/RECORD,,
+fastmcp-0.3.4.dist-info/METADATA,sha256=-DqzP1SZTCU0qgtFZ7K3ABSaswQz9Q5ShWU-UwN_mkM,15260
+fastmcp-0.3.4.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+fastmcp-0.3.4.dist-info/entry_points.txt,sha256=ff8bMtKX1JvXyurMibAacMSKbJEPmac9ffAKU9mLnM8,44
+fastmcp-0.3.4.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+fastmcp-0.3.4.dist-info/RECORD,,