Skip to main content
Glama
deenesjakoruzh
n0zer0d4y

vulcan-file-ops

by n0zer0d4y
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

# Vulcan File Ops MCP Server

TypeScript MCP Registry MCP Dev MCP Server MCP Server with Tools standard-readme compliant License: MIT

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

Related MCP server: file-system-mcp-server

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.

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.

Available Tools

17 tools
attach_imageA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesPath(s) to image file(s) to attach for AI vision analysis. For maximum MCP client compatibility, provide an array even when attaching a single image.

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden, and it does substantial work: it discloses a client capability prerequisite, a directory restriction, and non-obvious format behavior (SVG returned as XML markup, BMP unsupported). It omits what a successful attachment returns or how failures surface, but the disclosed constraints are the ones an agent is most likely to trip over.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, then capability context, then format constraints and caveats in a logical order. Slightly dense with parenthetical asides ('the formats vision models accept', 'convert to PNG'), but every sentence carries usable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with no output schema and no annotations, the description covers the vision-capability requirement, allowed-directory scoping, and accepted/rejected formats - the main things an agent needs to invoke it correctly. It could say more about what happens on success or unsupported input, but coverage is strong overall.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the single 'path' parameter is already documented, including the guidance to pass an array even for a single image. The description's 'single image or multiple images at once' and format notes add modest meaning but do not go beyond what the schema already conveys. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Attach') and resource ('image file') and immediately qualifies the outcome ('for AI vision analysis'), which cleanly separates it from text-oriented siblings like read_file or read_multiple_files. An agent can tell what this does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a clear use context ('enabling the AI to see and describe visual content, read text in images, analyze diagrams') and a prerequisite ('requires the MCP client to support vision capabilities'). It does not, however, name a sibling alternative or state when-not to use this (e.g., pointing text files to read_file).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_filesA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
forceNoForce deletion even if files are read-only
pathsYesArray of file or directory paths to delete
recursiveNoEnable recursive deletion for directories

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses path validation, concurrent processing, recursive deletion, force option, and allowed-directory scope. However, it does not detail error handling or recovery, slightly reducing transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is four sentences, each adding distinct information: purpose, features, validation, concurrency, limits, and scope. It is front-loaded with the core action and contains no redundant words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple deletion tool with 3 parameters and no output schema, the description covers purpose, constraints, and key behaviors. However, it lacks information on return values or partial failure handling, which would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline is 3. The description adds behavioral context beyond the schema by noting that all paths are validated and operations are concurrent, which enhances understanding of the parameters' effects.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it deletes single or multiple files and directories. It specifies secure deletion, recursive support, and path validation, which distinguishes it from sibling tools like move_file or write_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes constraints like maximum paths and allowed directories but does not explicitly compare to alternatives like move_file. Usage guidance is implied but not explicit about when to choose this tool over siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

edit_fileA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNoEdit mode: 'single' for one file, 'multiple' for batch editingsingle
pathNoPath to file (required for single mode)
editsNoArray of edits to apply
filesNoArray of file edit requests (required for multiple mode)
dryRunNoPreview changes without writing
failFastNoStop processing on first file failure (true) or continue with remaining files (false)
failOnAmbiguousNoIf true, fail when oldText matches multiple locations (unless expectedOccurrences > 1). If false, replace first occurrence only and warn about ambiguity.
matchingStrategyNoMatching strategy: - 'exact': Strict character-for-character match (fastest, safest) - 'flexible': Whitespace-insensitive line-by-line matching - 'fuzzy': Token-based regex matching (most permissive) - 'auto': Try exact → flexible → fuzzy (recommended, default)auto

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses atomic operations with rollback, concurrent processing, cross-platform line ending preservation, and a maximum of 50 files per operation. It mentions dry-run preview mode and matching strategies. However, it could be more explicit that the tool writes to disk and is potentially destructive if oldText matches incorrectly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-organized with sections for modes, matching strategies, features, and best practices. It front-loads the core purpose. Each sentence adds information, though slight trimming of redundant phrases (e.g., 'per-file matching strategy control' in Features) could improve conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and no output schema, the description mentions 'detailed diff output with statistics' but does not specify the exact return structure. It covers modes, strategies, and best practices adequately, but lacks explicit error handling details beyond ambiguous matches. Overall, it is sufficient for an agent to use correctly, but gaps remain in output information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. The description adds significant value by explaining matching strategies, best practices for oldText/newText, and the purpose of instruction and expectedOccurrences fields. It also provides critical guidance on multi-line content representation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool applies precise modifications to text and code files, details single and multi-file editing modes, and outlines matching strategies. It clearly distinguishes from sibling tools like write_file (which overwrites entire files) and delete_files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Best practices are provided (e.g., include 3-5 lines of context, use dryRun, set expectedOccurrences). A critical note about multi-line content warnings against using \n. It implicitly advises against using this tool for complete file rewrites (use write_file). However, it does not explicitly state when NOT to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

