feat: MCP passthrough deprecation -- parity map, warnings, CI canary (0.74.0, #478 phase 2) - #509
Merged
Merged
Conversation
This was referenced Jul 20, 2026
…pic #390) Parity map as code (mcp_parity.py, 39 entries incl. intentional non-ports) with offline registry-pinning tests; per-tool deprecation warnings in tool call (stderr + additive JSON 'deprecation' key), cli_equivalent column in tool list, warnings on agent --type mcp_tool (create/update/test; persisted agents.json and REST payloads untouched); /mcp/tools* serve routes marked deprecated in OpenAPI; weekly mcp-parity-canary workflow + make parity-check (stdlib-only script, live-verified 39/39 catalog coverage); docs flipped CLI-first (mcp-workflow banner, gotchas 0.74.0, CLAUDE.md, AGENT_CONTEXT, commands-reference, keboola-expert). Version 0.74.0.
padak
force-pushed
the
feat/mcp-deprecation-phase2-390
branch
from
July 21, 2026 19:28
03f5fda to
11bec88
Compare
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
1 participant
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.
Summary
Phase 2 of the #478 plan — the MCP passthrough deprecation track (0.74.0). Stacked on #508 (phase 0+1); merge that first, this PR's base then retargets to
main.Nothing breaks:
tool call/tool list/agent --type mcp_toolkeep working through the deprecation window — they just tell you exactly what to use instead.Parity map as code
src/keboola_agent_cli/mcp_parity.py— one entry per upstream tool (39/39 live catalog coverage, verified), including notes for the two intentional non-ports (query_data→workspace query,validate_semantic_query→semantic-layer validate). Offline tests pin every entry to a registered CLI operation, so renaming a native command without updating the map fails regular CI.Deprecation warnings (additive-only envelopes)
tool call NAME: per-tool message naming the exact replacement — stderr in human mode, additivedeprecationkey inside thedatapayload in--json(error envelopes untouched, test-pinned).tool list:cli_equivalentcolumn (human) / field (JSON) + a banner; unmapped tools get"".agent create/update/test --type mcp_tool: warning pointing at--type cli_command; persistedagents.jsonand REST payloads byte-identical (test provesagent showcarries no new key)./mcp/tools*routes markeddeprecated: truein OpenAPI (/mcp/server-statusstays — embedded-server health, used by doctor/UI).CI canary
.github/workflows/mcp-parity-canary.yml(weekly cron + manual) runsscripts/check_mcp_parity.py— stdlib-only (loads the map straight from the module file, no package import → barepython3, no dependency install), diffs the live keboola-mcp-serverTOOLS.mdagainst the map: new upstream tool → red run; removed upstream tool → warning. Local:make parity-check. Deliberately NOT in the PR-blocking test job (network).Docs flipped CLI-first
Deprecation banner atop
mcp-workflow.md;gotchas.md(since v0.74.0)section; CLAUDE.md,AGENT_CONTEXT,commands-reference.md,keboola-expert.mdupdated.Verification
make checkgreen: 4613 passed (16 new tests: 5 parity-map invariants + 11 warning/envelope tests).catalog: 39 tools, parity map: 39 entries — OK.tool call get_bucketsreturns data + thestorage bucketshint in both modes (stderr / JSON key);tool listmapsget_buckets→storage buckets,run_job→job run,docs_query→docs query,create_sql_transformation→transformation create.Remaining phase 3 (tracked in #390/#478): passthrough removal +
agents.jsonmcp_tool migration story, after a deprecation window.