NAME

mcp-fs - filesystem and command tools with optional sandboxing

SYNOPSIS

mcp-fs --stdio /path/to/workdir
mcp-fs --name project --bind 127.0.0.1:31741 /path/to/workdir
mcp-fs --stdio --host kaos --rsh rsh /root/src

DESCRIPTION

mcp-fs gives an MCP client tools to read, search and change files, and run commands. An assistant can use these tools to work on your projects without you writing a Perl server.

Start it with one or more project directories, called workdirs. The client connects to the server, lists its tools and makes requests. A request can select one of these workdirs; with only one, the selection can be omitted. Tools operate on files on disk. To work with unsaved Vim buffers, use mcp-vim.

Before starting an operation, the server checks permission rules and, when needed, asks you for approval. Operations normally run in a bubblewrap sandbox with the approved access. Workdirs provide the default filesystem scope; operations needing access elsewhere require the corresponding sandbox grants.

You can connect an MCP client directly over HTTP or stdin/stdout, or run the server through mcp-multibroker. See AnyEvent::MCP::Intro for a walkthrough from installation to a first filesystem request.

With --host, the same tools operate on a remote host over SSH (or the command selected by --rsh). Only Perl 5.8.4 and the tools used by the requested operations are needed remotely; neither mcp-fs nor its CPAN modules must be installed there. Each server instance uses one host, with any number of workdirs on that host.

FIRST USE

Configure your MCP client to launch the server with an existing project:

mcp-fs --stdio --name project /home/alice/src/project

The client starts the process and speaks MCP over stdin/stdout. Do not run another copy in a terminal. For HTTP clients, run without --stdio and use --print-url with the same --name and --bind settings; see "YOUR FIRST FILESYSTEM SERVER" in AnyEvent::MCP::Intro.

To inspect the tools available with your installed utilities without starting a listener, run mcp-fs --tool-help /home/alice/src/project.

Once connected, ask the assistant:

Show the configured workdirs and list my project's top-level files.
Read its README if present. Do not change files or run commands.

workdirs shows the available paths without a worker. Listing requests inspect permission, and reading a file requests read. Allow each once to try them. Approval is specific to the requested action and sandbox grants. If no dialog appears, inspect the tool error and server stderr: the helper needs a YAD display or usable terminal. See "PERMISSIONS".

For a separate sandbox check without MCP, change to your project directory and run:

mcp-fs --exec-cmd workdir-read -- ls

This uses the current directory as the workdir. It tests the sandbox, not client connectivity or permission prompting.

Remote workdirs

To use an existing directory on another machine:

mcp-fs --stdio --host server.example.org /srv/project
mcp-fs --stdio -h kaos -e rsh /root/src /srv/projects

Workdir arguments are ordinary absolute paths on that host, without a host: prefix. Omitting --host retains local operation, regardless of --rsh. The remote shell is started locally, outside the operation sandbox. Its connection does not require the remote operation's network grant. Combine unrelated hosts through mcp-multibroker.

Remote request cancellation and timeouts terminate the local remote-shell process, but may leave the remote worker running. After a connection failure, the outcome of a modifying operation may be unknown; inspect the remote filesystem before retrying it. Reliable remote process termination is not yet implemented.

TOOLS

The filesystem tools are:

workdirs

Report configured workdirs and available sandbox grants, without starting a worker.

list, find

Enumerate directory entries.

stat

Return lstat metadata without following symlinks.

file-read

Read byte ranges and return Base64 data.

read-lines

Read LF-delimited lines with selectable UTF-8, Latin-1 or Base64 representation.

grep

Search files using a literal pattern or PCRE.

file-write

Write Base64 bytes at an offset without implicit truncation.

path-op

Perform pathname mutations.

file-patch

Apply a unified diff to a single file.

exec

Run an argv array, not a shell command string. To use shell syntax, explicitly invoke a shell in that array.

For exec, stdin_encoding selects utf-8 (default), latin1 or base64. The 4 MiB limit applies to the resulting stdin bytes. The argv elements are Unicode MCP strings encoded as UTF-8 for the operating system; they cannot represent arbitrary non-UTF-8 argv bytes. Stdout and stderr are decoded as UTF-8, with a raw capture limit of 1 MiB per stream; use the byte-range tools for binary file contents. Its optional sandbox_grants replaces the default workdir-read grant rather than adding to it. Explicitly passing an empty array therefore asks for no grants. Command exit codes are normal tool results, not transport errors. On timeout, output collection stops and truncated is true; exit and signal still describe the reaped child.

