Movi MCP v1 is the local-first stdio extension surface for Movi.
The canonical public root still lives at the repo root (README.md +
manifest.yaml), the canonical machine-readable descriptor now lives at
../server.json, and ../apps/mcp/README.md explains the runtime
implementation path. This page explains the pure-MCP support surface; it does
not mean the repo already ships a live registry listing.
In plain language: it gives an agent or automation client a supervised control window into the same workflow humans use in the app. It can inspect jobs, read reports, patch overlays, preview reusable rules, and queue dry-run-safe follow-up work, but it does not get a secret “move files now” shortcut.
overlay-only, dry-run before execute, and rollback-readyThink of it like a supervised service window at the same workshop. The agent can ask for plans, previews, and review data through the window, but it still cannot reach behind the counter and move boxes on its own.
Repo-local runtime entrypoint:
bash tooling/runtime/bootstrap_env.sh
bash tooling/runtime/run_mcp_stdio.sh
Convenience npm script from the repo root:
npm run mcp:stdio
Quick discovery helpers:
npm run mcp:tools
npm run mcp:resources
Installed Python entrypoint, if you install the package or add the managed venv bin directory to your PATH:
movi-mcp
Both entrypoints are local-first and stdio-first. They are meant to be launched by an MCP-capable client from your machine, not published as a remote hosted endpoint.
If you want the shortest ecosystem answer:
extensions#161 review-pending and the repo does not yet ship a dedicated first-party setup page or branded workflow for themsuspicious.vt_suspicious warning instead of a clean approval receiptClient-specific entry pages:
Use these commands when you want to prove the MCP surface exists before wiring a client:
~/.cache/movi-organizer/venv/default/bin/movi-mcp --help
~/.cache/movi-organizer/venv/default/bin/movi-mcp --print-tools
~/.cache/movi-organizer/venv/default/bin/movi-mcp --print-resources
The exact tool names live in the server and client config, but the current v1 surface is intentionally narrow:
| Tool family | Why it exists | Safety boundary |
|---|---|---|
runtime.settings.get |
inspect the current local-first workspace defaults before creating work | read-only |
analyze.create |
start a local analyze job for a batch | creates a draft job only; does not apply file changes |
jobs.list / jobs.get |
inspect local job state | read-only |
review_queue.get |
read the current review queue, copilot summary, and collections | read-only |
manifest.get |
inspect resolved manifest rows | read-only |
manifest.patch_row / manifest.batch_patch |
update the overlay through the same review-safe path as the WebUI | writes to overlay only, not disk moves |
review_rule.preview / review_rule.apply |
preview or apply a rule against the overlay | preview/apply stay inside the review layer |
apply.preview |
queue a dry-run apply job | no direct execute shortcut |
report.get |
read the report plus review bridge context | read-only |
strategy_packs.list / watch_sources.list / inbox.scan |
inspect setup/intake surfaces for recurring work | discovery and template layers only |
inbox.analyze |
mirror the explicit inbox-to-analyze handoff from the app | creates an analyze draft only; still no autonomous execution |
Movi MCP v1 currently ships tools + resources. It does not claim a broader hosted control plane, and it does not need remote transports or a prompt catalog in v1 to be useful.
Movi MCP v1 also exposes read-only resources so an agent can load the rules of the road before it starts acting:
| Resource family | Purpose |
|---|---|
| workflow/safety boundary | explain review-first, overlay-only, dry-run-before-execute, and rollback-ready constraints |
| workflow/tool matrix | map tool families to the parts of the product they touch |
| job-scoped review/report resources | provide read-only access to review queue or report context for one existing job |
| allowlisted docs resource | load the public docs that explain overview, usage, architecture, MCP, and developer guidance |
Most MCP-capable clients want a stdio command plus arguments. The exact config format depends on the client, but the important part is simple:
{
"name": "movi",
"command": "bash",
"args": ["/absolute/path/to/movi-organizer/tooling/runtime/run_mcp_stdio.sh"]
}
If your client supports a working directory field, point it at the repository root. If it prefers installed entrypoints and you have the package-installed console script available, use movi-mcp instead.
If you want a client-specific landing page instead of a generic MCP snippet:
review_queue.get, manifest.get, report.get, and the read-only resources before taking any overlay action.manifest.patch_* and review_rule.apply as review-layer edits, not as execution.apply.preview before any human decides whether a real apply should happen.apply.execute is intentionally absent from Movi MCP v1.Movi MCP v1 as a tool that “organizes files automatically.” That would be false and would erase the core product boundary.