From 709b48bbb73ae26f39e0226703f8d2f4721d4ee2 Mon Sep 17 00:00:00 2001 From: Jeremiah Lowin <153965+jlowin@users.noreply.github.com> Date: Sun, 1 Dec 2024 20:55:16 -0500 Subject: [PATCH] Support dependencies --- README.md | 148 ++++++++++++++++++++--------------- examples/screenshot.py | 16 ++-- src/fastmcp/cli/claude.py | 16 ++-- src/fastmcp/cli/cli.py | 27 ++++--- src/fastmcp/server.py | 7 ++ tests/test_cli.py | 160 ++++++++++++++++++++++++++++---------- 6 files changed, 244 insertions(+), 130 deletions(-) diff --git a/README.md b/README.md index bf100d4..b462fdc 100644 --- a/README.md +++ b/README.md @@ -62,15 +62,20 @@ 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 @@ -154,8 +159,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 @@ -284,84 +291,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 +``` + +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 a custom name -fastmcp install server.py --name "My Server" +```python +from fastmcp import FastMCP -# With dependencies -fastmcp install server.py --with pandas --with numpy +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 - -# Second install - FOO and BAZ are preserved -fastmcp install server.py -e NEW=value +# Using a standard name +fastmcp run server.py -# 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 @@ -437,11 +461,11 @@ What insights can you provide about the structure and relationships?"""

