fastmcp 0.3.4__tar.gz → 0.3.5__tar.gz

fastmcp-0.3.5/.github/ai-labeler.yml

@@ -0,0 +1,88 @@
+instructions: |
+  Apply the minimal set of labels that accurately characterize the issue/PR:
+  - Use at most 1-2 labels unless there's a compelling reason for more
+  - Prefer specific labels (bug, feature) over generic ones (question, help wanted)
+  - For PRs that fix bugs, use 'bug' not 'enhancement'
+  - Never combine: bug + enhancement, feature + enhancement. For these labels, only choose the most relevant one.
+  - Reserve 'question' and 'help wanted' for when they're the primary characteristic
+
+labels:
+  - bug:
+    description: "Something isn't working as expected"
+    instructions: |
+      Apply when describing or fixing unexpected behavior:
+      - Issues: Clear error messages or unexpected outcomes
+      - PRs: Fixes for broken functionality
+      Don't apply enhancement/feature for bug fixes unless they add significant new functionality
+      beyond fixing the bug
+
+  - documentation:
+    description: "Improvements or additions to documentation"
+    instructions: |
+      Apply only when documentation is the primary focus:
+      - README updates
+      - Code comments and docstrings
+      - API documentation
+      - Usage examples
+      Don't apply for minor doc updates alongside code changes
+
+  - enhancement:
+    description: "Improvements to existing features"
+    instructions: |
+      Apply only for improvements to existing functionality:
+      - Performance improvements
+      - UI/UX improvements
+      - Expanded capabilities of existing features
+      Don't apply to:
+      - Bug fixes
+      - New features
+      - Minor tweaks
+
+  - feature:
+    description: "New functionality"
+    instructions: |
+      Apply only for net-new functionality:
+      - New API endpoints
+      - New commands or tools
+      - New user-facing capabilities
+      Don't apply to:
+      - Improvements to existing features (use enhancement)
+      - Bug fixes
+
+  - good first issue:
+    description: "Good for newcomers"
+    instructions: |
+      Apply very selectively to issues that are:
+      - Small in scope
+      - Well-documented
+      - Require minimal context
+      - Have clear success criteria
+      Don't apply if the task requires significant background knowledge
+
+  - help wanted:
+    description: "Extra attention is needed"
+    instructions: |
+      Apply only when it's the primary characteristic:
+      - Issue needs external expertise
+      - Current maintainers can't address it
+      - Additional contributors would be valuable
+      Don't apply just because an issue is open or needs work
+
+  - question:
+    description: "Further information is requested"
+    instructions: |
+      Apply only when the primary purpose is seeking information:
+      - Clarification needed before work can begin
+      - Architectural discussions
+      - Implementation strategy questions
+      Don't apply to:
+      - Bug reports that need more details
+      - Feature requests that need refinement
+
+# These files will be included in the context if they exist
+context-files:
+  - README.md
+  - CONTRIBUTING.md
+  - CODE_OF_CONDUCT.md
+  - .github/ISSUE_TEMPLATE/bug_report.md
+  - .github/ISSUE_TEMPLATE/feature_request.md

{fastmcp-0.3.4 → fastmcp-0.3.5}/.github/workflows/ai-labeler.yml

@@ -19,5 +19,6 @@ jobs:
       - uses: actions/checkout@v4
       - uses: jlowin/ai-labeler@v0.5.0
         with:
+          include-repo-labels: false
           openai-api-key: ${{ secrets.OPENAI_API_KEY }}
           controlflow-llm-model: openai/gpt-4o-mini

{fastmcp-0.3.4 → fastmcp-0.3.5}/.github/workflows/run-tests.yml

@@ -12,12 +12,14 @@ on:
       - "tests/**"
       - "uv.lock"
       - "pyproject.toml"
+      - ".github/workflows/**"
   pull_request:
     paths:
       - "src/**"
       - "tests/**"
       - "uv.lock"
       - "pyproject.toml"
+      - ".github/workflows/**"
 
   workflow_dispatch:
 
@@ -26,8 +28,13 @@ permissions:
 
 jobs:
   run_tests:
