fastmcp 2.14.4__py3-none-any.whl → 3.0.0b1__py3-none-any.whl

fastmcp/utilities/skills.py

@@ -0,0 +1,253 @@
+"""Client utilities for discovering and downloading skills from MCP servers."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from fastmcp.client import Client
+
+
+@dataclass
+class SkillSummary:
+    """Summary information about a skill available on a server."""
+
+    name: str
+    description: str
+    uri: str
+
+
+@dataclass
+class SkillFile:
+    """Information about a file within a skill."""
+
+    path: str
+    size: int
+    hash: str
+
+
+@dataclass
+class SkillManifest:
+    """Full manifest of a skill including all files."""
+
+    name: str
+    files: list[SkillFile]
+
+
+async def list_skills(client: Client) -> list[SkillSummary]:
+    """List all available skills from an MCP server.
+
+    Discovers skills by finding resources with URIs matching the
+    `skill://{name}/SKILL.md` pattern.
+
+    Args:
+        client: Connected FastMCP client
+
+    Returns:
+        List of SkillSummary objects with name, description, and URI
+
+    Example:
+        ```python
+        from fastmcp import Client
+        from fastmcp.utilities.skills import list_skills
+
+        async with Client("http://skills-server/mcp") as client:
+            skills = await list_skills(client)
+            for skill in skills:
+                print(f"{skill.name}: {skill.description}")
+        ```
+    """
+    resources = await client.list_resources()
+    skills = []
+
+    for resource in resources:
+        uri = str(resource.uri)
+        # Match skill://{name}/SKILL.md pattern
+        if uri.startswith("skill://") and uri.endswith("/SKILL.md"):
+            # Extract skill name from URI
+            path_part = uri[len("skill://") :]
+            name = path_part.rsplit("/", 1)[0]
+            skills.append(
+                SkillSummary(
+                    name=name,
+                    description=resource.description or "",
+                    uri=uri,
+                )
+            )
+
+    return skills
+
+
+async def get_skill_manifest(client: Client, skill_name: str) -> SkillManifest:
+    """Get the manifest for a specific skill.
+
+    Args:
+        client: Connected FastMCP client
+        skill_name: Name of the skill
+
+    Returns:
+        SkillManifest with file listing
+
+    Raises:
+        ValueError: If manifest cannot be read or parsed
+    """
+    manifest_uri = f"skill://{skill_name}/_manifest"
+    result = await client.read_resource(manifest_uri)
+
+    if not result:
+        raise ValueError(f"Could not read manifest for skill: {skill_name}")
+
+    content = result[0]
+    if hasattr(content, "text"):
+        try:
+            manifest_data = json.loads(content.text)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid manifest JSON for skill: {skill_name}") from e
+    else:
+        raise ValueError(f"Unexpected manifest format for skill: {skill_name}")
+
+    try:
+        return SkillManifest(
+            name=manifest_data["skill"],
+            files=[
+                SkillFile(path=f["path"], size=f["size"], hash=f["hash"])
+                for f in manifest_data["files"]
+            ],
+        )
+    except (KeyError, TypeError) as e:
+        raise ValueError(f"Invalid manifest format for skill: {skill_name}") from e
+
+
+async def download_skill(
+    client: Client,
+    skill_name: str,
+    target_dir: str | Path,
+    *,
+    overwrite: bool = False,
+) -> Path:
+    """Download a skill and all its files to a local directory.
+
+    Creates a subdirectory named after the skill containing all files.
+
+    Args:
+        client: Connected FastMCP client
+        skill_name: Name of the skill to download
+        target_dir: Directory where skill folder will be created
+        overwrite: If True, overwrite existing skill directory. If False
+            (default), raise FileExistsError if directory exists.
+
+    Returns:
+        Path to the downloaded skill directory
+
+    Raises:
+        ValueError: If skill cannot be found or downloaded
+        FileExistsError: If skill directory exists and overwrite=False
+
+    Example:
+        ```python
+        from fastmcp import Client
+        from fastmcp.utilities.skills import download_skill
+
+        async with Client("http://skills-server/mcp") as client:
+            skill_path = await download_skill(
+                client,
+                "pdf-processing",
+                "~/.claude/skills"
+            )
+            print(f"Downloaded to: {skill_path}")
+        ```
+    """
+    target_dir = Path(target_dir).expanduser().resolve()
+    skill_dir = target_dir / skill_name
+
+    # Check if directory exists
+    if skill_dir.exists() and not overwrite:
+        raise FileExistsError(
+            f"Skill directory already exists: {skill_dir}. "
+            "Use overwrite=True to replace."
+        )
+
+    # Get manifest to know what files to download
+    manifest = await get_skill_manifest(client, skill_name)
+
+    # Create skill directory
+    skill_dir.mkdir(parents=True, exist_ok=True)
+
+    # Download each file
+    for file_info in manifest.files:
+        # Security: reject absolute paths and paths that escape skill_dir
+        if Path(file_info.path).is_absolute():
+            continue
+        file_path = (skill_dir / file_info.path).resolve()
+        if not file_path.is_relative_to(skill_dir):
+            continue
+
+        file_uri = f"skill://{skill_name}/{file_info.path}"
+        result = await client.read_resource(file_uri)
+
+        if not result:
+            continue
+
+        content = result[0]
+
+        # Create parent directories if needed
+        file_path.parent.mkdir(parents=True, exist_ok=True)
+
+        # Write content
+        if hasattr(content, "text"):
+            file_path.write_text(content.text)
+        elif hasattr(content, "blob"):
+            # Handle base64-encoded binary content
+            import base64
+
+            file_path.write_bytes(base64.b64decode(content.blob))
+        else:
+            # Skip unknown content types
+            continue
+
+    return skill_dir
+
+
+async def sync_skills(
+    client: Client,
+    target_dir: str | Path,
+    *,
+    overwrite: bool = False,
+) -> list[Path]:
+    """Download all available skills from a server.
+
+    Args:
+        client: Connected FastMCP client
+        target_dir: Directory where skill folders will be created
+        overwrite: If True, overwrite existing files
+
+    Returns:
+        List of paths to downloaded skill directories
+
+    Example:
+        ```python
+        from fastmcp import Client
+        from fastmcp.utilities.skills import sync_skills
+
+        async with Client("http://skills-server/mcp") as client:
+            paths = await sync_skills(client, "~/.claude/skills")
+            print(f"Downloaded {len(paths)} skills")
+        ```
+    """
+    skills = await list_skills(client)
+    downloaded = []
+
+    for skill in skills:
+        try:
+            path = await download_skill(
+                client, skill.name, target_dir, overwrite=overwrite
+            )
+            downloaded.append(path)
+        except FileExistsError:
+            # Skip existing skills when not overwriting
+            continue
+
+    return downloaded

fastmcp/utilities/tests.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import copy
-import logging
 import multiprocessing
 import socket
 import time
@@ -12,7 +11,6 @@ from urllib.parse import parse_qs, urlparse
 
 import httpx
 import uvicorn
-from pytest import LogCaptureFixture
 
 from fastmcp import settings
 from fastmcp.client.auth.oauth import OAuth
@@ -224,20 +222,6 @@ async def run_server_async(
             await asyncio.wait_for(server_task, timeout=2.0)
 
 
-@contextmanager
-def caplog_for_fastmcp(
-    caplog: LogCaptureFixture,
-) -> Generator[LogCaptureFixture, None, None]:
-    """Context manager to capture logs from FastMCP loggers even when propagation is disabled."""
-    caplog.clear()
-    logger = logging.getLogger("fastmcp")
-    logger.addHandler(caplog.handler)
-    try:
-        yield caplog
-    finally:
-        logger.removeHandler(caplog.handler)
-
-
 class HeadlessOAuth(OAuth):
     """
     OAuth provider that bypasses browser interaction for testing.