Perl is required for normal server operation; missing optional GNU utilities can cause their tools to be omitted. The command requested by exec is resolved when the worker runs; it need not be present when the server starts. Inspect tools/list rather than assuming every tool is present.

Command output

exec, vcs-diff, vcs-status and vcs-log share three presentation options:

grep => $pattern

Optional PCRE line filter for stdout. It runs in a separate timed GNU grep worker after command output has been captured. It is not passed to the original command or a shell. Stderr remains unfiltered.

max_lines => $integer

Maximum returned stdout lines after filtering, default 2000, maximum 100000.

max_bytes => $integer

Maximum returned UTF-8 bytes per stream, default 65536, maximum 1048576. Clipping does not leave an incomplete UTF-8 character. Stderr has its own budget, so a large stdout does not hide diagnostics.

The command runs once and is drained to completion, subject to its timeout. Raw capture is bounded to 1 MiB per stream, independently of the returned output limits. capture_truncated means bytes were omitted before filtering or collection ended on timeout: matches in that omitted output are unknown. stdout_truncated, stderr_truncated and the combined truncated flag also account for returned-output limits.

Changing presentation options does not change the command's permission subject. exit, signal and timed_out always describe the original command, including a diff exit code indicating differences. A filter error makes the tool result an error and adds filter_error, while retaining that command status. The command may already have completed; do not rerun it merely because its output filter failed.

Version control

vcs-diff, vcs-status and vcs-log take a required backend: git, svn, cvs or hg, a workdir, an optional cwd (default .), and an optional files array. cwd selects a directory within the workdir; it does not change the granted mount boundary. Files are relative to cwd and must stay within the selected workdir. The worker checks its resolved directory after chdir and before starting the client, rejecting symlink escapes. Backend selection is explicit. With no files, the command examines the working copy at cwd. Files must be inside the selected workdir; they are passed as literal filenames, not options, revisions or shell code. Git diff shows unstaged changes; SVN, CVS and Mercurial diff compare the working copy with its base. No commit, update, fetch or push is performed. vcs-log reads revision history. CVS reports revisions separately per file (including their commit IDs), unlike Git's repository-wide commits. Use output limits to bound potentially long histories.

These tools have separate vcs-diff, vcs-status and vcs-log permission actions. They request workdir-read for the selected working copy. CVS additionally requests ssh-agent, which includes network access. SVN log may contact the repository and also requests ssh-agent to support svn+ssh; SVN diff/status, Git and Mercurial operations run without network or home access. A saved approval can cover the fixed operation regardless of filenames or output filters, for that workdir and backend, or all supported backends. Configured VCS clients and their configuration are trusted, including any helpers they invoke; these tools do not sandbox the client's own semantics. The ordinary sandbox grants still bound its host access. In unsandboxed mode, the normal full-authority approval requirement applies.

Clients are resolved at startup. executable.git, executable.svn, executable.cvs and executable.hg in trusted program/instance settings can override them. A missing client produces a tool error for that backend.

REQUIREMENTS

Bubblewrap is required by default, but can be disabled explicitly. Perl 5.8.4 or later must run in the worker environment at startup (except for --exec-cmd). GNU find, grep, patch and sed are optional; tools requiring an unavailable utility are omitted. Use tools/list to see which tools are available.

Remote startup resolves workdirs, HOME, required mounts, executable locations and VCS markers once; workdirs thereafter uses this snapshot. Optional mount-try paths are instead passed to bubblewrap for every invocation. Restart mcp-fs to refresh the workdir configuration and tools.

CONNECTIONS

HTTP is the default and does not print its URL on startup. --print-url prints the credential-bearing URL; the same token works in a bearer header. --stdio or PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL=stdio selects stdin/stdout. See "GLOBAL CONFIGURATION" in AnyEvent::MCP for named HTTP settings.

OPTIONS

Shared switches are documented in "COMMON COMMAND-LINE OPTIONS" in AnyEvent::MCP::Server::Simple. The following switches are specific to mcp-fs.

