feat(safety): annotate destructive tools and add a read-only mode

[BryanFRD]

Problem

The sub-MCPs expose irreversible / high-impact write tools with no machine-readable safety signal and no way to disable them:

• delete_secret, rotate_secret, create_secret, update_secret — packages/mcp-vault/src/tools/secret-mutations.ts
• delete_vault ("Delete a vault and ALL its secrets. Irreversible.") — packages/mcp-vault/src/tools/vaults.ts
• trigger_agent_run (spends FerrFleet run quota / executes agents) — packages/mcp-fleet/src/tools/agents.ts
• activate_release (switches the live serving release of a site) — packages/mcp-growth/src/tools/releases.ts
• revoke_token — packages/mcp/src/tools/tokens.ts

None of these declare MCP tool annotations. Every server.tool(...) call passes only (name, description, schema, handler) — no annotations: { readOnlyHint, destructiveHint, idempotentHint }. There is also no FERRLABS_MCP_READONLY-style switch to register only read tools.

Why it matters

The danger lives entirely in a free-text description string. MCP clients increasingly use destructiveHint / readOnlyHint to gate auto-approval and to warn users before running a tool. Without them, an assistant can silently delete_secret or trigger_agent_run (which costs money and runs code) with no client-side guardrail. A read-only mode is the standard mitigation for users who want the MCP for inspection only.

Proposed approach

• Add an annotations object to every server.tool registration: readOnlyHint: true for list/get/fetch tools, destructiveHint: true (and idempotentHint where applicable) for the mutating tools above.
• Add a FERRLABS_MCP_READONLY=1 env flag that skips registration of all write/destructive tools, documented in the README.
• Centralize the registration helper so the annotation is mandatory at the type level (hard to forget when adding a new tool).

Acceptance criteria

• tools/list reports correct readOnlyHint / destructiveHint for every tool.
• With FERRLABS_MCP_READONLY=1, no destructive tool is registered; a test asserts the registered set.
• README documents the read-only flag and the annotation convention.

[rpelevin]

I would treat annotations as the visible client hint, and read-only mode as the server-side enforcement boundary.

destructiveHint helps clients warn or gate, but the server still needs an invariant that a write/destructive handler is either not registered in read-only mode or fails before business logic runs.

A useful tool registration record could include:

• tool name;
• operation class: read, write, destructive, paid_or_quota, code_execution;
• readOnlyHint;
• destructiveHint;
• idempotentHint;
• requires_approval;
• readonly_mode_behavior: not_registered or fail_closed;
• handler id;
• test fixture id.

Tests I would add:

1. every registered tool must declare annotations through a shared helper.
2. delete_secret, delete_vault, trigger_agent_run, activate_release, and revoke_token are classified as destructive or high-impact writes.
3. FERRLABS_MCP_READONLY=1 exposes no destructive/write handlers in tools/list.
4. a direct call to a disabled write tool fails before the handler runs.
5. missing annotations fail a registration test, so new tools cannot silently bypass classification.
6. docs distinguish client-side warning hints from server-side read-only enforcement.

That preserves MCP client ergonomics without relying on clients alone to protect irreversible operations.