MCP Filesystem Server

Instructions

Implementation Reference

• src/utils/tools.ts:196-275 (handler)

  Main handler function that performs the file editing logic: reads file, applies sequential text replacements preserving indentation, generates unified diff, and writes changes unless dryRun.
  export async function editFile( args: z.infer<typeof EditFileArgsSchema>, config: Config ): Promise<string> { const endMetric = metrics.startOperation('edit_file') try { const validPath = await validatePath(args.path, config) // Read the original content const content = await fs.readFile(validPath, 'utf-8') let modifiedContent = content // Track whether any edit was applied let appliedAnyEdit = false // Apply each edit for (const edit of args.edits) { const contentLines = modifiedContent.split('\n') let matchFound = false // Normalize line endings const normalizedOld = edit.oldText.replace(/\r\n/g, '\n') const normalizedNew = edit.newText.replace(/\r\n/g, '\n') const oldLines = normalizedOld.split('\n') // Validate edit if (oldLines.length === 0) { throw new InvalidArgumentsError('edit_file', 'Edit operation contains empty oldText') } // Find and replace the text for (let i = 0; i <= contentLines.length - oldLines.length; i++) { const potentialMatch = contentLines.slice(i, i + oldLines.length).join('\n') if (potentialMatch === normalizedOld) { // Preserve indentation const originalIndent = contentLines[i].match(/^\s*/)?.[0] || '' const newLines = normalizedNew.split('\n').map((line, j) => { if (j === 0) return originalIndent + line.trimStart() const oldIndent = oldLines[j]?.match(/^\s*/)?.[0] || '' const newIndent = line.match(/^\s*/)?.[0] || '' if (oldIndent && newIndent) { const relativeIndent = newIndent.length - oldIndent.length return originalIndent + ' '.repeat(Math.max(0, relativeIndent)) + line.trimStart() } return line }) contentLines.splice(i, oldLines.length, ...newLines) modifiedContent = contentLines.join('\n') matchFound = true appliedAnyEdit = true break } } if (!matchFound) { throw new Error(`Could not find exact match for edit:\n${edit.oldText}`) } } // If no edits were applied, return early if (!appliedAnyEdit) { return 'No changes made - all edit patterns were empty or not found' } // Generate diff const diff = createUnifiedDiff(content, modifiedContent, validPath) // Write file if not a dry run if (!args.dryRun) { await fs.writeFile(validPath, modifiedContent, 'utf-8') await logger.debug(`Successfully edited file: ${validPath}`) } endMetric() return diff } catch (error) { metrics.recordError('edit_file') throw error }
• src/utils/tools.ts:175-187 (schema)

  Zod schemas defining EditOperation (oldText/newText) and EditFileArgsSchema (path, edits array, dryRun option) for input validation.
  export const EditOperation = z.object({ oldText: z.string().describe('Text to search for - must match exactly'), newText: z.string().describe('Text to replace with'), }) /** * Schema for edit_file arguments */ export const EditFileArgsSchema = z.object({ path: z.string().describe('Path to the file to edit'), edits: z.array(EditOperation).describe('List of edit operations to perform'), dryRun: z.boolean().default(false).describe('Preview changes using git-style diff format'), })
• src/index.ts:263-269 (registration)

  Tool registration in list_tools response: defines name, description, and converts EditFileArgsSchema to JSON schema for MCP protocol.
  name: 'edit_file', description: 'Make line-based edits to a text file. Each edit replaces exact line sequences ' + 'with new content. Returns a git-style diff showing the changes made. ' + 'Only works within allowed directories.', inputSchema: zodToJsonSchema(EditFileArgsSchema) as ToolInput, },
• src/index.ts:456-470 (handler)

  MCP call_tool dispatcher case: parses arguments with schema, calls editFile handler, returns result as text content.
  case 'edit_file': { const parsed = EditFileArgsSchema.safeParse(a) if (!parsed.success) { throw new FileSystemError(`Invalid arguments for ${name}`, 'INVALID_ARGS', undefined, { errors: parsed.error.format(), }) } const result = await editFile(parsed.data, config) endMetric() return { content: [{ type: 'text', text: result }], } }
• src/utils/tools.ts:286-307 (helper)

  Helper function to generate git-style unified diff between original and modified content, wrapped in markdown code block.
  function createUnifiedDiff( originalContent: string, modifiedContent: string, filePath: string ): string { const diff = createTwoFilesPatch( filePath, filePath, originalContent, modifiedContent, 'Original', 'Modified' ) // Find enough backticks to safely wrap the diff let numBackticks = 3 while (diff.includes('`'.repeat(numBackticks))) { numBackticks++ } return `${'`'.repeat(numBackticks)}diff\n${diff}${'`'.repeat(numBackticks)}\n\n` }