emperor-folder

emperor-folder

An MCP server confined to one folder. You name a directory (or a few); the model can list, read, search, and (if you allow it) write, edit and move files inside it, and cannot reach anything outside it: not with an absolute path, not with .., not through a symlink.

emperor-folder serve --root ~/notes            # read-only, Streamable HTTP on 127.0.0.1:8031/mcp

emperor-folder serve --root ~/notes --writable # also write, edit and move emperor-folder serve --root ~/notes --stdio # for desktop clients emperor-folder serve --root notes=~/notes --root code=~/src/app # two roots: notes/..., code/...

Why

Giving an agent "the filesystem" is the fastest way to give it your SSH keys. Most file tools check paths with string prefixes and then open them with the full authority of the process; a symlink, a .. the check missed, or a race between check and open, and the model is out.

emperor-folder does not check-then-open. It opens the root once as a cap-std directory handle and does every file operation *through that handle* with a relative path, so resolution happens under the operating system's (or cap-std's) beneath-the-root rules. There is no code path that opens a file by absolute path.

It is built on emperor-mcp: stateless Streamable HTTP (no session id, load-balancer friendly), output framed so file content reaches the model as data rather than instructions, and a doctor subcommand. It follows Emperor Profile P1.1: no write tool is offered unless the operator switches writing on at start-up, and tool definitions are lean (short descriptions, compact input schemas), so every request carries less of them.

Install

Release binaries for Linux (x86_64), macOS (Apple Silicon and Intel) and Windows are attached to each GitHub release, with a SHA256SUMS file and build provenance attestations: check a download with sha256sum -c SHA256SUMS --ignore-missing and gh attestation verify --repo yarenty/emperor-folder. From source (Rust 1.88 or newer):

cargo install emperor-folder

Or as a container (stdio, the folder mounted at /data, read-only unless you add --writable):

docker build -t emperor-folder https://github.com/yarenty/emperor-folder.git

docker run -i --rm -v ~/notes:/data emperor-folder # read-only docker run -i --rm -v ~/notes:/data emperor-folder --root /data --writable # also write, edit, move docker run -i --rm -v ~/notes:/data -e FOLDER_WRITABLE=true emperor-folder # the same, from the environment

Run

emperor-folder doctor --root ~/notes   # check first: exits 1 if something is wrong

emperor-folder serve --root ~/notes

RUST_LOG sets the log level (default info).

Connect

Claude Code

claude mcp add --transport http folder http://127.0.0.1:8031/mcp     # server already running

claude mcp add folder -- emperor-folder serve --stdio --root ~/notes # or let Claude Code start it

With --writable (and several roots) in the stdio form:

claude mcp add folder -- emperor-folder serve --stdio --writable --root notes=$HOME/notes --root code=$HOME/src/app

Claude Desktop (claude_desktop_config.json, stdio):

{

"mcpServers": { "folder": { "command": "/usr/local/bin/emperor-folder", "args": ["serve", "--stdio", "--root", "/Users/me/notes"] } } }

[kowalski](https://github.com/yarenty/kowalski) (config.toml):

[[mcp.servers]]

name = "folder" transport = "http" url = "http://127.0.0.1:8031/mcp"

or over stdio:

[[mcp.servers]]

name = "folder" transport = "stdio" command = ["emperor-folder", "serve", "--stdio", "--root", "/home/me/notes"]

Any other MCP client that speaks Streamable HTTP or stdio works the same way.

Tools

Seven tools, each a verb. Every path is relative to the root (. or omitted means the root). The three that change files are offered only with --writable; a read-only server lists four.

Every tool sets openWorldHint: false: it touches the named folders and nothing else.

list and search use ignore, ripgrep's walker: .gitignore (even outside a git checkout), .ignore and hidden files are skipped unless --no-ignore / --hidden say otherwise, and symlinks are never followed. Regexes use the regex crate: linear-time matching, no catastrophic backtracking, compiled size capped at 1 MiB. Globs match the path as the tools show it (*.rs matches src/main.rs).

Output. File content from read is framed as a document of unknown authorship (FrameKind::Document); listings, matches and metadata are JSON framed as computed results (FrameKind::Computed). The frame's per-call nonce means a file containing a fake end-of-data marker cannot break out of the block. Refusals come back as tool errors (isError: true) with a message that says what to do instead.

Several roots

--root can be given more than once. With one root nothing changes: paths are relative to it. With several, every path starts with the root's name, and . is a virtual folder whose entries are the roots:

emperor-folder serve --root notes=~/notes --root code=~/src/app

list .                      -> notes, code

read notes/todo.md search pattern=TODO -> matches in notes/... and code/... move notes/a.md -> code/docs/a.md (with --writable)

A root without a name is named after its folder (--root ~/notes is notes); two roots with the same name are refused at start-up. In NAME=DIR the name may not contain / or \, so ./a=b is a folder called a=b. Each root is its own cap-std handle: a path, .. or symlink cannot get from one root into another except through move, which names both ends.

Security model

What the model can do: see and read files under the roots that the ignore rules do not hide; with --writable, create, edit and rename files under the roots.

What it cannot do:

• Leave the root. Absolute paths (/etc/passwd, C:\ on Windows) are refused, and so is any path with a .. component, even one that would stay inside (a/../b). That check gives a clear error; the enforcement underneath is cap-std, which resolves every path beneath the root handle (openat2(RESOLVE_BENEATH) on Linux, component-by-component resolution elsewhere) and refuses any resolution that leaves it.
• Escape through symlinks. A symlink inside a root that points outside it (also into another root) is refused for read, write, edit, move, list and search alike; a symlink that stays inside works. The walker never follows links, and every path it yields is re-opened through the root handle, so a directory swapped for an escaping link mid-walk is skipped, not read.
• Write by default. The server starts read-only: write, edit and move are removed from the tool list, and the file operations refuse writes as well, until the operator passes --writable (or sets FOLDER_WRITABLE), as Emperor Profile P1.1 requires. Tool annotations (readOnlyHint, destructiveHint) tell clients which tools change files, so they can ask before running them.
• Exhaust the host or the context. Whole-file reads stop at --max-file-bytes (line-range reads stream and return at most that much) and at --max-chars characters, search skips larger files, list and search stop at --max-results, binary files other than small images are never returned.
• Be reached from a web page. On a loopback bind the Host header must be localhost, 127.0.0.1 or ::1 (DNS-rebinding protection). On a non-loopback bind the check is off, as the Emperor Profile expects a validating ingress in front; --allowed-host turns it back on for named hosts, and --allowed-origin refuses browser requests from any other origin.

Not in scope: authentication (put the HTTP endpoint behind your gateway or keep it on loopback), and ha