fastmcp 0.3.1__tar.gz → 0.3.3__tar.gz

{fastmcp-0.3.1 → fastmcp-0.3.3}/.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.1 → fastmcp-0.3.3}/.gitignore

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

{fastmcp-0.3.1 → fastmcp-0.3.3}/PKG-INFO

@@ -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 → fastmcp-0.3.3}/README.md

@@ -3,28 +3,39 @@
 
 <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:
@@ -51,22 +62,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
 ```
@@ -137,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
 
@@ -267,59 +291,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:
 
@@ -382,3 +454,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>