fastmcp 0.3.3__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.3 → 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.3 → 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.3 → fastmcp-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastmcp
-Version: 0.3.3
+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 -->
@@ -122,6 +128,8 @@ pip install fastmcp
 Let's create a simple MCP server that exposes a calculator tool and some data:
 
 ```python
+# server.py
+
 from fastmcp import FastMCP
 
 
@@ -143,14 +151,12 @@ def get_greeting(name: str) -> str:
     return f"Hello, {name}!"
 ```
 
-To use this server, you have two options:
-
-1. Install it in [Claude Desktop](https://claude.ai/download):
+You can install this server in [Claude Desktop](https://claude.ai/download) and interact with it right away by running:
 ```bash
 fastmcp install server.py
 ```
 
-2. Test it with the MCP Inspector:
+Alternatively, you can test it with the MCP Inspector:
 ```bash
 fastmcp dev server.py
 ```
@@ -181,9 +187,6 @@ from fastmcp import FastMCP
 # Create a named server
 mcp = FastMCP("My App")
 
-# Configure host/port for HTTP transport (optional)
-mcp = FastMCP("My App", host="localhost", port=8000)
-
 # Specify dependencies for deployment and development
 mcp = FastMCP("My App", dependencies=["pandas", "numpy"])
 ```
@@ -239,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:
@@ -491,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.3 → fastmcp-0.3.5}/README.md

@@ -98,6 +98,8 @@ pip install fastmcp
 Let's create a simple MCP server that exposes a calculator tool and some data:
 
 ```python
+# server.py
+
 from fastmcp import FastMCP
 
 
@@ -119,14 +121,12 @@ def get_greeting(name: str) -> str:
     return f"Hello, {name}!"
 ```
 
-To use this server, you have two options:
-
-1. Install it in [Claude Desktop](https://claude.ai/download):
+You can install this server in [Claude Desktop](https://claude.ai/download) and interact with it right away by running:
 ```bash
 fastmcp install server.py
 ```
 
-2. Test it with the MCP Inspector:
+Alternatively, you can test it with the MCP Inspector:
 ```bash
 fastmcp dev server.py
 ```
@@ -157,9 +157,6 @@ from fastmcp import FastMCP
 # Create a named server
 mcp = FastMCP("My App")
 
-# Configure host/port for HTTP transport (optional)
-mcp = FastMCP("My App", host="localhost", port=8000)
-
 # Specify dependencies for deployment and development
 mcp = FastMCP("My App", dependencies=["pandas", "numpy"])
 ```
@@ -215,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:
@@ -467,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.3 → 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.3 → fastmcp-0.3.5}/src/fastmcp/cli/claude.py

@@ -41,14 +41,31 @@ def update_claude_config(
         with_packages: Optional list of additional packages to install
         env_vars: Optional dictionary of environment variables. These are merged with
             any existing variables, with new values taking precedence.
+
+    Raises:
+        RuntimeError: If Claude Desktop's config directory is not found, indicating
+            Claude Desktop may not be installed or properly set up.
     """
     config_dir = get_claude_config_path()
     if not config_dir:
-        return False
+        raise RuntimeError(
+            "Claude Desktop config directory not found. Please ensure Claude Desktop "
+            "is installed and has been run at least once to initialize its configuration."
+        )
 
     config_file = config_dir / "claude_desktop_config.json"
     if not config_file.exists():
-        return False
+        try:
+            config_file.write_text("{}")
+        except Exception as e:
+            logger.error(
+                "Failed to create Claude config file",
+                extra={
+                    "error": str(e),
+                    "config_file": str(config_file),
+                },
+            )
+            return False
 
     try:
         config = json.loads(config_file.read_text())

{fastmcp-0.3.3 → 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.3 → 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.3 → fastmcp-0.3.5}/src/fastmcp/resources/base.py

@@ -1,34 +1,17 @@
 """Base classes and interfaces for FastMCP resources."""
 
 import abc
-from typing import Annotated, Union
+from typing import Union
 
 from pydantic import (
     AnyUrl,
     BaseModel,
-    BeforeValidator,
     ConfigDict,
     Field,
     FileUrl,
     ValidationInfo,
     field_validator,
 )
-from pydantic.networks import _BaseUrl  # TODO: remove this once pydantic is updated
-
-
-def maybe_cast_str_to_any_url(x) -> AnyUrl:
-    if isinstance(x, FileUrl):
-        return x
-    elif isinstance(x, AnyUrl):
-        return x
-    elif isinstance(x, str):
-        if x.startswith("file://"):
-            return FileUrl(x)
-        return AnyUrl(x)
-    raise ValueError(f"Expected str or AnyUrl, got {type(x)}")
-
-
-LaxAnyUrl = Annotated[_BaseUrl | str, BeforeValidator(maybe_cast_str_to_any_url)]
 
 
 class Resource(BaseModel, abc.ABC):
@@ -36,7 +19,8 @@ class Resource(BaseModel, abc.ABC):
 
     model_config = ConfigDict(validate_default=True)
 
-    uri: LaxAnyUrl = Field(default=..., description="URI of the resource")
+    # uri: Annotated[AnyUrl, BeforeValidator(maybe_cast_str_to_any_url)] = Field(
+    uri: AnyUrl = Field(default=..., description="URI of the resource")
     name: str | None = Field(description="Name of the resource", default=None)
     description: str | None = Field(
         description="Description of the resource", default=None
@@ -47,6 +31,15 @@ class Resource(BaseModel, abc.ABC):
         pattern=r"^[a-zA-Z0-9]+/[a-zA-Z0-9\-+.]+$",
     )
 
+    @field_validator("uri", mode="before")
+    def validate_uri(cls, uri: AnyUrl | str) -> AnyUrl:
+        if isinstance(uri, str):
+            # AnyUrl doesn't support triple-slashes, but files do ("file:///absolute/path")
+            if uri.startswith("file://"):
+                return FileUrl(uri)
+            return AnyUrl(uri)
+        return uri
+
     @field_validator("name", mode="before")
     @classmethod
     def set_default_name(cls, name: str | None, info: ValidationInfo) -> str: