fix(mcp): preserve binary skill other files via base64 encoding

[dyoshikawa]

Background

Issue #2573 tracks four follow-ups from the PR #2568 review.

Items 1 and 3, plus the isBinaryBuffer part of item 2, are obsolete: PR #2575 deleted isBinaryBuffer from src/utils/file.ts entirely, because skill companion files are now copied byte-faithfully with no text/binary split.

What remained actionable:

• Item 4 (live bug): src/mcp/skills.ts converted skill other-file buffers with fileBuffer.toString("utf-8") on both get and put, so binary skill files (images, archives) were corrupted through the MCP surface. This is the same class of bug PR fix: write binary skill other-files without UTF-8 corruption #2568/fix(skills): copy skill supporting files byte-faithfully #2575 fixed for import/generate.
• Surviving part of item 2: readFileBufferOrNull had no direct unit tests.

Changes

• Skill otherFiles entries now carry an optional encoding field ("utf-8" | "base64"), applied symmetrically on get and put.
  • On get, encoding is decided by whether the buffer survives a UTF-8 round trip byte-identically; text files keep encoding: "utf-8" and their existing body, so existing clients are unaffected.
  • On put, the client-declared encoding is trusted (defaulting to "utf-8"), base64 bodies are validated to reject silently-dropped invalid input, and the decoded bytes are written with writeFileBuffer instead of writeFileContent.
  • The 1MB size check now measures decoded byte length rather than string length.
• Tool schemas (src/mcp/skills.ts, src/mcp/tools.ts) and tool descriptions updated to expose encoding.
• docs/reference/mcp-server.md documents the otherFiles shape and the encoding rules (embedded docs regenerated).
• Tests: binary other file round-trips byte-identically through put/get, text file keeps the utf-8 shape, omitted encoding is treated as UTF-8 even when the body looks like base64, invalid base64 is rejected, plus direct readFileBufferOrNull tests (missing file -> null, existing file -> exact bytes).

Closes #2573

🤖 Generated with Claude Code