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

fastmcp/server/providers/skills/__init__.py

@@ -0,0 +1,59 @@
+"""Skills providers for exposing agent skills as MCP resources.
+
+This module provides a two-layer architecture for skill discovery:
+
+- **SkillProvider**: Handles a single skill folder, exposing its files as resources.
+- **SkillsDirectoryProvider**: Scans a directory, creates a SkillProvider per folder.
+- **Vendor providers**: Platform-specific providers for Claude, Cursor, VS Code, Codex,
+  Gemini, Goose, Copilot, and OpenCode.
+
+Example:
+    ```python
+    from pathlib import Path
+    from fastmcp import FastMCP
+    from fastmcp.server.providers.skills import ClaudeSkillsProvider, SkillProvider
+
+    mcp = FastMCP("Skills Server")
+
+    # Load a single skill
+    mcp.add_provider(SkillProvider(Path.home() / ".claude/skills/pdf-processing"))
+
+    # Or load all skills in a directory
+    mcp.add_provider(ClaudeSkillsProvider())  # Uses ~/.claude/skills/
+    ```
+"""
+
+from __future__ import annotations
+
+# Import providers
+from fastmcp.server.providers.skills.claude_provider import ClaudeSkillsProvider
+from fastmcp.server.providers.skills.directory_provider import SkillsDirectoryProvider
+from fastmcp.server.providers.skills.skill_provider import SkillProvider
+from fastmcp.server.providers.skills.vendor_providers import (
+    CodexSkillsProvider,
+    CopilotSkillsProvider,
+    CursorSkillsProvider,
+    GeminiSkillsProvider,
+    GooseSkillsProvider,
+    OpenCodeSkillsProvider,
+    VSCodeSkillsProvider,
+)
+
+
+# Backwards compatibility alias
+SkillsProvider = SkillsDirectoryProvider
+
+
+__all__ = [
+    "ClaudeSkillsProvider",
+    "CodexSkillsProvider",
+    "CopilotSkillsProvider",
+    "CursorSkillsProvider",
+    "GeminiSkillsProvider",
+    "GooseSkillsProvider",
+    "OpenCodeSkillsProvider",
+    "SkillProvider",
+    "SkillsDirectoryProvider",
+    "SkillsProvider",  # Backwards compatibility alias
+    "VSCodeSkillsProvider",
+]

fastmcp/server/providers/skills/_common.py