fastmcp/utilities/timeout.py

@@ -0,0 +1,47 @@
+"""Timeout normalization utilities."""
+
+from __future__ import annotations
+
+import datetime
+
+
+def normalize_timeout_to_timedelta(
+    value: int | float | datetime.timedelta | None,
+) -> datetime.timedelta | None:
+    """Normalize a timeout value to a timedelta.
+
+    Args:
+        value: Timeout value as int/float (seconds), timedelta, or None
+
+    Returns:
+        timedelta if value provided, None otherwise
+    """
+    if value is None:
+        return None
+    if isinstance(value, datetime.timedelta):
+        return value
+    if isinstance(value, int | float):
+        return datetime.timedelta(seconds=float(value))
+    raise TypeError(f"Invalid timeout type: {type(value)}")
+
+
+def normalize_timeout_to_seconds(
+    value: int | float | datetime.timedelta | None,
+) -> float | None:
+    """Normalize a timeout value to seconds (float).
+
+    Args:
+        value: Timeout value as int/float (seconds), timedelta, or None.
+            Zero values are treated as "disabled" and return None.
+
+    Returns:
+        float seconds if value provided and non-zero, None otherwise
+    """
+    if value is None:
+        return None
+    if isinstance(value, datetime.timedelta):
+        seconds = value.total_seconds()
+        return None if seconds == 0 else seconds
+    if isinstance(value, int | float):
+        return None if value == 0 else float(value)
+    raise TypeError(f"Invalid timeout type: {type(value)}")