Open Developer Guide

 -#### Prerequisites +### Prerequisites FastMCP requires Python 3.10+ and [uv](https://docs.astral.sh/uv/). -#### Installation +### Installation Create a fork of this repository, then clone it: @@ -460,7 +484,7 @@ uv sync --frozen --all-extras --dev -#### Testing +### Testing Please make sure to test any new functionality. Your tests should be simple and atomic and anticipate change rather than cement complex patterns. @@ -471,7 +495,7 @@ Run tests from the root directory: pytest -vv ``` -#### Formatting +### Formatting FastMCP enforces a variety of required formats, which you can automatically enforce with pre-commit. @@ -487,7 +511,7 @@ The hooks will now run on every commit (as well as on every PR). To run them man pre-commit run --all-files ``` -#### Opening a Pull Request +### Opening a Pull Request Fork the repository and create a new branch: diff --git a/examples/screenshot.py b/examples/screenshot.py index 012a253..f494cf7 100644 --- a/examples/screenshot.py +++ b/examples/screenshot.py @@ -1,7 +1,3 @@ -# /// script -# dependencies = ["fastmcp", "pyautogui", "Pillow"] -# /// - """ FastMCP Screenshot Example @@ -9,20 +5,24 @@ """ import io - from fastmcp import FastMCP, Image + # Create server -mcp = FastMCP("Screenshot Demo") +mcp = FastMCP("Screenshot Demo", dependencies=["pyautogui", "Pillow"]) @mcp.tool() def take_screenshot() -> Image: - """Take a screenshot of the user's screen and return it as an image""" + """ + Take a screenshot of the user's screen and return it as an image. Use + this tool anytime the user wants you to look at something they're doing. + """ import pyautogui - screenshot = pyautogui.screenshot() buffer = io.BytesIO() + # if the file exceeds ~1MB, it will be rejected by Claude + screenshot = pyautogui.screenshot() screenshot.convert("RGB").save(buffer, format="JPEG", quality=60, optimize=True) return Image(data=buffer.getvalue(), format="jpeg") diff --git a/src/fastmcp/cli/claude.py b/src/fastmcp/cli/claude.py index a5c7832..dee12e3 100644 --- a/src/fastmcp/cli/claude.py +++ b/src/fastmcp/cli/claude.py @@ -68,16 +68,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: diff --git a/src/fastmcp/cli/cli.py b/src/fastmcp/cli/cli.py index 83e4577..cd84a6a 100644 --- a/src/fastmcp/cli/cli.py +++ b/src/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: diff --git a/src/fastmcp/server.py b/src/fastmcp/server.py index ffc4da2..a215a9a 100644 --- a/src/fastmcp/server.py +++ b/src/fastmcp/server.py @@ -9,6 +9,7 @@ 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 @@ def __init__(self, name: str | None = None, **settings: Any): 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() diff --git a/tests/test_cli.py b/tests/test_cli.py index 0a8b371..3015b78 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -1,7 +1,7 @@ """Tests for the FastMCP CLI.""" import json -from unittest.mock import Mock, patch +from unittest.mock import patch import pytest from typer.testing import CliRunner @@ -19,11 +19,13 @@ def mock_config(tmp_path): @pytest.fixture -def mock_server_file(tmp_path): - """Create a mock server file.""" +def server_file(tmp_path): + """Create a server file.""" server_file = tmp_path / "server.py" server_file.write_text( - "from fastmcp import Server\n" "server = Server(name='test')\n" + """from fastmcp import FastMCP +mcp = FastMCP("test") +""" ) return server_file @@ -67,22 +69,16 @@ def test_parse_env_var(): ), ], ) -def test_install_with_env_vars(mock_config, mock_server_file, args, expected_env): +def test_install_with_env_vars(mock_config, server_file, args, expected_env): """Test installing with environment variables.""" runner = CliRunner() - with ( - patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path, - patch("fastmcp.cli.cli._import_server") as mock_import, - ): + with patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path: mock_config_path.return_value = mock_config.parent - mock_server = Mock() - mock_server.name = "test" # Set name as an attribute - mock_import.return_value = mock_server result = runner.invoke( app, - ["install", str(mock_server_file)] + args, + ["install", str(server_file)] + args, ) assert result.exit_code == 0 @@ -95,22 +91,16 @@ def test_install_with_env_vars(mock_config, mock_server_file, args, expected_env assert server["env"] == expected_env -def test_install_with_env_file(mock_config, mock_server_file, mock_env_file): +def test_install_with_env_file(mock_config, server_file, mock_env_file): """Test installing with environment variables from a file.""" runner = CliRunner() - with ( - patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path, - patch("fastmcp.cli.cli._import_server") as mock_import, - ): + with patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path: mock_config_path.return_value = mock_config.parent - mock_server = Mock() - mock_server.name = "test" # Set name as an attribute - mock_import.return_value = mock_server result = runner.invoke( app, - ["install", str(mock_server_file), "--env-file", str(mock_env_file)], + ["install", str(server_file), "--env-file", str(mock_env_file)], ) assert result.exit_code == 0 @@ -123,7 +113,7 @@ def test_install_with_env_file(mock_config, mock_server_file, mock_env_file): assert server["env"] == {"FOO": "bar", "BAZ": "123"} -def test_install_preserves_existing_env_vars(mock_config, mock_server_file): +def test_install_preserves_existing_env_vars(mock_config, server_file): """Test that installing preserves existing environment variables.""" # Set up initial config with env vars config = { @@ -136,7 +126,7 @@ def test_install_preserves_existing_env_vars(mock_config, mock_server_file): "fastmcp", "fastmcp", "run", - str(mock_server_file), + str(server_file), ], "env": {"FOO": "bar", "BAZ": "123"}, } @@ -146,19 +136,13 @@ def test_install_preserves_existing_env_vars(mock_config, mock_server_file): runner = CliRunner() - with ( - patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path, - patch("fastmcp.cli.cli._import_server") as mock_import, - ): + with patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path: mock_config_path.return_value = mock_config.parent - mock_server = Mock() - mock_server.name = "test" # Set name as an attribute - mock_import.return_value = mock_server # Install with a new env var result = runner.invoke( app, - ["install", str(mock_server_file), "--env-var", "NEW=value"], + ["install", str(server_file), "--env-var", "NEW=value"], ) assert result.exit_code == 0 @@ -169,7 +153,7 @@ def test_install_preserves_existing_env_vars(mock_config, mock_server_file): assert server["env"] == {"FOO": "bar", "BAZ": "123", "NEW": "value"} -def test_install_updates_existing_env_vars(mock_config, mock_server_file): +def test_install_updates_existing_env_vars(mock_config, server_file): """Test that installing updates existing environment variables.""" # Set up initial config with env vars config = { @@ -182,7 +166,7 @@ def test_install_updates_existing_env_vars(mock_config, mock_server_file): "fastmcp", "fastmcp", "run", - str(mock_server_file), + str(server_file), ], "env": {"FOO": "bar", "BAZ": "123"}, } @@ -192,19 +176,13 @@ def test_install_updates_existing_env_vars(mock_config, mock_server_file): runner = CliRunner() - with ( - patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path, - patch("fastmcp.cli.cli._import_server") as mock_import, - ): + with patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path: mock_config_path.return_value = mock_config.parent - mock_server = Mock() - mock_server.name = "test" # Set name as an attribute - mock_import.return_value = mock_server # Update an existing env var result = runner.invoke( app, - ["install", str(mock_server_file), "--env-var", "FOO=newvalue"], + ["install", str(server_file), "--env-var", "FOO=newvalue"], ) assert result.exit_code == 0 @@ -213,3 +191,101 @@ def test_install_updates_existing_env_vars(mock_config, mock_server_file): config = json.loads(mock_config.read_text()) server = next(iter(config["mcpServers"].values())) assert server["env"] == {"FOO": "newvalue", "BAZ": "123"} + + +def test_server_dependencies(mock_config, server_file): + """Test that server dependencies are correctly handled.""" + # Create a server file with dependencies + server_file = server_file.parent / "server_with_deps.py" + server_file.write_text( + """from fastmcp import FastMCP +mcp = FastMCP("test", dependencies=["pandas", "numpy"]) +""" + ) + + runner = CliRunner() + + with patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path: + mock_config_path.return_value = mock_config.parent + + result = runner.invoke(app, ["install", str(server_file)]) + + assert result.exit_code == 0 + + # Read the config file and check dependencies were added as --with args + config = json.loads(mock_config.read_text()) + server = next(iter(config["mcpServers"].values())) + assert "--with" in server["args"] + assert "pandas" in server["args"] + assert "numpy" in server["args"] + + +def test_server_dependencies_empty(mock_config, server_file): + """Test that server with no dependencies works correctly.""" + runner = CliRunner() + + with patch("fastmcp.cli.claude.get_claude_config_path") as mock_config_path: + mock_config_path.return_value = mock_config.parent + + result = runner.invoke(app, ["install", str(server_file)]) + + assert result.exit_code == 0 + + # Read the config file and check only fastmcp is in --with args + config = json.loads(mock_config.read_text()) + server = next(iter(config["mcpServers"].values())) + assert server["args"].count("--with") == 1 + assert "fastmcp" in server["args"] + + +def test_dev_with_dependencies(mock_config, server_file): + """Test that dev command handles dependencies correctly.""" + # Create a server file with dependencies + server_file = server_file.parent / "server_with_deps.py" + server_file.write_text( + """from fastmcp import FastMCP +mcp = FastMCP("test", dependencies=["pandas", "numpy"]) +""" + ) + + runner = CliRunner() + + with patch("subprocess.run") as mock_run: + mock_run.return_value.returncode = 0 # Set successful return code + result = runner.invoke(app, ["dev", str(server_file)]) + assert result.exit_code == 0 + + # Check that dependencies were passed to subprocess.run + mock_run.assert_called_once() + args = mock_run.call_args[0][0] + assert "npx" in args + assert "@modelcontextprotocol/inspector" in args + assert "uv" in args + assert "run" in args + assert "--with" in args + assert "pandas" in args + assert "numpy" in args + assert "fastmcp" in args + + +def test_run_with_dependencies(mock_config, server_file): + """Test that run command does not handle dependencies.""" + # Create a server file with dependencies + server_file = server_file.parent / "server_with_deps.py" + server_file.write_text( + """from fastmcp import FastMCP +mcp = FastMCP("test", dependencies=["pandas", "numpy"]) + +if __name__ == "__main__": + mcp.run() +""" + ) + + runner = CliRunner() + + with patch("subprocess.run") as mock_run: + result = runner.invoke(app, ["run", str(server_file)]) + assert result.exit_code == 0 + + # Run command should not call subprocess.run + mock_run.assert_not_called()