Vulcan File Ops MCP Server

Transform your desktop AI assistants into powerful development partners. Vulcan File Ops bridges the gap between conversational AI (Claude Desktop, ChatGPT Desktop, etc.) and your local filesystem, unlocking the same file manipulation capabilities found in AI-powered IDEs like Cursor and Cline. Write code, refactor projects, manage documentation, and perform complex file operations—matching the power of dedicated AI coding assistants. With enterprise-grade security controls, dynamic directory registration, and intelligent tool filtering, you maintain complete control while your AI assistant handles the heavy lifting.

Table of Contents

• Background

• Install

• Usage

• API

  • Read Operations

    • read_file

    • attach_image

    • read_multiple_files

  • Write Operations

    • write_file

    • write_multiple_files

    • edit_file

  • Filesystem Operations

    • make_directory

    • list_directory

    • move_file

    • file_operations

    • delete_files

    • get_file_info

    • register_directory

    • list_allowed_directories

  • Search Operations

    • glob_files

    • grep_files

  • Shell Operations

    • execute_shell

• Security

• Contributing

• License

Background

Model Context Protocol

The Model Context Protocol (MCP) enables AI assistants to securely access external resources and services. This server implements MCP for filesystem operations, allowing AI agents to read, write, and manage files within controlled directory boundaries.

Key Features

This enhanced implementation provides:

• Dynamic Directory Access: Runtime directory registration through conversational commands

• Document Support: Read/write PDF, DOCX, PPTX, XLSX, ODT with HTML-to-document conversion

• Batch Operations: Read, write, edit, copy, move, or rename multiple files concurrently

• Advanced File Editing: Pattern-based modifications with flexible matching and diff preview

• Flexible Reading Modes: Full file, head/tail, or arbitrary line ranges

• Image Vision Support: Attach images for AI analysis and description

• Directory Filtering: Exclude unwanted folders (node_modules, dist, .git) from listings

• Selective Tool Activation: Enable only specific tools or tool categories

• High Performance: Optimized search algorithms with smart recursion detection

• Security Controls: Path validation, access restrictions, and shell command approval

• Local Control: Full local installation with no external dependencies

Directory Access Model

This server supports multiple flexible approaches to directory access:

1. Pre-configured Access: Use --approved-folders to specify directories on server start for immediate access

2. Runtime Registration: Users can instruct AI agents to register directories during conversation via register_directory tool

3. MCP Roots Protocol: Client applications can provide workspace directories dynamically

4. Flexible Permissions: Combine multiple approaches - start with approved folders, add more at runtime

5. Secure Boundaries: All operations validate against registered directories regardless of access method

Install

This server requires Node.js and can be installed globally, locally, or run directly with npx. Most users should use npx for instant execution without installation.

Quick Start (Recommended for Most Users)

Run directly without installation:

For developers who want to contribute or modify the code, see Local Repository Execution below.

Global Installation

Install globally for system-wide access:

Local Installation

Install in a specific project:

Prerequisites

Node.js (version 14 or higher) must be installed on your system. This provides npm and npx, which are required to run this package.

• Download Node.js: https://nodejs.org/

• Check installation: Run node --version and npm --version

Dependencies

The server has no external service dependencies and operates entirely locally. All required packages are automatically downloaded when using npx.

Usage

This server can be used directly with npx (recommended) or installed globally/locally. The npx approach requires no installation and always uses the latest version.

Basic Configuration

Add to your MCP client configuration (e.g., claude_desktop_config.json):

Option 1: Using npx (Recommended - No Installation Required)

Option 2: Using Global Installation

After running npm install -g @n0zer0d4y/vulcan-file-ops:

Option 3: Using Local Installation

After running npm install @n0zer0d4y/vulcan-file-ops in your project:

Option 4: Local Repository Execution (For Developers)

If you've cloned this repository and want to run from source:

Then configure your MCP client:

Note: The vulcan-file-ops command will be available in your PATH after building, or you can use the full path: ./dist/cli.js

Advanced Configuration

Approved Folders

Pre-configure specific directories for immediate access on server start:

macOS/Linux (npx):