--exec-cmd SANDBOX-GRANT,...

Run command with specified sandbox grants, using current directory as workdir; no MCP listener or permission rules. Supply command and arguments after optional -- delimiter. Without command, run $SHELL or /bin/sh. --sandbox none runs with normal host-user privileges. Example: mcp-fs --exec-cmd workdir-read -- ls. --exec-cmd is local-only; it cannot be combined with --host.

--ask MODE

Permission prompts: helper (default), tty, yad, mcp, auto, or none. Local helper keeps decisions local; tty/yad force interface without fallback. mcp asks client; auto prefers client elicitation when advertised, otherwise local helper. none denies unmatched permission requests without prompting. Overrides PERL_ANYEVENT_MCP_PERMISSION_ASK.

-h, --host HOST

Run filesystem operations on HOST instead of the local machine. Empty or omitted HOST selects local operation. All workdirs belong to this one host. Remote workdir paths must be absolute. Host identity qualifies permission scopes, not workdir IDs, which use logical pathnames without following symlinks.

-e, --rsh COMMAND

Remote shell command, default ssh. Like rsync's -e, COMMAND may include arguments. Only used with --host; rsh is also supported. The command is split into arguments locally without a local shell. The remote shell invokes a short Perl loader. The launcher source is transferred over stdin, followed by length-prefixed binary startup frames; subsequent worker input remains on the same stream.

--sandbox MODE

Worker sandbox mode: bwrap (default), auto, none. bwrap requires working bubblewrap. auto uses bubblewrap if installed, otherwise runs unsandboxed; failing bubblewrap does not silently fall back. none runs with full host-user privileges. Unsandboxed workers require approval for maximum authority (world-write, network, shared-tmp, host-proc) even for reads; narrower grants cannot authorize them. Startup warns.

--exec-prefix COMMAND

Run workers and their executable probe through COMMAND, split into argv with shell-style quoting. No additional shell is used locally. For example, --exec-prefix 'doas -n' can read protected files on a machine using doas instead of sudo. Remote execution uses the existing SSH command shell and places the prefix before the remote Perl launcher. A failed prefix never falls back to the original credentials.

--sudo[=USER]

Shortcut for --exec-prefix 'sudo -n', optionally adding -u USER. Overrides --exec-prefix. For example, --sudo with --host user@host works when SSH must log in as an unprivileged account but passwordless sudo is permitted. --sudo=mail runs as the mail user. Sudo must work noninteractively; no password or terminal is supplied.

--host-dac

Keep the host user namespace and retain CAP_DAC_OVERRIDE inside bubblewrap. For example, a root worker can inspect a 0700 directory owned by another user within a granted workdir. Other capabilities are dropped; the existing mount and MCP permission restrictions still apply. Requires privileged bubblewrap; --sandbox none is incompatible.

--bwrap PATH

Use specified bubblewrap executable. Default: bwrap found in PATH. Relevant with --sandbox bwrap or --sandbox auto.

Shared-option behavior

--name NAME

Also selects permission profile fs-NAME and its rule file, rules/fs-NAME.ini. Default instance name: default.

--print-url[=USER]

Does not require a WORKDIR argument.

--tool-help

Requires normal WORKDIR arguments, since available tools depend on the selected workdirs and installed utilities.

--auto-allow TOOL[,ACTION[,CAPABILITY]]

For example, combining --auto-allow '*,inspect,workdir-read' with --auto-allow '*,read,workdir-read' approves only those two actions within read-only workdir authority. --auto-allow '*,*,workdir-write' approves any action requiring at most workdir-write authority, including reads.

Rules reside in $XDG_CONFIG_HOME/anyevent-mcp/rules/fs-NAME.ini, or the corresponding $HOME/.config path. The rules filename shares the service-instance name but has an fs namespace. The default instance uses rules/fs-default.ini. The rules path is printed on stderr when starting HTTP; normal startup leaves stdout untouched. Local and remote instances with the same --name intentionally share the same rule profile. Permission requests include a host dimension: local for local execution, or remote HOST using --host independently of --rsh. New persistent rules default to this host, but may match all hosts. The workdir matcher is simply the logical path, independent of host. Existing rules lacking match.host continue to apply across local and remote hosts; only newly saved host-specific rules restrict this. Use different instance names or match.host to separate approvals for different hosts. Unscoped rules apply across hosts sharing the profile.

