[Cylop]

Summary

Phase 4: permesh mcp, a local, read-only MCP server over stdio (protocol 2026-07-28 only), built on the official Rust SDK (rmcp 3.7, server + transport-io).

• Closed tool list mapping onto existing commands:

  Tool	Command
  doctor	doctor
  user_access	user
  resource_access	resource
  admins	admins
  orphaned	orphaned
  profile_check	profile check
  plan_join, plan_move, plan_leave	access join, access move, access leave
  verify_plan	access verify

  • Each call becomes an exact permesh --json argv parsed by the normal CLI parser and run by app::run, so it uses the same workspace, approvals and credentials as the CLI.
  • There is no pass-through: check, snapshot save, identity map, auth, provider, init, offboard and access review can't be reached.

• Results carry exit_code, the CLI's --json report, and a note when the capture is incomplete. Exit codes 4 and 6 are answers, not tool errors.

• Paths are confined to the workspace folder: no absolute paths, no .. escapes, no symlinks pointing out. Values are passed as --name=value and positionals after --, so data never becomes a flag.

• Plan outputs are new .json files only, never inside people/, profiles/ or hidden folders, and never overwritten.

• Shutdown and cancellation: calls run one at a time. Cancelling a call, closing stdin, Ctrl+C or SIGTERM drains a running call, so provider processes are stopped and reaped before exit.

• Docs: ADR 0035, docs/mcp.md, plus README, CHANGELOG, docs/README.md and docs/stability.md updates. permesh mcp is experimental.

Validation

• cargo test --workspace: 701 passed, 0 failed. tests/mcp.rs has 24 end-to-end stdio tests, including cancellation, SIGTERM and EOF tests with a native provider that hangs in discovery.
• cargo clippy --workspace --all-targets -- -D warnings, cargo fmt --check, cargo deny check and scripts/check_docs.py are clean.
• Final whole-branch review on Opus found 1 Important issue, plus 1 Minor that I raised to Important (SIGTERM orphaning provider processes). Both are fixed test-first.

Deferred minors

• A call cancelled while it waits behind another call still waits for its turn before returning Cancelled.
• In-workspace symlinks can reveal whether a file outside the workspace exists (from the order of the checks).
• A race between path checks and the CLI's file create, if a local writer swaps in a symlink. Overwriting stays impossible.
• An empty profiles/remove array gets a generic "Invalid tool arguments".
• Every MCP start failure is reported as a protocol-version problem.
• The instructions say every result has complete; it is report.complete, on successful results only.
• ADR 0035 doesn't list the rejected options.
• docs/mcp.md's "not available" list isn't exhaustive.