@@ -0,0 +1,101 @@
+"""Shared utilities and data structures for skills providers."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class SkillFileInfo:
+    """Information about a file within a skill."""
+
+    path: str  # Relative path within skill directory
+    size: int
+    hash: str  # sha256 hash
+
+
+@dataclass
+class SkillInfo:
+    """Parsed information about a skill."""
+
+    name: str  # Directory name (canonical identifier)
+    description: str  # From frontmatter or first line
+    path: Path  # Absolute path to skill directory
+    main_file: str  # Name of main file (e.g., "SKILL.md")
+    files: list[SkillFileInfo] = field(default_factory=list)
+    frontmatter: dict[str, Any] = field(default_factory=dict)
+
+
+def parse_frontmatter(content: str) -> tuple[dict[str, Any], str]:
+    """Parse YAML frontmatter from markdown content.
+
+    Args:
+        content: Markdown content potentially starting with ---
+
+    Returns:
+        Tuple of (frontmatter dict, remaining content)
+    """
+    if not content.startswith("---"):
+        return {}, content
+
+    # Find the closing ---
+    end_match = re.search(r"\n---\s*\n", content[3:])
+    if not end_match:
+        return {}, content
+
+    frontmatter_text = content[3 : 3 + end_match.start()]
+    remaining = content[3 + end_match.end() :]
+
+    # Parse YAML (simple key: value parsing, no complex types)
+    frontmatter: dict[str, Any] = {}
+    for line in frontmatter_text.strip().split("\n"):
+        if ":" in line:
+            key, _, value = line.partition(":")
+            key = key.strip()
+            value = value.strip()
+
+            # Handle quoted strings
+            if (value.startswith('"') and value.endswith('"')) or (
+                value.startswith("'") and value.endswith("'")
+            ):
+                value = value[1:-1]
+
+            # Handle lists [a, b, c]
+            if value.startswith("[") and value.endswith("]"):
+                items = value[1:-1].split(",")
+                value = [item.strip().strip("\"'") for item in items if item.strip()]
+
+            frontmatter[key] = value
+
+    return frontmatter, remaining
+
+
+def compute_file_hash(path: Path) -> str:
+    """Compute SHA256 hash of a file."""
+    sha256 = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(8192), b""):
+            sha256.update(chunk)
+    return f"sha256:{sha256.hexdigest()}"
+
+
+def scan_skill_files(skill_dir: Path) -> list[SkillFileInfo]:
+    """Scan a skill directory for all files."""
+    files = []
+    # Sort for deterministic ordering across platforms
+    for file_path in sorted(skill_dir.rglob("*")):
+        if file_path.is_file():
+            rel_path = file_path.relative_to(skill_dir)
+            files.append(
+                SkillFileInfo(
+                    # Use POSIX paths for cross-platform URI consistency
+                    path=rel_path.as_posix(),
+                    size=file_path.stat().st_size,
+                    hash=compute_file_hash(file_path),
+                )
+            )
+    return files

fastmcp/server/providers/skills/claude_provider.py

@@ -0,0 +1,44 @@
+"""Claude-specific skills provider for Claude Code skills."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Literal
+
+from fastmcp.server.providers.skills.directory_provider import SkillsDirectoryProvider
+
+
+class ClaudeSkillsProvider(SkillsDirectoryProvider):
+    """Provider for Claude Code skills from ~/.claude/skills/.
+
+    A convenience subclass that sets the default root to Claude's skills location.
+
+    Args:
+        reload: If True, re-scan on every request. Defaults to False.
+        supporting_files: How supporting files are exposed:
+            - "template": Accessed via ResourceTemplate, hidden from list_resources().
+            - "resources": Each file exposed as individual Resource in list_resources().
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.providers.skills import ClaudeSkillsProvider
+
+        mcp = FastMCP("Claude Skills")
+        mcp.add_provider(ClaudeSkillsProvider())  # Uses default location
+        ```
+    """
+
+    def __init__(
+        self,
+        reload: bool = False,
+        supporting_files: Literal["template", "resources"] = "template",
+    ) -> None:
+        root = Path.home() / ".claude" / "skills"
+
+        super().__init__(
+            roots=[root],
+            reload=reload,
+            main_file_name="SKILL.md",
+            supporting_files=supporting_files,
+        )

fastmcp/server/providers/skills/directory_provider.py