TRUSTED CONFIGURATION

In ~/.config/anyevent-mcp/global.ini (or the corresponding XDG_CONFIG_HOME location), [program NAME] supplies defaults based on the executable basename, while [instance NAME] overrides them for --name NAME. A symlinked executable therefore has its own program defaults.

[program mcp-fs]
mount-try.opt = ro:/opt
mount-try.perl = ro:/opt/perl
prepend-path = /opt/bin:/opt/sbin
mount.shared = rw:/srv/shared
env.cvs = CVS_RSH=/my/cvs/rsh
executable.perl = /opt/bin/perl

[instance myproject]
mount.opt =
prepend-path =
mount.extra = ro:/srv/project-tools

To override settings for one invocation, use the common -s / --set option rather than editing the file:

mcp-fs --stdio -s executable.perl=/opt/perl/bin/perl \
  -s prepend-path=/opt/perl/bin /srv/project

Command-line settings take precedence over program and instance settings; repeated keys use their last value. See "COMMON COMMAND-LINE OPTIONS" in AnyEvent::MCP::Server::Simple.

Automatic permission rules can also be configured:

[program mcp-fs]
auto-rule.10 = allow *,read,workdir-read
auto-rule.20 = allow *,write,workdir-write
auto-rule.30 = deny *,exec,*

The supported configuration entries are:

auto-rule.SUFFIX

Automatic permission rules apply to every named mcp-fs instance; CLI auto-rules are evaluated first.

mount.SUFFIX

A required sandbox mount. The named path must exist at startup.

mount-try.SUFFIX

An optional sandbox mount, using bubblewrap's --ro-bind-try or --bind-try. An absent path is skipped by bubblewrap at each invocation, without a startup existence check.

Both mount kinds are applied in alphabetical key order after the private sandbox mounts. The suffix is an arbitrary stable name; an empty instance value suppresses an inherited entry. Paths must be absolute. A colon after ro: or rw: starts the literal pathname; no separate quoting or escaping syntax is used.

env.SUFFIX

Specify NAME=value to set a literal value, or NAME to inherit that variable from the server environment if present. Values may contain spaces and equals signs; there is no shell expansion. Entries are applied in alphabetical key order after the default environment. An empty instance entry suppresses the corresponding program entry. SSH_AUTH_SOCK is managed exclusively by the ssh-agent grant, even when listed in these settings. Environment settings do not expose paths; custom executables outside the runtime/workdir mounts need configured mounts.

prepend-path

Add colon-separated directories before the bubblewrapped worker's fixed PATH of /usr/bin:/usr/sbin:/bin:/sbin:/usr/local/bin:/usr/local/sbin. Trailing colons are ignored, so both /opt/bin and /opt/bin: work. The server's PATH is not inherited. An empty instance value restores the fixed default rather than the program value. --sandbox=none continues to use the host environment. Directories outside the normal runtime mounts still need a configured mount to be accessible.

executable.find, executable.grep, executable.patch, executable.perl, executable.sed, executable.bwrap

Override automatic executable discovery. Explicit choices must resolve to executable files and are trusted instead of version-probed, except for executable.perl, which must satisfy the Perl minimum version. executable.perl defaults to perl in the worker's PATH; the other worker executables are discovered there too. --bwrap overrides executable.bwrap and is located on the host.

Configured mounts grant baseline access to every sandbox invocation (when present for mount-try), independently of tool permission grants. With world-read, only rw: exceptions are applied over the read-only host filesystem. With world-write, these configured mounts are ignored. Selecting / as a workdir makes workdir-read and workdir-write equivalent in filesystem reach to world-read and world-write, respectively, without changing saved permission identities. Host directory mounts are applied parent-first, followed by protected private system mounts and explicitly configured narrower exceptions. Baseline execution paths include /usr, /bin, system libraries and selected system configuration, but not /opt. Shared host temporary directories require shared-tmp, an explicit configured mount, or world-write. All other grants, including world-read, use private writable temporary directories. world-write implies shared-tmp.