Windows (npx):

Alternative: Local Repository Execution

For users running from a cloned repository (after npm run build):

Path Format Note:

• Windows: Include drive letter (e.g., C:/, D:/). Use forward slashes in JSON to avoid escaping backslashes.

• macOS/Linux: Start with / for absolute paths, or use ~ for home directory.

Benefits:

• Instant Access: Directories are validated and ready immediately when server starts

• Security: Only specified directories are accessible (unless using MCP Roots protocol)

• Convenience: No need to manually register directories via conversation

• AI Visibility: Approved directories are dynamically embedded in register_directory and list_allowed_directories tool descriptions, ensuring AI assistants can see which directories are pre-approved and avoid redundant registration attempts

How AI Assistants See Approved Folders:

When you configure --approved-folders, the server dynamically injects this information into the tool descriptions for register_directory and list_allowed_directories. This ensures:

• ✅ AI assistants can see which directories are already accessible

• ✅ AI knows NOT to re-register pre-approved directories or their subdirectories

• ✅ Clear visibility without requiring the AI to call list_allowed_directories first

• ✅ Works reliably across all MCP clients (including Cursor, Claude Desktop, etc.)

Example of what AI sees in tool description:

Notes:

• Paths must be absolute: Windows requires drive letter (C:/path), Unix/Mac starts with / or ~

• Comma-separated list of directories (no spaces unless part of path)

• Directories are validated on startup; server will exit if any path is invalid

• Works alongside runtime register_directory tool for additional access

• MCP Roots protocol (if used by client) will replace approved folders with workspace roots

Directory Filtering

Exclude specific folders from directory listings:

Tool Selection

Enable only specific tool categories:

Or enable individual tools:

Combined Configuration

All configuration options can be combined:

Windows Example (npx):

macOS/Linux Example (npx):

Alternative: Local Repository Execution

For users running from a cloned repository (after npm run build):

Directory Registration

To access a specific directory, instruct the AI agent:

The AI will use the register_directory tool to gain access, then perform operations within that directory.

API

Available Tools by Categories

Read Operations

read_file

Read file contents with flexible modes (full, head, tail, range)

Input:

• path (string): File path

• mode (string, optional): Read mode

  • full - Read entire file (default)

  • head - Read first N lines

  • tail - Read last N lines

  • range - Read arbitrary line range (e.g., lines 50-100)

• lines (number, optional): Number of lines for head/tail mode

• startLine (number, optional): Start line for range mode

• endLine (number, optional): End line for range mode

Output: File contents as text. Supports text files and documents (PDF, DOCX, PPTX, XLSX, ODT, ODP, ODS)

attach_image

Attach images for AI vision analysis

Input:

• path (string | string[]): Path to image file, or array of paths to attach multiple images at once

Output: Image content in MCP format for vision model processing. Supports PNG, JPEG, GIF, WebP, BMP, SVG

read_multiple_files

Batch read multiple files concurrently

Input:

• files (array): List of file objects with path and optional mode settings

Output: Contents of all files. Failed reads don't stop the operation

Write Operations

write_file

Create or replace file content

Input:

• path (string): File path

• content (string): File content (text or HTML for PDF/DOCX conversion)

Output: Success confirmation. Supports HTML-to-PDF/DOCX conversion with rich formatting

write_multiple_files

Create or replace multiple files concurrently

Input:

• files (array): List of file objects with path and content

Output: Status for each file. Failed writes don't stop other files

edit_file

Apply precise modifications to text and code files with intelligent matching. Supports both single-file and multi-file operations.

Single File Input (mode: 'single'):

• mode (string, optional): Set to "single" (default if omitted for backward compatibility)

• path (string): File path

• edits (array): List of edit operations, each containing:

  • oldText (string): Text to search for (include 3-5 lines of context)

  • newText (string): Text to replace with

  • instruction (string, optional): Description of what this edit does

  • expectedOccurrences (number, optional): Expected match count (default: 1)

• matchingStrategy (string, optional): Matching strategy

  • exact - Character-for-character match (fastest, safest)

  • flexible - Whitespace-insensitive matching, preserves indentation

  • fuzzy - Token-based regex matching (most permissive)

  • auto - Try exact → flexible → fuzzy (default)

