feature: add optional content_base64 to write_file to eliminate JSON escaping failures from LLM agents

[Ev3lynx727]

Summary

Add an optional content_base64 parameter to write_file so LLM agents can bypass JSON string escaping failures when content contains quotes, backticks, or special characters.

Problem

write_file accepts content as z.string(). When an LLM generates the tool call JSON, content with ", `, or ${} often results in malformed JSON → parse error → retry loop.

Token Cost (10KB doc)

Retries	Calls	Tokens	vs base64
0	1	3,770	+52%
1	2	7,590	-24%
2	3	11,410	-50%
4	5	19,050	-70% (3.3×)

Breakeven is sub-1 retry. Content with quotes/backticks almost always triggers the problem.

Full analysis: https://github.com/Ev3lynx727/server-commands-rtk/blob/develop/docs/references/000_user_experiences.md

Proposed Fix

WriteFileArgsSchema = z.object({
  path: z.string(),
  content: z.string().optional(),
  content_base64: z.string().optional(),
}).refine(
  args => args.content !== undefined || args.content_base64 !== undefined,
  "Must provide either content or content_base64"
);

When content_base64 is provided, decode server-side:

const content = args.content_base64
  ? Buffer.from(args.content_base64, 'base64').toString('utf-8')
  : args.content;
await writeFileContent(validPath, content);

Base64 charset (A-Za-z0-9+/=) is fully JSON-safe. The server already uses base64 for read_media_file (readFileAsBase64Stream), so zero new dependencies.

Bonus: Binary writes

content: string makes binary writes impossible. content_base64 enables them:

const buffer = Buffer.from(args.content_base64, 'base64');
await fs.writeFile(validPath, buffer);

Scope

Tool	Current	Proposed
write_file	content: string	Add content_base64?: string
edit_file	newText: string	Add newText_base64?: string

Prior art

• server-commands-rtk write_file tool (Node.js, MCP SDK): implements this exact pattern

[Ev3lynx727]

Environment Details

• Agent-Ai framework: OpenCode 1.17.8
• Node.js: v24.15.0
• MCP SDK (server-filesystem): ^1.25.2
• MCP SDK (reference implementation): ^1.9.0
• Platform: Linux x86_64
• server-filesystem version: 2026.1.14

Reproduction Procedure

Prerequisites

• Node.js >= 18
• @modelcontextprotocol/server-filesystem configured in any MCP host (OpenCode, Claude Desktop, etc.)

Steps

1. Attempt a tool call with content containing special characters:

{
  "name": "filesystem_write_file",
  "arguments": {
    "path": "/tmp/test.md",
    "content": "# Test\n\n`inline code` with \"double quotes\" and ${template} literals."
  }
}

2. Result: JSON Parse error: Unterminated string — LLM fails to properly escape backticks/quotes in the JSON parameter framing.

3. The failure is at the JSON serialization layer of MCP transport, not in the server implementation.

When it reproduces

• Content contains backticks (`)
• Content contains unescaped double quotes (")
• Content contains template literal syntax (${})
• Long strings (>10KB) with mixed special characters
• Never reproduces with content_base64 (base64 charset A-Za-z0-9+/= is fully JSON-safe)

Reference Implementation

Production implementation at server-commands-rtk (Node.js, MCP SDK v1.9.0, Apache 2.0):

Zod Schema

export const WriteFileArgs = z.object({
  path: z.string().min(1, "path is required"),
  content_b64: z.string().min(1, "content_b64 is required"),
});

Tool Definition

{
  name: "write_file",
  description: "Write a file with base64-encoded content...",
  inputSchema: {
    type: "object",
    properties: {
      path: { type: "string", description: "Absolute path" },
      content_b64: { type: "string", description: "Base64-encoded content" },
    },
    required: ["path", "content_b64"],
  },
}

Handler

const parsed = WriteFileArgs.parse(args);
const { path: filePath, content_b64 } = parsed;
const dir = path.dirname(filePath);
if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
const buffer = Buffer.from(content_b64, "base64");
const content = buffer.toString("utf8");
writeFileSync(filePath, content, "utf8");

Auto-create parent dirs

The write_file handler auto-creates parent directories if they don't exist. This is a separate UX issue — filesystem_write_file currently errors if the parent directory is missing.

Updated Proposal

Rather than a breaking change, make content_base64 optional alongside existing content:

WriteFileArgsSchema = z.object({
  path: z.string(),
  content: z.string().optional(),
  content_base64: z.string().optional(),
}).refine(
  args => args.content !== undefined || args.content_base64 !== undefined,
  "Must provide either content or content_base64"
);

// Handler
const content = args.content_base64
  ? Buffer.from(args.content_base64, "base64").toString("utf-8")
  : args.content;

Same pattern for edit_file -> newText/newText_base64.

Benefits

• Existing callers with simple content continue using content: string unchanged
• LLM agents hitting serialization issues switch to content_base64
• Binary files become writable for the first time
• Zero new dependencies — server already imports Buffer and has readFileAsBase64Stream

Stress Test Note (v2026.1.14)

We tested server-filesystem v2026.1.14 with a 45KB/90-line payload containing every special character category (backticks, double quotes, ${}, nested JSON) — all wrote correctly via the current content: string param. The latest SDK (^1.25.2) may handle parsing better on the receiving end, but the transport-level vulnerability remains: LLM-generated JSON can still malform before reaching the server. An optional base64 parameter eliminates this class of failure entirely, regardless of SDK version.

Connection

Both are the same root cause: special characters in tool call string parameters break JSON serialization in the MCP tool-call pipeline.

Issue	Tool	Breaks on	Error
#4394	write_file	", `, ${}, long strings	JSON parse error, unterminated string
#2033	edit_file	$() (PowerShell)	Cannot convert undefined or null to object

Why the Fix Works

content_base64 / newText_base64 encode the payload as base64 (A-Za-z0-9+/=). These characters are fully JSON-safe — no escaping, no interpolation, no parse errors.

The fix for #4394 (content_base64 in write_file) was extended to edit_file as newText_base64 in each EditOperation, which automatically covers #2033.

Implementation

Branch: feat/filesystem-content-base64 in Ev3lynx727/servers

• index.ts: WriteFileArgsSchema + EditOperation schema both accept *_base64
• index.ts handlers: Buffer.from(base64, 'base64').toString('utf-8') on server side
• newText_base64 decoded per EditOperation before passing to applyFileEdits