Defaults also include alternatives, font configuration, local timezone, TLS certificate stores, NSS configuration and DNS configuration where present. A synthetic passwd entry is created in the private root if the host root is not exposed. A workdir covering /etc will instead show the host passwd file, without ever modifying it. A root workdir exposes the host passwd and group databases.

The workdirs result includes workdir_vcs, a mapping from configured workdir identities to arrays of backends with metadata markers directly in that directory. Detection checks CVS, .git, .hg and .svn; a Git metadata file is supported as well as a directory. Symlink markers are reported without following them. This is a hint, not validation of a repository. There is no recursive scan or parent search, multiple markers are retained, and an empty array means no marker was found. Detection is independent of the available clients in vcs_backends and does not choose the backend for a VCS command.

SANDBOX GRANTS

workdir-read

Read access to the selected workdir.

workdir-write

Write access to the selected workdir; implies workdir-read.

all-workdirs-read

Read access to every configured workdir.

all-workdirs-write

Write access to every configured workdir; implies read access.

homedir-read

Read access to HOME.

homedir-write

Write access to HOME; implies read access.

world-read

Read access to the host filesystem.

world-write

Write access to the host filesystem; implies world-read. Also implies shared-tmp, so host /tmp and /var/tmp remain writable and visible.

network

Enable networking outside the sandbox's network namespace. Without this grant, bubblewrap uses a separate network namespace. Loopback connections between processes in that same sandbox work, but its 127.0.0.1 is not the host's 127.0.0.1. Connecting to a host-side loopback server requires network.

shared-tmp

Use the host's writable /tmp and /var/tmp instead of private writable temporary directories. Without this grant, temporary files are isolated and disappear when their sandbox ends, even with world-read. Host temporary files are visible across invocations, though the host may clean them up at any time. world-write automatically grants shared-tmp.

long-running

Allow exec timeouts over 300 seconds.

host-proc

Host-process access, available only without bubblewrap.

ssh-agent

Implies network. Exposes the server's SSH_AUTH_SOCK at /run/anyevent-mcp/ssh-agent and sets the child's variable to that path. In remote mode it uses the remote shell's agent socket, when available (for example through SSH agent forwarding), rather than mounting the local socket path. SSH authentication used to reach the host is separate from the worker's ssh-agent and network grants.

Also exposes ~/.ssh/known_hosts read-only if present, without mounting the rest of HOME. Private key files and SSH user configuration are not exposed. An unset or empty SSH_AUTH_SOCK exposes no socket, allowing rsh-based CVS; a configured socket must be an absolute path naming an existing socket node. Socket replacement requires a new invocation; an existing bind mount keeps the old node. Agent access permits authentication, not retrieval of private keys.

all-workdirs-read combined with workdir-write mounts all workdirs read-only except the selected one, which is writable. all-workdirs-write makes all writable. Configured workdirs are mounted using resolved absolute paths, but their permission-rule identities are verbatim command-line arguments.

Workdir selection

