Skip to content
BranchesTags

Repository files navigation

Vulcan File Ops MCP Server

TypeScript MCP Registry MCP Dev MCP Server MCP Server with Tools standard-readme compliant License: MIT MseeP.ai Security Assessment Badge

Secure • User-Controlled • High-Performance File Operations 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 VS Code extension like 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

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 as list_directory tool can bloat server output if these types folders, normally gitignored, are included
  • 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. By default you are asked to confirm each new directory through your MCP client (see Runtime Registration Policy)
  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:

npx @n0zer0d4y/vulcan-file-ops --help

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

Global Installation

Install globally for system-wide access:

npm install -g @n0zer0d4y/vulcan-file-ops

Local Installation

Install in a specific project:

npm install @n0zer0d4y/vulcan-file-ops

Prerequisites

Node.js (version 20.19 or higher, or 22.12 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.

For JSON-based clients such as Claude Desktop and Cursor, use their mcpServers JSON format. For Codex, use C:\Users\<username>\.codex\config.toml and the mcp_servers TOML table format shown below.

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

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": ["-y", "@n0zer0d4y/vulcan-file-ops"]
    }
  }
}

Codex (config.toml)

[mcp_servers.vulcan_file_ops]
command = "npx"
args = ["-y", "@n0zer0d4y/vulcan-file-ops"]
enabled = true
startup_timeout_sec = 120.0

Option 2: Using Global Installation

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

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "vulcan-file-ops"
    }
  }
}

Option 3: Using Local Installation

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

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "./node_modules/.bin/vulcan-file-ops"
    }
  }
}

Option 4: Local Repository Execution (For Developers)

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

git clone https://github.com/n0zer0d4y/vulcan-file-ops.git
cd vulcan-file-ops
npm install
npm run build

Then configure your MCP client:

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "node",
      "args": [
        "/absolute/path/to/vulcan-file-ops/dist/cli.js",
        "--approved-folders",
        "/path/to/your/allowed/directories"
      ]
    }
  }
}

Codex (config.toml)

[mcp_servers.vulcan_file_ops]
command = "node"
args = [
  'C:\absolute\path\to\vulcan-file-ops\dist\cli.js',
  "--approved-folders",
  'C:\path\to\your\allowed\directories'
]
cwd = 'C:\absolute\path\to\vulcan-file-ops'
enabled = true
startup_timeout_sec = 120.0

Note: For local repository execution, prefer node dist/cli.js with an absolute path. This works reliably in Codex and avoids PATH ambiguity.

Advanced Configuration

Approved Folders

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

macOS/Linux (npx):

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "-y",
        "@n0zer0d4y/vulcan-file-ops",
        "--approved-folders",
        "/Users/username/projects",
        "/Users/username/documents"
      ]
    }
  }
}

Windows (npx):

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "-y",
        "@n0zer0d4y/vulcan-file-ops",
        "--approved-folders",
        "C:/Users/username/projects",
        "C:/Users/username/documents"
      ]
    }
  }
}

Alternative: Local Repository Execution

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

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "vulcan-file-ops",
      "args": [
        "--approved-folders",
        "/Users/username/projects",
        "/Users/username/documents"
      ]
    }
  }
}

Codex with Approved Folders (config.toml)

[mcp_servers.vulcan_file_ops]
command = "node"
args = [
  'C:\absolute\path\to\vulcan-file-ops\dist\cli.js',
  "--approved-folders",
  'C:\Users\username\projects',
  'C:\Users\username\documents'
]
cwd = 'C:\absolute\path\to\vulcan-file-ops'
enabled = true
startup_timeout_sec = 120.0

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:

PRE-APPROVED DIRECTORIES (already accessible, DO NOT register these):
  - C:\Users\username\projects
  - C:\Users\username\documents

IMPORTANT: These directories and their subdirectories are ALREADY accessible
to all filesystem tools. Do NOT use register_directory for these paths.

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:

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--ignored-folders",
        "node_modules,dist,.git,.next"
      ]
    }
  }
}

Tool Selection

Enable only specific tool categories:

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--enabled-tool-categories",
        "read,filesystem"
      ]
    }
  }
}

Or enable individual tools:

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--enabled-tools",
        "read_file,list_directory,grep_files"
      ]
    }
  }
}

Shell Commands

execute_shell only runs commands whose root command is approved:

  • --approved-commands npm,node,git — comma-separated allowlist of root commands. Every command in a chain (;, &&, ||, |) must be approved.
  • --allow-dangerous-commands rm — approved commands that may also run when they match a dangerous pattern (for example rm -rf, del /s, Remove-Item -Recurse, sudo). Without this flag such commands are always blocked; the AI cannot override it.
  • --commands-env-file <path> — read APPROVED_COMMANDS from a .env-format file. Only that key is used and nothing is added to the server's environment. --approved-commands takes priority.