execute_shellA

Execute shell commands on the host system with security controls. Commands are executed as 'bash -c ' 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
commandYesShell command to execute. For Windows: executed as 'powershell.exe -Command <command>'. For Unix/Mac: executed as 'bash -c <command>'. *** WARNING: Command substitution using $(), ``, <(), or >() may be restricted for security.
timeoutNoTimeout in milliseconds for command execution. Defaults to 30000 (30 seconds). Commands exceeding this duration will be terminated.
workdirNoOptional absolute path to the directory where the command should be executed. Must be within allowed directories. If not provided, uses current working directory.
descriptionNoBrief description of what the command does and why it's needed. Be specific and concise. Ideally a single sentence. Can be up to 3 sentences for clarity. No line breaks.
requiresApprovalNoDeprecated and ignored. Kept for backward compatibility. Commands matching dangerous patterns can only be allowed by the server operator (--allow-dangerous-commands).

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations present, the description carries the full behavioral burden and does so thoroughly: it discloses the execution model (bash -c / powershell.exe -Command), the return payload (stdout, stderr, exit codes, signals), timeout-driven termination, symlink resolution and path validation, per-command approval in chains, blocked dangerous patterns, and the operator-only override. This is exactly the mutation/auth/security context an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then cleanly organized into a security-requirements block and a final imperative. It is long, and a few facts (timeout termination, workdir validation) are repeated from the schema, which slightly dilutes density, but the structure is easy to scan and nothing is padded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-parameter, no-annotation, no-output-schema mutation tool, the description covers everything an agent needs: execution semantics, return contents, timeout behavior, approval flow, directory prerequisites, and command-syntax restrictions. Return values are described inline, which is necessary given there is no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so the schema documents all five parameters. The description still adds value by clarifying workdir resolution ('workdir parameter or process.cwd()') and its validation, reinforcing the timeout termination behavior, and explicitly instructing the agent to always populate the description parameter with what and why. The requiresApproval deprecation is left to the schema only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a precise verb+resource ('Execute shell commands on the host system') and immediately frames the scope with security controls, clearly separating it from the file-oriented siblings like read_file, write_file, or grep_files. An agent knows exactly what this tool does without inspecting the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Prerequisites are explicit: at least one approved directory must be configured, workdir must be within allowed directories, and every command requires user approval. It also enumerates when-not conditions (newlines, command substitution, backticks, grouping, heredocs, escaped quotes). It never names an alternative sibling (e.g., prefer read_file/grep_files over shell for file reads), so it stops short of full routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

file_operationsA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
filesYesArray of source-destination file pairs
operationYesThe type of file operation to perform
onConflictNoHow to handle destination conflictserror

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses security validation, concurrency, conflict resolution, and file limit. No annotations, so description carries full burden; could add atomicity or error handling details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-loading purpose and key constraints with zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Missing output description for a bulk operation; agents need to know what is returned (e.g., success/failure per file).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already describes parameters well; description adds context (bulk, concurrent, validated, limit). Over baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states bulk file operations (move, copy, rename) on single or multiple files/concurrently, distinguishing it from single-file siblings like move_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

