Repository navigation
feat(mcp): every tool that writes takes dry_run and answers the request it would send - #576
Merged
Merged
Conversation
…uest it would send
A tool that writes, called with `dry_run: true`, sends nothing and answers
`{"dry_run": true, "request": {method, url, body}}`: the object the command
prints under `--dry-run -o json`, with secrets masked by the same function
(#556). What the tool reads before its first write is read; the plan is of the
first write. `request` is null where the tool would write nothing. A plan that
would grant access says `grants_access: true`.
One place does it for all 260 tools, and no tool declares the argument: a
middleware of every ycli server takes `dry_run` out of the call and answers the
write the core's guard stopped; `client_provider`, the one place a tool's client
is built, builds it with that guard; a listing transform adds the argument to
every tool whose `readOnlyHint` is false and puts the plan beside the tool's own
answer in its output schema.
`dry_run` written inside an argument (in a body that takes any key, or spelled
`dryRun`, `dry-run`) is refused before anything is sent: one who nests it
believes they are planning. A plan is no error: nothing in the log says a tool
failed, and no traceback of the signal is written.
A tool that only reads has no `dry_run` and refuses it like any argument it does
not have. A tool that grants access prompts for a person on a dry run too: the
client decides from the tool's entry, before the server sees the arguments.
ARCH-3 states the rule. Held by: the contract check that for every write case the tool's plan is the
command's plan and neither sends a write; a check that every writing tool takes
its client from the one guarded place; tests that calls side by side do not take
each other's flag and that the flag is gone after a call that failed; a check
that a secret given to a tool is not in its plan, by its literal value.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
bim-ba
force-pushed
the
feat/mcp-dry-run
branch
from
October 10, 2026 19:33
1a8330f to
8763566
Compare
This was referenced Oct 10, 2026
This branch was previously deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Every MCP tool that writes takes
dry_run. Withdry_run: trueit sends nothing and answers the request it would have sent. Decision: #556 (question 1, A).{"dry_run": true, "request": {"method": "PATCH", "url": "https://api.tracker.yandex.net/v3/boards/7", "body": {"name": "New"}}}How it works, in one place for all 260 tools
DryRun(middleware)new_server, so every ycli server has itdry_runout of the call, marks the call, answers the write the guard stoppedclient_providerGuard(dry_run=True)(#557)DryRunOffered(transform)new_serverreadOnlyHintis false, and the plan to its output schemaNo tool declares the argument and no tool function changed.
The answer
{"dry_run": true, "request": {method, url, body}};requestis whatycli … --dry-run -o jsonprints, secrets masked by the same function"grants_access": true(decided in this PR, see below){"dry_run": true, "request": null}, never the data it read: the caller asked for a planresult, where FastMCP puts that tool's answersdry_run: Unexpected keyword argument. Its schema has no such argumentdry_runthat is not true or falsedry_run: true or falsedry_run(ordryRun,dry-run) INSIDE an argument, at any depth`dry_run` is the tool's own argument: give it beside `body`, not inside itReads the tool makes before its first write go out. The plan is of the FIRST write only. Measured over the contract cases: one tool makes more than one write,
wiki_attachments_upload(it plans the opening of its upload session). No write tool ends a case without a write.Can a dry run send?
By construction no: under
dry_runthe only client a tool can get refuses its first write.test_every_tool_that_writes_takes_its_client_from_the_one_guarded_placeclient_provider; the only tools that reach a service otherwise arestatus_get(reads) andschema_get(no service)test_calls_side_by_side_do_not_take_each_other_s_flagtest_the_flag_is_set_for_the_one_call_and_for_nothing_after_itA plan says that it would grant access
Under
dry_runthe guard used to build the plan without the reason. Now a plan of an operation markedgrants_accesscarries it, and the tool's answer has"grants_access": true; the key is absent otherwise. The command's--dry-runoutput is unchanged (the reason is no field of the plan). Say if this should not be here: it is three lines and one key of the schema.With the mark of #571
A tool that grants access prompts for a person on a dry run too, and in
dontAskmode the dry run is denied like the grant: the client decides from the tool'stools/listentry before the server sees any argument. Not avoidable from the server. In the reference (serve-the-mcp-server, en and ru), with the way out:ycli … --dry-run.Changes for clients
tools/list, measured on the served server: 747,797 -> 791,215 bytes (+43,418, about 167 per write tool). Input schemas over 5,000 bytes (mcp: Codex compacts every tool schema over 5,000 bytes; upgrade FastMCP to 4.0.11 #372): 14 before, 14 after; the closest below the line,datalens_sparkclusters_create, went 4,748 -> 4,915. Largest input schema 29,264 -> 29,431, under the budget of 32,768, whose test is unchanged.{"type": "object", "anyOf": [<the plan>, <its own>], "$defs": <its own definitions>}, or for a tool that answers a list the same union underresult. The definitions stay at the root, where the tool's references look for them. Measured on FastMCP 4.0.11: its client validates an answer against the schema, so the plan has to be in it. Side effect for a user of the FastMCP client on such a server:result.dataof a write tool is a plaindict, not an object built from the schema;structured_contentis as before.mcp_signatures.txtandmcp_output_schemas.txtchange for 260 tools each, which is the number of tools withreadOnlyHintfalse.dry_run: true, and takes no other key), with two cases showing the check still bites.After the review (five findings, all fixed)
$defssat under the union and 154 of 260 write tools had references pointing nowhere:schema_getcould not find a part of a write tool's reply, and on a server that lists output schemas a real write was sent and the client then raised on the answer$refof every write tool's output schema resolves; through a real client on each service server alone, a plan and a normal answer both validate for a tool with definitions and for one that answers a list;schema_getfindsCalendaroftracker_boards_update. My first schema test useddict[str, str], which has no definitions: that is why the suite was greendry_runinside a body that takes any key was SENT as a field (tracker_issues_updatewithbody: {…, "dry_run": true})RequestPlanned, no record with a tracebackARCHITECTURE.mdwas not in the diffNot fixed here, older than this PR and the same on the CLI (carried to #575): a secret the request MODEL does not mark comes back unmasked in a plan (
tracker_triggers_createwebhook password,datalens_trinoclusters_catalog_createconnector password).Also here
One line in the docstring of the tool-search class of #571: the FastMCP version its overrides were written against (4.0.11).
Verified
On this head, over main
ec278275(0.141.0; the commit's parent, by hash; #577 is in it, so the guard lines are no longer in this diff): ruff, ty, lint-imports, ast-grep (each by exit code, 0), the commit hooks over the commit (exit 0), rulesync and the generated reference without drift; the full suite: 8143 passed, 5 skipped, coverage 100 %.NOT RUN: any live run (the plan is made before a service is reached; the reads before a write are the existing path); a check in a real Claude Code session of the prompt on a dry run of a marked tool (the vendor's page is the evidence).
🤖 Generated with Claude Code