write_file
Write or append content to files in 25-30 line chunks for optimal performance. Use 'rewrite' mode for initial writes and 'append' for subsequent chunks. Always specify absolute paths for reliable file handling.
Instructions
Write or append to file contents.
CHUNKING IS STANDARD PRACTICE: Always write files in chunks of 25-30 lines maximum.
This is the normal, recommended way to write files - not an emergency measure.
STANDARD PROCESS FOR ANY FILE:
1. FIRST → write_file(filePath, firstChunk, {mode: 'rewrite'}) [≤30 lines]
2. THEN → write_file(filePath, secondChunk, {mode: 'append'}) [≤30 lines]
3. CONTINUE → write_file(filePath, nextChunk, {mode: 'append'}) [≤30 lines]
ALWAYS CHUNK PROACTIVELY - don't wait for performance warnings!
WHEN TO CHUNK (always be proactive):
1. Any file expected to be longer than 25-30 lines
2. When writing multiple files in sequence
3. When creating documentation, code files, or configuration files
HANDLING CONTINUATION ("Continue" prompts):
If user asks to "Continue" after an incomplete operation:
1. Read the file to see what was successfully written
2. Continue writing ONLY the remaining content using {mode: 'append'}
3. Keep chunks to 25-30 lines each
Files over 50 lines will generate performance notes but are still written successfully.
Only works within allowed directories.
IMPORTANT: Always use absolute paths for reliability. Paths are automatically normalized regardless of slash direction. Relative paths may fail as they depend on the current working directory. Tilde paths (~/...) might not work in all contexts. Unless the user explicitly asks for relative paths, use absolute paths.
This command can be referenced as "DC: ..." or "use Desktop Commander to ..." in your instructions.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | ||
| mode | No | rewrite | |
| path | Yes |
Implementation Reference
- Handler function that parses arguments using the schema, validates line limits, calls the writeFile helper, and returns success/error response.export async function handleWriteFile(args: unknown): Promise<ServerResult> { try { const parsed = WriteFileArgsSchema.parse(args); // Get the line limit from configuration const config = await configManager.getConfig(); const MAX_LINES = config.fileWriteLineLimit ?? 50; // Default to 50 if not set // Strictly enforce line count limit const lines = parsed.content.split('\n'); const lineCount = lines.length; let errorMessage = ""; if (lineCount > MAX_LINES) { errorMessage = `✅ File written successfully! (${lineCount} lines) 💡 Performance tip: For optimal speed, consider chunking files into ≤30 line pieces in future operations.`; } // Pass the mode parameter to writeFile await writeFile(parsed.path, parsed.content, parsed.mode); // Provide more informative message based on mode const modeMessage = parsed.mode === 'append' ? 'appended to' : 'wrote to'; return { content: [{ type: "text", text: `Successfully ${modeMessage} ${parsed.path} (${lineCount} lines) ${errorMessage}` }], }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return createErrorResponse(errorMessage); } }
- src/tools/filesystem.ts:873-897 (helper)Core implementation that validates the path, performs telemetry capture, and executes the actual file write or append using Node.js fs.promises.export async function writeFile(filePath: string, content: string, mode: 'rewrite' | 'append' = 'rewrite'): Promise<void> { const validPath = await validatePath(filePath); // Get file extension for telemetry const fileExtension = getFileExtension(validPath); // Calculate content metrics const contentBytes = Buffer.from(content).length; const lineCount = countLines(content); // Capture file extension and operation details in telemetry without capturing the file path capture('server_write_file', { fileExtension: fileExtension, mode: mode, contentBytes: contentBytes, lineCount: lineCount }); // Use different fs methods based on mode if (mode === 'append') { await fs.appendFile(validPath, content); } else { await fs.writeFile(validPath, content); } }
- src/tools/schemas.ts:56-60 (schema)Zod schema defining input parameters: path (string), content (string), mode (enum rewrite/append with default). Used for validation in handler.export const WriteFileArgsSchema = z.object({ path: z.string(), content: z.string(), mode: z.enum(['rewrite', 'append']).default('rewrite'), });
- src/server.ts:1244-1246 (registration)Dispatch in CallToolRequestSchema handler that routes 'write_file' tool calls to the filesystem-handlers.handleWriteFile function.case "write_file": result = await handlers.handleWriteFile(args); break;
- src/server.ts:307-346 (registration)Tool specification registration in ListToolsRequestSchema response, including name, detailed description with chunking instructions, input schema from WriteFileArgsSchema, and annotations.name: "write_file", description: ` Write or append to file contents. IMPORTANT: DO NOT use this tool to create PDF files. Use 'write_pdf' for all PDF creation tasks. CHUNKING IS STANDARD PRACTICE: Always write files in chunks of 25-30 lines maximum. This is the normal, recommended way to write files - not an emergency measure. STANDARD PROCESS FOR ANY FILE: 1. FIRST → write_file(filePath, firstChunk, {mode: 'rewrite'}) [≤30 lines] 2. THEN → write_file(filePath, secondChunk, {mode: 'append'}) [≤30 lines] 3. CONTINUE → write_file(filePath, nextChunk, {mode: 'append'}) [≤30 lines] ALWAYS CHUNK PROACTIVELY - don't wait for performance warnings! WHEN TO CHUNK (always be proactive): 1. Any file expected to be longer than 25-30 lines 2. When writing multiple files in sequence 3. When creating documentation, code files, or configuration files HANDLING CONTINUATION ("Continue" prompts): If user asks to "Continue" after an incomplete operation: 1. Read the file to see what was successfully written 2. Continue writing ONLY the remaining content using {mode: 'append'} 3. Keep chunks to 25-30 lines each Files over 50 lines will generate performance notes but are still written successfully. Only works within allowed directories. ${PATH_GUIDANCE} ${CMD_PREFIX_DESCRIPTION}`, inputSchema: zodToJsonSchema(WriteFileArgsSchema), annotations: { title: "Write File", readOnlyHint: false, destructiveHint: true, openWorldHint: false, }, },