States context for bulk operations and performance limits, but lacks explicit when-not or alternative tool mentions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_file_infoA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the constraint of allowed directories but does not mention other behavioral traits such as no side effects, permissions, or rate limits. Adequate but lacks richer context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no waste. First sentence states purpose, second provides details, third gives usage guidance and constraint. Front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers purpose, details of metadata, when to use, and the constraint. For a simple tool with one parameter and no output schema, it is largely complete, though it could mention return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter 'path' with no description in schema (0% coverage). The description only says 'files or directories' without specifying format, absolute/relative, or examples, adding minimal value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool extracts comprehensive metadata and statistics for files or directories, distinguishing it from sibling tools like read_file (content) or list_directory (listing entries). It specifies the details included: size, timestamps, permissions, entry type.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates the tool is for inspecting file properties without accessing content, and notes it only works in allowed directories. It provides clear context but does not explicitly state when not to use or name alternatives, though siblings imply differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

glob_filesA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesDirectory to search
patternYesGlob pattern: *.js, **/*.test.ts
excludePatternsNoExclude patterns

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description discloses recursive search, glob patterns, absolute paths, and directory restrictions. Missing details like read-only nature, performance implications, or auth requirements, which would be valuable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences front-loaded with purpose, then details. No redundancy, every sentence provides useful information. Efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a file search tool, description covers key aspects: pattern syntax, recursion, return type (absolute paths), and directory constraints. No output schema needed; description sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. Description adds value by explaining pattern examples ('*.ext', '**/*.ext') and describing excludePatterns purpose, going beyond schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it performs recursive pattern-based searches for files and directories using glob-style patterns. Distinguishes from sibling tools like grep_files (content search) and listing tools by focusing on path patterns.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear usage context: use when exact paths are unknown, with examples of simple and recursive patterns. No explicit when-not-to-use or alternative tool references, but the description adequately guides usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

grep_filesA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
-ANoLines after match
-BNoLines before match
-CNoLines before+after match
-iNoCase insensitive
globNoGlob filter. Without a slash it matches file names at any depth (*.md, *.test.ts); with a slash it matches the path relative to the search root (src/**/*.ts)
pathNoDirectory/file to search (optional)
typeNoFile type filter: js, py, ts, etc
patternYesRegex pattern to search for
multilineNoAllow . to match newlines
head_limitNoLimit results to N
output_modeNocontent|files_with_matches|countcontent

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and largely succeeds: it discloses scoping constraints ('Respects ignored folders', 'Only searches within allowed directories'), result capping via head_limit, and the shape of the return (matching line numbers and context). It omits error behavior for invalid regex and any performance/pagination caveats.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action, then organized into capability and output-mode clusters; every sentence is relevant. It is slightly list-like and repeats some schema-level detail, but for an 11-parameter tool the length is justified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema and no annotations, yet the description covers the return shape (line numbers/context vs. paths vs. counts), the safety scoping (allowed directories, ignored folders), and result limiting. It stops short of covering error cases or search-root defaults, but an agent has enough to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3; the description adds genuine meaning for output_mode by spelling out what 'content', 'files_with_matches', and 'count' actually yield, which the bare enum values do not. The flags (-i, -A/-B/-C, type, glob, multiline) largely restate schema descriptions rather than extending them.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Search text patterns within file contents using regex') and clarifies its role in the workflow by pointing to read_file/read_multiple_files for retrieving content, implicitly distinguishing it from file-name-based tools like glob_files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells the agent how this tool pairs with read_file/read_multiple_files ('use with ... to retrieve actual content'), which is real routing guidance. However, it never states when NOT to use it (e.g., use glob_files for locating files by name), so no explicit exclusion is offered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_allowed_directoriesA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It describes a read-only listing with no side effects, but could mention if there are any constraints like rate limits or whether the list is cached.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences in first paragraph clearly state purpose and nuance; second paragraph adds current state. While efficient, the second paragraph slightly repeats the purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity (no parameters, no output schema), the description is fully complete: explains what it shows, includes subdirectory behavior, and provides usage guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters, so baseline 4. The description adds no parameter info because none exist, which is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it displays all accessible directories, includes the nuance of subdirectory implicit accessibility, and distinguishes from sibling tools like list_directory and register_directory.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use (to determine filesystem scope before file access), notes the current state (no directories), and directs to register_directory as an alternative for adding directories.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_directoryA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesAbsolute path to the directory to list
formatNoOutput format: 'simple' (basic listing), 'detailed' (with sizes and metadata), 'tree' (hierarchical text tree), 'json' (structured data)simple
sortByNoSort by name (alphabetical) or size (largest first)name
excludePatternsNoGlob patterns to exclude (e.g., ['*.log', 'temp*']). Applied in addition to globally configured ignored folders.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses that globally configured ignored folders are automatically filtered and that the tool replaces previous versions, but does not mention error handling or performance characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each providing essential information: purpose, replacement status, format options, filtering behavior, and access restriction. No redundant or irrelevant content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 4 parameters, no annotations, and no output schema, the description covers purpose, formats, sort options, exclusion patterns, and access restrictions adequately. The missing output schema is acceptable since the tool returns directory listings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the format parameter variants (simple, detailed, tree, json) and clarifying that excludePatterns are applied in addition to global filters, which is not in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List directory contents with flexible output formats' and specifies that it replaces three previous tools, making its purpose distinct from siblings like 'execute_shell' or 'file_operations'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions 'Only works within allowed directories' but does not provide explicit when-to-use or when-not-to-use guidance relative to alternatives like 'glob_files' or 'get_file_info'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

