Filesystem

Exposes filesystem operations as standardized MCP Tools through a JSON-RPC 2.0 transport layer, allowing LLM clients to invoke file operations with structured request/response contracts. The server implements the MCP protocol primitives to register tool schemas, handle invocations, and return results in a format compatible with any MCP-aware client (Claude, custom agents, etc.). This abstraction decouples filesystem logic from transport concerns, enabling the same tool definitions to work across stdio, HTTP, or WebSocket transports.

Implements a security model where filesystem access is restricted to explicitly configured allowed paths (allowlist), preventing directory traversal and unauthorized file access. The server validates all incoming file paths against the allowlist before executing any operation, rejecting requests that attempt to access paths outside the permitted scope. Configuration is passed at server initialization time, allowing operators to define which directories or files LLM clients can interact with, with support for glob patterns or explicit path lists.

Provides a tool that reads file contents and returns them in the appropriate encoding (UTF-8 text or base64 binary), automatically detecting or accepting hints about file type. The implementation uses Node.js fs.readFile() with encoding parameters, returning text files as strings and binary files as base64-encoded strings to ensure JSON-RPC compatibility. The tool includes metadata about file size and encoding used, allowing clients to understand what they received.

Provides a tool to write content to files, creating them if they don't exist or overwriting them if they do, with support for both text and base64-encoded binary content. The implementation uses Node.js fs.writeFile() which provides atomic semantics on most filesystems (write to temp file, then rename), ensuring partial writes don't corrupt files. The tool validates the target path against the allowlist and returns confirmation with file size written.

Provides a tool to list files and subdirectories within a specified path, with optional recursive traversal to show the full directory tree. The implementation uses Node.js fs.readdirSync() or fs.promises.readdir() with recursive option, returning structured metadata for each entry (name, type, size, modification time). Clients can filter results by file type or pattern, and the tool respects the allowlist to prevent listing unauthorized directories.

Provides a tool to delete files or directories, with an optional recursive flag to remove non-empty directories and their contents. The implementation uses Node.js fs.rmSync() or fs.promises.rm() with recursive option, validating the target path against the allowlist before deletion. The tool returns confirmation of what was deleted and the number of files/directories removed.

Provides a tool to move files from one location to another or rename them, with validation that both source and destination paths pass the allowlist. The implementation uses Node.js fs.renameSync() or fs.promises.rename(), which is atomic on most filesystems. The tool handles conflicts by either failing if the destination exists or optionally overwriting, depending on configuration.

Provides a tool to retrieve file or directory metadata (size, modification time, permissions, type) without reading the full file content, using Node.js fs.statSync() or fs.promises.stat(). This is efficient for large files where only metadata is needed. The tool returns structured information about file type, size in bytes, creation/modification/access times, and permission bits.

Provides a tool to create directories, with an optional flag to create parent directories if they don't exist (mkdir -p behavior). The implementation uses Node.js fs.mkdirSync() or fs.promises.mkdir() with recursive option, validating the target path against the allowlist. The tool returns confirmation of the created directory path.

Provides a tool to copy files or directories from one location to another, with optional recursive copying for directory trees. The implementation uses Node.js fs.cpSync() or fs.promises.cp() (Node 16.7+), validating both source and destination paths against the allowlist. The tool preserves file metadata (permissions, timestamps) and handles both files and directories uniformly.