-    name: Run tests
-    runs-on: ubuntu-latest
+    name: "Run tests: Python ${{ matrix.python-version }} on ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10"]
+      fail-fast: false
 
     steps:
       - uses: actions/checkout@v4
@@ -35,11 +42,11 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v4
 
-      - name: Set up Python
-        run: uv python install 3.11
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
 
       - name: Install FastMCP
-        run: uv sync --extra dev
+        run: uv sync --extra tests
 
       - name: Run tests
         run: uv run pytest -vv

{fastmcp-0.3.4 → fastmcp-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastmcp
-Version: 0.3.4
+Version: 0.3.5
 Summary: A more ergonomic interface for MCP servers
 Author: Jeremiah Lowin
 License: Apache-2.0
@@ -20,6 +20,12 @@ Requires-Dist: pytest-asyncio>=0.23.5; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.6.1; extra == 'dev'
 Requires-Dist: pytest>=8.3.3; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: tests
+Requires-Dist: pre-commit; extra == 'tests'
+Requires-Dist: pytest-asyncio>=0.23.5; extra == 'tests'
+Requires-Dist: pytest-xdist>=3.6.1; extra == 'tests'
+Requires-Dist: pytest>=8.3.3; extra == 'tests'
+Requires-Dist: ruff; extra == 'tests'
 Description-Content-Type: text/markdown
 
 <!-- omit in toc -->
@@ -236,6 +242,27 @@ async def fetch_weather(city: str) -> str:
         return response.text
 ```
 
+Complex input handling example:
+```python
+from pydantic import BaseModel, Field
+from typing import Annotated
+
+class ShrimpTank(BaseModel):
+    class Shrimp(BaseModel):
+        name: Annotated[str, Field(max_length=10)]
+
+    shrimp: list[Shrimp]
+
+@mcp.tool()
+def name_shrimp(
+    tank: ShrimpTank,
+    # You can use pydantic Field in function signatures for validation.
+    extra_names: Annotated[list[str], Field(max_length=10)],
+) -> list[str]:
+    """List all shrimp names in the tank"""
+    return [shrimp.name for shrimp in tank.shrimp] + extra_names
+```
+
 ### Prompts
 
 Prompts are reusable templates that help LLMs interact with your server effectively. They're like "best practices" encoded into your server. A prompt can be as simple as a string:
@@ -488,23 +515,20 @@ FastMCP requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
 
 ### Installation
 
-Create a fork of this repository, then clone it:
+For development, we recommend installing FastMCP with development dependencies, which includes various utilities the maintainers find useful.
 
 ```bash
-git clone https://github.com/YouFancyUserYou/fastmcp.git
+git clone https://github.com/jlowin/fastmcp.git
 cd fastmcp
+uv sync --frozen --extra dev
 ```
 
-Next, create a virtual environment and install FastMCP:
+For running tests only (e.g., in CI), you only need the testing dependencies:
 
 ```bash
-uv venv
-source .venv/bin/activate
-uv sync --frozen --all-extras --dev
+uv sync --frozen --extra tests
 ```
 
-
-
 ### Testing
 
 Please make sure to test any new functionality. Your tests should be simple and atomic and anticipate change rather than cement complex patterns.

{fastmcp-0.3.4 → fastmcp-0.3.5}/README.md

@@ -212,6 +212,27 @@ async def fetch_weather(city: str) -> str:
         return response.text
 ```
 
+Complex input handling example:
+```python
+from pydantic import BaseModel, Field
+from typing import Annotated
+
+class ShrimpTank(BaseModel):
+    class Shrimp(BaseModel):
+        name: Annotated[str, Field(max_length=10)]
+
+    shrimp: list[Shrimp]
+
+@mcp.tool()
+def name_shrimp(
+    tank: ShrimpTank,
+    # You can use pydantic Field in function signatures for validation.
+    extra_names: Annotated[list[str], Field(max_length=10)],
+) -> list[str]:
+    """List all shrimp names in the tank"""
+    return [shrimp.name for shrimp in tank.shrimp] + extra_names
+```
+
 ### Prompts
 
 Prompts are reusable templates that help LLMs interact with your server effectively. They're like "best practices" encoded into your server. A prompt can be as simple as a string:
@@ -464,23 +485,20 @@ FastMCP requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
 
 ### Installation
 
-Create a fork of this repository, then clone it:
+For development, we recommend installing FastMCP with development dependencies, which includes various utilities the maintainers find useful.
 
 ```bash
-git clone https://github.com/YouFancyUserYou/fastmcp.git
+git clone https://github.com/jlowin/fastmcp.git
 cd fastmcp
+uv sync --frozen --extra dev
 ```
 
-Next, create a virtual environment and install FastMCP:
+For running tests only (e.g., in CI), you only need the testing dependencies:
 
 ```bash
-uv venv
-source .venv/bin/activate
-uv sync --frozen --all-extras --dev
+uv sync --frozen --extra tests
 ```
 
-
-
 ### Testing
 
 Please make sure to test any new functionality. Your tests should be simple and atomic and anticipate change rather than cement complex patterns.

fastmcp-0.3.5/Windows_Notes.md

@@ -0,0 +1,58 @@
+# Getting your development environment set up properly
+To get your environment up and running properly, you'll need a slightly different set of commands that are windows specific:
+```bash
+uv venv
+.venv\Scripts\activate
+uv pip install -e ".[dev]"
+```
+
+This will install the package in editable mode, and install the development dependencies.
+
+
+# Fixing `AttributeError: module 'collections' has no attribute 'Callable'`
+- open `.venv\Lib\site-packages\pyreadline\py3k_compat.py`
+- change `return isinstance(x, collections.Callable)` to 
+``` 
+from collections.abc import Callable
+return isinstance(x, Callable)
+```
+
+# Helpful notes
+For developing FastMCP
+## Install local development version of FastMCP into a local FastMCP project server
+- ensure
+- change directories to your FastMCP Server location so you can install it in your .venv
+- run `.venv\Scripts\activate` to activate your virtual environment
+- Then run a series of commands to uninstall the old version and install the new
+```bash
+# First uninstall
+uv pip uninstall fastmcp
+
+# Clean any build artifacts in your fastmcp directory
+cd C:\path\to\fastmcp
+del /s /q *.egg-info
+
+# Then reinstall in your weather project
+cd C:\path\to\new\fastmcp_server
+uv pip install --no-cache-dir -e C:\Users\justj\PycharmProjects\fastmcp
+
+# Check that it installed properly and has the correct git hash
+pip show fastmcp
+```
+
+## Running the FastMCP server with Inspector
+MCP comes with a node.js application called Inspector that can be used to inspect the FastMCP server. To run the inspector, you'll need to install node.js and npm. Then you can run the following commands:
+```bash
+fastmcp dev server.py
+```
+This will launch a web app on http://localhost:5173/ that you can use to inspect the FastMCP server.
+
+## If you start development before creating a fork - your get out of jail free card
+- Add your fork as a new remote to your local repository `git remote add fork git@github.com:YOUR-USERNAME/REPOSITORY-NAME.git`
+  - This will add your repo, short named 'fork', as a remote to your local repository
+- Verify that it was added correctly by running `git remote -v`
+- Commit your changes
+- Push your changes to your fork `git push fork <branch>`
+- Create your pull request on GitHub 
+
+

fastmcp-0.3.5/examples/complex_inputs.py

@@ -0,0 +1,28 @@
+"""
+FastMCP Complex inputs Example
+
+Demonstrates validation via pydantic with complex models.
+"""
+
+from pydantic import BaseModel, Field
+from typing import Annotated
+from fastmcp.server import FastMCP
+
+mcp = FastMCP("Shrimp Tank")
+
+
+class ShrimpTank(BaseModel):
+    class Shrimp(BaseModel):
+        name: Annotated[str, Field(max_length=10)]
+
+    shrimp: list[Shrimp]
+
+
+@mcp.tool()
+def name_shrimp(
+    tank: ShrimpTank,
+    # You can use pydantic Field in function signatures for validation.
+    extra_names: Annotated[list[str], Field(max_length=10)],
+) -> list[str]:
+    """List all shrimp names in the tank"""
+    return [shrimp.name for shrimp in tank.shrimp] + extra_names

{fastmcp-0.3.4 → fastmcp-0.3.5}/pyproject.toml

@@ -23,16 +23,14 @@ requires = ["hatchling>=1.21.0", "hatch-vcs>=0.4.0"]
 build-backend = "hatchling.build"
 
 [project.optional-dependencies]
-dev = [
-    "copychat>=0.5.2",
-    "ipython>=8.12.3",
-    "pdbpp>=0.10.3",
+tests = [
     "pre-commit",
-    "pytest-xdist>=3.6.1",
     "pytest>=8.3.3",
     "pytest-asyncio>=0.23.5",
+    "pytest-xdist>=3.6.1",
     "ruff",
 ]
+dev = ["fastmcp[tests]", "copychat>=0.5.2", "ipython>=8.12.3", "pdbpp>=0.10.3"]
 
 [tool.pytest.ini_options]
 asyncio_mode = "auto"

{fastmcp-0.3.4 → fastmcp-0.3.5}/src/fastmcp/cli/cli.py

@@ -11,8 +11,8 @@ import typer
 from typing_extensions import Annotated
 import dotenv
 
-from ..utilities.logging import get_logger
-from . import claude
+from fastmcp.cli import claude
+from fastmcp.utilities.logging import get_logger
 
 logger = get_logger("cli")
 
@@ -24,6 +24,22 @@ app = typer.Typer(
 )
 
 
+def _get_npx_command():
+    """Get the correct npx command for the current platform."""
+    if sys.platform == "win32":
+        # Try both npx.cmd and npx.exe on Windows
+        for cmd in ["npx.cmd", "npx.exe", "npx"]:
+            try:
+                subprocess.run(
+                    [cmd, "--version"], check=True, capture_output=True, shell=True
+                )
+                return cmd
+            except subprocess.CalledProcessError:
+                continue
+        return None
+    return "npx"  # On Unix-like systems, just use npx
+
+
 def _parse_env_var(env_var: str) -> Tuple[str, str]:
     """Parse environment variable string in format KEY=VALUE."""
     if "=" not in env_var:
@@ -67,11 +83,17 @@ def _parse_file_path(file_spec: str) -> Tuple[Path, Optional[str]]:
     Returns:
         Tuple of (file_path, server_object)
     """
-    if ":" in file_spec:
+    # First check if we have a Windows path (e.g., C:\...)
+    has_windows_drive = len(file_spec) > 1 and file_spec[1] == ":"
+
+    # Split on the last colon, but only if it's not part of the Windows drive letter
+    # and there's actually another colon in the string after the drive letter
+    if ":" in (file_spec[2:] if has_windows_drive else file_spec):
         file_str, server_object = file_spec.rsplit(":", 1)
     else:
         file_str, server_object = file_spec, None
 
+    # Resolve the file path
     file_path = Path(file_str).expanduser().resolve()
     if not file_path.exists():
         logger.error(f"File not found: {file_path}")
@@ -93,6 +115,11 @@ def _import_server(file: Path, server_object: Optional[str] = None):
     Returns:
         The server object
     """
+    # Add parent directory to Python path so imports can be resolved
+    file_dir = str(file.parent)
+    if file_dir not in sys.path:
+        sys.path.insert(0, file_dir)
+
     # Import the module
     spec = importlib.util.spec_from_file_location("server_module", file)
     if not spec or not spec.loader:
@@ -199,10 +226,22 @@ def dev(
             with_packages = list(set(with_packages + server.dependencies))
 
         uv_cmd = _build_uv_command(file_spec, with_editable, with_packages)
-        # Run the MCP Inspector command
+
+        # Get the correct npx command
+        npx_cmd = _get_npx_command()
+        if not npx_cmd:
+            logger.error(
+                "npx not found. Please ensure Node.js and npm are properly installed "
+                "and added to your system PATH."
+            )
+            sys.exit(1)
+
+        # Run the MCP Inspector command with shell=True on Windows
+        shell = sys.platform == "win32"
         process = subprocess.run(
-            ["npx", "@modelcontextprotocol/inspector"] + uv_cmd,
+            [npx_cmd, "@modelcontextprotocol/inspector"] + uv_cmd,
             check=True,
+            shell=shell,
         )
         sys.exit(process.returncode)
     except subprocess.CalledProcessError as e:
@@ -217,7 +256,9 @@ def dev(
         sys.exit(e.returncode)
     except FileNotFoundError:
         logger.error(
-            "npx not found. Please install Node.js and npm.",
+            "npx not found. Please ensure Node.js and npm are properly installed "
+            "and added to your system PATH. You may need to restart your terminal "
+            "after installation.",
             extra={"file": str(file)},
         )
         sys.exit(1)

{fastmcp-0.3.4 → fastmcp-0.3.5}/src/fastmcp/exceptions.py

@@ -15,3 +15,7 @@ class ResourceError(FastMCPError):
 
 class ToolError(FastMCPError):
     """Error in tool operations."""
+
+
+class InvalidSignature(Exception):
+    """Invalid signature for use with FastMCP."""

{fastmcp-0.3.4 → fastmcp-0.3.5}/src/fastmcp/tools/base.py

@@ -1,8 +1,8 @@
 import fastmcp
 from fastmcp.exceptions import ToolError
 
-
-from pydantic import BaseModel, Field, TypeAdapter, validate_call
+from fastmcp.utilities.func_metadata import func_metadata, FuncMetadata
+from pydantic import BaseModel, Field
 
 
 import inspect
@@ -19,6 +19,9 @@ class Tool(BaseModel):
     name: str = Field(description="Name of the tool")
     description: str = Field(description="Description of what the tool does")
     parameters: dict = Field(description="JSON schema for tool parameters")
+    fn_metadata: FuncMetadata = Field(
+        description="Metadata about the function including a pydantic model for tool arguments"
+    )
     is_async: bool = Field(description="Whether the tool is async")
     context_kwarg: Optional[str] = Field(
         None, description="Name of the kwarg that should receive context"
@@ -41,9 +44,6 @@ class Tool(BaseModel):
         func_doc = description or fn.__doc__ or ""
         is_async = inspect.iscoroutinefunction(fn)
 
-        # Get schema from TypeAdapter - will fail if function isn't properly typed
-        parameters = TypeAdapter(fn).json_schema()
-
         # Find context parameter if it exists
         if context_kwarg is None:
             sig = inspect.signature(fn)
@@ -52,14 +52,18 @@ class Tool(BaseModel):
                     context_kwarg = param_name
                     break
 
-        # ensure the arguments are properly cast
-        fn = validate_call(fn)
+        func_arg_metadata = func_metadata(
+            fn,
+            skip_names=[context_kwarg] if context_kwarg is not None else [],
+        )
+        parameters = func_arg_metadata.arg_model.model_json_schema()
 
         return cls(
             fn=fn,
             name=func_name,
             description=func_doc,
             parameters=parameters,
+            fn_metadata=func_arg_metadata,
             is_async=is_async,
             context_kwarg=context_kwarg,
         )
@@ -67,13 +71,13 @@ class Tool(BaseModel):
     async def run(self, arguments: dict, context: Optional["Context"] = None) -> Any:
         """Run the tool with arguments."""
         try:
-            # Inject context if needed
-            if self.context_kwarg:
-                arguments[self.context_kwarg] = context
-
-            # Call function with proper async handling
-            if self.is_async:
-                return await self.fn(**arguments)
-            return self.fn(**arguments)
+            return await self.fn_metadata.call_fn_with_arg_validation(
+                self.fn,
+                self.is_async,
+                arguments,
+                {self.context_kwarg: context}
+                if self.context_kwarg is not None
+                else None,
+            )
         except Exception as e:
             raise ToolError(f"Error executing tool {self.name}: {e}") from e