Changed in 1.3.0: the server no longer reads a .env file from its working directory. Use --approved-commands or --commands-env-file. Do not use --env-file: Node.js reserves that flag and would apply the file to the server process itself.

Note: execute_shell is not a sandbox. An approved interpreter or code-running tool (node, python, bash, npm, git, find -exec, ...) can do anything your user account can do. Only approve commands you are comfortable letting the AI run.

Runtime Registration Policy

--runtime-registration <confirm|allow|deny> controls the register_directory tool:

  • confirm (default) — you are asked to approve each new directory through your MCP client's confirmation prompt (MCP elicitation). If the client does not support confirmation prompts, registration is refused; add the folder with --approved-folders instead, or use allow.
  • allow — directories are registered without a prompt (the behavior before 1.3.0).
  • deny — runtime registration is disabled; only --approved-folders and MCP Roots grant access.

Filesystem roots (such as C:\ or /) and your home directory itself can only be registered with allow.

Combined Configuration

All configuration options can be combined:

Windows Example (npx):

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--approved-folders",
        "C:/Users/username/projects",
        "C:/Users/username/documents",
        "--ignored-folders",
        "node_modules,dist,.git",
        "--approved-commands",
        "npm,node,git,ls,pwd,cat,echo",
        "--enabled-tool-categories",
        "read,filesystem,shell",
        "--enabled-tools",
        "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell"
      ]
    }
  }
}

macOS/Linux Example (npx):

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "npx",
      "args": [
        "@n0zer0d4y/vulcan-file-ops",
        "--approved-folders",
        "/Users/username/projects",
        "/Users/username/documents",
        "--ignored-folders",
        "node_modules,dist,.git",
        "--approved-commands",
        "npm,node,git,ls,pwd,cat,echo",
        "--enabled-tool-categories",
        "read,filesystem,shell",
        "--enabled-tools",
        "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell"
      ]
    }
  }
}

Alternative: Local Repository Execution

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

{
  "mcpServers": {
    "vulcan-file-ops": {
      "command": "vulcan-file-ops",
      "args": [
        "--approved-folders",
        "/Users/username/projects",
        "/Users/username/documents",
        "--ignored-folders",
        "node_modules,dist,.git",
        "--approved-commands",
        "npm,node,git,ls,pwd,cat,echo",
        "--enabled-tool-categories",
        "read,filesystem,shell",
        "--enabled-tools",
        "read_file,attach_image,read_multiple_files,write_file,write_multiple_files,edit_file,make_directory,list_directory,move_file,file_operations,delete_files,get_file_info,register_directory,list_allowed_directories,glob_files,grep_files,execute_shell"
      ]
    }
  }
}

Directory Registration

To access a specific directory, instruct the AI agent:

"Please register the directory C:\path\to\your\folder for access, then list its contents."

The AI will use the register_directory tool to gain access, then perform operations within that directory. With the default --runtime-registration confirm policy your MCP client asks you to approve the directory first.

API

Available Tools by Categories

Read Operations

read_file

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

Note: This tool is limited to single-file operations only. RECOMMENDED: Use read_multiple_files instead, which supports both single and batch file operations for greater flexibility.

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 and WebP (the formats vision models accept). SVG files are returned as their markup text; BMP is not supported (convert to PNG)

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

Note: This tool is limited to single-file operations only. RECOMMENDED: Use write_multiple_files instead, which supports both single and batch file operations for greater flexibility.

Automatic directory creation:

  • If the target file's parent directory does not exist but is inside your configured approved folders, the server will automatically create the required directory structure before writing the file
  • If the path is outside approved folders, the operation fails with a clear error and no directories are created

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

Automatic directory creation:

  • For each requested file, if the parent directory does not exist but is inside your configured approved folders, the server will automatically create the required directory structure before writing
  • Paths outside approved folders are rejected during validation and no directories are created; the operation fails with a detailed list of invalid paths

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

Note: This tool is limited to single-file operations only. RECOMMENDED: Use file_operations instead, which supports move, copy, and rename operations for both single and batch files with greater flexibility.

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. The directory's real path (symlinks resolved) is registered. Subject to --runtime-registration (default: user confirmation via the MCP client).

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. Patterns are limited to 1,000 characters.

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

Regex matching runs in a worker thread with a time budget (5 s per file, 30 s per search), so a pathological pattern fails with a timeout error instead of freezing the server. Patterns are limited to 1,000 characters.

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). If not provided, process.cwd() is used and validated
  • timeout (number, optional): Timeout in milliseconds (default: 30000)
  • requiresApproval (boolean, optional): Deprecated and ignored (kept for compatibility)

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

