fastmcp 0.3.2__tar.gz → 0.3.4__tar.gz

{fastmcp-0.3.2 → fastmcp-0.3.4}/.github/workflows/run-tests.yml

@@ -7,7 +7,18 @@ env:
 on:
   push:
     branches: ["main"]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "uv.lock"
+      - "pyproject.toml"
   pull_request:
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "uv.lock"
+      - "pyproject.toml"
+
   workflow_dispatch:
 
 permissions:

{fastmcp-0.3.2 → fastmcp-0.3.4}/.gitignore

@@ -9,6 +9,7 @@ wheels/
 # Virtual environments
 .venv
 .DS_Store
+.env
 
 
 src/fastmcp/_version.py

{fastmcp-0.3.2 → fastmcp-0.3.4}/PKG-INFO

@@ -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>