Model Context Protocol · local stdio

Whatbox MCP

A security-first MCP server that gives an AI agent bounded, structured access to one owner-authorized Whatbox slot — read-only by default, and every change gated behind a signed plan and your explicit approval.

read-only by default approval-gated mutations no secrets in context
View on GitHub Get started
$ git clone https://github.com/SNSEIxAUGMNTD/whatbox-mcp.git && cd whatbox-mcp
$ npm ci && npm run build

The design

Two modes, one boundary

The server is an observation layer first. Control is a separate, deliberately harder path — off unless you turn it on, and never able to act destructively without a human in the loop.

Observe Always on

Bounded, credential-free inspection over pinned SSH. No shell, no file contents, no configured paths in the output.

  • Storage, service, and torrent-process state
  • Directory listings & a directory-only structure map
  • Userland Nginx readiness & safe diagnostics
  • One consolidated operational snapshot

Act Off by default

Set WHATBOX_MUTATIONS_ENABLED=true to unlock changes. Reversible actions run from a signed plan; destructive ones always stop and ask.

  • Upload · download · move · mkdir (never overwrite)
  • Configuration backup & free-space checks
  • Service start / stop / restart
  • Atomic website deploy with health check & rollback
  • Torrent add / control / remove via loopback RPC

Every tool, by consequence

Risk is a first-class property

Each tool is labelled by what it can do. The label drives the safety flow — not a guess by the model.

Reversible · auto-runs
whatbox_upload_path whatbox_download_path whatbox_move_path whatbox_make_directory whatbox_backup_configuration whatbox_website_deploy_execute whatbox_torrent_add whatbox_torrent_control

Runs once a signed plan is created, when mutations are enabled. Undoable.

Destructive · always asks
whatbox_quarantine_path whatbox_purge_quarantine whatbox_service_control (stop) whatbox_website_rollback whatbox_torrent_remove

Requires explicit human approval via MCP elicitation — even in agent auto-mode. Delete quarantines first; purge needs a second approval.

Read-only · safe
whatbox_operational_snapshot whatbox_storage_status whatbox_services_status whatbox_website_diagnostics whatbox_torrents_status whatbox_list_tools

Run the /tools command any time for the full catalog and the current mutation state.

The approval gate

How a destructive change actually happens

A model cannot self-approve. The confirmation comes from your client's own UI, bound to an HMAC-signed plan that names the exact action and targets.

PlanAn immutable, signed plan binds the slot, action, and exact target digests. Expires in minutes.
AskThe tool returns input_required with the sealed plan and a yes/no prompt to you.
VerifyOn approval, action & targets are re-checked and the plan is consumed exactly once.
ExecuteThe change runs, is health-checked where relevant, and is written to a redacted audit log.

What holds, always

Safety guarantees

No generic shell. Every remote command is a fixed, server-authored template.
No secrets in context. Credentials stay in a local 0600 file, never in tool arguments or output.
Pinned host identity. The SSH host key is verified by SHA-256 fingerprint.
Contained paths. Access is limited to configured roots, with symlink & traversal denial.
Delete means quarantine. Removal is reversible; permanent purge is a separate second approval.
Space-aware. Remote and local free space are checked before every transfer.