make_directoryA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathsYesDirectory paths to create. For maximum MCP client compatibility, provide an array even when creating a single directory.

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description discloses key behaviors: idempotent (won't error if exist), recursive parent creation, and directory restrictions. This covers safety and constraints adequately.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: the first front-loads core functionality, the second adds idempotency and constraints. No extra words, every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main functionality, idempotency, recursion, and allowed directories. It does not mention failure behavior or return value, but for a simple creation tool with no output schema, these are minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (the 'paths' parameter has a detailed description). The tool description adds no further parameter details beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Create single or multiple directories' with specific verb and resource. It distinguishes from sibling tools by mentioning 'recursive parent creation (like Unix 'mkdir -p')' and idempotency, which is unique among file operation tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (create directories recursively, idempotently) and includes a limitation ('Only works within allowed directories'), but does not explicitly state when not to use or provide alternatives among the sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

move_fileA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
sourceYes
destinationYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses atomicity, safe failure on existing destination, and directory constraints. Missing details on symlinks or error handling for missing source, but substantial transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, with purpose front-loaded. Every sentence adds value: purpose, cross-directory support, safe behavior, rename capability, and directory constraint. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter tool without output schema, the description covers purpose, behavior, and constraints. Lacks details on recursive moves or cross-filesystem behavior, but these are reasonable gaps given simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. It implies source and destination are paths and adds constraints (must be within allowed directories). However, it does not explicitly describe each parameter's format or constraints, missing an opportunity for clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'relocate or rename' and resource 'files and directories'. It distinguishes from sibling tools (none do moving/renaming) and provides specific behaviors like cross-directory moves and same-directory renames.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use compared to siblings like copy or file_operations. Context is implied but not detailed, making it adequate but not strong.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_fileA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNoRead mode: 'full' reads entire file, 'head' reads first N lines, 'tail' reads last N lines, 'range' reads lines from startLine to endLine (inclusive, 1-indexed). Document files (PDF, DOCX, etc.) ignore mode and always return full content.full
pathYesPath to the file to read
linesNoNumber of lines to read (required when mode is 'head' or 'tail', must be positive integer)
endLineNoEnding line number (1-indexed, inclusive, required when mode is 'range')
startLineNoStarting line number (1-indexed, required when mode is 'range')

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses modes, document file behavior, PDF metadata extraction, and allowed directory constraints. It could mention limitations for binary files or error scenarios.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear flow: file types, modes, special behavior, and restrictions. Every sentence contributes essential information without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately explains return values (e.g., PDF metadata) and covers modes, file support, and directory limits. It lacks details on file size limits or encoding, but is sufficiently complete for a read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds significant value beyond the schema: document files ignore mode, lines required for head/tail, 1-indexed and inclusive range, and path restrictions. This enriches the agent's understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads files with flexible modes, supports text and document formats, and lists specific modes. It distinguishes from siblings like read_multiple_files by focusing on single file reading with mode options.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear guidance on when to use each mode (head, tail, range for text; document files always full) and mentions directory restrictions. However, it does not explicitly compare to alternative tools like grep_files or get_file_info.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_multiple_filesA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
filesYesArray of file read requests. Each request can specify its own read mode, allowing you to read different files with different modes in a single operation. For example, you can read the last 100 lines of one log file while reading lines 50-150 from another file simultaneously.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description covers key behaviors: concurrency, per-file modes, document file handling, maximum files, and directory restrictions. It does not detail error behavior or return format, but these are less critical for a read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise at four sentences, front-loaded with the core purpose, and every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and lack of output schema, the description covers essential aspects: input, modes, constraints, and document support. It could mention error handling but is otherwise complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds context about concurrency and document behavior but does not significantly enhance understanding beyond the schema's detailed parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: batch reading multiple files concurrently with per-file mode control. It explicitly distinguishes from the sibling 'read_file' tool by emphasizing concurrency and batch processing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context (when to use for batch reads with concurrency) and constraints (under 50 files, allowed directories). However, it does not explicitly mention when not to use or name alternatives like 'read_file' for single files.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

register_directoryA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesDirectory path to register for access

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and does so: it discloses the confirmation/auth requirement, the refusal condition, the scope of access granted (directory plus all subdirectories, all filesystem operations), and the runtime exclusions. These are exactly the behavioral traits an agent needs before invoking a state-changing access grant.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the action and its effect, then constraints, then current state. Efficient overall, though the trailing 'CURRENTLY ACCESSIBLE DIRECTORIES' line reads as dynamic state that may be better placed elsewhere; it still earns its place by signaling why registration is needed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-annotation, no-output-schema access-grant tool, the description covers authorization, refusal behavior, scope, and exclusions. Nothing essential for a correct call is missing; return values need not be explained given no output schema exists.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter, and schema description coverage is 100%, so the schema already documents 'path'. The description adds no format, relative-vs-absolute, or validation detail beyond what the schema provides, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Register a directory for access') and immediately explains the effect: dynamic access to human-specified directories during conversation, with all subdirectories covered for every filesystem operation. This clearly separates it from siblings like list_allowed_directories or read_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives strong context and hard exclusions: registration requires user confirmation in the MCP client, is refused if no confirmation prompt exists, and filesystem roots and the home directory cannot be registered at runtime. It also notes the current state ('CURRENTLY ACCESSIBLE DIRECTORIES: None') to motivate use. It stops short of naming an alternative tool for inspecting existing access, so not a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

write_fileA

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: -, , , , , , , , ,

  • CSS styling: colors, fonts, alignment, borders, margins, padding

  • Example: 'TitleContent'

  • 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
contentYesFile content to write. For multi-line content, use actual newlines in the string value, not escape sequences like \n. Example: 'line1\nline2' should be formatted as an actual multi-line string in JSON.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses key behaviors: 'Overwrites without confirmation', only works in allowed directories, and how content is interpreted (HTML vs plain text). Also warns about multi-line encoding issues. No annotations present, so description fully covers behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with sections, but slightly lengthy. Front-loaded with purpose. Could be more concise by trimming the HTML tag list, but still efficient given the valuable info.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Comprehensive for a write tool: covers formats, encoding, directory limitations, and multi-line handling. No output schema, but return behavior is implied. Appropriate given sibling tools and no nested objects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds significant meaning beyond the input schema: path context (allowed directories) and extensive content details (format support, HTML tags, multi-line instructions). Schema coverage is 50%, but the description compensates fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Create/replace files' and specifies supported formats (text, PDF, DOCX with HTML). Distinguishes from sibling tools like edit_file (for modifying) and read_file (for reading) by focusing on writing and specific formats.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance on multi-line content formatting and allowed directories. Implies appropriate use for creating/replacing files, but does not explicitly state when not to use or mention alternatives like edit_file for editing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

write_multiple_filesA

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
filesYesArray of files to write, each with path and content

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description covers concurrency, format support, auto-detection, partial failure handling, and restricted directories. Missing explicit statement about overwrite behavior and return value details, but overall good.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with sections and bolded IMPORTANT note. Slightly verbose (e.g., redundant auto-detection statement), but overall efficient and front-loads key info.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, description covers format support, error handling, allowed directories, and multi-line content. Lacks explicit overwrite behavior and return fields, but sufficiently complete for agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with description on content field. Description adds nuance about multi-line content using actual newlines and auto-detection, but does not significantly expand beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it writes multiple files concurrently, supports text, PDF, DOCX with HTML formatting, and auto-detects file type by extension. Distinguishes from sibling `write_file` which handles single files, and other file operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context for when to use this tool (multiple concurrent writes) and includes important constraints like allowed directories. Lacks explicit when-not or alternatives like `write_file`, but the intent is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.3.0
    • Changedexecute_shell1 field changed
      • changedInput schema / properties / requiresApproval / description
        Previous value: -"Indicates if this command requires explicit user approval. Set to true for potentially dangerous operations (installing packages, deleting files, etc.)."New value: +"Deprecated and ignored. Kept for backward compatibility. Commands matching dangerous patterns can only be allowed by the server operator (--allow-dangerous-commands)."
    • Changedgrep_files1 field changed
      • changedInput schema / properties / glob / description
        Previous value: -"Glob filter: *.js, **/*.test.ts"New value: +"Glob filter. Without a slash it matches file names at any depth (*.md, *.test.ts); with a slash it matches the path relative to the search root (src/**/*.ts)"
  2. 17 tool updatesv1.2.14
    • First observedattach_image
    • First observeddelete_files
    • First observededit_file
    • First observedexecute_shell
    • First observedfile_operations
    • First observedget_file_info
    • First observedglob_files
    • First observedgrep_files
    • First observedlist_allowed_directories
    • First observedlist_directory
    • First observedmake_directory
    • First observedmove_file
    • First observedread_file
    • First observedread_multiple_files
    • First observedregister_directory
    • First observedwrite_file
    • First observedwrite_multiple_files
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.2/5.0

Scored across 17 tools

Disambiguation4/5

Most tools target distinct file operations, but a few boundaries blur: move_file overlaps with file_operations (which also moves/renames), and list_directory's tree mode overlaps with glob_files for recursive listing. Descriptions clarify single-vs-bulk and listing-vs-pattern use, so misselection is limited.

Naming Consistency4/5

Names are uniformly snake_case and nearly all follow verb_noun (read_file, write_multiple_files, list_directory). The outlier is file_operations, a noun phrase rather than an action verb, and list_allowed_directories inserts an adjective, but overall the pattern is predictable.

Tool Count4/5

17 tools is slightly above the ideal 3-15 range but each tool has a clear role in a full filesystem server. Batch/single variants and specialized tools like attach_image and register_directory justify their place, with no obvious filler.

Completeness5/5

The surface covers the full filesystem lifecycle: create, read, write, edit, move, copy/rename (via file_operations), delete, list, glob/grep search, metadata, plus shell execution and directory access management. No critical gaps remain for typical file operations.

Maintenance

ActivityMaintained
ResponsivenessSlow

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches