Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Share strict skill snapshot projection (#6089)

nate nowackd14c168b8322
diff --git a/fastmcp_slim/fastmcp/skills/_constants.py b/fastmcp_slim/fastmcp/skills/_constants.py
index 38199bb05..4854cd751 100644
--- a/fastmcp_slim/fastmcp/skills/_constants.py
+++ b/fastmcp_slim/fastmcp/skills/_constants.py
@@ -1,3 +1,5 @@
"""Shared constants for the MCP Skills extension."""
SKILLS_EXTENSION_ID = "io.modelcontextprotocol/skills"
+MAX_SKILL_FILES = 512
+MAX_SKILL_BYTES = 16 * 1024 * 1024
diff --git a/fastmcp_slim/fastmcp/skills/_snapshot.py b/fastmcp_slim/fastmcp/skills/_snapshot.py
index 3b78f9be3..2754fbaec 100644
--- a/fastmcp_slim/fastmcp/skills/_snapshot.py
+++ b/fastmcp_slim/fastmcp/skills/_snapshot.py
@@ -2,7 +2,6 @@
from __future__ import annotations
-import hashlib
import math
import re
from dataclasses import dataclass
@@ -14,11 +13,9 @@ import yaml
from mcp.shared.path_security import safe_join
from yaml.nodes import MappingNode
-from fastmcp.skills.models import MCPSkill, SkillFrontmatter, SkillResource
-
-# SEP-2640 per-skill limits; servers should not serve skills that exceed them.
-MAX_SKILL_RESOURCES = 512
-MAX_SKILL_BYTES = 16 * 1024 * 1024
+from fastmcp.skills._constants import MAX_SKILL_BYTES, MAX_SKILL_FILES
+from fastmcp.skills.models import MCPSkill, SkillFrontmatter
+from fastmcp.skills.skill import Skill
class _FrontmatterLoader(yaml.SafeLoader):
@@ -99,35 +96,19 @@ def snapshot(root: Path, skill_path: str) -> Snapshot:
main = root / "SKILL.md"
if main not in paths:
raise ValueError("skill must contain SKILL.md")
- if len(paths) > MAX_SKILL_RESOURCES:
- raise ValueError(f"skill has more than {MAX_SKILL_RESOURCES} files")
+ if len(paths) > MAX_SKILL_FILES:
+ raise ValueError(f"skill has more than {MAX_SKILL_FILES} files")
if sum(path.stat().st_size for path in paths) > MAX_SKILL_BYTES:
raise ValueError(f"skill is larger than {MAX_SKILL_BYTES} bytes")
- records: list[SkillResource] = []
+ contents: dict[str, bytes] = {}
files: list[tuple[str, Path]] = []
- frontmatter: SkillFrontmatter | None = None
for path in paths:
- safe_join(root, path.relative_to(root).as_posix())
- content = path.read_bytes()
- uri = f"skill://{quote(skill_path, safe='/')}/{quote(path.relative_to(root).as_posix(), safe='/')}"
- records.append(
- SkillResource(
- uri=uri,
- digest=f"sha256:{hashlib.sha256(content).hexdigest()}",
- size=len(content),
- )
- )
+ relative = path.relative_to(root).as_posix()
+ safe_join(root, relative)
+ contents[relative] = path.read_bytes()
+ uri = f"skill://{quote(skill_path, safe='/')}/{quote(relative, safe='/')}"
files.append((uri, path))
- if path == main:
- frontmatter = parse_frontmatter(content)
if scan_files(root) != paths:
raise ValueError("skill files changed while building the manifest")
- if sum(record.size for record in records) > MAX_SKILL_BYTES:
- raise ValueError(f"skill is larger than {MAX_SKILL_BYTES} bytes")
- assert frontmatter is not None
- entry = MCPSkill(
- uri=f"skill://{quote(skill_path, safe='/')}/SKILL.md",
- frontmatter=frontmatter,
- resources=records,
- )
+ entry = Skill.from_files(contents).to_mcp_skill(skill_path)
return Snapshot(entry=entry, files=tuple(files))
diff --git a/fastmcp_slim/fastmcp/skills/skill.py b/fastmcp_slim/fastmcp/skills/skill.py
index 2694e97a9..23f34093f 100644
--- a/fastmcp_slim/fastmcp/skills/skill.py
+++ b/fastmcp_slim/fastmcp/skills/skill.py
@@ -13,12 +13,9 @@ from urllib.parse import quote
from pydantic import JsonValue
+from fastmcp.skills._constants import MAX_SKILL_BYTES, MAX_SKILL_FILES
from fastmcp.skills.models import MCPSkill, SkillFrontmatter, SkillResource
-# SEP-2640 per-skill limits; servers should not serve skills that exceed them.
-MAX_SKILL_FILES = 512
-MAX_SKILL_BYTES = 16 * 1024 * 1024
-
def _validate_relative_path(path: str) -> str:
if not isinstance(path, str) or not path:
diff --git a/tests/experimental/skills/test_snapshot.py b/tests/experimental/skills/test_snapshot.py
index 0ab596275..e41b5f742 100644
--- a/tests/experimental/skills/test_snapshot.py
+++ b/tests/experimental/skills/test_snapshot.py
@@ -34,6 +34,27 @@ def test_snapshot_preserves_raw_bytes_and_frontmatter(tmp_path: Path):
]
+def test_snapshot_retains_backing_paths_for_encoded_nested_files(tmp_path: Path):
+ (tmp_path / "SKILL.md").write_bytes(
+ b"---\r\nname: review\r\ndescription: Review code\r\n---\r\n"
+ )
+ (tmp_path / "refs").mkdir()
+ supporting = tmp_path / "refs" / "100% #notes.md"
+ supporting.write_bytes(b"\x00\xff\r\n")
+
+ snap = snapshot(tmp_path, "team/review")
+
+ assert dict(snap.files) == {
+ "skill://team/review/SKILL.md": tmp_path / "SKILL.md",
+ "skill://team/review/refs/100%25%20%23notes.md": supporting,
+ }
+ assert isinstance(snap.entry.resources, list)
+ for resource in snap.entry.resources:
+ content = dict(snap.files)[resource.uri].read_bytes()
+ assert resource.size == len(content)
+ assert resource.digest == f"sha256:{hashlib.sha256(content).hexdigest()}"
+
+
@pytest.mark.parametrize(
"extra",
[
@@ -98,7 +119,7 @@ def test_frontmatter_tolerates_utf8_bom():
@pytest.mark.parametrize(
("limit", "value"),
- [("MAX_SKILL_RESOURCES", 1), ("MAX_SKILL_BYTES", 64)],
+ [("MAX_SKILL_FILES", 1), ("MAX_SKILL_BYTES", 64)],
)
def test_snapshot_rejects_skills_over_spec_limits(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch, limit: str, value: int