Persistent permission rules default to the selected workdir, with an explicit option to match any configured workdir, including future additions. This controls reuse of the rule, not the workdirs accessible in one operation. The multibroker alias is shown in permission prompts, without changing the rule file. Tools accept workdir as a persistent positive integer ID, a numeric string containing that ID, or an exact configured or resolved workdir path. workdirs returns workdirs and resolved_workdirs objects keyed by ID, not arrays indexed by argument position. IDs are shared across server instances in $XDG_CONFIG_HOME/anyevent-mcp/fs-workdir-ids.json, or under $HOME/.config when XDG_CONFIG_HOME is unset. IDs use the logical absolute pathname, without resolving symlinks (relative local arguments are made absolute against the server's working directory). The same logical pathname on local and remote servers receives the same ID, even when it resolves to different physical directories. Permission-rule identities remain the verbatim arguments; each server interprets IDs in its own workdirs.

The registry stores ID => [workdir, last_use] pairs, with last_use as a Unix timestamp. Starting a server resolves its IDs once and reserves any new allocations under the file lock. An AnyEvent timer runs immediately and every 5.25 days, rereading the registry and overwriting those fixed assignments with fresh timestamps. Other entries expire after seven days without refresh; their IDs can be reused. Restart servers after manually changing the registry. Numeric IDs therefore survive restarts and argument reordering while retained, but are not permanent references to paths that have expired.

Non-numeric strings are matched only against configured workdirs, never interpreted as arbitrary filesystem paths. Unknown or ambiguous selectors fail. With only one workdir, the field may be omitted. Overlapping workdirs have unspecified mount order and access effects; do not rely on overlapping workdir boundaries for isolation.

LIMITATIONS

With bubblewrap, regardless of granted sandbox grants, the sandbox mounts procfs at /proc. Its process entries are restricted by the PID namespace, but kernel-wide and hardware information (including /proc/irq and /proc/bus) remains visible. This is a limitation of bubblewrap's --proc option, which does not support subset=pid.

PERMISSIONS

AnyEvent::MCP::Server::Permissions applies ordered allow, deny and ask decisions to these action classes:

inspect

stat, list, find.

read

file-read, read-lines, grep.

write

file-write, file-patch.

manage

path-op.

exec

Command execution.

file-write may create files despite being in the write class; manage refers specifically to pathname operations rather than an exclusive right to create files. Filesystem operations have no path-based persistent subjects: their rules match action, sandbox-grants, and match.workdir when selected-workdir authority is required. All-workdirs-only requests have no workdir identity. Rules without match.workdir can apply to any selected workdir if their sandbox grants cover the request; dialog-generated workdir rules select exact or any. The independent match.host dimension matches local, a remote host, or all hosts, independently of the remote transport. Instances with the same name share a rule file, including broad unscoped rules. Requested paths are shown in the approval dialog for information only. Exec additionally offers persistent command/argv scopes as match.subject. When stdin is provided, exec attaches display-only details to the permission request: Unicode text for UTF-8 input, or a bounded escaped-byte preview for Latin-1/Base64 input. The YAD helper offers a separate View stdin... window; the preview shows input size and truncation. This does not change authorization: persistent exec rules match argv, not stdin, and later runs may supply different scripts or bytes. Conversion takes place before approval and the worker receives the exact resulting bytes. file-patch supplies View patch details with the target and supplied diff. Base64 patches are decoded for display: valid UTF-8 is shown as Unicode, otherwise non-printable bytes and backslashes are escaped in a byte view. The UI chooses whether to show a separate viewer or an inline preview. Each tool checks permissions before starting its worker. Approval defaults to the local helper selected by PERL_ANYEVENT_MCP_PERMISSION_HELPER, which tries YAD, then a terminal, then denies once. Client elicitation is selected with --ask mcp, --ask auto, or the corresponding PERL_ANYEVENT_MCP_PERMISSION_ASK value.

You can edit the rule file at any time. It is reread on permission checks, so changes apply without restarting the server. Keep it owned by your user and private (mode 0600). See AnyEvent::MCP::Server::Permissions for the rule syntax and ordering.

Permission retries retain earlier one-time approvals within the same call. For one worker accessing several paths, the required sandbox-grant set combines the authority needed for all paths and is approved once. An insufficient reduction fails before the worker starts. Multi-path stat requires all paths inside its selected workdir. path-op can attempt cross-workdir renames after approving the sandbox grants required for both paths. The sandboxed rename(2) may fail with EXDEV across mounts; no copy/delete fallback is attempted. mkpath requires a path inside the selected workdir. path-op performs requested operations in this fixed order: unlink, rmdir, mkpath, mkdir, symlink, truncate, chmod, rename. mkpath includes each missing component in the combined permission check before starting the worker. The first failure stops subsequent operations; successful earlier mutations remain in place. There is no rollback or all-or-nothing transaction.

Exec defaults to a 30-second timeout and permits up to 300 seconds without additional timeout authority. A larger explicit timeout, up to 21600 seconds (six hours), also requires long-running. This capability is added to the requested permissions automatically. Cancellation still terminates the worker, regardless of its allowed timeout.

The host-proc grant is unavailable with bubblewrap. Runtime mounts provide sandbox machinery. Symlinks resolve within granted mounts. Without bubblewrap, workers operate in the host mount and process namespaces.

PATCHES

file-patch uses "PATCH UTILITIES" in AnyEvent::MCP for normalization and validation. GNU patch runs inside the granted sandbox with fuzz zero. Successful output replaces the original by rename after checking its identity, size, timestamps, metadata and link count. These stat checks do not detect every concurrent edit; they are not a filesystem transaction.