Report a skill file deleted before reload as a failed read and align read error messages

Author: vijaydeepsinha

docs/advanced/skills.md

@@ -207,8 +207,8 @@ are not served.
     The catalog reads and hashes every file when `load()` runs. By default, it reads files from
     the provider again on each `resources/read` and checks their bytes against that fingerprint.
 
-    If a file changes afterwards, reading it fails with an internal error (`-32603`) until you
-    [reload the catalog](#reloading-skills) or restart the server. And because `load()`
+    If a file changes or is deleted afterwards, reading it fails with an internal error (`-32603`)
+    until you [reload the catalog](#reloading-skills) or restart the server. And because `load()`
     reads every file, a large asset directory makes startup slower.
 
 ### Reloading skills
@@ -265,8 +265,8 @@ connection runs the timer only while a client is connected.
 !!! note
     With `auto_refresh`, the catalog keeps the bytes of every served file **in memory**. That's
     what lets the previous skills keep serving consistently, even if you edit or delete a file on
-    disk while a refresh is still running. Without it, a file edited on disk reads as an internal
-    error until the next `reload()`.
+    disk between refreshes. Without it, a file edited or deleted on disk reads as an internal
+    error until you call `reload()`.
 
 !!! warning
     Clients don't hear about a reload. They may keep a `skills/list` result for `ttl_ms`, and a

src/mcp/server/skills/catalog.py

@@ -72,7 +72,7 @@ class _Fingerprint(BaseModel, frozen=True):
 class _SkillFileResource(Resource):
     """One file of a skill, read from the provider on every `resources/read`.
 
-    The bytes are checked against the digest taken at load time, so a manifest
+    The bytes are checked against the digest taken at the last scan, so a manifest
     entry never describes content other than what is served.
     """
 
@@ -91,9 +91,15 @@ def size(self) -> int:
         return self._fingerprint.size
 
     async def read(self) -> str | bytes:
-        data = await self._provider.read_file(self._path)
+        try:
+            data = await self._provider.read_file(self._path)
+        except OSError as exc:
+            # A file removed or made unreadable between scans is an expected state, not a crash.
+            raise ResourceError(
+                f"{self.uri} could not be read; it was deleted or became unreadable after the last scan"
+            ) from exc
         if _fingerprint(data) != self._fingerprint:
-            raise ResourceError(f"{self.uri} changed since the catalog was loaded")
+            raise ResourceError(f"{self.uri} changed after the last scan")
         try:
             return data.decode("utf-8")
         except UnicodeDecodeError:

tests/server/skills/test_catalog.py

@@ -54,6 +54,7 @@
 pytestmark = pytest.mark.anyio
 
 CATALOG_LOGGER = "mcp.server.skills.catalog"
+SERVER_LOGGER = "mcp.server.mcpserver.server"
 
 
 class _RawResult(BaseModel):
@@ -484,6 +485,31 @@ async def test_reading_a_file_that_changed_after_load_is_an_internal_error() ->
         with pytest.raises(MCPError) as exc_info:
             await client.read_resource("skill://git-workflow/SKILL.md")
     assert exc_info.value.code == INTERNAL_ERROR
+    assert exc_info.value.message == "skill://git-workflow/SKILL.md changed after the last scan"
+
+
+async def test_reading_a_file_deleted_after_load_is_an_internal_error_without_a_traceback(
+    tmp_path: Path, caplog: pytest.LogCaptureFixture
+) -> None:
+    """SDK-defined: a file removed before the next reload is an expected state, logged as a failed read, not a crash."""
+    (tmp_path / "git-workflow").mkdir()
+    (tmp_path / "git-workflow" / "SKILL.md").write_bytes(_skill_md("git-workflow"))
+    (tmp_path / "git-workflow" / "guide.md").write_bytes(b"# Guide\n")
+    catalog = await SkillCatalog.load(FilesystemSkillProvider(tmp_path), parse_frontmatter=_parse)
+    (tmp_path / "git-workflow" / "guide.md").unlink()
+
+    with caplog.at_level(logging.INFO, logger=SERVER_LOGGER):
+        async with Client(MCPServer("skills", extensions=[catalog])) as client:
+            with pytest.raises(MCPError) as exc_info:
+                await client.read_resource("skill://git-workflow/guide.md")
+
+    assert exc_info.value.code == INTERNAL_ERROR
+    assert (
+        exc_info.value.message
+        == "skill://git-workflow/guide.md could not be read; it was deleted or became unreadable after the last scan"
+    )
+    records = [record for record in caplog.records if record.name == SERVER_LOGGER]
+    assert [(record.levelno, record.exc_info) for record in records] == [(logging.INFO, None)]
 
 
 async def test_reading_a_uri_outside_the_catalog_is_invalid_params() -> None: