@agent-infra/mcp-server-filesystem

Implements the Model Context Protocol (MCP) specification for reading file contents with support for large files through streaming. The server exposes a standardized read_file tool that accepts file paths and returns contents as UTF-8 text, with streaming capability to handle files larger than typical context windows. Uses MCP's transport layer (stdio or HTTP) to communicate with LLM clients and maintains protocol compliance for tool schema validation.

Exposes a write_file tool through the MCP protocol that allows LLM clients to create or overwrite files on the filesystem. Implements atomic write patterns (write-to-temp-then-rename or similar) to prevent partial writes on failure. Validates file paths to prevent directory traversal attacks and enforces optional write restrictions based on allowed directories. Returns success/failure status and file metadata (size, path, timestamp) to the client.

Provides a list_directory tool that returns structured metadata about files and subdirectories (names, types, sizes, modification times) without reading full contents. Implements recursive directory traversal with optional depth limiting to prevent runaway queries on large directory trees. Returns results as JSON-serializable structures compatible with MCP's structured data format. Supports filtering by file type or pattern matching.

Implements a delete_file tool that removes files or directories from the filesystem through the MCP protocol. Supports recursive deletion for directories with optional safety flags (e.g., require explicit confirmation for non-empty directories). Validates paths to prevent accidental deletion of critical system files. Returns confirmation of deletion and error details if operation fails.

Exposes a stat_file tool that returns detailed filesystem metadata (size, permissions, timestamps, ownership, type) for files and directories without reading contents. Uses native filesystem stat calls to retrieve accurate, up-to-date metadata. Returns results as structured JSON compatible with MCP's data format. Useful for agents that need to make decisions based on file properties (e.g., skip large files, check modification times).

Implements path validation logic that prevents directory traversal attacks (e.g., ../../../etc/passwd) and enforces optional allowed-list restrictions on which directories agents can access. Uses path normalization and canonicalization to resolve symlinks and relative paths before checking against security boundaries. Validates all file operations (read, write, delete) against these rules before executing. Returns clear error messages when operations violate security policies.

Implements the MCP protocol specification for server-side communication, supporting multiple transport mechanisms (stdio, HTTP/SSE, WebSocket). Handles MCP message serialization/deserialization, request/response routing, and error handling according to the protocol specification. Manages tool schema registration and validation to ensure clients receive accurate capability descriptions. Provides hooks for custom transport implementations.