fastmcp 2.2.0__tar.gz → 2.2.1__tar.gz

fastmcp-2.2.1/.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.1/.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.1/.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.1}/.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.1}/.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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.2.0
+Version: 2.2.1
 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.1}/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.1}/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.0 → fastmcp-2.2.1}/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.1/src/contrib/README.md

@@ -0,0 +1,9 @@
+# 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.

fastmcp-2.2.1/src/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.1/src/contrib/bulk_tool_caller/__init__.py

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

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

@@ -0,0 +1,131 @@
+from typing import Any
+
+from mcp.types import CallToolResult
+from pydantic import BaseModel, Field
+
+from contrib.mcp_mixin.mcp_mixin import _DEFAULT_SEPARATOR_TOOL, MCPMixin, mcp_tool
+from fastmcp import FastMCP
+from fastmcp.client import Client
+from fastmcp.client.transports import FastMCPTransport
+
+
+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.1/src/contrib/bulk_tool_caller/example.py

@@ -0,0 +1,17 @@
+"""Sample code for FastMCP using MCPMixin."""
+
+from contrib.bulk_tool_caller import BulkToolCaller
+from fastmcp import FastMCP
+
+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.1/src/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 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.1/src/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",
+]

fastmcp-2.2.1/src/contrib/mcp_mixin/example.py

@@ -0,0 +1,52 @@
+"""Sample code for FastMCP using MCPMixin."""
+
+import asyncio
+
+from contrib.mcp_mixin import (
+    MCPMixin,
+    mcp_prompt,
+    mcp_resource,
+    mcp_tool,
+)
+from fastmcp import FastMCP
+
+mcp = FastMCP()
+
+
+class Sample(MCPMixin):
+    def __init__(self, name):
+        self.name = name
+
+    @mcp_tool()
+    def first_tool(self):
+        """First tool description."""
+        return f"Executed tool {self.name}."
+
+    @mcp_resource(uri="test://test")
+    def first_resource(self):
+        """First resource description."""
+        return f"Executed resource {self.name}."
+
+    @mcp_prompt()
+    def first_prompt(self):
+        """First prompt description."""
+        return f"here's a prompt! {self.name}."
+
+
+first_sample = Sample("First")
+second_sample = Sample("Second")
+
+first_sample.register_all(mcp_server=mcp, prefix="first")
+second_sample.register_all(mcp_server=mcp, prefix="second")
+
+
+async def list_components():
+    print("MCP Server running with registered components...")
+    print("Tools:", list(await mcp.get_tools()))
+    print("Resources:", list(await mcp.get_resources()))
+    print("Prompts:", list(await mcp.get_prompts()))
+
+
+if __name__ == "__main__":
+    asyncio.run(list_components())
+    mcp.run()