MCP SmallEdit

Instructions

Implementation Reference

• src/index.ts:801-813 (handler)

  The handler implementation for the 'help' tool. It extracts the 'tool' parameter (default 'all'), looks up the corresponding help content from the helpContent object, and returns it as a text response.
  case 'help': { const { tool = 'all' } = args; const helpKey = tool === 'all' ? 'overview' : tool; const content = helpContent[helpKey] || `No help available for tool: ${tool}\n\nAvailable tools: ${Object.keys(helpContent).join(', ')}`; return { content: [{ type: 'text', text: content }] }; }
• src/index.ts:268-276 (schema)

  The input schema for the 'help' tool, defining an optional 'tool' string parameter.
  inputSchema: { type: 'object', properties: { tool: { type: 'string', description: 'Tool name for help (e.g., "sed_edit", "perl_edit") or "all" for overview' } } }
• src/index.ts:265-277 (registration)

  The registration of the 'help' tool in the server's tools array, including name, description, and input schema.
  { name: 'help', description: 'Get detailed help and examples for smalledit tools', inputSchema: { type: 'object', properties: { tool: { type: 'string', description: 'Tool name for help (e.g., "sed_edit", "perl_edit") or "all" for overview' } } } }
• src/index.ts:283-559 (helper)

  The helpContent object containing detailed help text for all tools, including overview, used by the 'help' handler.
  const helpContent = { overview: `SmallEdit MCP Tool - Help ======================== Provides efficient tools for small, targeted file edits. Available tools: - sed_edit: Pattern-based file editing (uses perl backend) - perl_edit: Direct perl one-liner execution - quick_replace: Simple find/replace without regex - line_edit: Edit specific lines by number - awk_process: AWK script processing - sed_multifile: Apply patterns to multiple files - diff_preview: Preview changes before applying - restore_backup: Restore files from .bak backups - list_backups: Find all backup files - help: This help system 🎯 WHEN TO USE SMALLEDIT vs FILESYSTEM TOOLS: ========================================== USE SMALLEDIT FOR: - Single line changes - Simple pattern replacements - Version number updates - Removing debug statements - Quick find/replace operations - Bulk simple edits across files USE FILESYSTEM TOOLS INSTEAD FOR: - Multi-line code blocks - Complex JSON/YAML structures - Adding new functions or classes - Large refactoring operations - Any edit that's hard to express as a pattern - When you need precise control over formatting ⚠️ COMMON ISSUES TO AVOID: - Don't use smalledit for complex multi-line edits - Be careful with quotes in shell commands - Always preview changes first with diff_preview - Clean up .bak files periodically - Remember perl syntax differs from sed 💡 BETTER ALTERNATIVES: - Instead of sed → Use perl (more portable) - For JSON files → Consider jq instead - For YAML files → Consider yq instead - For modern sed → Install 'sd' (brew install sd) - For better grep → Use ripgrep (rg) 💡 RECOMMENDED WORKFLOW: 1. Use diff_preview first to check changes 2. If it looks good, apply the edit 3. If something goes wrong, use restore_backup 4. Use list_backups to find and clean old backups General tips: - Always use preview/diff_preview to test first - Backups are created by default (.bak files) - Perl patterns are more portable than sed - Use quotes carefully in patterns 🛑 TROUBLESHOOTING: ================ If you see errors like: - "undefined label 'ard/Code'" → macOS sed issue, use perl instead - "unterminated substitute" → Quote escaping problem - "extra characters at end" → Multi-line content issue, use filesystem tools - "division by zero" (awk) → Check field separators and data format 📦 SMALLEDIT PHILOSOPHY: ===================== SmallEdit is designed for SMALL edits. If you're trying to do something complex and getting errors, you're probably using the wrong tool. That's not a bug - it's a feature! Use filesystem:edit_file instead. `, sed_edit: `sed_edit - Pattern-based file editing =================================== Uses perl backend for cross-platform compatibility. Examples: // Simple replacement sed_edit({ file: "config.json", pattern: "s/localhost/production/g" }) // Delete lines containing pattern sed_edit({ file: "app.js", pattern: "$_ = '' if /console\\.log/" }) // Preview changes first sed_edit({ file: "test.txt", pattern: "s/old/new/g", preview: true }) // Edit without backup sed_edit({ file: "temp.txt", pattern: "s/a/b/g", backup: false }) Note: Actually uses perl internally for better compatibility. WHEN NOT TO USE: - Multi-line replacements - Complex code modifications - JSON/YAML structure changes → Use filesystem:edit_file instead! `, perl_edit: `perl_edit - Perl one-liner execution =================================== Direct access to perl's text processing power. Examples: // Simple substitution perl_edit({ file: "data.txt", script: "s/foo/bar/g" }) // Delete lines perl_edit({ file: "log.txt", script: "$_ = '' if /DEBUG/" }) // Transform to uppercase perl_edit({ file: "names.txt", script: "$_ = uc" }) // Complex multiline operations perl_edit({ file: "code.js", script: "s/function\\s+(\\w+)\\s*\\(/const $1 = (/g", multiline: true }) Tips: - Use $_ for the current line - Escape backslashes in regex - multiline mode slurps entire file `, quick_replace: `quick_replace - Simple find and replace ===================================== Literal text replacement without regex. Examples: // Replace all occurrences quick_replace({ file: "doc.txt", find: "Version 1.0", replace: "Version 2.0" }) // Replace only first occurrence quick_replace({ file: "config.ini", find: "debug=true", replace: "debug=false", all: false }) // Replace with special characters quick_replace({ file: "data.csv", find: "$price", replace: "\\$19.99" }) Note: Special regex characters are automatically escaped. `, line_edit: `line_edit - Line-specific operations ================================== Edit, delete, or insert at specific line numbers. Examples: // Replace line 10 line_edit({ file: "list.txt", lineNumber: 10, action: "replace", content: "New line 10" }) // Delete lines 5-15 line_edit({ file: "data.txt", lineRange: "5,15", action: "delete" }) // Insert after line 1 line_edit({ file: "imports.js", lineNumber: 1, action: "insert_after", content: "import React from 'react';" }) // Insert before last line line_edit({ file: "footer.html", lineRange: "$", action: "insert_before", content: "<!-- Updated -->" }) Ranges: - Single line: lineNumber: 42 - Range: lineRange: "10,20" - To end: lineRange: "5,$" `, awk_process: `awk_process - AWK script processing ================================= Powerful text processing with AWK. Examples: // Sum second column awk_process({ file: "numbers.txt", script: "{sum += $2} END {print sum}" }) // Process CSV (comma-separated) awk_process({ file: "data.csv", script: "BEGIN{FS=\",\"} {print $1, $3}" }) // Filter and calculate awk_process({ file: "sales.txt", script: "$3 > 100 {count++; total += $3} END {print \"Count:\", count, \"Avg:\", total/count}" }) // Output to file awk_process({ file: "input.txt", script: "{print $2, $1}", outputFile: "reversed.txt" }) Tips: - Use FS for field separator - $1, $2 etc are fields - NR is line number - END block runs after processing `, sed_multifile: `sed_multifile - Multi-file operations =================================== Apply patterns to multiple files at once. Examples: // Update all JS files sed_multifile({ filePattern: "*.js", pattern: "s/var /let /g" }) // Process files in subdirectories sed_multifile({ directory: "./src", filePattern: "*.ts", pattern: "s/console\\.log.*//g" }) // Without backups (careful!) sed_multifile({ filePattern: "*.tmp", pattern: "s/old/new/g", backup: false }) Note: Uses perl internally. Be careful with patterns affecting many files! `, diff_preview: `diff_preview - Preview changes ============================ See what changes would be made before applying. Examples: // Preview perl substitution diff_preview({ file: "config.json", command: "s/8080/3000/g" }) // Preview with sed syntax diff_preview({ file: "data.txt", command: "10,20d", tool: "sed" }) // Preview AWK processing diff_preview({ file: "log.csv", command: "BEGIN{FS=\",\"} {print $2}", tool: "awk" }) Output: - Shows unified diff format - No changes made to original file - Temp files are cleaned up `, restore_backup: `restore_backup - Restore from backup ================================= Restore a file from its .bak backup file. Examples: // Basic restore restore_backup({ file: "config.json" }) // Looks for config.json.bak and restores it // Restore and remove backup restore_backup({ file: "data.txt", keepBackup: false }) // After a bad edit sed_edit({ file: "app.js", pattern: "s/function/fungtion/g" }) // Oops! restore_backup({ file: "app.js" }) // Fixed! Safety features: - Creates .before-restore backup of current file - Checks for alternative backup formats (.backup, .orig, ~) - Clear error if no backup found `, list_backups: `list_backups - Find backup files ============================== List all backup files in a directory. Examples: // List all .bak files in current directory list_backups({}) // Search specific directory list_backups({ directory: "./src" }) // Find different backup patterns list_backups({ pattern: "*.backup" }) list_backups({ pattern: "*~" }) // Emacs-style // Check entire project list_backups({ directory: ".", pattern: "*.bak" }) Output shows: - Backup file path - File size - Modification date - Original file name (inferred) Useful for cleanup or finding old versions. ` };