Read the full contents of a file. Text files are returned as UTF-8 text; binary files are detected automatically and returned as base64.

Args:

• path (string): Absolute or relative path to the file.

Returns: file contents as text, or a note that the file is binary with base64 content.

Error Handling:

• Returns an error if the path is outside allowed directories or matches a blocked pattern (e.g. .ssh, .aws).

• Returns "File or directory not found" if the path does not exist.

Read a specific line range from a file. Useful for large files where reading the whole thing would exceed limits.

Args:

• path (string): Path to the file.

• start_line (number): 1-indexed starting line (inclusive).

• end_line (number): 1-indexed ending line (inclusive).

Returns: the requested lines, each prefixed with its line number.

Create a new file or overwrite an existing one. Parent directories are created automatically.

Overwriting an EXISTING file requires interactive user approval (elicitation) — the server will pause and ask the connected client to confirm before proceeding.

Args:

• path (string): Path to write to.

• content (string): Text content to write (UTF-8).

• overwrite (boolean, optional): Must be true to overwrite an existing file. Default: false.

Error Handling:

• Returns an error without writing if the file exists and overwrite is not true.

• Returns an error if the user declines the overwrite approval prompt.

Create a directory, including any missing parent directories (like mkdir -p).

Args:

• path (string): Directory path to create.

Returns: confirmation of the created path. No error if the directory already exists.

List the contents of a directory with metadata (type, size, modified date).

Args:

• path (string): Directory to list.

• recursive (boolean, optional): List subdirectories recursively. Default: false.

• show_hidden (boolean, optional): Include dotfiles/dotdirs. Default: false.

Returns: a listing with one entry per line: type, size, modified date, name.

Move or rename a file or directory. ALWAYS requires interactive user approval before proceeding.

Args:

• source (string): Current path.

• destination (string): Target path.

Error Handling:

• Both source and destination are validated against allowed directories and blocked paths.

• Returns an error if the user declines the approval prompt.

Copy a file or directory (recursively for directories). Does not modify the source, so no approval is required.

Args:

• source (string): Path to copy from.

• destination (string): Path to copy to.

Permanently delete a single file. ALWAYS requires interactive user approval before proceeding — this cannot be undone.

Args:

• path (string): Path to the file to delete.

Permanently delete a directory and all its contents, recursively. ALWAYS requires interactive user approval before proceeding — this cannot be undone.

Args:

• path (string): Directory to delete.

Find files matching a glob pattern within a directory (e.g. "**/.ts", ".log").

Args:

• directory (string): Base directory to search within.

• pattern (string): Glob pattern to match filenames against.

• max_results (number, optional): Cap on returned results. Default: 50.

Returns: a list of matching file paths, relative to the search directory.

Grep-like search: find a text query across files in a directory, returning matching lines with 2 lines of context before/after.

Args:

• directory (string): Base directory to search within.

• query (string): Text to search for (case-sensitive, literal substring match).

• file_pattern (string, optional): Glob to limit which files are searched (e.g. "**/*.js"). Default: all files.

• max_results (number, optional): Cap on returned matches. Default: 50.

Returns: matching lines with file path, line number, and surrounding context.

Execute a shell command and return its stdout/stderr. ALWAYS requires interactive user approval before running.

Args:

• command (string): The command to execute (interpreted by the platform shell — cmd.exe on Windows, bash on Linux).

• cwd (string, optional): Working directory. Defaults to the first allowed directory.

• timeout (number, optional): Timeout in milliseconds. Default: 30000, max 300000.

Returns: stdout, stderr, and exit code.

Error Handling:

• Returns an error if the user declines the approval prompt.

• Returns an error if the command exceeds the timeout (process is killed).

Start a long-running command in the background and return immediately with its process ID. ALWAYS requires interactive user approval before running.

Args:

• command (string): The command to execute.

• cwd (string, optional): Working directory. Defaults to the first allowed directory.

Returns: the process ID (pid), which can be used with list_processes and kill_process.

Note: background processes have no timeout, but they are tracked and can be killed with kill_process. They do not survive this server process restarting (e.g. Claude Desktop being closed and reopened).

List background processes started via run_command_background during this session, with their status.

Returns: a list of tracked processes with PID, command, status, and start time.

Terminate a background process previously started with run_command_background. Requires interactive user approval before proceeding.

Args:

• pid (number): Process ID to kill (must be one tracked by this server — see list_processes).

Get metadata about a file or directory: size, created/modified dates, permissions, and type.

Args:

• path (string): Path to inspect.

Returns: size in bytes, created/modified timestamps, POSIX permission bits, and whether it's a directory or symlink.

Get information about the machine this server is running on: OS, hostname, home directory, Node version, CPU count, and total memory.

Returns: a JSON object with platform details.