@@ -0,0 +1,153 @@
+"""Directory scanning provider for discovering multiple skills."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Literal
+
+from fastmcp.resources.resource import Resource
+from fastmcp.resources.template import ResourceTemplate
+from fastmcp.server.providers.aggregate import AggregateProvider
+from fastmcp.server.providers.skills.skill_provider import SkillProvider
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.versions import VersionSpec
+
+logger = get_logger(__name__)
+
+
+class SkillsDirectoryProvider(AggregateProvider):
+    """Provider that scans directories and creates a SkillProvider per skill folder.
+
+    This extends AggregateProvider to combine multiple SkillProviders into one.
+    Each subdirectory containing a main file (default: SKILL.md) becomes a skill.
+    Can scan multiple root directories - if a skill name appears in multiple roots,
+    the first one found wins.
+
+    Args:
+        roots: Root directory(ies) containing skill folders. Can be a single path
+            or a sequence of paths.
+        reload: If True, re-discover skills on each request. Defaults to False.
+        main_file_name: Name of the main skill file. Defaults to "SKILL.md".
+        supporting_files: How supporting files are exposed in child SkillProviders:
+            - "template": Accessed via ResourceTemplate, hidden from list_resources().
+            - "resources": Each file exposed as individual Resource in list_resources().
+
+    Example:
+        ```python
+        from pathlib import Path
+        from fastmcp import FastMCP
+        from fastmcp.server.providers.skills import SkillsDirectoryProvider
+
+        mcp = FastMCP("Skills")
+        # Single directory
+        mcp.add_provider(SkillsDirectoryProvider(
+            roots=Path.home() / ".claude" / "skills",
+            reload=True,  # Re-scan on each request
+        ))
+        # Multiple directories
+        mcp.add_provider(SkillsDirectoryProvider(
+            roots=[Path("/etc/skills"), Path.home() / ".local" / "skills"],
+        ))
+        ```
+    """
+
+    def __init__(
+        self,
+        roots: str | Path | Sequence[str | Path],
+        reload: bool = False,
+        main_file_name: str = "SKILL.md",
+        supporting_files: Literal["template", "resources"] = "template",
+    ) -> None:
+        super().__init__()
+        # Normalize to sequence: single path becomes list
+        if isinstance(roots, (str, Path)):
+            roots = [roots]
+
+        self._roots = [Path(r).resolve() for r in roots]
+        self._reload = reload
+        self._main_file_name = main_file_name
+        self._supporting_files = supporting_files
+        self._discovered = False
+
+        # Discover skills at init
+        self._discover_skills()
+
+    def _discover_skills(self) -> None:
+        """Scan root directories and create SkillProvider per valid skill folder."""
+        # Clear existing providers if reloading
+        self.providers.clear()
+
+        seen_skill_names: set[str] = set()
+
+        for root in self._roots:
+            if not root.exists():
+                logger.debug(f"Skills root does not exist: {root}")
+                continue
+
+            for skill_dir in root.iterdir():
+                if not skill_dir.is_dir():
+                    continue
+
+                main_file = skill_dir / self._main_file_name
+                if not main_file.exists():
+                    continue
+
+                skill_name = skill_dir.name
+                # Skip if we've already seen this skill name (first wins)
+                if skill_name in seen_skill_names:
+                    logger.debug(
+                        f"Skipping duplicate skill '{skill_name}' from {root} "
+                        f"(already found in earlier root)"
+                    )
+                    continue
+
+                try:
+                    provider = SkillProvider(
+                        skill_path=skill_dir,
+                        main_file_name=self._main_file_name,
+                        supporting_files=self._supporting_files,
+                    )
+                    self.providers.append(provider)
+                    seen_skill_names.add(skill_name)
+                except (FileNotFoundError, PermissionError, OSError):
+                    logger.exception(f"Failed to load skill: {skill_dir.name}")
+
+        self._discovered = True
+        logger.debug(
+            f"SkillsDirectoryProvider loaded {len(self.providers)} skills "
+            f"from {len(self._roots)} root(s)"
+        )
+
+    async def _ensure_discovered(self) -> None:
+        """Ensure skills are discovered, rediscovering if reload is enabled."""
+        if self._reload or not self._discovered:
+            self._discover_skills()
+
+    # Override list methods to support reload
+    async def _list_resources(self) -> Sequence[Resource]:
+        await self._ensure_discovered()
+        return await super()._list_resources()
+
+    async def _list_resource_templates(self) -> Sequence[ResourceTemplate]:
+        await self._ensure_discovered()
+        return await super()._list_resource_templates()
+
+    async def _get_resource(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> Resource | None:
+        await self._ensure_discovered()
+        return await super()._get_resource(uri, version)
+
+    async def _get_resource_template(
+        self, uri: str, version: VersionSpec | None = None
+    ) -> ResourceTemplate | None:
+        await self._ensure_discovered()
+        return await super()._get_resource_template(uri, version)
+
+    def __repr__(self) -> str:
+        roots_repr = self._roots[0] if len(self._roots) == 1 else self._roots
+        return (
+            f"SkillsDirectoryProvider(roots={roots_repr!r}, "
+            f"reload={self._reload}, skills={len(self.providers)})"
+        )