fastmcp 2.2.8__tar.gz → 2.2.10__tar.gz

{fastmcp-2.2.8 → fastmcp-2.2.10}/.github/ISSUE_TEMPLATE/bug.yml

@@ -27,10 +27,15 @@ body:
         [minimal, reproducible example](https://stackoverflow.com/help/minimal-reproducible-example)
         demonstrating the bug.
 
+        If possible, your example should be a single-file script. Instead of `.run()`-ing an MCP server, use a `Client` to directly interact with it (`async with Client(mcp) as client: ...`) and demonstrate the issue.
+
       placeholder: |
-        from fastmcp import FastMCP
+        from fastmcp import FastMCP, Client
+
+        mcp = FastMCP()
 
-        ...
+        async with Client(mcp) as client:
+            ...
       render: Python
 
   - type: textarea

{fastmcp-2.2.8 → fastmcp-2.2.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.2.8
+Version: 2.2.10
 Summary: The fast, Pythonic way to build MCP servers.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp
@@ -379,6 +379,10 @@ 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
+```
 
 ### Static Checks
 

{fastmcp-2.2.8 → fastmcp-2.2.10}/README.md

@@ -350,6 +350,10 @@ 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
+```
 
 ### Static Checks
 

{fastmcp-2.2.8 → fastmcp-2.2.10}/docs/clients/client.mdx

@@ -155,6 +155,8 @@ The standard client methods return user-friendly representations that may change
 
 ### Raw MCP Protocol Objects
 
+<VersionBadge version="2.2.7" />
+
 The FastMCP client attempts to provide a "friendly" interface to the MCP protocol, but sometimes you may need access to the raw MCP protocol objects. Each of the main client methods that returns data has a corresponding `*_mcp` method that returns the raw MCP protocol objects directly.
 
 <Warning>

{fastmcp-2.2.8 → fastmcp-2.2.10}/docs/docs.json

@@ -20,6 +20,11 @@
             "x": "https://x.com/jlowin"
         }
     },