• dryRun (boolean, optional): Preview changes without writing (default: false)

• failOnAmbiguous (boolean, optional): Fail when matches are ambiguous (default: true)

Multi-File Input (mode: 'multiple'):

• mode (string): Set to "multiple"

• files (array): Array of file edit requests (max 50), each containing:

  • path (string): File path

  • edits (array): List of edit operations for this file (same structure as above)

  • matchingStrategy (string, optional): Per-file matching strategy

  • dryRun (boolean, optional): Per-file dry-run mode

  • failOnAmbiguous (boolean, optional): Per-file ambiguity handling

• failFast (boolean, optional): Stop on first failure with rollback (true, default) or continue (false)

Features:

• Concurrent processing for multi-file operations

• Atomic operations with automatic rollback on failure (when failFast: true)

• Cross-platform line ending preservation

• Detailed diff output with statistics

Output: Detailed diff with statistics. For multi-file operations, includes per-file results and summary statistics with rollback information for atomic operations.

Important: Use actual newline characters in oldText/newText, NOT escape sequences like \n.

Filesystem Operations

make_directory

Create single or multiple directories (like Unix mkdir -p)

Input:

• paths (string | array): Single path or array of paths

Output: Success confirmation. Creates parent directories recursively, idempotent

list_directory

List directory contents with multiple output formats

Input:

• path (string): Directory path

• format (string, optional): Output format

  • simple - Basic [DIR]/[FILE] listing (default)

  • detailed - With sizes, timestamps, and statistics

  • tree - Hierarchical text tree view

  • json - Structured data with full metadata

• sortBy (string, optional): Sort order

  • name - Alphabetical (default)

  • size - Largest first

• excludePatterns (array, optional): Glob patterns to exclude (e.g., ['*.log', 'temp*'])

Output: Directory listing in specified format with metadata

move_file

Relocate or rename files and directories

Input:

• source (string): Source path

• destination (string): Destination path

Output: Success confirmation

file_operations

Bulk file operations (move, copy, rename)

Input:

• operation (string): Operation type

  • move - Relocate files

  • copy - Duplicate files

  • rename - Rename files

• files (array): List of source-destination pairs

• onConflict (string, optional): Conflict resolution

  • skip - Skip existing files

  • overwrite - Replace existing files

  • error - Fail on conflicts (default)

Output: Status for each operation. Maximum 100 files per operation

delete_files

Delete single or multiple files and directories

Input:

• paths (array): List of paths to delete

• recursive (boolean, optional): Enable recursive deletion

• force (boolean, optional): Force delete read-only files

Output: Status for each deletion. Non-recursive by default for safety

get_file_info

Retrieve file and directory metadata

Input:

• path (string): File or directory path

Output: Size, timestamps, permissions, and type information

register_directory

Enable runtime access to new directories

Input:

• path (string): Directory path to register

Output: Success confirmation. Directory becomes accessible for operations

list_allowed_directories

Display currently accessible directory paths

Input: None

Output: List of all allowed directories

Search Operations

glob_files

Find files using glob pattern matching

Input:

• path (string): Directory to search

