Pin non-blocking skill reads, drop SSE guidance, and tighten dynamic resource docs

Author: vijaydeepsinha

docs/advanced/extensions.md

@@ -137,13 +137,15 @@ The client is its own program, and it carries both halves of the client story:
 
 Normally `resources()` is called once, when the server is built. If your resources change while
 the server runs, set `resources_are_dynamic = True` and the server asks `resources()` again on
-every listing and lookup.
+every listing, and on every lookup that a resource registered directly on the server or an
+earlier dynamic extension hasn't already answered.
 
 Build the new resources completely before you start returning them, so a request never sees a
 half-updated set. Return them as a tuple, and the same tuple until they change, so the server can
-look a resource up by URI instead of scanning every resource on each request. If two resources
-share a URI, the one registered directly on the server wins,
-then dynamic ones in extension order, then templates.
+look a resource up by URI instead of scanning every resource on each request. Don't change a
+resource's URI inside a tuple you've returned; return a new tuple instead. If two resources share
+a URI, the one registered directly on the server wins, then dynamic ones in extension order, then
+templates.
 
 To run background work, such as a task that keeps those resources up to date, override
 `lifespan()` with an `@asynccontextmanager`. Code before its `yield` runs when the server starts,

docs/advanced/skills.md

@@ -254,9 +254,9 @@ Every 30 seconds here, the catalog calls `reload()`. Automatic refresh is **off
 `auto_refresh=True` alone, `refresh_interval` defaults to 60 seconds; it must be a finite number
 greater than zero.
 
-There's no task to start and nothing to stop: the timer runs with the server's lifespan, on stdio,
-SSE and streamable HTTP. SSE enters the lifespan once per connection, so there the timer runs only
-while a client is connected.
+There's no task to start and nothing to stop: the timer runs with the server's lifespan. On
+streamable HTTP that is the server's whole lifetime. A transport that enters the lifespan once per
+connection runs the timer only while a client is connected.
 
 * **A failed refresh changes nothing.** The error is logged and the previous skills keep serving.
   The catalog tries again after the next interval.

src/mcp/server/extension.py

@@ -106,7 +106,7 @@ class Extension:
     #: Reverse-DNS extension identifier, advertised under `ServerCapabilities.extensions`.
     identifier: str
     resources_are_dynamic: bool = False
-    """When true, `resources()` is consulted on each resource listing or lookup."""
+    """When true, `resources()` is called again on each resource listing, and on each lookup not already answered."""
 
     def __init_subclass__(cls, **kwargs: Any) -> None:
         super().__init_subclass__(**kwargs)

src/mcp/server/mcpserver/resources/resource_manager.py

@@ -109,10 +109,12 @@ def add_template(
         return template
 
     def add_resource_provider(self, provider: Callable[[], Sequence[Resource]]) -> None:
-        """Register a dynamic source of concrete resources, consulted on every listing and lookup.
+        """Register a dynamic source of concrete resources.
 
-        Resources added with `add_resource` take precedence, then providers in the order they were added.
-        A provider that returns the same tuple again is looked up by URI without rescanning it.
+        The provider is called on every listing, and on every lookup that a resource added with
+        `add_resource` or an earlier provider hasn't already answered. A provider that returns the
+        same tuple again is looked up by URI without rescanning it, so don't change a resource's URI
+        inside a returned tuple; return a new tuple instead.
         """
         self._resource_sources.append(_ResourceSource(provider))
 

tests/server/skills/test_filesystem.py

@@ -335,6 +335,26 @@ def fstat(fd: int) -> Any:
         await FilesystemSkillProvider(tmp_path).read_file("pipe")
 
 
+async def test_read_file_opens_without_blocking_so_a_fifo_swapped_in_cannot_hang_it(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """SDK-defined: opening a real FIFO needs POSIX, so record the open flags to pin the guard everywhere."""
+    (tmp_path / "SKILL.md").write_bytes(b"x")
+    flags: list[int] = []
+    real_open = os.open
+
+    def recording_open(path: Any, open_flags: int, *args: Any, **kwargs: Any) -> int:
+        flags.append(open_flags)
+        return real_open(path, open_flags, *args, **kwargs)
+
+    monkeypatch.setattr(os, "open", recording_open)
+
+    assert await FilesystemSkillProvider(tmp_path).read_file("SKILL.md") == b"x"
+    nonblock = getattr(os, "O_NONBLOCK", 0)
+    assert len(flags) == 1
+    assert flags[0] & nonblock == nonblock
+
+
 async def test_a_root_that_is_itself_a_link_is_served(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
     """SDK-defined: trusted-root link metadata is not refused; simulate it without needing link privileges."""
     real = tmp_path / "real"