π The fast, Pythonic way to build MCP servers and clients.
Keep linked skill folders discoverable (#5766)
nate nowack564d8b626d3a
diff --git a/docs/servers/providers/skills.mdx b/docs/servers/providers/skills.mdxindex 7c2e2d478..69b486cf8 100644--- a/docs/servers/providers/skills.mdx+++ b/docs/servers/providers/skills.mdx@@ -111,7 +111,7 @@ skill://pdf-processing/examples/sample.pdf```<Note>-Skill files, including the main file, must resolve within the skill directory. Links to files within that directory are supported. Directory providers discover skill folders that resolve within each configured root; select a folder directly with `SkillProvider` to use a skill stored elsewhere.+Skill files, including the main file, must resolve within the skill directory. Links to files within that directory are supported. A skill folder can itself be a link, such as an entry in `~/.claude/skills` that points to a checkout elsewhere; the skill's files must then resolve within the folder it links to.</Note>## Provider Architecturediff --git a/fastmcp_slim/fastmcp/server/providers/skills/_common.py b/fastmcp_slim/fastmcp/server/providers/skills/_common.pyindex 473c2de40..08067cd8a 100644--- a/fastmcp_slim/fastmcp/server/providers/skills/_common.py+++ b/fastmcp_slim/fastmcp/server/providers/skills/_common.py@@ -9,6 +9,7 @@ from pathlib import Pathfrom typing import Anyimport yaml+from mcp.shared.path_security import PathEscapeError, safe_join@dataclass@@ -116,6 +117,18 @@ def parse_frontmatter(content: str) -> tuple[dict[str, Any], str]:return parsed, remaining+def resolve_within(base: Path, relative: str) -> Path:+ """Resolve `relative` under `base`, rejecting paths that escape `base`.++ `base` must already be resolved. The containment check uses it as given, so+ replacing it with a link after it was selected cannot move the boundary.+ """+ path = safe_join(base, relative)+ if not path.is_relative_to(base):+ raise PathEscapeError(f"Path {path} escapes base {base}")+ return path++def compute_file_hash(path: Path) -> str:"""Compute SHA256 hash of a file."""sha256 = hashlib.sha256()diff --git a/fastmcp_slim/fastmcp/server/providers/skills/directory_provider.py b/fastmcp_slim/fastmcp/server/providers/skills/directory_provider.pyindex 0011127f4..93678abf0 100644--- a/fastmcp_slim/fastmcp/server/providers/skills/directory_provider.py+++ b/fastmcp_slim/fastmcp/server/providers/skills/directory_provider.py@@ -6,7 +6,7 @@ from collections.abc import Sequencefrom pathlib import Pathfrom typing import Literal-from mcp.shared.path_security import PathEscapeError, safe_join+from mcp.shared.path_security import PathEscapeErrorfrom fastmcp.resources.base import Resourcefrom fastmcp.resources.template import ResourceTemplate@@ -88,9 +88,11 @@ class SkillsDirectoryProvider(AggregateProvider):continuefor skill_dir in root.iterdir():+ # Skill folders may be links to directories elsewhere; the skill's+ # own files must still resolve within the folder it links to.try:- skill_dir = safe_join(root, skill_dir.name)- except (PathEscapeError, OSError, RuntimeError):+ skill_dir = skill_dir.resolve(strict=True)+ except (OSError, RuntimeError):logger.warning(f"Skipping skill directory that cannot be used: {skill_dir.name}")diff --git a/fastmcp_slim/fastmcp/server/providers/skills/skill_provider.py b/fastmcp_slim/fastmcp/server/providers/skills/skill_provider.pyindex f27f6dafb..8cf1bd07a 100644--- a/fastmcp_slim/fastmcp/server/providers/skills/skill_provider.py+++ b/fastmcp_slim/fastmcp/server/providers/skills/skill_provider.py@@ -9,7 +9,7 @@ from pathlib import Pathfrom typing import Any, Literal, castfrom urllib.parse import quote, unquote-from mcp.shared.path_security import PathEscapeError, safe_join+from mcp.shared.path_security import PathEscapeErrorfrom pydantic import AnyUrlfrom fastmcp.resources.base import Resource, ResourceResult@@ -18,6 +18,7 @@ from fastmcp.server.providers.base import Providerfrom fastmcp.server.providers.skills._common import (SkillInfo,parse_frontmatter,+ resolve_within,scan_skill_files,)from fastmcp.utilities.logging import get_logger@@ -54,7 +55,9 @@ class SkillResource(Resource):if self.is_manifest:return self._generate_manifest()else:- main_file_path = safe_join(self.skill_info.path, self.skill_info.main_file)+ main_file_path = resolve_within(+ self.skill_info.path, self.skill_info.main_file+ )return main_file_path.read_text(encoding="utf-8")def _generate_manifest(self) -> str:@@ -81,7 +84,7 @@ class SkillFileTemplate(ResourceTemplate):# Security: reject traversal, absolute-path injection, null bytes, and# symlink escapes before touching the filesystem.try:- full_path = safe_join(self.skill_info.path, file_path)+ full_path = resolve_within(self.skill_info.path, file_path)except PathEscapeError as e:raise ValueError(f"Invalid path: {e}") from e@@ -119,7 +122,7 @@ class SkillFileTemplate(ResourceTemplate):# Security: reject traversal, absolute-path injection, null bytes, and# symlink escapes before touching the filesystem.try:- full_path = safe_join(self.skill_info.path, file_path)+ full_path = resolve_within(self.skill_info.path, file_path)except PathEscapeError as e:raise ValueError(f"Invalid path: {e}") from e@@ -155,7 +158,7 @@ class SkillFileResource(Resource):# Security: reject traversal, absolute-path injection, null bytes, and# symlink escapes before touching the filesystem.try:- full_path = safe_join(self.skill_info.path, self.file_path)+ full_path = resolve_within(self.skill_info.path, self.file_path)except PathEscapeError as e:raise ValueError(f"Invalid path: {e}") from e@@ -228,7 +231,7 @@ class SkillProvider(Provider):if not self._skill_path.exists():raise FileNotFoundError(f"Skill directory not found: {self._skill_path}")- main_file = safe_join(self._skill_path, self._main_file_name)+ main_file = resolve_within(self._skill_path, self._main_file_name)if not main_file.exists():raise FileNotFoundError(diff --git a/tests/server/providers/test_skill_main_files.py b/tests/server/providers/test_skill_main_files.pyindex 30a05e081..7edad5c5d 100644--- a/tests/server/providers/test_skill_main_files.py+++ b/tests/server/providers/test_skill_main_files.py@@ -3,7 +3,7 @@from pathlib import Pathimport pytest-from mcp.shared.path_security import PathEscapeError, safe_join+from mcp.shared.path_security import PathEscapeErrorfrom mcp_types import TextResourceContentsfrom fastmcp import Client, FastMCP@@ -41,20 +41,16 @@ async def test_main_file_is_checked_again_when_read(tmp_path: Path) -> None:await resource.read()[email protected]("entry_link", [False, True])-async def test_directory_keeps_other_skills_when_an_entry_is_outside(- tmp_path: Path, entry_link: bool+async def test_directory_keeps_other_skills_when_a_main_file_is_outside(+ tmp_path: Path,) -> None:root = tmp_path / "skills"root.mkdir()make_skill(root / "ordinary")outside = make_skill(tmp_path / "other")- if entry_link:- (root / "linked").symlink_to(outside, target_is_directory=True)- else:- linked = make_skill(root / "linked")- (linked / "SKILL.md").unlink()- (linked / "SKILL.md").symlink_to(outside / "SKILL.md")+ linked = make_skill(root / "linked")+ (linked / "SKILL.md").unlink()+ (linked / "SKILL.md").symlink_to(outside / "SKILL.md")provider = SkillsDirectoryProvider(root)resources = await provider.list_resources()@@ -112,30 +108,17 @@ async def test_directory_links_within_root_remain_discoverable(tmp_path: Path) -}-async def test_directory_keeps_the_selected_target_when_a_link_changes(- tmp_path: Path, monkeypatch: pytest.MonkeyPatch+async def test_directory_discovers_skill_folders_linked_from_elsewhere(+ tmp_path: Path,) -> None:root = tmp_path / "skills"root.mkdir()- selected = make_skill(root / "selected", "# Selected instructions")- other = make_skill(tmp_path / "other", "# Other instructions")- link = root / "linked"- link.symlink_to(selected, target_is_directory=True)-- def select_path(base: Path, name: str) -> Path:- resolved = safe_join(base, name)- if name == "linked":- link.unlink()- link.symlink_to(other, target_is_directory=True)- return resolved-- monkeypatch.setattr(- "fastmcp.server.providers.skills.directory_provider.safe_join", select_path- )+ make_skill(tmp_path / "checkout")+ (root / "checkout").symlink_to(tmp_path / "checkout", target_is_directory=True)resources = await SkillsDirectoryProvider(root).list_resources()assert {resource.name for resource in resources} == {- "selected/SKILL.md",- "selected/_manifest",+ "checkout/SKILL.md",+ "checkout/_manifest",}@@ -152,3 +135,42 @@ async def test_directory_keeps_valid_skills_when_a_link_cannot_resolve("ordinary/SKILL.md","ordinary/_manifest",}+++async def test_main_file_stays_in_the_loaded_directory_after_a_link_swap(+ tmp_path: Path,+) -> None:+ root = tmp_path / "skills"+ root.mkdir()+ skill = make_skill(root / "skill")+ outside = make_skill(tmp_path / "other", "# Other instructions")+ provider = SkillsDirectoryProvider(root)+ resource = await provider.get_resource("skill://skill/SKILL.md")+ assert resource is not None+ (skill / "SKILL.md").unlink()+ skill.rmdir()+ skill.symlink_to(outside, target_is_directory=True)++ with pytest.raises(PathEscapeError):+ await resource.read()+++async def test_supporting_files_stay_in_the_loaded_directory_after_a_link_swap(+ tmp_path: Path,+) -> None:+ root = tmp_path / "skills"+ root.mkdir()+ skill = make_skill(root / "skill")+ (skill / "notes.md").write_text("# Notes", encoding="utf-8")+ outside = make_skill(tmp_path / "other")+ (outside / "notes.md").write_text("# Other notes", encoding="utf-8")+ server = FastMCP()+ server.add_provider(SkillsDirectoryProvider(root))+ for path in (skill / "notes.md", skill / "SKILL.md"):+ path.unlink()+ skill.rmdir()+ skill.symlink_to(outside, target_is_directory=True)++ async with Client(server) as client:+ with pytest.raises(Exception, match="escapes"):+ await client.read_resource("skill://skill/notes.md")