fastmcp 2.2.0__tar.gz → 2.2.2__tar.gz

fastmcp-2.2.2/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,63 @@
+name: 🐛 Bug Report
+description: Report a bug or unexpected behavior in FastMCP
+labels: [bug, pending]
+
+body:
+  - type: markdown
+    attributes:
+      value: Thank you for contributing to FastMCP! 🙏
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: |
+        Please explain what you're experiencing and what you would expect to happen instead.
+
+        Provide as much detail as possible to help us understand and solve your problem quickly.
+    validations:
+      required: true
+
+  - type: textarea
+    id: example
+    attributes:
+      label: Example Code
+      description: >
+        If applicable, please provide a self-contained,
+        [minimal, reproducible example](https://stackoverflow.com/help/minimal-reproducible-example)
+        demonstrating the bug.
+
+      placeholder: |
+        from fastmcp import FastMCP
+
+        ...
+      render: Python
+
+  - type: textarea
+    id: version
+    attributes:
+      label: Version Information
+      description: |
+        Please provide information about your FastMCP version, MCP version, Python version, and OS.
+
+        To get this information, run the following command in your terminal and paste the output below:
+
+        ```bash
+        fastmcp version
+        ```
+
+        If there is other information that would be helpful, please include it as well.
+      render: Text
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional_context
+    attributes:
+      label: Additional Context
+      description: |
+        Add any other context about the problem here. This could include:
+        - The full error message and traceback (if applicable)
+        - Information about your environment (e.g., virtual environment, installed packages)
+        - Steps to reproduce the issue
+        - Any recent changes in your code or setup that might be relevant

fastmcp-2.2.2/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: FastMCP Documentation
+    url: https://gofastmcp.com
+    about: Please review the documentation before opening an issue.
+  - name: MCP Python SDK
+    url: https://github.com/modelcontextprotocol/python-sdk/issues
+    about: Issues related to the low-level MCP Python SDK, including the FastMCP 1.0 module that is included in the `mcp` package, should be filed on the official MCP repository.

fastmcp-2.2.2/.github/ISSUE_TEMPLATE/enhancement.yml

@@ -0,0 +1,38 @@
+name: 💡 Enhancement Request
+description: Suggest an idea or improvement for FastMCP
+labels: [enhancement, pending]
+
+body:
+  - type: markdown
+    attributes:
+      value: Thank you for contributing to FastMCP! We value your ideas for improving the framework. 💡
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Enhancement Description
+      description: |
+        Please describe the enhancement you'd like to see in FastMCP.
+
+        - What problem would this solve?
+        - How would this improve your workflow or experience with FastMCP?
+        - Are there any alternative solutions you've considered?
+    validations:
+      required: true
+
+  - type: textarea
+    id: use_case
+    attributes:
+      label: Use Case
+      description: |
+        Describe a specific use case or scenario where this enhancement would be beneficial.
+        If possible, provide an example of how you envision using this feature.
+
+  - type: textarea
+    id: example
+    attributes:
+      label: Proposed Implementation
+      description: >
+        If you have ideas about how this enhancement could be implemented,
+        please share them here. Code snippets, pseudocode, or general approaches are welcome.
+      render: Python

{fastmcp-2.2.0 → fastmcp-2.2.2}/.github/workflows/run-tests.yml

@@ -60,4 +60,3 @@ jobs:
 
       - name: Run tests
         run: uv run pytest -vv
-        if: ${{ !(github.event.pull_request.head.repo.fork) }}

{fastmcp-2.2.0 → fastmcp-2.2.2}/.pre-commit-config.yaml

@@ -27,4 +27,3 @@ repos:
     hooks:
       - id: pyright-pretty
         files: ^src/|^tests/
-        exclude: ^examples/

{fastmcp-2.2.0 → fastmcp-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.2.0
+Version: 2.2.2
 Summary: The fast, Pythonic way to build MCP servers.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp
@@ -17,11 +17,11 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: dotenv>=0.9.9
 Requires-Dist: exceptiongroup>=1.2.2
 Requires-Dist: httpx>=0.28.1
 Requires-Dist: mcp<2.0.0,>=1.6.0
 Requires-Dist: openapi-pydantic>=0.5.1
+Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rich>=13.9.4
 Requires-Dist: typer>=0.15.2
 Requires-Dist: websockets>=15.0.1
@@ -95,6 +95,7 @@ FastMCP handles the complex protocol details and server management, letting you
   - [Proxy Servers](#proxy-servers)
   - [Composing MCP Servers](#composing-mcp-servers)
   - [OpenAPI \& FastAPI Generation](#openapi--fastapi-generation)
+  - [Handling `stderr`](#handling-stderr)
 - [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)
@@ -695,6 +696,12 @@ mcp_server = FastMCP.from_openapi(openapi_spec, client=http_client)
 if __name__ == "__main__":
     mcp_server.run()
 ```
+
+### Handling `stderr`
+The MCP spec allows for the server to write anything it wants to `stderr`, and it
+doesn't specify the format in any way. FastMCP will forward the server's `stderr`
+to the client's `stderr`.
+
 ## Running Your Server
 
 Choose the method that best suits your needs:

{fastmcp-2.2.0 → fastmcp-2.2.2}/README.md

@@ -66,6 +66,7 @@ FastMCP handles the complex protocol details and server management, letting you
   - [Proxy Servers](#proxy-servers)
   - [Composing MCP Servers](#composing-mcp-servers)
   - [OpenAPI \& FastAPI Generation](#openapi--fastapi-generation)
+  - [Handling `stderr`](#handling-stderr)
 - [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)
@@ -666,6 +667,12 @@ mcp_server = FastMCP.from_openapi(openapi_spec, client=http_client)
 if __name__ == "__main__":
     mcp_server.run()
 ```
+
+### Handling `stderr`
+The MCP spec allows for the server to write anything it wants to `stderr`, and it
+doesn't specify the format in any way. FastMCP will forward the server's `stderr`
+to the client's `stderr`.
+
 ## Running Your Server
 
 Choose the method that best suits your needs:

{fastmcp-2.2.0 → fastmcp-2.2.2}/docs/clients/client.mdx

@@ -226,6 +226,15 @@ MCP allows servers to make requests *back* to the client for certain capabilitie
     )
     ```
 
+### Utility Methods
+
+*   **`ping()`**: Sends a ping request to the server to verify connectivity.
+    ```python
+    async def check_connection():
+        async with client:
+            await client.ping()
+            print("Server is reachable")
+    ```
 
 ### Error Handling
 

{fastmcp-2.2.0 → fastmcp-2.2.2}/docs/docs.json

@@ -61,7 +61,8 @@
                     "patterns/composition",
                     "patterns/decorating-methods",
                     "patterns/openapi",
-                    "patterns/fastapi"
+                    "patterns/fastapi",
+                    "patterns/contrib"
                 ]
             },
             {

{fastmcp-2.2.0 → fastmcp-2.2.2}/docs/getting-started/quickstart.mdx

@@ -32,7 +32,7 @@ from fastmcp import FastMCP
 
 mcp = FastMCP("My MCP Server")
 
-@mcp.tool
+@mcp.tool()
 def greet(name: str) -> str:
     return f"Hello, {name}!"
 ```
@@ -48,7 +48,7 @@ from fastmcp import FastMCP, Client
 
 mcp = FastMCP("My MCP Server")
 
-@mcp.tool
+@mcp.tool()
 def greet(name: str) -> str:
     return f"Hello, {name}!"
 
@@ -75,7 +75,7 @@ from fastmcp import FastMCP, Client
 
 mcp = FastMCP("My MCP Server")
 
-@mcp.tool
+@mcp.tool()
 def greet(name: str) -> str:
     return f"Hello, {name}!"
 

fastmcp-2.2.2/docs/patterns/contrib.mdx

@@ -0,0 +1,42 @@
+---
+title: "Contrib Modules"
+description: "Community-contributed modules extending FastMCP"
+icon: "cubes"
+---
+
+
+FastMCP includes a `contrib` package that holds community-contributed modules. These modules extend FastMCP's functionality but aren't officially maintained by the core team.
+
+Contrib modules provide additional features, integrations, or patterns that complement the core FastMCP library. They offer a way for the community to share useful extensions while keeping the core library focused and maintainable.
+
+The available modules can be viewed in the [contrib directory](https://github.com/jlowin/fastmcp/tree/main/src/contrib).
+
+## Usage
+
+To use a contrib module, import it from the `fastmcp.contrib` package:
+
+```python
+from fastmcp.contrib import my_module
+```
+
+## Important Considerations
+
+- **Stability**: Modules in `contrib` may have different testing requirements or stability guarantees compared to the core library.
+- **Compatibility**: Changes to core FastMCP might break modules in `contrib` without explicit warnings in the main changelog.
+- **Dependencies**: Contrib modules may have additional dependencies not required by the core library. These dependencies are typically documented in the module's README or separate requirements files.
+
+## Contributing
+
+We welcome contributions to the `contrib` package! If you have a module that extends FastMCP in a useful way, consider contributing it:
+
+1. Create a new directory in `src/fastmcp/contrib/` for your module
+3. Add proper tests for your module in `tests/contrib/`
+2. Include comprehensive documentation in a README.md file, including usage and examples, as well as any additional dependencies or installation instructions
+5. Submit a pull request
+
+The ideal contrib module:
+- Solves a specific use case or integration need
+- Follows FastMCP coding standards
+- Includes thorough documentation and examples
+- Has comprehensive tests
+- Specifies any additional dependencies

{fastmcp-2.2.0 → fastmcp-2.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ dynamic = ["version"]
 description = "The fast, Pythonic way to build MCP servers."
 authors = [{ name = "Jeremiah Lowin" }]
 dependencies = [
-    "dotenv>=0.9.9",
+    "python-dotenv>=1.1.0",
     "exceptiongroup>=1.2.2",
     "httpx>=0.28.1",
     "mcp>=1.6.0,<2.0.0",

{fastmcp-2.2.0 → fastmcp-2.2.2}/src/fastmcp/cli/cli.py

@@ -186,7 +186,7 @@ def version(ctx: Context):
         "MCP version": importlib.metadata.version("mcp"),
         "Python version": platform.python_version(),
         "Platform": platform.platform(),
-        "FastMCP root path": f"~/{Path(__file__).resolve().parents[3].relative_to(Path.home())}",
+        "FastMCP root path": Path(fastmcp.__file__).resolve().parents[1],
     }
 
     g = Table.grid(padding=(0, 1))

{fastmcp-2.2.0 → fastmcp-2.2.2}/src/fastmcp/client/client.py

@@ -45,7 +45,8 @@ class Client:
     ):
         self.transport = infer_transport(transport)
         self._session: ClientSession | None = None
-        self._session_cms: list[AbstractAsyncContextManager[ClientSession]] = []
+        self._session_cm: AbstractAsyncContextManager[ClientSession] | None = None
+        self._nesting_counter: int = 0
 
         self._session_kwargs: SessionKwargs = {
             "sampling_callback": None,
@@ -85,29 +86,21 @@ class Client:
         return self._session is not None
 
     async def __aenter__(self):
-        if self.is_connected():
-            # We're already connected, no need to add None to the session_cms list
-            return self
-
-        try:
-            session_cm = self.transport.connect_session(**self._session_kwargs)
-            self._session_cms.append(session_cm)
-            self._session = await self._session_cms[-1].__aenter__()
-            return self
-        except Exception as e:
-            # Ensure cleanup if __aenter__ fails partially
-            self._session = None
-            if self._session_cms:
-                self._session_cms.pop()
-            raise ConnectionError(
-                f"Failed to connect using {self.transport}: {e}"
-            ) from e
+        if self._nesting_counter == 0:
+            # create new session
+            self._session_cm = self.transport.connect_session(**self._session_kwargs)
+            self._session = await self._session_cm.__aenter__()
+
+        self._nesting_counter += 1
+        return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
-        if self._session_cms:
-            await self._session_cms[-1].__aexit__(exc_type, exc_val, exc_tb)
+        self._nesting_counter -= 1
+
+        if self._nesting_counter == 0 and self._session_cm is not None:
+            await self._session_cm.__aexit__(exc_type, exc_val, exc_tb)
+            self._session_cm = None
             self._session = None
-            self._session_cms.pop()
 
     # --- MCP Client Methods ---
     async def ping(self) -> None:

{fastmcp-2.2.0 → fastmcp-2.2.2}/src/fastmcp/client/transports.py

@@ -3,6 +3,7 @@ import contextlib
 import datetime
 import os
 import shutil
+import sys
 from collections.abc import AsyncIterator
 from pathlib import Path
 from typing import (
@@ -185,7 +186,7 @@ class PythonStdioTransport(StdioTransport):
         args: list[str] | None = None,
         env: dict[str, str] | None = None,
         cwd: str | None = None,
-        python_cmd: str = "python",
+        python_cmd: str = sys.executable,
     ):
         """
         Initialize a Python transport.

fastmcp-2.2.2/src/fastmcp/contrib/README.md

@@ -0,0 +1,19 @@
+# FastMCP Contrib Modules
+
+This directory holds community-contributed modules for FastMCP. These modules extend FastMCP's functionality but are not officially maintained by the core team.
+
+**Guarantees:**
+*   Modules in `contrib` may have different testing requirements or stability guarantees compared to the core library.
+*   Changes to the core FastMCP library might break modules in `contrib` without explicit warnings in the main changelog.
+
+Use these modules at your own discretion. Contributions are welcome, but please include tests and documentation.
+
+## Usage
+
+To use a contrib module, import it from the `fastmcp.contrib` package.
+
+```python
+from fastmcp.contrib import my_module
+```
+
+Note that the contrib modules may have different dependencies than the core library, which can be noted in their respective README's or even separate requirements / dependency files.

fastmcp-2.2.2/src/fastmcp/contrib/bulk_tool_caller/README.md

@@ -0,0 +1,35 @@
+# Bulk Tool Caller
+
+This module provides the `BulkToolCaller` class, which extends the `MCPMixin` to offer tools for performing multiple tool calls in a single request to a FastMCP server. This can be useful for optimizing interactions with the server by reducing the overhead of individual tool calls.
+
+## Usage
+
+To use the `BulkToolCaller`, see the example [example.py](./example.py) file. The `BulkToolCaller` can be instantiated and then registered with a FastMCP server URL. It provides methods to call multiple tools in bulk, either different tools or the same tool with different arguments.
+
+
+## Provided Tools
+
+The `BulkToolCaller` provides the following tools:
+
+### `call_tools_bulk`
+
+Calls multiple different tools registered on the MCP server in a single request.
+
+- **Arguments:**
+    - `tool_calls` (list of `CallToolRequest`): A list of objects, where each object specifies the `tool` name and `arguments` for an individual tool call.
+    - `continue_on_error` (bool, optional): If `True`, continue executing subsequent tool calls even if a previous one resulted in an error. Defaults to `True`.
+
+- **Returns:**
+    A list of `CallToolRequestResult` objects, each containing the result (`isError`, `content`) and the original `tool` name and `arguments` for each call.
+
+### `call_tool_bulk`
+
+Calls a single tool registered on the MCP server multiple times with different arguments in a single request.
+
+- **Arguments:**
+    - `tool` (str): The name of the tool to call.
+    - `tool_arguments` (list of dict): A list of dictionaries, where each dictionary contains the arguments for an individual run of the tool.
+    - `continue_on_error` (bool, optional): If `True`, continue executing subsequent tool calls even if a previous one resulted in an error. Defaults to `True`.
+
+- **Returns:**
+    A list of `CallToolRequestResult` objects, each containing the result (`isError`, `content`) and the original `tool` name and `arguments` for each call.

fastmcp-2.2.2/src/fastmcp/contrib/bulk_tool_caller/__init__.py

@@ -0,0 +1,3 @@
+from .bulk_tool_caller import BulkToolCaller
+
+__all__ = ["BulkToolCaller"]

fastmcp-2.2.2/src/fastmcp/contrib/bulk_tool_caller/bulk_tool_caller.py

@@ -0,0 +1,135 @@
+from typing import Any
+
+from mcp.types import CallToolResult
+from pydantic import BaseModel, Field
+
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.transports import FastMCPTransport
+from fastmcp.contrib.mcp_mixin.mcp_mixin import (
+    _DEFAULT_SEPARATOR_TOOL,
+    MCPMixin,
+    mcp_tool,
+)
+
+
+class CallToolRequest(BaseModel):
+    """A class to represent a request to call a tool with specific arguments."""
+
+    tool: str = Field(description="The name of the tool to call.")
+    arguments: dict[str, Any] = Field(
+        description="A dictionary containing the arguments for the tool call."
+    )
+
+
+class CallToolRequestResult(CallToolResult):
+    """
+    A class to represent the result of a bulk tool call.
+    It extends CallToolResult to include information about the requested tool call.
+    """
+
+    tool: str = Field(description="The name of the tool that was called.")
+    arguments: dict[str, Any] = Field(
+        description="The arguments used for the tool call."
+    )
+
+    @classmethod
+    def from_call_tool_result(
+        cls, result: CallToolResult, tool: str, arguments: dict[str, Any]
+    ) -> "CallToolRequestResult":
+        """
+        Create a CallToolRequestResult from a CallToolResult.
+        """
+        return cls(
+            tool=tool,
+            arguments=arguments,
+            isError=result.isError,
+            content=result.content,
+        )
+
+
+class BulkToolCaller(MCPMixin):
+    """
+    A class to provide a "bulk tool call" tool for a FastMCP server
+    """
+
+    def register_tools(
+        self,
+        mcp_server: "FastMCP",
+        prefix: str | None = None,
+        separator: str = _DEFAULT_SEPARATOR_TOOL,
+    ) -> None:
+        """
+        Register the tools provided by this class with the given MCP server.
+        """
+        self.connection = FastMCPTransport(mcp_server)
+
+        super().register_tools(mcp_server=mcp_server)
+
+    @mcp_tool()
+    async def call_tools_bulk(
+        self, tool_calls: list[CallToolRequest], continue_on_error: bool = True
+    ) -> list[CallToolRequestResult]:
+        """
+        Call multiple tools registered on this MCP server in a single request. Each call can
+         be for a different tool and can include different arguments. Useful for speeding up
+         what would otherwise take several individual tool calls.
+        """
+        results = []
+
+        for tool_call in tool_calls:
+            result = await self._call_tool(tool_call.tool, tool_call.arguments)
+
+            results.append(result)
+
+            if result.isError and not continue_on_error:
+                return results
+
+        return results
+
+    @mcp_tool()
+    async def call_tool_bulk(
+        self,
+        tool: str,
+        tool_arguments: list[dict[str, str | int | float | bool | None]],
+        continue_on_error: bool = True,
+    ) -> list[CallToolRequestResult]:
+        """
+        Call a single tool registered on this MCP server multiple times with a single request.
+         Each call can include different arguments. Useful for speeding up what would otherwise
+         take several individual tool calls.
+
+        Args:
+            tool: The name of the tool to call.
+            tool_arguments: A list of dictionaries, where each dictionary contains the arguments for an individual run of the tool.
+        """
+        results = []
+
+        for tool_call_arguments in tool_arguments:
+            result = await self._call_tool(tool, tool_call_arguments)
+
+            results.append(result)
+
+            if result.isError and not continue_on_error:
+                return results
+
+        return results
+
+    async def _call_tool(
+        self, tool: str, arguments: dict[str, Any]
+    ) -> CallToolRequestResult:
+        """
+        Helper method to call a tool with the provided arguments.
+        """
+
+        async with Client(self.connection) as client:
+            result = await client.call_tool(
+                name=tool, arguments=arguments, _return_raw_result=True
+            )
+
+            return CallToolRequestResult(
+                tool=tool,
+                arguments=arguments,
+                isError=result.isError,
+                content=result.content,
+            )

fastmcp-2.2.2/src/fastmcp/contrib/bulk_tool_caller/example.py

@@ -0,0 +1,17 @@
+"""Sample code for FastMCP using MCPMixin."""
+
+from fastmcp import FastMCP
+from fastmcp.contrib.bulk_tool_caller import BulkToolCaller
+
+mcp = FastMCP()
+
+
+@mcp.tool()
+def echo_tool(text: str) -> str:
+    """Echo the input text"""
+    return text
+
+
+bulk_tool_caller = BulkToolCaller()
+
+bulk_tool_caller.register_tools(mcp)

fastmcp-2.2.2/src/fastmcp/contrib/mcp_mixin/README.md

@@ -0,0 +1,39 @@
+# MCP Mixin
+
+This module provides the `MCPMixin` base class and associated decorators (`@mcp_tool`, `@mcp_resource`, `@mcp_prompt`).
+
+It allows developers to easily define classes whose methods can be registered as tools, resources, or prompts with a `FastMCP` server instance using the `register_all()`, `register_tools()`, `register_resources()`, or `register_prompts()` methods provided by the mixin.
+
+## Usage
+
+Inherit from `MCPMixin` and use the decorators on the methods you want to register.
+
+```python
+from fastmcp import FastMCP
+from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool, mcp_resource
+
+class MyComponent(MCPMixin):
+    @mcp_tool(name="my_tool", description="Does something cool.")
+    def tool_method(self):
+        return "Tool executed!"
+
+    @mcp_resource(uri="component://data")
+    def resource_method(self):
+        return {"data": "some data"}
+
+mcp_server = FastMCP()
+component = MyComponent()
+
+# Register all decorated methods with a prefix
+# Useful if you will have multiple instantiated objects of the same class
+# and want to avoid name collisions.
+component.register_all(mcp_server, prefix="my_comp") 
+
+# Register without a prefix
+# component.register_all(mcp_server) 
+
+# Now 'my_comp_my_tool' tool and 'my_comp+component://data' resource are registered (if prefix used)
+# Or 'my_tool' and 'component://data' are registered (if no prefix used)
+```
+
+The `prefix` argument in registration methods is optional. If omitted, methods are registered with their original decorated names/URIs. Individual separators (`tools_separator`, `resources_separator`, `prompts_separator`) can also be provided to `register_all` to change the separator for specific types.

fastmcp-2.2.2/src/fastmcp/contrib/mcp_mixin/__init__.py

@@ -0,0 +1,8 @@
+from .mcp_mixin import MCPMixin, mcp_tool, mcp_resource, mcp_prompt
+
+__all__ = [
+    "MCPMixin",
+    "mcp_tool",
+    "mcp_resource",
+    "mcp_prompt",
+]