docs+chore(filesystem): batch Info findings — read_file deprecation signal + read_media_file docstring

[yakuphanycl]

Summary

Two batched Info-level documentation/metadata improvements to src/filesystem/index.ts, surfaced by an external MCP audit using the mcp-audit skill.

Per the audit's disclosure SOP, Info-severity findings are batched into a single PR rather than scattered across the tracker. No security impact, no behavioural change.

Findings addressed

F-007 — read_file lacks structured deprecation signal

Default severity: Info (SHAPE--class observation)

read_file already carries the human-readable deprecation in title ("Read File (Deprecated)") and description ("DEPRECATED: Use read_text_file instead."). What's missing is a programmatic signal an MCP client can detect without parsing English from the description.

Fix: add the SDK-supported _meta slot to the registerTool config:

_meta: { deprecated: true, replacement: "read_text_file" }

The SDK already exposes _meta?: Record<string, unknown> in the registerTool config object (@modelcontextprotocol/sdk@^1.26.0, server/mcp.d.ts line ~156), so this is purely additive — no SDK upgrade required, no spec deviation. Clients that ignore _meta see no change; clients that opt in get a stable, parseable signal.

F-008 — read_media_file description missing when-to-use + MIME fallback

Default severity: Info (DISC-003 / DISC-004)

The current two-line description tells what the tool does but not when an agent should reach for it instead of read_text_file, and silently elides the application/octet-stream fallback for unknown extensions.

Fix: rewrite description to add (a) when-to-use guidance — binary content (PNG/JPEG/GIF/WebP/BMP/SVG/MP3/WAV/OGG/FLAC); for plain text use read_text_file because base64 encoding inflates text payloads ~33% with no benefit — and (b) the MIME-fallback note (unknown extensions return as a generic blob with application/octet-stream).

Description-only edit. The handler block (lines 267-298 in current source) is untouched.

Why batched

Per disclosure-sop §2, Info-severity findings (documentation, discoverability, metadata) are batched into one PR per upstream repo. Scattering 2 separate issues for non-functional improvements is unfriendly to maintainers.

Diff

7 insertions, 2 deletions in src/filesystem/index.ts. No new files, no new dependencies, no behavioural change.

Test plan

• Edits are mechanically safe: _meta is part of the SDK's registerTool config interface; description change is a pure string concat.
• read_media_file handler block (lines 267-298) untouched — only the registration metadata above it changes.
• Branch built off upstream/main at commit 4503e2d.
• Maintainer review of description wording.

Reference

Audit case-study (pending publication on the auditor's side): wrg-skills/docs/case-studies/filesystem-mcp-2026-04-26.md. This PR is independent of the case-study landing — the canonical evidence is the diff itself.

🤖 Generated with Claude Code