+    "integrations": {
+        "ga4": {
+            "measurementId": "G-64R5W1TJXG"
+        }
+    },
     "name": "FastMCP",
     "navbar": {
         "primary": {

{fastmcp-2.2.8 → fastmcp-2.2.10}/docs/getting-started/quickstart.mdx

@@ -43,7 +43,8 @@ def greet(name: str) -> str:
 
 To test the server, create a FastMCP client and point it at the server object.
 
-```python my_server.py {1, 9-16}
+```python my_server.py {1-2, 10-17}
+import asyncio
 from fastmcp import FastMCP, Client
 
 mcp = FastMCP("My MCP Server")

{fastmcp-2.2.8 → fastmcp-2.2.10}/docs/servers/tools.mdx

@@ -708,3 +708,13 @@ The duplicate behavior options are:
 -   `"error"`: Raises a `ValueError`, preventing the duplicate registration.
 -   `"replace"`: Silently replaces the existing tool with the new one.
 -   `"ignore"`: Keeps the original tool and ignores the new registration attempt.
+
+### Legacy JSON Parsing
+
+<VersionBadge version="2.2.10" />
+
+FastMCP 1.0 and < 2.2.10 relied on a crutch that attempted to work around LLM limitations by automatically parsing stringified JSON in tool arguments (e.g., converting `"[1,2,3]"` to `[1,2,3]`). As of FastMCP 2.2.10, this behavior is disabled by default because it circumvents type validation and can lead to unexpected type coercion issues (e.g. parsing "true" as a bool and attempting to call a tool that expected a string, which would fail type validation).
+
+Most modern LLMs correctly format JSON, but if working with models that unnecessarily stringify JSON (as was the case with Claude Desktop in late 2024), you can re-enable this behavior on your server by setting the environment variable `FASTMCP_TOOL_ATTEMPT_PARSE_JSON_ARGS=1`.
+
+We strongly recommend leaving this disabled unless necessary.

{fastmcp-2.2.8 → fastmcp-2.2.10}/examples/desktop.py

@@ -19,6 +19,13 @@ def desktop() -> list[str]:
     return [str(f) for f in desktop.iterdir()]
 
 
+# Add a dynamic greeting resource
+@mcp.resource("greeting://{name}")
+def get_greeting(name: str) -> str:
+    """Get a personalized greeting"""
+    return f"Hello, {name}!"
+
+
 @mcp.tool()
 def add(a: int, b: int) -> int:
     """Add two numbers"""

{fastmcp-2.2.8 → fastmcp-2.2.10}/pyproject.toml

@@ -47,7 +47,9 @@ dev = [
     "pyright>=1.1.389",
     "pytest>=8.3.3",
     "pytest-asyncio>=0.23.5",
+    "pytest-cov>=6.1.1",
     "pytest-flakefinder",
+    "pytest-report>=0.2.1",
     "pytest-xdist>=3.6.1",
     "ruff",
 ]

{fastmcp-2.2.8 → fastmcp-2.2.10}/src/fastmcp/server/server.py

@@ -14,6 +14,7 @@ from typing import TYPE_CHECKING, Any, Generic, Literal
 
 import anyio
 import httpx
+import pydantic
 import uvicorn
 from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
 from mcp.server.auth.middleware.bearer_auth import (
@@ -39,7 +40,7 @@ from mcp.types import Prompt as MCPPrompt
 from mcp.types import Resource as MCPResource
 from mcp.types import ResourceTemplate as MCPResourceTemplate
 from mcp.types import Tool as MCPTool
-from pydantic.networks import AnyUrl
+from pydantic import AnyUrl
 from starlette.applications import Starlette
 from starlette.middleware import Middleware
 from starlette.middleware.authentication import AuthenticationMiddleware
@@ -88,6 +89,8 @@ class MountedServer:
         if prompt_separator is None:
             prompt_separator = "_"
 
+        _validate_resource_prefix(f"{prefix}{resource_separator}")
+
         self.server = server
         self.prefix = prefix
         self.tool_separator = tool_separator
@@ -1074,6 +1077,7 @@ class FastMCP(Generic[LifespanResultT]):
 
         # Import resources and templates from the mounted server
         resource_prefix = f"{prefix}{resource_separator}"
+        _validate_resource_prefix(resource_prefix)
         for key, resource in (await server.get_resources()).items():
             self._resource_manager.add_resource(resource, key=f"{resource_prefix}{key}")
         for key, template in (await server.get_resource_templates()).items():
@@ -1131,3 +1135,13 @@ class FastMCP(Generic[LifespanResultT]):
         from fastmcp.server.proxy import FastMCPProxy
 
         return FastMCPProxy(client=client, **settings)
+
+
+def _validate_resource_prefix(prefix: str) -> None:
+    valid_resource = "resource://path/to/resource"
+    try:
+        AnyUrl(f"{prefix}{valid_resource}")
+    except pydantic.ValidationError as e:
+        raise ValueError(
+            f"Resource prefix or separator would result in an invalid resource URI: {e}"
+        )

{fastmcp-2.2.8 → fastmcp-2.2.10}/src/fastmcp/settings.py

@@ -27,6 +27,16 @@ class Settings(BaseSettings):
 
     test_mode: bool = False
     log_level: LOG_LEVEL = "INFO"
+    tool_attempt_parse_json_args: bool = Field(
+        default=False,
+        description="""
+        Note: this enables a legacy behavior. If True, will attempt to parse
+        stringified JSON lists and objects strings in tool arguments before
+        passing them to the tool. This is an old behavior that can create
+        unexpected type coercion issues, but may be helpful for less powerful
+        LLMs that stringify JSON instead of passing actual lists and objects.
+        Defaults to False.""",
+    )
 
 
 class ServerSettings(BaseSettings):
@@ -83,3 +93,6 @@ class ClientSettings(BaseSettings):
     )
 
     log_level: LOG_LEVEL = Field(default_factory=lambda: Settings().log_level)
+
+
+settings = Settings()

{fastmcp-2.2.8 → fastmcp-2.2.10}/src/fastmcp/tools/tool.py

@@ -10,6 +10,7 @@ from mcp.types import EmbeddedResource, ImageContent, TextContent, ToolAnnotatio
 from mcp.types import Tool as MCPTool
 from pydantic import BaseModel, BeforeValidator, Field
 
+import fastmcp
 from fastmcp.exceptions import ToolError
 from fastmcp.utilities.json_schema import prune_params
 from fastmcp.utilities.logging import get_logger
@@ -107,6 +108,7 @@ class Tool(BaseModel):
         context: Context[ServerSessionT, LifespanContextT] | None = None,
     ) -> list[TextContent | ImageContent | EmbeddedResource]:
         """Run the tool with arguments."""
+
         try:
             injected_args = (
                 {self.context_kwarg: context} if self.context_kwarg is not None else {}
@@ -114,16 +116,32 @@ class Tool(BaseModel):
 
             parsed_args = arguments.copy()
 
-            # Pre-parse data from JSON in order to handle cases like `["a", "b", "c"]`
-            # being passed in as JSON inside a string rather than an actual list.
-            #
-            # Claude desktop is prone to this - in fact it seems incapable of NOT doing
-            # this. For sub-models, it tends to pass dicts (JSON objects) as JSON strings,
-            # which can be pre-parsed here.
-            for param_name in self.parameters["properties"]:
-                if isinstance(parsed_args.get(param_name, None), str):
+            if fastmcp.settings.settings.tool_attempt_parse_json_args:
+                # Pre-parse data from JSON in order to handle cases like `["a", "b", "c"]`
+                # being passed in as JSON inside a string rather than an actual list.
+                #
+                # Claude desktop is prone to this - in fact it seems incapable of NOT doing
+                # this. For sub-models, it tends to pass dicts (JSON objects) as JSON strings,
+                # which can be pre-parsed here.
+                signature = inspect.signature(self.fn)
+                for param_name in self.parameters["properties"]:
+                    arg = parsed_args.get(param_name, None)
+                    # if not in signature, we won't have annotations, so skip logic
+                    if param_name not in signature.parameters:
+                        continue
+                    # if not a string, we won't have a JSON to parse, so skip logic
+                    if not isinstance(arg, str):
+                        continue
+                    # skip if the type is a simple type (int, float, bool)
+                    if signature.parameters[param_name].annotation in (
+                        int,
+                        float,
+                        bool,
+                    ):
+                        continue
                     try:
-                        parsed_args[param_name] = json.loads(parsed_args[param_name])
+                        parsed_args[param_name] = json.loads(arg)
+
                     except json.JSONDecodeError:
                         pass
 

fastmcp-2.2.10/src/fastmcp/utilities/tests.py

@@ -0,0 +1,41 @@
+import copy
+from contextlib import contextmanager
+from typing import Any
+
+from fastmcp.settings import settings
+
+
+@contextmanager
+def temporary_settings(**kwargs: Any):
+    """
+    Temporarily override ControlFlow setting values.
+
+    Args:
+        **kwargs: The settings to override, including nested settings.
+
+    Example:
+        Temporarily override a setting:
+        ```python
+        import fastmcp
+        from fastmcp.utilities.tests import temporary_settings
+
+        with temporary_settings(log_level='DEBUG'):
+            assert fastmcp.settings.settings.log_level == 'DEBUG'
+        assert fastmcp.settings.settings.log_level == 'INFO'
+        ```
+    """
+    old_settings = copy.deepcopy(settings.model_dump())
+
+    try:
+        # apply the new settings
+        for attr, value in kwargs.items():
+            if not hasattr(settings, attr):
+                raise AttributeError(f"Setting {attr} does not exist.")
+            setattr(settings, attr, value)
+        yield
+
+    finally:
+        # restore the old settings
+        for attr in kwargs:
+            if hasattr(settings, attr):
+                setattr(settings, attr, old_settings[attr])

{fastmcp-2.2.8 → fastmcp-2.2.10}/tests/server/test_import_server.py

@@ -1,6 +1,7 @@
 import json
 from urllib.parse import quote
 
+import pytest
 from mcp.types import TextContent, TextResourceContents
 
 from fastmcp.client.client import Client
@@ -391,3 +392,25 @@ async def test_import_with_proxy_resource_templates():
         user_data = json.loads(result[0].text)
         assert user_data["name"] == "John Doe"
         assert user_data["email"] == "john@example.com"
+
+
+async def test_import_invalid_resource_prefix():
+    main_app = FastMCP("MainApp")
+    api_app = FastMCP("APIApp")
+
+    with pytest.raises(
+        ValueError,
+        match="Resource prefix or separator would result in an invalid resource URI",
+    ):
+        await main_app.import_server("api_sub", api_app)
+
+
+async def test_import_invalid_resource_separator():
+    main_app = FastMCP("MainApp")
+    api_app = FastMCP("APIApp")
+
+    with pytest.raises(
+        ValueError,
+        match="Resource prefix or separator would result in an invalid resource URI",
+    ):
+        await main_app.import_server("api", api_app, resource_separator="_")

{fastmcp-2.2.8 → fastmcp-2.2.10}/tests/server/test_mount.py

@@ -59,6 +59,26 @@ class TestBasicMount:
         assert isinstance(result[0], TextContent)
         assert result[0].text == "Hello, World!"
 
+    async def test_mount_invalid_resource_prefix(self):
+        main_app = FastMCP("MainApp")
+        api_app = FastMCP("APIApp")
+
+        with pytest.raises(
+            ValueError,
+            match="Resource prefix or separator would result in an invalid resource URI",
+        ):
+            main_app.mount("api_sub", api_app)
+
+    async def test_mount_invalid_resource_separator(self):
+        main_app = FastMCP("MainApp")
+        api_app = FastMCP("APIApp")
+
+        with pytest.raises(
+            ValueError,
+            match="Resource prefix or separator would result in an invalid resource URI",
+        ):
+            main_app.mount("api", api_app, resource_separator="_")
+
     async def test_unmount_server(self):
         """Test unmounting a server removes access to its tools."""
         main_app = FastMCP("MainApp")

{fastmcp-2.2.8 → fastmcp-2.2.10}/tests/server/test_server_interactions.py

@@ -349,81 +349,6 @@ class TestToolParameters:
             assert isinstance(result[0], TextContent)
             assert result[0].text == "true"
 
-    async def test_tool_list_coercion(self):
-        """Test JSON string to collection type coercion."""
-        mcp = FastMCP()
-
-        @mcp.tool()
-        def process_list(items: list[int]) -> int:
-            return sum(items)
-
-        async with Client(mcp) as client:
-            # JSON array string should be coerced to list
-            result = await client.call_tool(
-                "process_list", {"items": "[1, 2, 3, 4, 5]"}
-            )
-            assert isinstance(result[0], TextContent)
-            assert result[0].text == "15"
-
-    async def test_tool_list_coercion_error(self):
-        """Test that a list coercion error is raised if the input is not a valid list."""
-        mcp = FastMCP()
-
-        @mcp.tool()
-        def process_list(items: list[int]) -> int:
-            return sum(items)
-
-        async with Client(mcp) as client:
-            with pytest.raises(
-                ClientError,
-                match="Input should be a valid list",
-            ):
-                await client.call_tool("process_list", {"items": "['a', 'b', 3]"})
-
-    async def test_tool_dict_coercion(self):
-        """Test JSON string to dict type coercion."""
-        mcp = FastMCP()
-
-        @mcp.tool()
-        def process_dict(data: dict[str, int]) -> int:
-            return sum(data.values())
-
-        async with Client(mcp) as client:
-            # JSON object string should be coerced to dict
-            result = await client.call_tool(
-                "process_dict", {"data": '{"a": 1, "b": "2", "c": 3}'}
-            )
-            assert isinstance(result[0], TextContent)
-            assert result[0].text == "6"
-
-    async def test_tool_set_coercion(self):
-        """Test JSON string to set type coercion."""
-        mcp = FastMCP()
-
-        @mcp.tool()
-        def process_set(items: set[int]) -> int:
-            assert isinstance(items, set)
-            return sum(items)
-
-        async with Client(mcp) as client:
-            result = await client.call_tool("process_set", {"items": "[1, 2, 3, 4, 5]"})
-            assert isinstance(result[0], TextContent)
-            assert result[0].text == "15"
-
-    async def test_tool_tuple_coercion(self):
-        """Test JSON string to tuple type coercion."""
-        mcp = FastMCP()
-
-        @mcp.tool()
-        def process_tuple(items: tuple[int, str]) -> int:
-            assert isinstance(items, tuple)
-            return items[0] + len(items[1])
-
-        async with Client(mcp) as client:
-            result = await client.call_tool("process_tuple", {"items": '["1", "two"]'})
-            assert isinstance(result[0], TextContent)
-            assert result[0].text == "4"
-
     async def test_annotated_field_validation(self):
         mcp = FastMCP()
 

fastmcp-2.2.10/tests/test_examples.py

@@ -0,0 +1,92 @@
+"""Tests for example servers"""
+
+import pytest
+from mcp.types import (
+    PromptMessage,
+    TextContent,
+    TextResourceContents,
+)
+from pydantic import AnyUrl
+
+from fastmcp import Client
+
+
+@pytest.mark.anyio
+async def test_simple_echo():
+    """Test the simple echo server"""
+    from examples.simple_echo import mcp
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("echo", {"text": "hello"})
+        assert len(result) == 1
+        assert isinstance(result[0], TextContent)
+        assert result[0].text == "hello"
+
+
+@pytest.mark.anyio
+async def test_complex_inputs():
+    """Test the complex inputs server"""
+    from examples.complex_inputs import mcp
+
+    async with Client(mcp) as client:
+        tank = {"shrimp": [{"name": "bob"}, {"name": "alice"}]}
+        result = await client.call_tool(
+            "name_shrimp", {"tank": tank, "extra_names": ["charlie"]}
+        )
+        assert len(result) == 1
+        assert isinstance(result[0], TextContent)
+        assert result[0].text == '[\n  "bob",\n  "alice",\n  "charlie"\n]'
+
+
+@pytest.mark.anyio
+async def test_desktop(monkeypatch):
+    """Test the desktop server"""
+    from examples.desktop import mcp
+
+    async with Client(mcp) as client:
+        # Test the add function
+        result = await client.call_tool("add", {"a": 1, "b": 2})
+        assert len(result) == 1
+        assert isinstance(result[0], TextContent)
+        assert result[0].text == "3"
+
+    async with Client(mcp) as client:
+        result = await client.read_resource(AnyUrl("greeting://rooter12"))
+        assert len(result) == 1
+        assert isinstance(result[0], TextResourceContents)
+        assert isinstance(result[0].text, str)
+        assert result[0].text == "Hello, rooter12!"
+
+
+@pytest.mark.anyio
+async def test_echo():
+    """Test the echo server"""
+    from examples.echo import mcp
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("echo_tool", {"text": "hello"})
+        assert len(result) == 1
+        assert isinstance(result[0], TextContent)
+        assert result[0].text == "hello"
+
+    async with Client(mcp) as client:
+        result = await client.read_resource(AnyUrl("echo://static"))
+        assert len(result) == 1
+        assert isinstance(result[0], TextResourceContents)
+        assert isinstance(result[0].text, str)
+        assert result[0].text == "Echo!"
+
+    async with Client(mcp) as client:
+        result = await client.read_resource(AnyUrl("echo://server42"))
+        assert len(result) == 1
+        assert isinstance(result[0], TextResourceContents)
+        assert isinstance(result[0].text, str)
+        assert result[0].text == "Echo: server42"
+
+    async with Client(mcp) as client:
+        result = await client.get_prompt("echo", {"text": "hello"})
+        assert len(result.messages) == 1
+        assert isinstance(result.messages[0], PromptMessage)
+        assert isinstance(result.messages[0].content, TextContent)
+        assert isinstance(result.messages[0].content.text, str)
+        assert result.messages[0].content.text == "hello"

{fastmcp-2.2.8 → fastmcp-2.2.10}/tests/tools/test_tool.py

@@ -2,8 +2,11 @@ import pytest
 from mcp.types import ImageContent, TextContent
 from pydantic import BaseModel
 
-from fastmcp import Image
+from fastmcp import FastMCP, Image
+from fastmcp.client import Client
+from fastmcp.exceptions import ClientError
 from fastmcp.tools.tool import Tool
+from fastmcp.utilities.tests import temporary_settings
 
 
 class TestToolFromFunction:
@@ -150,9 +153,14 @@ class TestToolFromFunction:
             x: int = 10
 
 
-class TestToolJsonParsing:
+class TestLegacyToolJsonParsing:
     """Tests for Tool's JSON pre-parsing functionality."""
 
+    @pytest.fixture(autouse=True)
+    def enable_legacy_json_parsing(self):
+        with temporary_settings(tool_attempt_parse_json_args=True):
+            yield
+
     async def test_json_string_arguments(self):
         """Test that JSON string arguments are parsed and validated correctly"""
 
@@ -264,3 +272,78 @@ class TestToolJsonParsing:
         invalid_json = '{"x": 1, "y": {"invalid": "hello"}}'
         with pytest.raises(Exception):
             await tool.run({"data": invalid_json})
+
+    async def test_tool_list_coercion(self):
+        """Test JSON string to collection type coercion."""
+        mcp = FastMCP()
+
+        @mcp.tool()
+        def process_list(items: list[int]) -> int:
+            return sum(items)
+
+        async with Client(mcp) as client:
+            # JSON array string should be coerced to list
+            result = await client.call_tool(
+                "process_list", {"items": "[1, 2, 3, 4, 5]"}
+            )
+            assert isinstance(result[0], TextContent)
+            assert result[0].text == "15"
+
+    async def test_tool_list_coercion_error(self):
+        """Test that a list coercion error is raised if the input is not a valid list."""
+        mcp = FastMCP()
+
+        @mcp.tool()
+        def process_list(items: list[int]) -> int:
+            return sum(items)
+
+        async with Client(mcp) as client:
+            with pytest.raises(
+                ClientError,
+                match="Input should be a valid list",
+            ):
+                await client.call_tool("process_list", {"items": "['a', 'b', 3]"})
+
+    async def test_tool_dict_coercion(self):
+        """Test JSON string to dict type coercion."""
+        mcp = FastMCP()
+
+        @mcp.tool()
+        def process_dict(data: dict[str, int]) -> int:
+            return sum(data.values())
+
+        async with Client(mcp) as client:
+            # JSON object string should be coerced to dict
+            result = await client.call_tool(
+                "process_dict", {"data": '{"a": 1, "b": "2", "c": 3}'}
+            )
+            assert isinstance(result[0], TextContent)
+            assert result[0].text == "6"
+
+    async def test_tool_set_coercion(self):
+        """Test JSON string to set type coercion."""
+        mcp = FastMCP()
+
+        @mcp.tool()
+        def process_set(items: set[int]) -> int:
+            assert isinstance(items, set)
+            return sum(items)
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("process_set", {"items": "[1, 2, 3, 4, 5]"})
+            assert isinstance(result[0], TextContent)
+            assert result[0].text == "15"
+
+    async def test_tool_tuple_coercion(self):
+        """Test JSON string to tuple type coercion."""
+        mcp = FastMCP()
+
+        @mcp.tool()
+        def process_tuple(items: tuple[int, str]) -> int:
+            assert isinstance(items, tuple)
+            return items[0] + len(items[1])
+
+        async with Client(mcp) as client:
+            result = await client.call_tool("process_tuple", {"items": '["1", "two"]'})
+            assert isinstance(result[0], TextContent)
+            assert result[0].text == "4"