• pattern (string): Glob pattern (e.g., **/*.ts)

• excludePatterns (array, optional): Patterns to exclude

Output: List of matching file paths

grep_files

Search for text patterns within files

Input:

• pattern (string): Regex pattern to search

• path (string, optional): Directory to search

• -i (boolean, optional): Case insensitive

• -A/-B/-C (number, optional): Context lines before/after matches

• type (string, optional): File type filter (js, py, ts, etc.)

• output_mode (string, optional): Output format

  • content - Matching lines with line numbers (default)

  • files_with_matches - File paths only

  • count - Match counts per file

• head_limit (number, optional): Limit results

Output: Matching lines with context, file paths, or match counts

Shell Operations

execute_shell

Execute shell commands with security controls

Input:

• command (string): Shell command to execute

• description (string, optional): Command purpose

• workdir (string, optional): Working directory (must be within allowed directories)

• timeout (number, optional): Timeout in milliseconds (default: 30000)

Output: Exit code, stdout, stderr, and execution metadata

Security: All file/directory paths in command arguments are automatically extracted and validated against allowed directories. Commands referencing paths outside approved directories are blocked, preventing directory restriction bypasses.

Multi-File Edit Examples

Batch refactor across multiple files:

Per-file configuration:

For detailed usage examples, see Tool Usage Guide

Security

This MCP server implements enterprise-grade security controls to protect against common filesystem vulnerabilities. All security measures are based on industry best practices and address known CVE patterns.

Protected Against

Path Traversal & Directory Bypass (CWE-22)

• Protected Pattern: CVE-2025-54794 / CVE-2025-53110

• Mitigation: Canonical path validation with path separator requirements prevents prefix collision attacks

• Implementation: Uses isPathWithinAllowedDirectories() which requires actual subdirectory paths (not just prefix matches)

• Example: Blocks /path/to/allowed_evil when /path/to/allowed is approved

Command Injection (CWE-78)

• Protected Pattern: CVE-2025-54795

• Mitigation: Multi-layer validation including command substitution detection, root command extraction, and dangerous pattern matching

• Implementation: Blocks $(), ` `, >(), <() patterns; validates all commands in chains; requires approval for dangerous operations

• Example: Prevents echo "; malicious_cmd; echo" injection attempts

Shell Command Directory Bypass (CWE-22)

• Protected Pattern: Path restriction bypass via absolute paths in shell commands

• Mitigation: Path extraction and validation for all file/directory paths embedded in command arguments

• Implementation: Extracts paths from command strings (handles Windows/Unix paths, quotes, relative paths, environment variables), validates each path against allowed directories before execution

• Example: Blocks type C:\Windows\System32\drivers\etc\hosts and cat /etc/passwd when these paths are outside approved directories

• Scope: Applies to all shell commands executed via execute_shell tool - paths in arguments are validated just like filesystem operations

Symlink Attacks (CWE-59 / CWE-61)

• Protected Pattern: CVE-2025-53109

• Mitigation: All paths resolved via realpath() before validation to follow symlinks to actual targets

• Implementation: Symlink targets must be within allowed directories; validates parent directories for new files

• Example: Blocks symlinks pointing to /etc/passwd even if symlink is in allowed directory

Directory Traversal

• Mitigation: Strict path normalization and validation against approved directories only

• Implementation: Rejects ../ traversal attempts; validates parent directories before file creation

• Example: Blocks access to /unauthorized/path regardless of traversal attempts

Security Controls

Path Validation

• Canonical Path Resolution: All paths normalized and resolved before validation

• Separator Requirement: Subdirectories must include path separators (prevents prefix collision)

• Realpath Resolution: Symlinks resolved to actual targets before access checks

• Parent Directory Validation: New file creation validates parent directory is within allowed scope

Command Execution

• Command Whitelisting: Only pre-approved commands execute without confirmation

• Pattern Detection: Blocks dangerous patterns (destructive, privilege escalation, network execution)

• Command Substitution Blocking: Prevents $(), backticks, process substitution

• Root Command Extraction: Analyzes all commands in chained operations for approval

• Path Argument Validation: Extracts and validates all file/directory paths in command arguments against allowed directories (prevents bypass via absolute paths in commands)

Access Controls

• Directory Whitelisting: Operations restricted to explicitly approved directories

• Runtime Registration: Additional directories require explicit registration via register_directory tool

• Atomic Validation: Paths validated before any file operations begin

• Cross-Platform Safety: Proper handling of Windows/Unix path differences and UNC paths

Security Best Practices

1. Minimize Approved Directories: Only approve directories that require AI access

2. Use Directory Filtering: Exclude sensitive folders (e.g., .git, node_modules) from listings

3. Limit Tool Access: Enable only necessary tools via --enabled-tools or --enabled-tool-categories

4. Command Approval: Pre-approve safe commands via --approved-commands; require approval for others

5. Monitor Operations: Review MCP client logs for unexpected access attempts

6. Regular Updates: Keep the server updated to receive security patches

Security Audit

This server has been audited against known vulnerabilities:

• ✅ CVE-2025-54794 (Path Restriction Bypass) - FIXED

• ✅ CVE-2025-54795 (Command Injection) - PROTECTED

• ✅ CVE-2025-53109 (Symlink Attacks) - PROTECTED

• ✅ CVE-2025-53110 (Directory Containment Bypass) - PROTECTED

For detailed security analysis, see Vulnerability Research Findings.

Supported File Types

Text File Operations

Read Tools (read_file, read_multiple_files):

• Text files: Reads any file as UTF-8 encoded text (source code, configuration files, markdown, JSON, XML, CSV, logs)

• Document files: Automatically detects and parses:

  • PDF (.pdf) - Plain text extraction via pdf-parse

  • Word (.docx) - Markdown with formatting (headings, bold, lists, tables) via mammoth

  • PowerPoint (.pptx) - Plain text extraction via officeparser

  • Excel (.xlsx) - Plain text extraction via officeparser

  • OpenDocument Text (.odt) - Plain text extraction via officeparser

  • OpenDocument Presentation (.odp) - Plain text extraction via officeparser

  • OpenDocument Spreadsheet (.ods) - Plain text extraction via officeparser

• read_file supports four modes for text files:

  • full: Read entire file

  • head: Read first N lines

  • tail: Read last N lines

  • range: Read arbitrary line range (e.g., lines 50-100, inclusive, 1-indexed)

• read_multiple_files allows per-file mode specification - each file can use a different mode in a single operation

• Document files ignore mode parameters and always return full content

• Will produce garbled output for unsupported binary files (images, executables, compressed files)

Write Tools (write_file, write_multiple_files, edit_file):

• Writes UTF-8 encoded text content

• Supports HTML-to-PDF/DOCX conversion with rich formatting (headings, bold, italic, tables, lists, colors)

• Can create: Source code, configuration files, markdown, JSON, XML, CSV, text documents, formatted PDF/DOCX from HTML

• Plain text fallback for PDF/DOCX when HTML is not detected

• Cannot write binary files (no base64-to-binary conversion available)

Image File Operations

Attach Image Tool (attach_image):

• Attaches images for AI vision analysis (requires vision-capable MCP client)

• Supported formats: PNG, JPEG, GIF, WebP, BMP, SVG

• Batch support: Can attach single image or multiple images in one call

• Images are presented to the AI as if uploaded directly by the user

• Enables visual analysis: reading text in images, analyzing diagrams, describing scenes

• Use cases:

  • Analyze screenshots for debugging

  • Extract text from images (OCR-like)

  • Compare UI mockups (attach multiple screenshots at once)

  • Describe charts and graphs

  • Identify objects in photos

• Returns images in MCP standard format for client vision processing

• Only works within allowed directories

Example Usage:

Client Compatibility:

• ✅ Works with: Claude Desktop, Claude.ai, Cursor, ChatGPT Desktop

• ✅ Requires: MCP client with vision capabilities

• ❌ Non-vision clients will receive an error

Note: There is currently no write capability for binary files. You can attach images for vision analysis but cannot create or modify image files through the filesystem tools.

File System Operations

File Operations Tool (file_operations, move_file):

• Works with any file type (text or binary)

• Operations: move, copy, rename

• Handles both files and directories

• Preserves file content without modification during operations

File Editing

Edit File Tool (edit_file):

• Intelligent file modification with automatic matching strategies (exact → flexible → fuzzy)

• Supports multiple sequential edits in one operation

• Provides detailed diff output with statistics

• Optional preview mode (dryRun: true)

• Preserves indentation and line endings

Development Setup

Testing

The project includes comprehensive test coverage. Run tests with:

Contributing

Pull requests are not being accepted for this project.

Bug reports and feature requests are welcome through GitHub issues. Please include:

• For bugs: reproduction steps, expected vs actual behavior, environment details

• For features: clear description of what you need and your use case

Existing issues may already cover your topic, so please search first.

License

This project is licensed under the MIT License - see the LICENSE file for details.