fastmcp 2.8.0__tar.gz → 2.9.0__tar.gz

{fastmcp-2.8.0 → fastmcp-2.9.0}/.github/release.yml

@@ -9,7 +9,7 @@ changelog:
         - feature
       exclude:
         labels:
-          - breaking change
+          - contrib
 
     - title: Enhancements 🔧
       labels:
@@ -17,22 +17,31 @@ changelog:
       exclude:
         labels:
           - breaking change
+          - contrib
 
     - title: Fixes 🐞
       labels:
         - bug
       exclude:
         labels:
-          - breaking change
+          - contrib
 
     - title: Breaking Changes 🛫
       labels:
         - breaking change
+      exclude:
+        labels:
+          - contrib
 
     - title: Docs 📚
       labels:
         - documentation
 
+    - title: Examples & Contrib 💡
+      labels:
+        - example
+        - contrib
+
     - title: Dependencies 📦
       labels:
         - dependencies

{fastmcp-2.8.0 → fastmcp-2.9.0}/.pre-commit-config.yaml

@@ -1,4 +1,4 @@
-fail_fast: true
+fail_fast: false
 
 repos:
   - repo: https://github.com/abravalheri/validate-pyproject

fastmcp-2.9.0/CLAUDE.md

@@ -0,0 +1,36 @@
+# FastMCP Development Guidelines
+
+## Testing and Investigation
+
+### In-Memory Transport - Always Preferred
+
+When testing or investigating FastMCP servers, **always prefer the in-memory transport** unless you specifically need HTTP transport features. Pass a FastMCP server directly to a Client to eliminate separate processes and network complexity.
+
+```python
+# Create your FastMCP server
+mcp = FastMCP("TestServer")
+
+@mcp.tool
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+
+# Pass server directly to client - uses in-memory transport
+async with Client(mcp) as client:
+    result = await client.call_tool("greet", {"name": "World"})
+```
+
+### When to Use HTTP Transport
+
+Only use HTTP transport when testing network-specific features. Prefer StreamableHttp over SSE as it's the modern approach.
+
+```python
+# Only when network testing is required
+async with Client(transport=StreamableHttpTransport(server_url)) as client:
+    result = await client.ping()
+```
+
+## Development Workflow
+
+- You must always run pre-commit if you open a PR, because it is run as part of a required check.
+- When opening PRs, apply labels appropriately for bugs/breaking changes/enhancements/features. Generally, improvements are enhancements (not features) unless told otherwise.
+- NEVER modify files in docs/python-sdk/**, as they are auto-generated.

{fastmcp-2.8.0 → fastmcp-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.8.0
+Version: 2.9.0
 Summary: The fast, Pythonic way to build MCP servers.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp
@@ -20,7 +20,7 @@ Requires-Python: >=3.10
 Requires-Dist: authlib>=1.5.2
 Requires-Dist: exceptiongroup>=1.2.2
 Requires-Dist: httpx>=0.28.1
-Requires-Dist: mcp<2.0.0,>=1.9.2
+Requires-Dist: mcp<2.0.0,>=1.9.4
 Requires-Dist: openapi-pydantic>=0.5.1
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rich>=13.9.4
@@ -33,6 +33,7 @@ Description-Content-Type: text/markdown
 
 <!-- omit in toc -->
 # FastMCP v2 🚀
+
 <strong>The fast, Pythonic way to build MCP servers and clients.</strong>
 
 *FastMCP is made with 💙 by [Prefect](https://www.prefect.io/)*
@@ -46,13 +47,16 @@ Description-Content-Type: text/markdown
 </div>
 
 > [!Note]
+>
 > #### Beyond the Protocol
-> 
-> FastMCP is the standard framework for working with the Model Context Protocol. FastMCP 1.0 was incorporated into the [official low-level Python SDK](https://github.com/modelcontextprotocol/python-sdk), and FastMCP 2.0 *(this project)* provides a complete toolkit for working with the MCP ecosystem.
 >
-> FastMCP has a comprehensive set of features that go far beyond the core MCP specification, all in service of providing **the simplest path to production**. These include client support, server composition, auth, automatic generation from OpenAPI specs, remote server proxying, built-in testing tools, integrations, and more.
+> FastMCP is the standard framework for working with the Model Context Protocol. FastMCP 1.0 was incorporated into the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) in 2024.
+>
+> This is FastMCP 2.0, the **actively maintained version** that provides a complete toolkit for working with the MCP ecosystem.
 >
-> Ready to upgrade or get started? Follow the [installation instructions](/getting-started/installation), which include specific steps for upgrading from the official MCP SDK.
+> FastMCP 2.0 has a comprehensive set of features that go far beyond the core MCP specification, all in service of providing **the simplest path to production**. These include deployment, auth, clients, server proxying and composition, generating servers from REST APIs, dynamic tool rewriting, built-in testing tools, integrations, and more.
+>
+> Ready to upgrade or get started? Follow the [installation instructions](https://gofastmcp.com/getting-started/installation), which include steps for upgrading from the official MCP SDK.
 
 ---
 
@@ -74,6 +78,7 @@ if __name__ == "__main__":
 ```
 
 Run the server locally:
+
 ```bash
 fastmcp run server.py
 ```
@@ -82,9 +87,10 @@ fastmcp run server.py
 
 FastMCP's complete documentation is available at **[gofastmcp.com](https://gofastmcp.com)**, including detailed guides, API references, and advanced patterns. This readme provides only a high-level overview.
 
-Documentation is also available in [llms.txt format](https://llmstxt.org/), which is a simple markdown standard that LLMs can consume easily. 
+Documentation is also available in [llms.txt format](https://llmstxt.org/), which is a simple markdown standard that LLMs can consume easily.
 
 There are two ways to access the LLM-friendly documentation:
+
 - [`llms.txt`](https://gofastmcp.com/llms.txt) is essentially a sitemap, listing all the pages in the documentation.
 - [`llms-full.txt`](https://gofastmcp.com/llms-full.txt) contains the entire documentation. Note this may exceed the context window of your LLM.
 
@@ -174,7 +180,7 @@ Learn more in the [**FastMCP Server Documentation**](https://gofastmcp.com/serve
 
 ### Tools
 
-Tools allow LLMs to perform actions by executing your Python functions (sync or async). Ideal for computations, API calls, or side effects (like `POST`/`PUT`). FastMCP handles schema generation from type hints and docstrings. Tools can return various types, including text, JSON-serializable objects, and even images using the [`fastmcp.Image`](https://gofastmcp.com/servers/tools#return-values) helper.
+Tools allow LLMs to perform actions by executing your Python functions (sync or async). Ideal for computations, API calls, or side effects (like `POST`/`PUT`). FastMCP handles schema generation from type hints and docstrings. Tools can return various types, including text, JSON-serializable objects, and even images or audio aided by the FastMCP media helper classes.
 
 ```python
 @mcp.tool
@@ -220,12 +226,13 @@ Learn more in the [**Prompts Documentation**](https://gofastmcp.com/servers/prom
 ### Context
 
 Access MCP session capabilities within your tools, resources, or prompts by adding a `ctx: Context` parameter. Context provides methods for:
-*   **Logging:** Log messages to MCP clients with `ctx.info()`, `ctx.error()`, etc.
-*   **LLM Sampling:** Use `ctx.sample()` to request completions from the client's LLM.
-*   **HTTP Request:** Use `ctx.http_request()` to make HTTP requests to other servers.
-*   **Resource Access:** Use `ctx.read_resource()` to access resources on the server
-*   **Progress Reporting:** Use `ctx.report_progress()` to report progress to the client.
-*   and more...
+
+- **Logging:** Log messages to MCP clients with `ctx.info()`, `ctx.error()`, etc.
+- **LLM Sampling:** Use `ctx.sample()` to request completions from the client's LLM.
+- **HTTP Request:** Use `ctx.http_request()` to make HTTP requests to other servers.
+- **Resource Access:** Use `ctx.read_resource()` to access resources on the server
+- **Progress Reporting:** Use `ctx.report_progress()` to report progress to the client.
+- and more...
 
 To access the context, add a parameter annotated as `Context` to any mcp-decorated function. FastMCP will automatically inject the correct context object when the function is called.
 
@@ -365,16 +372,19 @@ if __name__ == "__main__":
 FastMCP supports three transport protocols:
 
 **STDIO (Default)**: Best for local tools and command-line scripts.
+
 ```python
 mcp.run(transport="stdio")  # Default, so transport argument is optional
 ```
 
 **Streamable HTTP**: Recommended for web deployments.
+
 ```python
-mcp.run(transport="streamable-http", host="127.0.0.1", port=8000, path="/mcp")
+mcp.run(transport="http", host="127.0.0.1", port=8000, path="/mcp")
 ```
 
 **SSE**: For compatibility with existing SSE clients.
+
 ```python
 mcp.run(transport="sse", host="127.0.0.1", port=8000)
 ```
@@ -387,22 +397,26 @@ Contributions are the core of open source! We welcome improvements and features.
 
 ### Prerequisites
 
-*   Python 3.10+
-*   [uv](https://docs.astral.sh/uv/) (Recommended for environment management)
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) (Recommended for environment management)
 
 ### Setup
 
-1. Clone the repository: 
+1. Clone the repository:
+
    ```bash
    git clone https://github.com/jlowin/fastmcp.git 
    cd fastmcp
    ```
-2. Create and sync the environment: 
+
+2. Create and sync the environment:
+
    ```bash
    uv sync
    ```
+
    This installs all dependencies, including dev tools.
-   
+
 3. Activate the virtual environment (e.g., `source .venv/bin/activate` or via your IDE).
 
 ### Unit Tests
@@ -410,10 +424,13 @@ Contributions are the core of open source! We welcome improvements and features.
 FastMCP has a comprehensive unit test suite. All PRs must introduce or update tests as appropriate and pass the full suite.
 
 Run tests using pytest:
+
 ```bash
 pytest
 ```
+
 or if you want an overview of the code coverage
+
 ```bash
 uv run pytest --cov=src --cov=examples --cov-report=html
 ```
@@ -423,10 +440,13 @@ uv run pytest --cov=src --cov=examples --cov-report=html
 FastMCP uses `pre-commit` for code formatting, linting, and type-checking. All PRs must pass these checks (they run automatically in CI).
 
 Install the hooks locally:
+
 ```bash
 uv run pre-commit install
 ```
+
 The hooks will now run automatically on `git commit`. You can also run them manually at any time:
+
 ```bash
 pre-commit run --all-files
 # or via uv
@@ -435,11 +455,11 @@ uv run pre-commit run --all-files
 
 ### Pull Requests
 
-1.  Fork the repository on GitHub.
-2.  Create a feature branch from `main`.
-3.  Make your changes, including tests and documentation updates.
-4.  Ensure tests and pre-commit hooks pass.
-5.  Commit your changes and push to your fork.
-6.  Open a pull request against the `main` branch of `jlowin/fastmcp`.
+1. Fork the repository on GitHub.
+2. Create a feature branch from `main`.
+3. Make your changes, including tests and documentation updates.
+4. Ensure tests and pre-commit hooks pass.
+5. Commit your changes and push to your fork.
+6. Open a pull request against the `main` branch of `jlowin/fastmcp`.
 
-Please open an issue or discussion for questions or suggestions before starting significant work!
+Please open an issue or discussion for questions or suggestions before starting significant work!

{fastmcp-2.8.0 → fastmcp-2.9.0}/README.md

@@ -2,6 +2,7 @@
 
 <!-- omit in toc -->
 # FastMCP v2 🚀
+
 <strong>The fast, Pythonic way to build MCP servers and clients.</strong>
 
 *FastMCP is made with 💙 by [Prefect](https://www.prefect.io/)*
@@ -15,13 +16,16 @@
 </div>
 
 > [!Note]
+>
 > #### Beyond the Protocol
-> 
-> FastMCP is the standard framework for working with the Model Context Protocol. FastMCP 1.0 was incorporated into the [official low-level Python SDK](https://github.com/modelcontextprotocol/python-sdk), and FastMCP 2.0 *(this project)* provides a complete toolkit for working with the MCP ecosystem.
 >
-> FastMCP has a comprehensive set of features that go far beyond the core MCP specification, all in service of providing **the simplest path to production**. These include client support, server composition, auth, automatic generation from OpenAPI specs, remote server proxying, built-in testing tools, integrations, and more.
+> FastMCP is the standard framework for working with the Model Context Protocol. FastMCP 1.0 was incorporated into the [official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) in 2024.
+>
+> This is FastMCP 2.0, the **actively maintained version** that provides a complete toolkit for working with the MCP ecosystem.
 >
-> Ready to upgrade or get started? Follow the [installation instructions](/getting-started/installation), which include specific steps for upgrading from the official MCP SDK.
+> FastMCP 2.0 has a comprehensive set of features that go far beyond the core MCP specification, all in service of providing **the simplest path to production**. These include deployment, auth, clients, server proxying and composition, generating servers from REST APIs, dynamic tool rewriting, built-in testing tools, integrations, and more.
+>
+> Ready to upgrade or get started? Follow the [installation instructions](https://gofastmcp.com/getting-started/installation), which include steps for upgrading from the official MCP SDK.
 
 ---
 
@@ -43,6 +47,7 @@ if __name__ == "__main__":
 ```
 
 Run the server locally:
+
 ```bash
 fastmcp run server.py
 ```
@@ -51,9 +56,10 @@ fastmcp run server.py
 
 FastMCP's complete documentation is available at **[gofastmcp.com](https://gofastmcp.com)**, including detailed guides, API references, and advanced patterns. This readme provides only a high-level overview.
 
-Documentation is also available in [llms.txt format](https://llmstxt.org/), which is a simple markdown standard that LLMs can consume easily. 
+Documentation is also available in [llms.txt format](https://llmstxt.org/), which is a simple markdown standard that LLMs can consume easily.
 
 There are two ways to access the LLM-friendly documentation:
+
 - [`llms.txt`](https://gofastmcp.com/llms.txt) is essentially a sitemap, listing all the pages in the documentation.
 - [`llms-full.txt`](https://gofastmcp.com/llms-full.txt) contains the entire documentation. Note this may exceed the context window of your LLM.
 
@@ -143,7 +149,7 @@ Learn more in the [**FastMCP Server Documentation**](https://gofastmcp.com/serve
 
 ### Tools
 
-Tools allow LLMs to perform actions by executing your Python functions (sync or async). Ideal for computations, API calls, or side effects (like `POST`/`PUT`). FastMCP handles schema generation from type hints and docstrings. Tools can return various types, including text, JSON-serializable objects, and even images using the [`fastmcp.Image`](https://gofastmcp.com/servers/tools#return-values) helper.
+Tools allow LLMs to perform actions by executing your Python functions (sync or async). Ideal for computations, API calls, or side effects (like `POST`/`PUT`). FastMCP handles schema generation from type hints and docstrings. Tools can return various types, including text, JSON-serializable objects, and even images or audio aided by the FastMCP media helper classes.
 
 ```python
 @mcp.tool
@@ -189,12 +195,13 @@ Learn more in the [**Prompts Documentation**](https://gofastmcp.com/servers/prom
 ### Context
 
 Access MCP session capabilities within your tools, resources, or prompts by adding a `ctx: Context` parameter. Context provides methods for:
-*   **Logging:** Log messages to MCP clients with `ctx.info()`, `ctx.error()`, etc.
-*   **LLM Sampling:** Use `ctx.sample()` to request completions from the client's LLM.
-*   **HTTP Request:** Use `ctx.http_request()` to make HTTP requests to other servers.
-*   **Resource Access:** Use `ctx.read_resource()` to access resources on the server
-*   **Progress Reporting:** Use `ctx.report_progress()` to report progress to the client.
-*   and more...
+
+- **Logging:** Log messages to MCP clients with `ctx.info()`, `ctx.error()`, etc.
+- **LLM Sampling:** Use `ctx.sample()` to request completions from the client's LLM.
+- **HTTP Request:** Use `ctx.http_request()` to make HTTP requests to other servers.
+- **Resource Access:** Use `ctx.read_resource()` to access resources on the server
+- **Progress Reporting:** Use `ctx.report_progress()` to report progress to the client.
+- and more...
 
 To access the context, add a parameter annotated as `Context` to any mcp-decorated function. FastMCP will automatically inject the correct context object when the function is called.
 
@@ -334,16 +341,19 @@ if __name__ == "__main__":
 FastMCP supports three transport protocols:
 
 **STDIO (Default)**: Best for local tools and command-line scripts.
+
 ```python
 mcp.run(transport="stdio")  # Default, so transport argument is optional
 ```
 
 **Streamable HTTP**: Recommended for web deployments.
+
 ```python
-mcp.run(transport="streamable-http", host="127.0.0.1", port=8000, path="/mcp")
+mcp.run(transport="http", host="127.0.0.1", port=8000, path="/mcp")
 ```
 
 **SSE**: For compatibility with existing SSE clients.
+
 ```python
 mcp.run(transport="sse", host="127.0.0.1", port=8000)
 ```
@@ -356,22 +366,26 @@ Contributions are the core of open source! We welcome improvements and features.
 
 ### Prerequisites
 
-*   Python 3.10+
-*   [uv](https://docs.astral.sh/uv/) (Recommended for environment management)
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) (Recommended for environment management)
 
 ### Setup
 
-1. Clone the repository: 
+1. Clone the repository:
+
    ```bash
    git clone https://github.com/jlowin/fastmcp.git 
    cd fastmcp
    ```
-2. Create and sync the environment: 
+
+2. Create and sync the environment:
+
    ```bash
    uv sync
    ```
+
    This installs all dependencies, including dev tools.
-   
+
 3. Activate the virtual environment (e.g., `source .venv/bin/activate` or via your IDE).
 
 ### Unit Tests
@@ -379,10 +393,13 @@ Contributions are the core of open source! We welcome improvements and features.
 FastMCP has a comprehensive unit test suite. All PRs must introduce or update tests as appropriate and pass the full suite.
 
 Run tests using pytest:
+
 ```bash
 pytest
 ```
+
 or if you want an overview of the code coverage
+
 ```bash
 uv run pytest --cov=src --cov=examples --cov-report=html
 ```
@@ -392,10 +409,13 @@ uv run pytest --cov=src --cov=examples --cov-report=html
 FastMCP uses `pre-commit` for code formatting, linting, and type-checking. All PRs must pass these checks (they run automatically in CI).
 
 Install the hooks locally:
+
 ```bash
 uv run pre-commit install
 ```
+
 The hooks will now run automatically on `git commit`. You can also run them manually at any time:
+
 ```bash
 pre-commit run --all-files
 # or via uv
@@ -404,11 +424,11 @@ uv run pre-commit run --all-files
 
 ### Pull Requests
 
-1.  Fork the repository on GitHub.
-2.  Create a feature branch from `main`.
-3.  Make your changes, including tests and documentation updates.
-4.  Ensure tests and pre-commit hooks pass.
-5.  Commit your changes and push to your fork.
-6.  Open a pull request against the `main` branch of `jlowin/fastmcp`.
+1. Fork the repository on GitHub.
+2. Create a feature branch from `main`.
+3. Make your changes, including tests and documentation updates.
+4. Ensure tests and pre-commit hooks pass.
+5. Commit your changes and push to your fork.
+6. Open a pull request against the `main` branch of `jlowin/fastmcp`.
 
-Please open an issue or discussion for questions or suggestions before starting significant work!
+Please open an issue or discussion for questions or suggestions before starting significant work!