MCP SmallEdit

Instructions

Implementation Reference

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

  The execution handler for the 'help' tool. It extracts the optional 'tool' parameter, looks up the corresponding help content from the helpContent object, and returns it as text content.

  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 definition for the 'help' tool, specifying 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)

  Registration of the 'help' tool in the listTools response, 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 documentation and examples for all tools, including 'overview' and per-tool help texts 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.
  `
  };