Build skill manifests with a bisect range instead of scanning every path

Author: vijaydeepsinha

src/mcp/server/skills/catalog.py

@@ -8,6 +8,7 @@
 import logging
 import mimetypes
 import re
+from bisect import bisect_left
 from collections.abc import Callable, Mapping, Sequence
 from pathlib import PurePosixPath
 from typing import Any, Literal, Self, TypeVar
@@ -179,8 +180,8 @@ async def load(
         if ttl_ms < 0:
             raise ValueError("ttl_ms must not be negative")
         paths = _check_paths(list(await provider.list_files()))
-        visible = [path for path in paths if not any(segment.startswith(".") for segment in path.split("/"))]
-        skill_paths = sorted(path for path in visible if path.split("/")[-1] == _SKILL_FILE)
+        visible = sorted(path for path in paths if not any(segment.startswith(".") for segment in path.split("/")))
+        skill_paths = [path for path in visible if path.split("/")[-1] == _SKILL_FILE]
 
         skills: dict[str, Skill] = {}
         served: set[str] = set()
@@ -312,6 +313,15 @@ def _check_paths(paths: list[str]) -> list[str]:
     return paths
 
 
+def _paths_under(sorted_paths: Sequence[str], prefix: str) -> list[str]:
+    """Return the paths that start with `prefix`; they are contiguous in sorted order, so no full scan is needed."""
+    start = bisect_left(sorted_paths, prefix)
+    end = start
+    while end < len(sorted_paths) and sorted_paths[end].startswith(prefix):
+        end += 1
+    return list(sorted_paths[start:end])
+
+
 def _fingerprint(data: bytes) -> _Fingerprint:
     return _Fingerprint(digest=hashlib.sha256(data).hexdigest(), size=len(data))
 
@@ -321,7 +331,7 @@ async def _load_skill(
     parse_frontmatter: Callable[[str], Mapping[str, Any]],
     skill_path: str,
     skill_md: bytes,
-    visible: Sequence[str],
+    sorted_visible: Sequence[str],
     fingerprints: dict[str, _Fingerprint],
 ) -> tuple[Skill, list[str]]:
     """Build the `Skill` whose `SKILL.md` is `skill_path`, along with the paths of its files.
@@ -331,7 +341,7 @@ async def _load_skill(
     """
     frontmatter = _parse_frontmatter(skill_md, parse_frontmatter)
     root = skill_path.removesuffix(_SKILL_FILE)
-    skill_files = [path for path in visible if path.startswith(root)]
+    skill_files = _paths_under(sorted_visible, root)
     for path in skill_files:
         if path not in fingerprints:
             fingerprints[path] = _fingerprint(await provider.read_file(path))

tests/server/skills/test_catalog.py

@@ -181,6 +181,30 @@ async def test_a_nested_skill_is_listed_and_its_files_also_belong_to_the_parent_
     ]
 
 
+async def test_a_skills_files_exclude_siblings_that_only_share_a_name_prefix() -> None:
+    """SDK-defined: a manifest holds only what is under `acme/`, not `acme-tools/`, `acme0/` or `acme.md`.
+
+    The provider lists in reverse order, so the result can't depend on the listing order.
+    """
+    files = {
+        "acme/SKILL.md": _skill_md("acme"),
+        "acme/guide.md": b"guide",
+        "acme-tools/SKILL.md": _skill_md("acme-tools"),
+        "acme0/SKILL.md": _skill_md("acme0"),
+        "acme.md": b"loose",
+    }
+    provider = _MemoryProvider(files, listing=sorted(files, reverse=True))
+    catalog = await SkillCatalog.load(provider, parse_frontmatter=_parse)
+    async with Client(MCPServer("skills", extensions=[catalog]), extensions=[ClientSkills()]) as client:
+        skills = {skill.uri: skill for skill in await client.extension(ClientSkills).list_skills()}
+
+    assert isinstance(skills["skill://acme/SKILL.md"].resources, list)
+    assert [r.uri for r in skills["skill://acme/SKILL.md"].resources] == [
+        "skill://acme/SKILL.md",
+        "skill://acme/guide.md",
+    ]
+
+
 async def test_hidden_files_and_directories_are_never_listed_or_served() -> None:
     """SDK-defined (matches typescript-sdk #3047): a path segment starting with `.` is skipped entirely."""
     server = await _server(