Public: anyone can read this; the crew can change it.

MCP `fleet`: query and act with dry-run by default #10182

Parked opened this in answer to
Closed without merging

MCP flow can now act on what a fleet query selects, not just list it: { q, action, dryRun? } runs one fleet operation over every row the query line q matches. It calls the same previewFleetOp / applyFleetOp that POST /api/v1/fleet/ops calls, so the plan and receipt JSON are the API's, plus a says sentence to relay.

Notes

stopped parked by the crew deploy aa02af6

opened this

MCP flow can now act on what a fleet query selects, not just list it: { q, action, dryRun? } runs one fleet operation over every row the query line q matches. It calls the same previewFleetOp / applyFleetOp that POST /api/v1/fleet/ops calls, so the plan and receipt JSON are the API's, plus a says sentence to relay. The query half was already there (flow with q, #10132), so this adds an action to that tool instead of making a new fleet tool, as docs/MCP.md asks.

Two departures from the issue's wording

  • dryRun instead of apply: true. docs/MCP.md fixes dryRun as the dry-run switch for every tool. Leaving it out or setting it true plans and changes nothing, on any token; only dryRun: false writes.
  • Applying needs an admin token, not rw. That matches the API, so MCP is not an easier way in than /api/v1/fleet/ops. An agent may plan but never apply, as on the page and in the API. The receipt's id is undone with limb action: "undo" within 24 hours.

What to look at

  • src/http/mcp/tools/flow.ts: the tool is now writes: true, with readsWhen making every call a read except an action with dryRun: false. As a result, tools/list no longer marks flow as read-only, so a client may treat its plain reads as writes too.
  • src/crew/conversation_confirm.ts: flow is added to ASKING, so the forge's own agent asks before applying an operation, the way it does for archive. Plans and row reads still go through without asking.
  • docs/MCP.md has a paragraph on the new action.

Tests

  • test/mcp-fleet-act.test.ts:
    • A plan by default on a read token, deep-equal to the API's dry-run answer, and nothing changes.
    • Applying is refused on ro and rw tokens and works on an admin token; the receipt matches GET /api/v1/fleet/ops/:id.
    • An agent can plan but not apply.
    • A bad action, a bad dryRun or a bad query line each answer with their reason.
  • test/conversation-confirm.test.ts now requires flow to be in ASKING.

Checks run: bun scripts/gate.ts and bun x tsc --noEmit are clean, and test/mcp-size.test.ts passes without raising any ceiling. I ran the MCP, fleet and conversation-confirm suites by hand (397 pass). Once conversation_confirm.ts changed, scripts/fast.ts named 1,505 files, so I stopped that run and left the full suite to the forge's check.

To try it: call flow with { "q": "repo owner:you", "action": { "verb": "ceiling", "value": 7.5 } } to see the plan, then add "dryRun": false with an admin token to apply it.

🤖 Generated with Claude Code

Closes #450

3 earlier comments
commented

MCP flow can now act on what a fleet query selects, not just list it: { q, action, dryRun? } runs one fleet operation over every row the query line q matches. It calls the same previewFleetOp / applyFleetOp that POST /api/v1/fleet/ops calls, so the plan and receipt JSON are the API's, plus a says sentence to relay. The query half was already there (flow with q, #10132), so this adds an action to that tool instead of making a new fleet tool, as docs/MCP.md asks.

Two departures from the issue's wording

  • dryRun instead of apply: true. docs/MCP.md fixes dryRun as the dry-run switch for every tool. Leaving it out or setting it true plans and changes nothing, on any token; only dryRun: false writes.
  • Applying needs an admin token, not rw. That matches the API, so MCP is not an easier way in than /api/v1/fleet/ops. An agent may plan but never apply, as on the page and in the API. The receipt's id is undone with limb action: "undo" within 24 hours.

What to look at

  • src/http/mcp/tools/flow.ts: the tool is now writes: true, with readsWhen making every call a read except an action with dryRun: false. As a result, tools/list no longer marks flow as read-only, so a client may treat its plain reads as writes too.
  • src/crew/conversation_confirm.ts: flow is added to ASKING, so the forge's own agent asks before applying an operation, the way it does for archive. Plans and row reads still go through without asking.
  • docs/MCP.md has a paragraph on the new action.

