vulcan-file-ops

Attach an image file for AI vision analysis. The image will be presented to the AI model as if uploaded directly by the user, enabling the AI to see and describe visual content, read text in images, analyze diagrams, etc. Supports attaching a single image or multiple images at once. Supports PNG, JPEG, GIF and WebP (the formats vision models accept). SVG files are returned as their XML markup text; BMP is not supported (convert to PNG). Note: This requires the MCP client to support vision capabilities. Only works within allowed directories.

Delete single or multiple files and directories securely. Supports recursive directory deletion with safety controls. All paths are validated before deletion begins. Operations are processed concurrently for performance. Maximum 100 paths per operation. Only works within allowed directories.

Apply precise modifications to text and code files with intelligent matching. **Single File Editing (mode: 'single'):** Edit one file with multiple sequential edits using exact, flexible, or fuzzy matching strategies. **Multi-File Editing (mode: 'multiple'):** Edit multiple files concurrently in a single operation. Each file can have its own edit configuration. **Matching Strategies:** 1. Exact: Character-for-character match (fastest, safest) 2. Flexible: Whitespace-insensitive, preserves original indentation 3. Fuzzy: Token-based regex matching for maximum compatibility **Features:** - Concurrent processing for multi-file operations - Per-file matching strategy control - Dry-run preview mode - Detailed diff output with statistics - Atomic operations with rollback capability - Cross-platform line ending preservation **Maximum:** 50 files per multi-file operation **Best Practices:** - Include 3-5 lines of context before and after the change for reliability - Add 'instruction' field to describe the purpose of each edit - Use 'dryRun: true' to preview changes before applying - For multiple related changes, use array of edits (applied sequentially) - Set 'expectedOccurrences' to validate replacement count - Use 'matchingStrategy' to control matching behavior (defaults to 'auto') **CRITICAL - Multi-line Content:** - Use actual newline characters in oldText/newText strings, NOT \n escape sequences - The MCP/JSON layer handles encoding automatically - Using \n literally will search for/write backslash+n characters (wrong!) Only works within allowed directories.

Execute shell commands on the host system with security controls. Commands are executed as 'bash -c <command>' on Unix/Mac. The tool captures stdout, stderr, exit codes, and signals. Commands exceeding the timeout will be automatically terminated. ⚠️ SECURITY REQUIREMENTS: - At least ONE approved directory must be configured before executing any shell commands - Working directory (workdir parameter or process.cwd()) MUST be within allowed directories - All file/directory paths in arguments and redirections are validated against allowed directories (symlinks are resolved) - Every command in a chain must be approved; chain with ';', '&&', '||' or '|' on a single line - Not allowed: newlines, command substitution, backticks, a lone '&', ( ) { } grouping or script blocks, heredocs, escaped quotes (\" \') - Commands matching dangerous patterns are blocked unless the server operator allowed them If no workdir is specified, the server's current working directory will be used and validated. No pre-approved commands. All commands require user approval before execution. IMPORTANT: Always provide a clear description of what the command does and why it's needed.

Perform bulk file operations (move, copy, rename) on single or multiple files and directories concurrently. All operations are validated for security before execution. Supports conflict resolution strategies for existing destinations. Maximum 100 files per operation for performance.

Extract comprehensive metadata and statistics for files or directories. Provides detailed information including size, timestamps (creation and last modification), permissions, and entry type. Perfect for inspecting file properties and attributes without accessing the actual content. Only works within allowed directories.

Perform recursive pattern-based searches for files and directories. Accepts glob-style patterns matching paths relative to the search root. Use simple patterns like '*.ext' for current directory matches, or '**/*.ext' for deep subdirectory searches. Returns absolute paths to all discovered items. Excellent for locating files when exact paths are unknown. Only searches within allowed directories.

Search text patterns within file contents using regex. Returns matching line numbers and context - use with read_file/read_multiple_files to retrieve actual content. Supports: regex patterns, case-insensitive (-i), context lines (-A/-B/-C), file type filters (type: js/py/ts/etc), glob patterns, multiline mode. Output modes: content (lines+context), files_with_matches (paths only), count (match counts). Respects ignored folders. Use head_limit to cap results. Only searches within allowed directories.

Display all directories currently accessible to the server. Note that subdirectories within listed paths are implicitly accessible as well. Use this to determine available filesystem scope and plan operations accordingly before attempting file access. CURRENTLY ACCESSIBLE DIRECTORIES: None. Use this tool to register directories for access.

List directory contents with flexible output formats. Replaces the previous list_directory, list_directory_with_sizes, and directory_tree tools. Supports simple listings, detailed views with sizes/timestamps, hierarchical tree display, and structured JSON output. Automatically filters globally configured ignored folders. Only works within allowed directories.

Create single or multiple directories with recursive parent creation (like Unix 'mkdir -p'). Idempotent - won't error if directories exist. Only works within allowed directories.

Relocate or rename files and directories in a single atomic operation. Supports cross-directory moves with simultaneous renaming when needed. Fails safely if the destination path already exists to prevent accidental overwrites. Can also perform simple same-directory renames. Both source and destination must be within allowed directories.

Read files with flexible modes. Supports text and documents (PDF, DOCX, PPTX, XLSX, ODT, ODP, ODS). PDF: Extracts with format metadata (fonts, colors, layout). Modes: full (entire file), head (first N lines), tail (last N lines), range (lines from startLine to endLine, inclusive, 1-indexed). Document files ignore mode parameters and always return full content. Only works within allowed directories.

Batch read multiple files concurrently with per-file mode control. Supports text and documents (PDF, DOCX, PPTX, XLSX, ODT, ODP, ODS). Each file can specify its own read mode: full, head (first N lines), tail (last N lines), or range (arbitrary line range). Document files ignore mode parameters and return full content. Processes files concurrently for performance. Maximum 50 files per operation. Only works within allowed directories.

Register a directory for access. This allows the AI to dynamically gain access to directories specified by the human user during conversation. The directory and all its subdirectories will become accessible for all filesystem operations. By default the user must confirm each registration in their MCP client (registration is refused if the client cannot show a confirmation prompt); filesystem roots and the home directory cannot be registered at runtime. CURRENTLY ACCESSIBLE DIRECTORIES: None. Use this tool to register directories for access.

Create/replace files. Supports text (UTF-8), PDF, and DOCX with HTML formatting. **PDF/DOCX with HTML Formatting:** - Provide HTML content for rich formatting (headings, bold, italic, colors, tables, lists) - Supports: <h1>-<h6>, <p>, <div>, <span>, <strong>, <em>, <u>, <table>, <ul>, <ol> - CSS styling: colors, fonts, alignment, borders, margins, padding - Example: '<html><body><h1 style="color: #2c3e50;">Title</h1><p>Content</p></body></html>' - Plain text fallback: If content is not HTML, creates simple formatted document **Text files:** UTF-8 encoding. **Overwrites without confirmation.** IMPORTANT - Multi-line Content: - Use actual newline characters in the content string, NOT escape sequences like \n - MCP/JSON will handle the encoding automatically - Incorrect: {"content": "line1\nline2"} - this writes literal \n characters - Correct: Use actual line breaks in your JSON string value Only works within allowed directories.

Write multiple files concurrently. Supports text, PDF, and DOCX with HTML formatting. File type auto-detected by extension. Failed writes for individual files won't stop others. Returns detailed results for each file. **PDF/DOCX with HTML:** Provide HTML content for rich formatting. Automatically detects HTML and applies formatting. Plain text creates simple documents. IMPORTANT - Multi-line Content: - Use actual newline characters in content strings, NOT \n escape sequences - Each file's content will be written exactly as provided in the string Only works within allowed directories.