Reject non-text codecs and clarify the migration edge cases

Validate encoding by decoding a probe byte instead of codecs.lookup, so
registered-but-not-text codecs (base64_codec, rot13, hex) are rejected
at construction alongside unknown names, rather than passing validation
and failing on read.

Scope the migration guide's "flips the other way" example to a newly
textual type (application/xml) - text/* files were never blobs in v1 -
and call out separately that text/* files previously decoded with the
platform locale rather than UTF-8.

Author: maxisbey

docs/migration.md

@@ -838,7 +838,7 @@ The field is now `encoding: str | None`. A string means "decode with this encodi
 
 Passing the removed `is_binary=` argument now raises a `ValidationError` at construction (see the section above) rather than being silently ignored. A misspelled `encoding` also fails at construction rather than on the first read.
 
-One case flips the other way: a non-UTF-8 file with a textual mime type (say UTF-16 XML) previously shipped byte-exact as a blob and now fails to decode. Set `encoding` to the file's real encoding, or `encoding=None` to keep serving it as a blob.
+Two edge cases to check. A non-UTF-8 file with a *newly* textual mime type (say a UTF-16 `application/xml`) previously shipped byte-exact as a blob and now fails to decode. And an existing `text/*` file that was only readable through your platform's locale encoding (v1 decoded these with the locale, not UTF-8) now fails too. In both cases set `encoding` to the file's real encoding, or `encoding=None` to serve the bytes as a blob.
 
 **Before (v1):**
 

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

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import codecs
 import json
 from collections.abc import Callable
 from functools import partial
@@ -169,13 +168,17 @@ def validate_absolute_path(cls, path: Path) -> Path:
 
     @pydantic.field_validator("encoding")
     @classmethod
-    def validate_known_encoding(cls, encoding: str | None) -> str | None:
-        """Ensure the encoding names a known codec, so a typo fails at construction not at read."""
+    def validate_text_encoding(cls, encoding: str | None) -> str | None:
+        """Ensure the encoding names a usable text codec, so a mistake fails at construction not at read."""
         if encoding is not None:
+            # Decoding a probe byte rejects both unknown names and codecs that
+            # aren't text encodings (base64_codec, rot13, ...) via LookupError.
             try:
-                codecs.lookup(encoding)
+                b"x".decode(encoding)
             except LookupError as e:
-                raise ValueError(f"unknown encoding: {encoding}") from e
+                raise ValueError(str(e)) from e
+            except UnicodeError:
+                pass  # a real text encoding; the probe byte just doesn't decode in it
         return encoding
 
     async def read(self) -> str | bytes:

tests/server/mcpserver/resources/test_file_resources.py

@@ -124,6 +124,18 @@ def test_unknown_declared_charset_is_rejected(temp_file: Path):
         FileResource(uri=temp_file.as_uri(), path=temp_file, mime_type="text/plain; charset=not-a-codec")
 
 
+def test_multibyte_encoding_is_accepted(temp_file: Path):
+    """UTF-16 can't decode a lone probe byte but is still a valid text encoding."""
+    resource = FileResource(uri=temp_file.as_uri(), path=temp_file, encoding="utf-16")
+    assert resource.encoding == "utf-16"
+
+
+def test_non_text_codec_is_rejected(temp_file: Path):
+    """A registered codec that isn't a text encoding (bytes-to-bytes) is not a usable encoding."""
+    with pytest.raises(ValidationError, match="not a text encoding"):
+        FileResource(uri=temp_file.as_uri(), path=temp_file, encoding="base64_codec")
+
+
 @pytest.mark.anyio
 async def test_json_file_is_served_as_text_by_default(temp_file: Path):
     """The mime type that motivated the encoding field: JSON must not become a base64 blob."""