fix(filesystem): return valid MCP content type from read_media_file (#4029)

[bryan-anthropic]

Summary

read_media_file returns a content block with type: "blob" for any file that isn't image/* or audio/*. blob is not a valid MCP content type — the content-block union is text | image | audio | resource_link | resource — so a strict client rejects the whole tool result on schema validation (surfaced as MCP error -32602 invalid_union; the reference TypeScript SDK raises a Zod parse error on the invalid content[0]). The result: for any non-image/non-audio file, this tool is unusable against a strict client.

Closes #4029.

Fix

Map the MIME type to a valid MCP content block:

• image/* → { type: "image", data, mimeType }
• audio/* → { type: "audio", data, mimeType }
• anything else → an embedded resource { type: "resource", resource: { uri, mimeType, blob } } — the spec-correct carrier for arbitrary binary data — instead of the invalid type: "blob".

Alongside the handler change:

• the tool's outputSchema is widened to the matching union (so the server-side structuredContent validation accepts both shapes);
• resource.uri is built with pathToFileURL() so spaces / non-ASCII / Windows paths are correctly percent-encoded;
• the now-unnecessary as unknown as CallToolResult cast is dropped, so tsc enforces the returned shape;
• the tool description and README are updated to note that non-media files are returned as an embedded resource.

⚠ Behavior change (worth a release note)

For a file that is neither image nor audio, read_media_file previously returned { type: "blob", data, mimeType } and now returns { type: "resource", resource: { uri, mimeType, blob } } — the base64 payload moves from .data to .resource.blob. Any client that read .data/.mimeType off a blob-typed result for non-media files will need to read the embedded resource instead. Since type: "blob" was never a valid MCP content type (strict clients already rejected it), this is a correctness fix — but it may warrant a server-filesystem version bump / changelog entry.

Alternative considered

If you'd rather keep read_media_file strictly image/audio, the alternative is to reject non-media files (drop blob from the enum and throw for unsupported types) — the approach in #4163. That's simpler but removes the ability to return arbitrary bytes. This PR takes the capability-preserving route; happy to switch to the reject approach if you prefer it.

Tests

Adds a read_media_file (issue #4029) suite to src/filesystem/__tests__/structured-content.test.ts. These are real client.callTool() round-trips through the MCP SDK client, so a schema-invalid result fails the call:

• image / audio return their content type, with a byte round-trip of the base64 data;
• a non-media binary returns a type: "resource" block (never "blob"), the base64 blob round-trips to the original bytes, and the uri decodes back to the file that was read;
• a spaced + non-ASCII filename asserts the uri is percent-encoded (guards pathToFileURL vs a raw file:// string concatenation);
• tools/list advertises the widened outputSchema union with both branches present (guards the JSON-Schema serialization path, which is separate from the callTool validation the other cases exercise).
• each callTool case also asserts structuredContent mirrors content — the SDK validates the two fields independently against the union, so mirror-equality is the only thing that catches them drifting apart (mutation-verified: a schema-valid drifted structuredContent fails exactly these assertions).

npm run build + npm test pass (152 tests).

Related

• Fixes filesystem: read_media_file returns invalid 'blob' content type, violating MCP spec #4029.
• fix(filesystem): use valid MCP content type for read_media_file #4044 implements the same embedded-resource approach; this PR additionally adds pathToFileURL URI-encoding, drops the as unknown as CallToolResult cast, updates the README, and adds the tools/list serialization + uri-identity tests.
• fix(filesystem): reject non-media read_media_file inputs #4163 implements the alternative (reject non-media) approach described above.
• fix(filesystem): declare openWorldHint on all tools #4480 adds openWorldHint: false to all filesystem tools, touching this same file (including the read_media_file block); the two branches auto-merge cleanly in either order (verified locally).

🤖 Generated with Claude Code

[bryan-anthropic]

@olaservo @domdomegg — could I get a review on this when you have a chance? 🙏

[olaservo]

Looks good to me!

[olaservo]

Hi, just ran the npm release process for this change and its now live in https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem/v/2026.7.10

[bryan-anthropic]

@olaservo thank you!