Strip userinfo textually and address review notes on the docs

Author: maxisbey

docs/advanced/caching.md

@@ -39,7 +39,7 @@ One caveat on paginated lists: the protocol requires the **same `cacheScope` on
 
 On a 2026-07-28 session, `Client` honors the hints for you: it has a built-in response cache, on by default. A result that arrives carrying a `ttlMs` is stored, and an identical call within that TTL is served from the cache with no round trip. A result that carries *no* hint is not cached: hint-less results get `CacheConfig.default_ttl_ms`, which defaults to `0` (immediately stale), so a server that declares nothing sees exactly the call-for-call traffic it always did.
 
-```python title="client.py" hl_lines="33 35 38"
+```python title="client.py" hl_lines="34 36 39"
 --8<-- "docs_src/caching/tutorial003.py"
 ```
 

docs/migration.md

@@ -429,7 +429,7 @@ For protocol 2026-07-28 over Streamable HTTP, a tool's input-schema property may
 
 ### `Client` verbs may serve cached responses ([SEP-2549](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2549))
 
-On protocol 2026-07-28, servers attach caching hints (`ttlMs`, `cacheScope`) to the cacheable results, and `Client` now honors them: `list_tools`, `list_prompts`, `list_resources`, `list_resource_templates`, and `read_resource` may serve a cached response instead of making a round trip, for as long as the server's `ttlMs` says the result is fresh. Servers that send no hints, including every pre-2026 server, see identical call-for-call behavior, because hint-less results are not cached. Pass `Client(..., cache=False)` to disable the cache and restore v1 behavior exactly; per-call control (`cache_mode`) and configuration (`CacheConfig`) are described in [Caching hints](advanced/caching.md).
+On protocol 2026-07-28, servers attach caching hints (`ttlMs`, `cacheScope`) to the cacheable results, and `Client` now honors them: `list_tools`, `list_prompts`, `list_resources`, `list_resource_templates`, and `read_resource` may serve a cached response instead of making a round trip, for as long as the server's `ttlMs` says the result is fresh. With the default configuration, servers that send no hints, including every pre-2026 server, see identical call-for-call behavior, because hint-less results are not cached (a `CacheConfig.default_ttl_ms` above zero caches them too). Pass `Client(..., cache=False)` to disable the cache and restore v1 behavior exactly; per-call control (`cache_mode`) and configuration (`CacheConfig`) are described in [Caching hints](advanced/caching.md).
 
 ### Server extensions API ([SEP-2133](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2133))
 

docs_src/caching/tutorial003.py

@@ -30,10 +30,11 @@ async def list_tools(ctx: ServerRequestContext[Any], params: PaginatedRequestPar
 
 
 async def main() -> None:
+    start = state.fetches
     async with Client(server, cache=CacheConfig(clock=lambda: state.now)) as client:
         await client.list_tools()  # fetch 1
         await client.list_tools()  # fresh for 60s: served from the cache
         state.now += 60.0
         await client.list_tools()  # the TTL ran out: fetch 2
         await client.list_tools(cache_mode="refresh")  # skip the cache read: fetch 3
-        print(f"4 calls, {state.fetches} fetches")
+        print(f"4 calls, {state.fetches - start} fetches")

src/mcp/client/client.py

@@ -9,7 +9,7 @@
 from contextlib import AsyncExitStack
 from dataclasses import KW_ONLY, dataclass, field
 from typing import Any, Literal, TypeVar, cast
-from urllib.parse import urlsplit, urlunsplit
+from urllib.parse import urlsplit
 
 import anyio
 import anyio.lowlevel
@@ -132,10 +132,11 @@ def _strip_userinfo(url: str) -> str:
 
     Credentials must not enter cache-key material; any further normalization could merge distinct servers.
     """
-    parts = urlsplit(url)
-    if "@" not in parts.netloc:
+    netloc = urlsplit(url).netloc  # raw authority bytes (urlsplit case-folds only `.scheme`), so slicing is exact
+    if "@" not in netloc:
         return url
-    return urlunsplit(parts._replace(netloc=parts.netloc.rpartition("@")[2]))
+    start = url.index("//") + 2
+    return url[:start] + netloc.rpartition("@")[2] + url[start + len(netloc) :]
 
 
 def _evicting_message_handler(cache: ClientResponseCache, user_handler: MessageHandlerFnT | None) -> MessageHandlerFnT:

tests/client/test_client_caching.py

@@ -133,6 +133,22 @@ def test_userinfo_variants_of_a_server_url_share_one_cache_identity() -> None:
     assert _private_arm(bare) == _private_arm(with_password) == _private_arm(with_token)
 
 
+@pytest.mark.parametrize(
+    ("with_userinfo", "bare"),
+    [
+        ("HTTPS://a@X.example/mcp", "HTTPS://X.example/mcp"),
+        ("https://u@h/p?", "https://h/p?"),
+        ("https://u@h/p#", "https://h/p#"),
+    ],
+    ids=["scheme-case", "empty-query", "empty-fragment"],
+)
+def test_stripping_userinfo_changes_no_other_byte_of_the_url(with_userinfo: str, bare: str) -> None:
+    """The removed `userinfo@` is the only byte difference: no scheme case-folding, no dropped
+    empty `?`/`#` delimiters. A userinfo-free URL passes through untouched, so arm equality
+    proves the stripped form is byte-identical to the bare URL."""
+    assert _private_arm(Client(with_userinfo)) == _private_arm(Client(bare))
+
+
 def test_the_server_url_is_sha256_hashed_before_it_enters_key_material() -> None:
     """Pins the docs' secrets-never-in-keys claim: a query-string secret never appears in store keys."""
     client = Client("https://user:pass@example.com/mcp?api_key=SECRET")