Skip to content

MCP: confine file access with --automation-read-root and --automation-write-root (#769) - #798

Merged
echelon merged 9 commits into
storytold:mainfrom
isaac-levine:mcp-automation-roots
Oct 12, 2026
Merged

echelon merged 9 commits into
storytold:mainfrom
isaac-levine:mcp-automation-roots

Conversation

@isaac-levine

@isaac-levine isaac-levine commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

wordcraft-cli mcp gives the agent on the other end the same file access as the user running it. VectorCraft already has two flags for this, so this adds the same ones here with the same names and behaviour, and one client config works across the apps:

wordcraft-cli mcp --automation-read-root /work/project --automation-write-root /work/project/out

Every file a command reads has to be inside the read root and every file it writes inside the write root. A root left out grants none of its access, so the read root alone makes the server read-only. Paths are made absolute, symlinks followed (for a file that doesn't exist yet, the nearest existing folder is resolved and the rest must be plain names), then compared with the root by whole path components, so /work2 is not inside /work. On Windows case is ignored and device names like CON and NUL are refused. Refusals come back as normal tool errors with VectorCraft's wording, for example automation path rejected: outside the read root /work/project: /etc/passwd.

Where the checks live

All path-based access in the engine already went through io::open_path_with and io::save_path_with, apart from four commands that called std::fs directly (insert.picture, picture.change, mailings.recipients, file.exportPng). Those now go through two small helpers, io::read_file and io::write_file, and the checks sit in those four functions. A new test fails if a command module starts touching the file system on its own again. Headless::with_automation_roots in the mcp crate runs each call inside the confinement, and the CLI gets the flag parsing (--flag DIR or --flag=DIR, a flag given twice or a missing folder is an error, --connect together with the flags is an error). docs/mcp.md gets a "Confining file access" section.

Covered reads: open_document, file.open, file.newFromTemplate, insert.textFromFile, insert.object, insert.picture, picture.change, mailings.recipients, review.compare, tools.updateStyles, styles.organizer, styles.copyFrom. Pictures referenced from an opened HTML file are only read from beside that file, which is inside the read root already. Covered writes: save_document, file.save, file.saveAs, file.exportPdf, file.exportPng, file.saveTemplate, mailings.finish.

Not covered: the desktop app (wordcraft --control) doesn't take the flags yet. In VectorCraft the app-side version also has to leave the user's own file dialogs and the app's own folders unconfined, which is a bigger change in ui-egui, so the docs say a running app is not confined. Commands that take no path still read and change the open document. The Zotero commands talk over a socket, not files. And like VectorCraft this is check-then-open, so it keeps an agent inside the folders it was given rather than defending against another program racing it.

Testing

Unit tests on the path logic (inside/outside, .., same-prefix sibling, relative and empty paths, symlinks out through a temp dir, missing roots, each root left out, both roots the same folder). crates/mcp/tests/automation_roots.rs goes through the MCP protocol and checks that every command above is refused outside its root and works inside, that nothing is written outside, and that links out are refused. CLI tests cover the flag parsing and the --connect conflict. I also ran the built binary by hand with only a read root and confirmed open_document outside it is refused and inside it works.

cargo xtask ci passes all six steps (fmt, clippy, test, assets, layers, wasm). Windows paths weren't exercised, I only have a Mac.

Fixes #769

isaac-levine and others added 7 commits October 11, 2026 22:51
# Conflicts:
#	crates/engine/src/io.rs
…ngine/src

- print.rs::print_pdf_to_file (file.printPdf, added on main) wrote with std::fs::write
  directly, so a confined agent could print a PDF anywhere. It now goes through
  io::write_file, which checks the automation write root.
- The guard test now walks every file under crates/engine/src (not only cmd/), except
  io.rs, file_access.rs and the tests*.rs modules, and also flags OpenOptions.
- Tests: an engine test that file.printPdf is refused outside the write root, works inside
  and is unchanged without roots; the MCP integration test covers it too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… writes in docs/mcp.md

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@echelon

echelon commented Oct 12, 2026

Copy link
Copy Markdown
Member

Thanks, this is a careful piece of work. I merged main and made a few small changes so it covers code that landed after you opened it:

  • Merged main. save_path_with now takes &ExportOptions, and it still checks the write root first.
  • file.printPdf (print.rs::print_pdf_to_file, new on main) wrote with std::fs::write directly, so a confined agent could print a PDF anywhere. It now goes through io::write_file, and docs/mcp.md lists it.
  • commands_do_not_touch_the_file_system_themselves now walks every file under crates/engine/src, not just cmd/. It skips io.rs, file_access.rs and the tests*.rs modules, and it also flags OpenOptions, so the next file outside cmd/ can't slip past.
  • Tests: an engine test shows file.printPdf is refused outside the write root, works inside it and behaves the same as before when no roots are given. The MCP integration test covers it as well.

Behaviour with no flags is unchanged.

@echelon
echelon merged commit 64319e0 into storytold:main Oct 12, 2026
@echelon

echelon commented Oct 12, 2026

Copy link
Copy Markdown
Member

Thanks for the contribution, @isaac-levine! This is now merged into main. If you haven't already, please come join us on Discord: https://discord.gg/artcraft

@isaac-levine

Copy link
Copy Markdown
Contributor Author

Thanks for picking up the printPdf path and widening the guard test, that is a better net than mine. I'll keep the same shape on the other apps.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

MCP server: add --automation-read-root / --automation-write-root, like VectorCraft

2 participants