fastmcp 0.3.1__py3-none-any.whl → 0.3.3__py3-none-any.whl

fastmcp/cli/claude.py

@@ -3,7 +3,7 @@
 import json
 import sys
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Dict
 
 from ..utilities.logging import get_logger
 
@@ -30,16 +30,17 @@ def update_claude_config(
     *,
     with_editable: Optional[Path] = None,
     with_packages: Optional[list[str]] = None,
-    force: bool = False,
+    env_vars: Optional[Dict[str, str]] = None,
 ) -> bool:
-    """Add the MCP server to Claude's configuration.
+    """Add or update a FastMCP server in Claude's configuration.
 
     Args:
         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
+        env_vars: Optional dictionary of environment variables. These are merged with
+            any existing variables, with new values taking precedence.
     """
     config_dir = get_claude_config_path()
     if not config_dir:
@@ -54,30 +55,33 @@ def update_claude_config(
         if "mcpServers" not in config:
             config["mcpServers"] = {}
 
-        if server_name in config["mcpServers"]:
-            if not force:
-                logger.warning(
-                    f"Server '{server_name}' already exists in Claude config. "
-                    "Use `--force` to replace.",
-                    extra={"config_file": str(config_file)},
-                )
-                return False
-            logger.info(
-                f"Replacing existing server '{server_name}' in Claude config",
-                extra={"config_file": str(config_file)},
-            )
+        # Always preserve existing env vars and merge with new ones
+        if (
+            server_name in config["mcpServers"]
+            and "env" in config["mcpServers"][server_name]
+        ):
+            existing_env = config["mcpServers"][server_name]["env"]
+            if env_vars:
+                # New vars take precedence over existing ones
+                env_vars = {**existing_env, **env_vars}
+            else:
+                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:
@@ -89,11 +93,17 @@ def update_claude_config(
         # Add fastmcp run command
         args.extend(["fastmcp", "run", file_spec])
 
-        config["mcpServers"][server_name] = {
+        server_config = {
             "command": "uv",
             "args": args,
         }
 
+        # Add environment variables if specified
+        if env_vars:
+            server_config["env"] = env_vars
+
+        config["mcpServers"][server_name] = server_config
+
         config_file.write_text(json.dumps(config, indent=2))
         logger.info(
             f"Added server '{server_name}' to Claude config",

fastmcp/cli/cli.py

@@ -5,10 +5,11 @@ import importlib.util
 import subprocess
 import sys
 from pathlib import Path
-from typing import Optional, Tuple
+from typing import Optional, Tuple, Dict
 
 import typer
 from typing_extensions import Annotated
+import dotenv
 
 from ..utilities.logging import get_logger
 from . import claude
@@ -23,6 +24,17 @@ app = typer.Typer(
 )
 
 
+def _parse_env_var(env_var: str) -> Tuple[str, str]:
+    """Parse environment variable string in format KEY=VALUE."""
+    if "=" not in env_var:
+        logger.error(
+            f"Invalid environment variable format: {env_var}. Must be KEY=VALUE"
+        )
+        sys.exit(1)
+    key, value = env_var.split("=", 1)
+    return key.strip(), value.strip()
+
+
 def _build_uv_command(
     file_spec: str,
     with_editable: Optional[Path] = None,
@@ -181,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(
@@ -220,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)
 
@@ -246,7 +256,6 @@ def run(
             "file": str(file),
             "server_object": server_object,
             "transport": transport,
-            "with_editable": str(with_editable) if with_editable else None,
         },
     )
 
@@ -304,16 +313,32 @@ def install(
             help="Additional packages to install",
         ),
     ] = [],
-    force: Annotated[
-        bool,
+    env_vars: Annotated[
+        list[str],
+        typer.Option(
+            "--env-var",
+            "-e",
+            help="Environment variables in KEY=VALUE format",
+        ),
+    ] = [],
+    env_file: Annotated[
+        Optional[Path],
         typer.Option(
-            "--force",
+            "--env-file",
             "-f",
-            help="Replace existing server if one exists with the same name",
+            help="Load environment variables from a .env file",
+            exists=True,
+            file_okay=True,
+            dir_okay=False,
+            resolve_path=True,
         ),
-    ] = False,
+    ] = None,
 ) -> None:
-    """Install a FastMCP server in the Claude desktop app."""
+    """Install a FastMCP server in the Claude desktop app.
+
+    Environment variables are preserved once added and only updated if new values
+    are explicitly provided.
+    """
     file, server_object = _parse_file_path(file_spec)
 
     logger.debug(
@@ -324,7 +349,6 @@ def install(
             "server_object": server_object,
             "with_editable": str(with_editable) if with_editable else None,
             "with_packages": with_packages,
-            "force": force,
         },
     )
 
@@ -334,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)
@@ -345,12 +370,34 @@ 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:
+        env_dict = {}
+        # Load from .env file if specified
+        if env_file:
+            try:
+                env_dict.update(dotenv.dotenv_values(env_file))
+            except Exception as e:
+                logger.error(f"Failed to load .env file: {e}")
+                sys.exit(1)
+
+        # Add command line environment variables
+        for env_var in env_vars:
+            key, value = _parse_env_var(env_var)
+            env_dict[key] = value
+
     if claude.update_claude_config(
         file_spec,
         name,
         with_editable=with_editable,
         with_packages=with_packages,
-        force=force,
+        env_vars=env_dict,
     ):
         logger.info(f"Successfully installed {name} in Claude app")
     else:

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.1.dist-info → fastmcp-0.3.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastmcp
-Version: 0.3.1
+Version: 0.3.3
 Summary: A more ergonomic interface for MCP servers
 Author: Jeremiah Lowin
 License: Apache-2.0
@@ -9,6 +9,7 @@ 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: python-dotenv>=1.0.1
 Requires-Dist: typer>=0.9.0
 Provides-Extra: dev
 Requires-Dist: copychat>=0.5.2; extra == 'dev'
@@ -26,28 +27,39 @@ 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)
 
-A fast, Pythonic way to build [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers
 
 </div>
 
-FastMCP makes building MCP servers simple and intuitive. Create tools, expose resources, and define prompts with clean, Pythonic code:
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers are a new, standardized way to provide context and tools to your LLMs, and FastMCP makes building MCP servers simple and intuitive. Create tools, expose resources, and define prompts with clean, Pythonic code:
 
 ```python
+# demo.py
+
 from fastmcp import FastMCP
 
+
 mcp = FastMCP("Demo 🚀")
 
+
 @mcp.tool()
 def add(a: int, b: int) -> int:
     """Add two numbers"""
     return a + b
 ```
 
-That's it! FastMCP handles all the complex protocol details and server management, so you can focus on building great tools. It's designed to be high-level and Pythonic - in most cases, decorating a function is all you need.
+That's it! Give Claude access to the server by running:
+
+```bash
+fastmcp install demo.py
+```
+
+FastMCP handles all the complex protocol details and server management, so you can focus on building great tools. It's designed to be high-level and Pythonic - in most cases, decorating a function is all you need.
 
 
 ### Key features:
@@ -74,22 +86,33 @@ That's it! FastMCP handles all the complex protocol details and server managemen
   - [Prompts](#prompts)
   - [Images](#images)
   - [Context](#context)
-- [Deployment](#deployment)
-  - [Development](#development)
-  - [Claude Desktop](#claude-desktop)
+- [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
 ```
@@ -160,8 +183,10 @@ 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
 
@@ -290,59 +315,107 @@ 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)
 
-### Claude Desktop
+Once your server is ready, install it in Claude Desktop to use it with Claude:
 
-Install your server in Claude Desktop:
 ```bash
-# Basic usage (name is taken from your FastMCP instance)
 fastmcp install server.py
+```
+
+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:
+
+```python
+from fastmcp import FastMCP
 
-# With a custom name
-fastmcp install server.py --name "My Server"
+mcp = FastMCP("My App")
+
+if __name__ == "__main__":
+    mcp.run()
+```
 
-# With dependencies
-fastmcp install server.py --with pandas --with numpy
+Run it with:
+```bash
+# Using the FastMCP CLI
+fastmcp run server.py
 
-# Replace an existing server
-fastmcp install server.py --force
+# Or with Python/uv directly
+python server.py
+uv run python server.py
 ```
 
-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
+
+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.
+
+Choose this method when you need:
+- Custom deployment configurations
+- Integration with other services
+- Direct control over the server lifecycle
+
+### Server Object Names
+
+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
+# Using a standard name
+fastmcp run server.py
+
+# Using a custom name
+fastmcp run server.py:my_custom_server
+```
 
 ## Examples
 
+Here are a few examples of FastMCP servers. For more, see the `examples/` directory.
+
 ### Echo Server
 A simple server demonstrating resources, tools, and prompts:
 
@@ -405,3 +478,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.1.dist-info → fastmcp-0.3.3.dist-info}/RECORD

@@ -1,9 +1,9 @@
 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=hId0cTmAfCrav72Hg5LeO0SPPNyEVtIOcoKVAy8gD3k,3390
-fastmcp/cli/cli.py,sha256=0r9_HR_wayV5MZARS02ZO1RnRCT8roxdY1CGGYzPNqo,10044
+fastmcp/cli/claude.py,sha256=APgTMQm7qa68Fz4EObZYmrgY-8-wjn6vCJZD7Se6XlU,3765
+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
@@ -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.1.dist-info/METADATA,sha256=PdOwJThIuqGDpSExh8dUsYyxUQBq0rw5MnOV3an2aTs,12108
-fastmcp-0.3.1.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-fastmcp-0.3.1.dist-info/entry_points.txt,sha256=ff8bMtKX1JvXyurMibAacMSKbJEPmac9ffAKU9mLnM8,44
-fastmcp-0.3.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-fastmcp-0.3.1.dist-info/RECORD,,
+fastmcp-0.3.3.dist-info/METADATA,sha256=pDlwjd5p0ErFBvpK2D6u9jAWb4rsGzL9f3l95IWJToc,15319
+fastmcp-0.3.3.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+fastmcp-0.3.3.dist-info/entry_points.txt,sha256=ff8bMtKX1JvXyurMibAacMSKbJEPmac9ffAKU9mLnM8,44
+fastmcp-0.3.3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+fastmcp-0.3.3.dist-info/RECORD,,