insert_text
Replace or insert text at specific line ranges in files using line-number operations. Ideal for large files or precise edits without context-heavy processing.
Instructions
Insert or replace text at precise line ranges in files
Ideal for direct line-number operations (from code citations like 12:15:file.ts) and large files where context-heavy editing is inefficient.
TIP: Combine with read_symbol to edit any symbol anywhere without knowing its file or line range!
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Path to the file | |
| from_line | Yes | Starting line number (1-based) | |
| text | Yes | Text to insert | |
| to_line | No | Replace up to this line number (1-based, inclusive). If omitted only inserts |
Implementation Reference
- src/tools/insertText.ts:26-32 (handler)Handler function that resolves the file path, reads the file content, updates the text at the specified line range using helper functions, writes back to the file, and returns context around the change.
handler: (args) => { const fullPath = util.resolve(args.file_path) const content = util.readFile(fullPath) const newContent = updateText(content, args.from_line, args.text, args.to_line) util.writeFile(fullPath, newContent) return getContext(newContent, args.from_line, args.text, fullPath) }, - src/tools/insertText.ts:7-12 (schema)Zod schema defining the input parameters for the insert_text tool.
const schema = z.object({ file_path: z.string().min(1).describe('Path to the file'), from_line: z.number().int().min(1).describe('Starting line number (1-based)'), text: z.string().describe('Text to insert'), to_line: z.number().int().min(1).optional().describe('Replace up to this line number (1-based, inclusive). If omitted only inserts'), }) - src/tools.ts:22-29 (registration)Registration of all tools in the tools object, including insert_text mapped to its implementation.
const tools = { read_symbol: readSymbol, import_symbol: importSymbol, search_replace: searchReplace, insert_text: insertText, os_notification: osNotification, utils_debug: utilsDebug, } as const satisfies Record<string, Tool<any>> - src/tools/insertText.ts:37-53 (helper)Helper function that performs the actual line-based text insertion or replacement in the file content.
export function updateText(content: string, fromLine: number, text: string, toLine?: number): string { const endLine = toLine ?? fromLine if (endLine < fromLine) { throw new Error(`Invalid line range: to_line (${endLine}) cannot be less than from_line (${fromLine})`) } const lines = content === '' ? [] : content.split('\n') if (fromLine > lines.length + 1) { throw new Error(`from_line ${fromLine} is beyond file length (${lines.length} lines). Maximum allowed: ${lines.length + 1}`) } if (toLine && endLine > lines.length) { throw new Error(`to_line ${endLine} is beyond file length (${lines.length} lines). Maximum allowed: ${lines.length}`) } const linesToRemove = toLine ? (endLine - fromLine + 1) : 0 const newLines = text.split('\n') lines.splice(fromLine - 1, linesToRemove, ...newLines) return lines.join('\n') } - src/tools/insertText.ts:55-63 (helper)Helper function that generates a context snippet around the inserted text for response.
function getContext(content: string, fromLine: number, text: string, path: string): string { const lines = content.split('\n') const newLines = text.split('\n') // Show from_line - 2 to from_line + newLines.length + 2 const startLine = Math.max(0, fromLine - 1 - CONTEXT_LINES) const endLine = Math.min(lines.length, fromLine - 1 + newLines.length + CONTEXT_LINES) const header = `=== ${startLine + 1}:${endLine + 1}:${path} ===` return `${header}\n${lines.slice(startLine, endLine).join('\n')}` }