fastmcp/utilities/types.py

@@ -480,7 +480,7 @@ def replace_type(type_, type_map: dict[type, type]):
     new_args = tuple(replace_type(arg, type_map) for arg in args)
 
     if origin is UnionType:
-        return Union[new_args]  # type: ignore # noqa: UP007
+        return Union[new_args]  # noqa: UP007
     else:
         return origin[new_args]
 

fastmcp/utilities/versions.py

@@ -0,0 +1,285 @@
+"""Version comparison utilities for component versioning.
+
+This module provides utilities for comparing component versions. Versions are
+strings that are first attempted to be parsed as PEP 440 versions (using the
+`packaging` library), falling back to lexicographic string comparison.
+
+Examples:
+    - "1", "2", "10" → parsed as PEP 440, compared semantically (1 < 2 < 10)
+    - "1.0", "2.0" → parsed as PEP 440
+    - "v1.0" → 'v' prefix stripped, parsed as "1.0"
+    - "2025-01-15" → not valid PEP 440, compared as strings
+    - None → sorts lowest (unversioned components)
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import total_ordering
+from typing import TYPE_CHECKING
+
+from packaging.version import InvalidVersion, Version
+
+if TYPE_CHECKING:
+    from fastmcp.utilities.components import FastMCPComponent
+
+
+@dataclass
+class VersionSpec:
+    """Specification for filtering components by version.
+
+    Used by transforms and providers to filter components to a specific
+    version or version range. Unversioned components (version=None) always
+    match any spec.
+
+    Args:
+        gte: If set, only versions >= this value match.
+        lt: If set, only versions < this value match.
+        eq: If set, only this exact version matches (gte/lt ignored).
+    """
+
+    gte: str | None = None
+    lt: str | None = None
+    eq: str | None = None
+
+    def matches(self, version: str | None, *, match_none: bool = True) -> bool:
+        """Check if a version matches this spec.
+
+        Args:
+            version: The version to check, or None for unversioned.
+            match_none: Whether unversioned (None) components match. Defaults to True
+                for backward compatibility with retrieval operations. Set to False
+                when filtering (e.g., enable/disable) to exclude unversioned components
+                from version-specific rules.
+
+        Returns:
+            True if the version matches the spec.
+        """
+        if version is None:
+            return match_none
+
+        if self.eq is not None:
+            return version == self.eq
+
+        key = parse_version_key(version)
+
+        if self.gte is not None:
+            gte_key = parse_version_key(self.gte)
+            if key < gte_key:
+                return False
+
+        if self.lt is not None:
+            lt_key = parse_version_key(self.lt)
+            if not key < lt_key:
+                return False
+
+        return True
+
+    def intersect(self, other: VersionSpec | None) -> VersionSpec:
+        """Return a spec that satisfies both this spec and other.
+
+        Used by transforms to combine caller constraints with filter constraints.
+        For example, if a VersionFilter has lt="3.0" and caller requests eq="1.0",
+        the intersection validates "1.0" is in range and returns the exact spec.
+
+        Args:
+            other: Another spec to intersect with, or None.
+
+        Returns:
+            A VersionSpec that matches only versions satisfying both specs.
+        """
+        if other is None:
+            return self
+
+        if self.eq is not None:
+            # This spec wants exact - validate against other's range
+            if other.matches(self.eq):
+                return self
+            return VersionSpec(eq="__impossible__")
+
+        if other.eq is not None:
+            # Other wants exact - validate against our range
+            if self.matches(other.eq):
+                return other
+            return VersionSpec(eq="__impossible__")
+
+        # Both are ranges - take tighter bounds
+        return VersionSpec(
+            gte=max_version(self.gte, other.gte),
+            lt=min_version(self.lt, other.lt),
+        )
+
+
+@total_ordering
+class VersionKey:
+    """A comparable version key that handles None, PEP 440 versions, and strings.
+
+    Comparison order:
+    1. None (unversioned) sorts lowest
+    2. PEP 440 versions sort by semantic version order
+    3. Invalid versions (strings) sort lexicographically
+    4. When comparing PEP 440 vs string, PEP 440 comes first
+    """
+
+    __slots__ = ("_is_none", "_is_pep440", "_parsed", "_raw")
+
+    def __init__(self, version: str | None) -> None:
+        self._raw = version
+        self._is_none = version is None
+        self._is_pep440 = False
+        self._parsed: Version | str | None = None
+
+        if version is not None:
+            # Strip leading 'v' if present (common convention like "v1.0")
+            normalized = version.lstrip("v") if version.startswith("v") else version
+            try:
+                self._parsed = Version(normalized)
+                self._is_pep440 = True
+            except InvalidVersion:
+                # Fall back to string comparison for non-PEP 440 versions
+                self._parsed = version
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, VersionKey):
+            return NotImplemented
+        if self._is_none and other._is_none:
+            return True
+        if self._is_none != other._is_none:
+            return False
+        # Both are not None
+        if self._is_pep440 and other._is_pep440:
+            return self._parsed == other._parsed
+        if not self._is_pep440 and not other._is_pep440:
+            return self._parsed == other._parsed
+        # One is PEP 440, other is string - never equal
+        return False
+
+    def __lt__(self, other: object) -> bool:
+        if not isinstance(other, VersionKey):
+            return NotImplemented
+        # None sorts lowest
+        if self._is_none and other._is_none:
+            return False  # Equal
+        if self._is_none:
+            return True  # None < anything
+        if other._is_none:
+            return False  # anything > None
+
+        # Both are not None
+        if self._is_pep440 and other._is_pep440:
+            # Both PEP 440 - compare normally
+            assert isinstance(self._parsed, Version)
+            assert isinstance(other._parsed, Version)
+            return self._parsed < other._parsed
+        if not self._is_pep440 and not other._is_pep440:
+            # Both strings - lexicographic
+            assert isinstance(self._parsed, str)
+            assert isinstance(other._parsed, str)
+            return self._parsed < other._parsed
+        # Mixed: PEP 440 sorts before strings
+        # (arbitrary but consistent choice)
+        return self._is_pep440
+
+    def __repr__(self) -> str:
+        return f"VersionKey({self._raw!r})"
+
+
+def parse_version_key(version: str | None) -> VersionKey:
+    """Parse a version string into a sortable key.
+
+    Args:
+        version: The version string, or None for unversioned.
+
+    Returns:
+        A VersionKey suitable for sorting.
+    """
+    return VersionKey(version)
+
+
+def version_sort_key(component: FastMCPComponent) -> VersionKey:
+    """Get a sort key for a component based on its version.
+
+    Use with sorted() or max() to order components by version.
+
+    Args:
+        component: The component to get a sort key for.
+
+    Returns:
+        A sortable VersionKey.
+
+    Example:
+        ```python
+        tools = [tool_v1, tool_v2, tool_unversioned]
+        highest = max(tools, key=version_sort_key)  # Returns tool_v2
+        ```
+    """
+    return parse_version_key(component.version)
+
+
+def compare_versions(a: str | None, b: str | None) -> int:
+    """Compare two version strings.
+
+    Args:
+        a: First version string (or None).
+        b: Second version string (or None).
+
+    Returns:
+        -1 if a < b, 0 if a == b, 1 if a > b.
+
+    Example:
+        ```python
+        compare_versions("1.0", "2.0")  # Returns -1
+        compare_versions("2.0", "1.0")  # Returns 1
+        compare_versions(None, "1.0")   # Returns -1 (None < any version)
+        ```
+    """
+    key_a = parse_version_key(a)
+    key_b = parse_version_key(b)
+    return (key_a > key_b) - (key_a < key_b)
+
+
+def is_version_greater(a: str | None, b: str | None) -> bool:
+    """Check if version a is greater than version b.
+
+    Args:
+        a: First version string (or None).
+        b: Second version string (or None).
+
+    Returns:
+        True if a > b, False otherwise.
+    """
+    return compare_versions(a, b) > 0
+
+
+def max_version(a: str | None, b: str | None) -> str | None:
+    """Return the greater of two versions.
+
+    Args:
+        a: First version string (or None).
+        b: Second version string (or None).
+
+    Returns:
+        The greater version, or None if both are None.
+    """
+    if a is None:
+        return b
+    if b is None:
+        return a
+    return a if compare_versions(a, b) >= 0 else b
+
+
+def min_version(a: str | None, b: str | None) -> str | None:
+    """Return the lesser of two versions.
+
+    Args:
+        a: First version string (or None).
+        b: Second version string (or None).
+
+    Returns:
+        The lesser version, or None if both are None.
+    """
+    if a is None:
+        return b
+    if b is None:
+        return a
+    return a if compare_versions(a, b) <= 0 else b

{fastmcp-2.14.4.dist-info → fastmcp-3.0.0b1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.14.4
+Version: 3.0.0b1
 Summary: The fast, Pythonic way to build MCP servers and clients.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp
@@ -26,20 +26,23 @@ Requires-Dist: jsonref>=1.1.0
 Requires-Dist: jsonschema-path>=0.3.4
 Requires-Dist: mcp<2.0,>=1.24.0
 Requires-Dist: openapi-pydantic>=0.5.1
-Requires-Dist: packaging>=20.0
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: packaging>=24.0
 Requires-Dist: platformdirs>=4.0.0
 Requires-Dist: py-key-value-aio[disk,keyring,memory]<0.4.0,>=0.3.0
 Requires-Dist: pydantic[email]>=2.11.7
-Requires-Dist: pydocket<0.17.0,>=0.16.6
 Requires-Dist: pyperclip>=1.9.0
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: rich>=13.9.4
 Requires-Dist: uvicorn>=0.35
+Requires-Dist: watchfiles>=1.0.0
 Requires-Dist: websockets>=15.0.1
 Provides-Extra: anthropic
 Requires-Dist: anthropic>=0.40.0; extra == 'anthropic'
 Provides-Extra: openai
 Requires-Dist: openai>=1.102.0; extra == 'openai'
+Provides-Extra: tasks
+Requires-Dist: pydocket>=0.16.4; extra == 'tasks'
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -78,7 +81,7 @@ Description-Content-Type: text/markdown
 > **For production MCP applications, install FastMCP:** `pip install fastmcp`
 
 > [!Important]
-> FastMCP 3.0 is in development and may include breaking changes. To avoid unexpected issues, pin your dependency to v2: `fastmcp<3`
+> FastMCP 3.0 is in development and may include some breaking changes. To avoid unexpected issues, pin your dependency to v2: `fastmcp<3`
 
 ---
 
@@ -126,7 +129,7 @@ There are two ways to access the LLM-friendly documentation:
 ## Table of Contents
 
 - [FastMCP v2 🚀](#fastmcp-v2-)
-  - [📚 Documentation](#-documentation)
+    - [📚 Documentation](#-documentation)
   - [What is MCP?](#what-is-mcp)
   - [Why FastMCP?](#why-fastmcp)
   - [Installation](#installation)