Skip to content

πŸš€ 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.mdx
index 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 Architecture
diff --git a/fastmcp_slim/fastmcp/server/providers/skills/_common.py b/fastmcp_slim/fastmcp/server/providers/skills/_common.py
index 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 Path
from typing import Any
import 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.py
index 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 Sequence
from pathlib import Path
from typing import Literal
-from mcp.shared.path_security import PathEscapeError, safe_join
+from mcp.shared.path_security import PathEscapeError
from fastmcp.resources.base import Resource
from fastmcp.resources.template import ResourceTemplate
@@ -88,9 +88,11 @@ class SkillsDirectoryProvider(AggregateProvider):
continue
for 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.py
index 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 Path
from typing import Any, Literal, cast
from urllib.parse import quote, unquote
-from mcp.shared.path_security import PathEscapeError, safe_join
+from mcp.shared.path_security import PathEscapeError
from pydantic import AnyUrl
from fastmcp.resources.base import Resource, ResourceResult
@@ -18,6 +18,7 @@ from fastmcp.server.providers.base import Provider
from 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.py
index 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 Path
import pytest
-from mcp.shared.path_security import PathEscapeError, safe_join
+from mcp.shared.path_security import PathEscapeError
from mcp_types import TextResourceContents
from 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")