Security:

  • At least one approved directory must be configured before executing shell commands
  • Working directory (whether explicit or default process.cwd()) is always validated against allowed directories
  • Every command in a chain (;, &&, ||, |) must be in --approved-commands
  • File and directory operands (arguments, option values such as --out=..., and redirection targets) are validated against allowed directories after resolving symlinks and junctions; operands with variables that cannot be resolved are refused
  • Commands must be a single line. Not allowed: newlines, command substitution, backticks, a lone &, ( )/{ } grouping or script blocks, heredocs, and escaped quotes (\", \')
  • Commands matching dangerous patterns are blocked unless the operator allowed them with --allow-dangerous-commands
  • execute_shell is not a sandbox: approved interpreters and code-running tools can still do anything your account can do

Multi-File Edit Examples

Batch refactor across multiple files:

{
  files: [
    {
      path: "src/utils.ts",
      edits: [{
        instruction: "Update deprecated function call",
        oldText: "oldApi.getData()",
        newText: "newApi.fetchData()"
      }]
    },
    {
      path: "src/components/Button.tsx",
      edits: [{
        instruction: "Update component prop",
        oldText: "onClick={oldHandler}",
        newText: "onClick={newHandler}"
      }]
    },
    {
      path: "src/hooks/useData.ts",
      edits: [{
        instruction: "Update hook implementation",
        oldText: "const data = oldApi.getData()",
        newText: "const data = newApi.fetchData()"
      }]
    }
  ],
  failFast: true  // Atomic operation - rollback all if any fails
}

Per-file configuration:

{
  files: [
    {
      path: "config.json",
      edits: [{
        oldText: '"version": "1.0.0"',
        newText: '"version": "1.1.0"'
      }],
      matchingStrategy: "exact"  // JSON needs exact matches
    },
    {
      path: "src/app.py",
      edits: [{
        oldText: "def old_function():",
        newText: "def new_function():"
      }],
      matchingStrategy: "flexible"  // Python indentation may vary
    },
    {
      path: "README.md",
      edits: [{
        oldText: "## Old Section",
        newText: "## New Section"
      }],
      matchingStrategy: "auto"  // Let AI decide best strategy
    }
  ],
  failFast: false  // Continue even if some files fail
}

For detailed usage examples, see Tool Usage Guide

Security

This MCP server implements security controls to protect against common filesystem vulnerabilities, based on known CVE patterns. To report a vulnerability, please follow SECURITY.md (private reporting; do not open a public issue).

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: Commands are parsed with a conservative, quote-aware parser; only a small grammar that bash and PowerShell interpret the same way is accepted, and every command in a chain must be approved
  • Implementation: Rejects newlines and control characters, command substitution, backticks, escaped quotes, a lone &, grouping/script blocks and heredocs; dangerous patterns are blocked unless the operator allows them (--allow-dangerous-commands)
  • Example: echo "\"; malicious_cmd; echo \"" and newline-separated commands are rejected

Shell Command Directory Bypass (CWE-22)

  • Protected Pattern: Path restriction bypass via paths in shell commands
  • Mitigation: Every file operand (arguments, option values such as --out=..., redirection targets, cd targets) is validated against allowed directories after resolving symlinks and junctions
  • Implementation: Operands are checked lexically, after realpath, and with physical resolution (symlinks followed before .., as a POSIX kernel does); relative operands are checked against every directory a cd could leave the command in; unresolvable variables and PowerShell provider paths (env:, HKLM:, ...) are refused
  • Example: Blocks cat /etc/passwd, type C:\Windows\System32\drivers\etc\hosts, echo x >C:\outside\file and cat link/secret (where link points outside) when the targets are outside approved directories
  • Scope: execute_shell is not a sandbox. An approved interpreter or code-running tool can still do anything your account can do, so approve commands sparingly

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 Allowlist: Only commands listed in --approved-commands execute; everything else is blocked
  • Pattern Detection: Blocks dangerous patterns (destructive, privilege escalation, network execution) unless the operator allows the command with --allow-dangerous-commands
  • Structural Parsing: Rejects command substitution, backticks, newlines, grouping and other constructs that could hide commands from validation
  • Root Command Extraction: Analyzes all commands in chained operations for approval
  • Path Operand Validation: Validates all file/directory operands, including redirection targets, against allowed directories with symlink resolution

Access Controls

  • Directory Whitelisting: Operations restricted to explicitly approved directories
  • Runtime Registration: Additional directories require registration via register_directory, which asks the user to confirm by default (--runtime-registration)
  • Resource Limits: Full-file text reads are capped at 10 MB, attach_image at 10 MB per image and 20 MB per call, and Office/ODF documents are checked for zip bombs before parsing
  • 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: Approve only the commands you need via --approved-commands; avoid shells and interpreters (bash, sh, powershell, node, python, eval), which can run arbitrary code
  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 comprehensively audited against known vulnerabilities and static analysis findings:

CVE Protection Status:

  • ✅ CVE-2025-54794 (Path Restriction Bypass) - FIXED
  • ✅ CVE-2025-54795 (Command Injection) - PROTECTED (escaped-quote and newline variants closed in 1.3.0)
  • ✅ CVE-2025-53109 (Symlink Attacks) - PROTECTED (make_directory and execute_shell gaps closed in 1.3.0)
  • ✅ CVE-2025-53110 (Directory Containment Bypass) - PROTECTED
  • ✅ Shell Execution Directory Bypass - FIXED in 1.3.0. The November 2024 fix was incomplete: slash-prefixed paths, attached redirections and symlinked paths could still escape

Latest Security Audits:

  • 📋 Security hardening release 1.3.0 - October 2026

    • Scope: Independent audit of GitHub issue #3 plus a Snyk Open Source / Snyk Code / container scan and manual review
    • Fixed: newline command chaining past the allowlist, shell path validation gaps (slash paths, redirections, symlinks), self-approved dangerous commands, make_directory symlink escape, AI-initiated directory registration without consent, .env loading from the working directory, PDF image handling that could crash the server or fetch remote URLs, unbounded regex/read/decompression resource use, symlink dereferencing in directory copies
    • Dependencies: refreshed with a 14-day release quarantine; all packages pass npm audit signatures
    • See CHANGELOG.md for details

  • 📋 Snyk Vulnerability Audit Report - November 2025

    • Status: 5/6 Snyk findings validated as false positives, 1 finding fixed
    • Risk Level: LOW - Comprehensive path traversal protection verified
    • Static Analysis: Snyk false positive rate 83% due to custom validation not recognized
    • Test Coverage: 2000+ lines of security tests validate all protection measures

  • 📋 CVE Manual Audit - November 2025

    • Status: Critical make_directory vulnerability identified and fixed
    • Focus: CVE-2025-54794/54795 pattern analysis and mitigation strategies
    • Date: November 4, 2025 (Manual CVE Research)

  • 📋 Shell Command Directory Bypass Audit - November 2025

    • Status: Partially fixed November 2024; completed in 1.3.0 (October 2026)
    • Issue: Shell commands previously could access files outside approved directories via absolute paths
    • Severity: HIGH (CVSS ~7.5) - Path traversal via command arguments
    • Fix Status: ✅ FIXED in 1.3.0 - symlink-aware validation of all operands, including redirections
    • Test Coverage: 419 lines of comprehensive tests, all passing

  • 📋 Security Test Coverage Summary

    • Test Suite: 2000+ lines of security-focused tests in src/tests/
    • CVE Tests: Explicit tests for CVE-2025-54794, CVE-2025-54795, CVE-2025-53109
    • Coverage: Path traversal, symlinks (129+ cases), command injection, shell bypass

Security Architecture:

  • Multi-layer path validation (canonical resolution, boundary checking, symlink protection)
  • Defense-in-depth with atomic operations and race condition prevention
  • Directory whitelisting with prefix collision protection
  • Comprehensive security annotations for static analysis tools

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 (SVG is returned as markup text; BMP is not supported)
  • 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:

# Single image
User: "Attach /screenshots/error.png and tell me what's wrong"
AI: [Analyzes image] "This screenshot shows a TypeError on line 42..."

# Multiple images at once
User: "Attach both /screenshots/before.png and /screenshots/after.png and compare them"
AI: [Analyzes both images] "The 'before' screenshot shows..., while the 'after' screenshot..."

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

# Clone the repository
git clone https://github.com/n0zer0d4y/vulcan-file-ops.git
cd vulcan-file-ops

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

# Start development server
npm start

Testing

The project includes comprehensive test coverage. Run tests with:

npm test

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.

About

A Security-centric MCP Server providing enterprise-grade filesystem powers to AI assistants—read, write, edit, and manage files with comprehensive CVE protection and user-controlled access.. [Explore comprehensive code documentation and architecture details on DeepWiki](https://deepwiki.com/n0zer0d4y/vulcan-file-ops)

www.npmjs.com/package/@n0zer0d4y/vulcan-file-ops?activeTab=readme

Topics

batch-operationscode-analysiscode-generationdeveloper-toolsdocx-generationdynamic-directory-accessfilesystemmcp-servermodel-context-protocolpdf-generationsecure-mcpselective-tool-activationshell-executionvibe-coding

Resources

Readme
MIT license

Security policy

Security policy
Activity

Stars

9 stars

Watchers

0 watching

Forks

4 forks
Report repository

Releases

Packages

Contributors

Languages