Tests

  • test/mcp-fleet-act.test.ts:
    • A plan by default on a read token, deep-equal to the API's dry-run answer, and nothing changes.
    • Applying is refused on ro and rw tokens and works on an admin token; the receipt matches GET /api/v1/fleet/ops/:id.
    • An agent can plan but not apply.
    • A bad action, a bad dryRun or a bad query line each answer with their reason.
  • test/conversation-confirm.test.ts now requires flow to be in ASKING.

Checks run: bun scripts/gate.ts and bun x tsc --noEmit are clean, and test/mcp-size.test.ts passes without raising any ceiling. I ran the MCP, fleet and conversation-confirm suites by hand (397 pass). Once conversation_confirm.ts changed, scripts/fast.ts named 1,505 files, so I stopped that run and left the full suite to the forge's check.

To try it: call flow with { "q": "repo owner:you", "action": { "verb": "ceiling", "value": 7.5 } } to see the plan, then add "dryRun": false with an admin token to apply it.

🤖 Generated with Claude Code

commented

MCP flow now handles fleet operations: called with { q, action, dryRun? } it runs previewFleetOp / applyFleetOp, the same functions behind POST /api/v1/fleet/ops, and answers the same plan or receipt JSON plus a says line. It only plans unless dryRun is false, and any token can ask for a plan. Applying needs an admin token. Agents can never apply, and the forge's own agent confirms first through src/crew/conversation_confirm.ts. The tool keeps readsWhen, so every call other than an apply still counts as a read. limb undo with the receipt's id reverts an apply within 24 hours. docs/MCP.md documents the new call. test/mcp-fleet-act.test.ts covers:

  • the plan on a read token, which changes nothing;
  • read-write and agent tokens being refused when they try to apply;
  • an admin apply and its undo;
  • a bad verb, a non-boolean dryRun and a bad query line.

The last check failed on the gate rule "say how to try it on the preview" because no commit had a Try: line. The new commit 4de54975 is empty and only adds that line. I didn't amend the earlier commit, because that would need a force push.

Locally, bun scripts/gate.ts and bun x tsc --noEmit pass, and test/mcp-fleet-act.test.ts plus test/conversation-confirm.test.ts pass (27 tests). The new commit is not pushed: every git push for about 30 minutes got "CONNECT tunnel failed, response 502" from the sandbox proxy to forge.open-platform.sh. Until a plain git push from this branch goes through, the forge has nothing new to check.

Try: on the preview, send tools/call to /mcp for flow with {"q":"repo","action":{"verb":"ceiling","value":3}} on a read token. It should answer the plan with dryRun: true and change nothing. The same call with "dryRun": false and an admin token applies it and returns the receipt id to pass to limb undo.

🤖 Generated with Claude Code

commented

flow with { q, action, dryRun? } now does the fleet operation through MCP (#450). It calls the same previewFleetOp / applyFleetOp as POST /api/v1/fleet/ops and returns the same plan and receipt JSON, plus a says sentence.

  • Dry run by default: it only plans unless dryRun is false, and any token can plan.
  • Applying: it needs an admin token, the same as the API. An agent's token can never apply, and the forge's own agent must get a confirm in the conversation first (ASKING in src/crew/conversation_confirm.ts).
  • Undo: limb with action: "undo" and the receipt's id reverts an applied operation for one day.

This update merges main. The only conflict was in docs/MCP.md, where this pull's flow fleet-op paragraph and main's crew { kind: "week" } paragraph (#10722) were both added in the same place. Both paragraphs are kept, one after the other.

Checks run:

  • bun scripts/gate.ts and bun x tsc --noEmit pass. The first type check failed because @vscode/ripgrep was missing from the local node_modules; it passed after bun install.
  • scripts/fast.ts named 1,620 test files, too many to run here. I ran the 15 files that cover this change instead: test/conversation-confirm.test.ts, test/mcp-fleet-act.test.ts, test/mcp-size.test.ts and the fleet tests. All 172 tests pass. The full suite runs in the forge's check on this push.

To try it on the preview (https://lab--10182--forge-trevato-apps.open-platform.sh):

  1. Call the MCP tool flow with a q and an action to get a plan without changing anything.
  2. With an admin token, call it again with dryRun: false to apply it and get a receipt.
  3. Call limb with { action: "undo", id }, using the receipt's id, to revert it.

🤖 Generated with Claude Code

commented

Parked by the crew: the check stayed red through 2 automatic tries

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs