[Michael Lip (theluckystrike)]

Overview

TL;DR: Agents can now clear synced data for an Airbyte Cloud connection, for all streams or only the named ones, without leaving the agent for the UI or the API. The new clear_cloud_connection MCP tool is marked destructive, respects safe mode, and needs the connection name as confirmation.

Closes #1385

Changes

• api_util.clear_connection(): calls the Config API POST /v1/connections/clear, or POST /v1/connections/clear/stream when stream descriptors are given. These are the same endpoints the Cloud web app uses for "Clear data".
• CloudConnection.clear(stream_names=None): starts the clear job and returns a SyncResult for it (no wait; call wait_for_completion() to wait). Named streams are resolved against the selected streams of the connection's catalog, so each descriptor carries its source namespace. It raises PyAirbyteInputError before any API call for an empty list, for a stream that is unknown or not selected, and for a stream name that exists in more than one namespace (it does not guess which one).
• clear_cloud_connection MCP tool: destructive=True, open_world=True. It calls check_guid_created_in_session like the other destructive tools, and requires name to match the connection's actual name, like permanently_delete_cloud_connection. stream_names accepts a list, a CSV string or a JSON array string, through resolve_list_of_strings. An empty string resolves to an empty list and is refused, so it can never fall back to "clear everything". The reply gives the job ID and the job URL.

Review Spotlight

• CloudConnection._resolve_stream_descriptors(): how stream names map to namespaced descriptors.
• The guard order in clear_cloud_connection: safe mode check, then workspace lookup, then name confirmation, then the clear.

Risks

• A clear deletes destination data and cannot be undone. The tool is therefore behind safe mode and the name confirmation, and read-only mode drops it with the other destructive tools.
• Per-stream clear uses the Config API, like the existing state and catalog helpers. The public API jobs endpoint has no per-stream clear.
• I did not run a live clear against a Cloud workspace. All tests mock the API.

Test plan

• tests/unit_tests/test_cloud_api_util.py: endpoint path and body for a full clear and a per-stream clear.
• tests/unit_tests/test_cloud_connections.py: full clear, per-stream clear with namespaces and de-duplication, and the refusals for an empty list, an unknown stream, an unselected stream and an ambiguous stream name.
• tests/unit_tests/test_mcp_cloud.py: stream name forms (none, CSV, list), name mismatch, safe mode refusal, and the destructive hint.

Commands and results (base f229555, uv sync --frozen --all-groups):

• uv run pytest tests/unit_tests/test_cloud_connections.py tests/unit_tests/test_mcp_cloud.py tests/unit_tests/test_cloud_api_util.py: 122 passed.
• Without the source change: 6 new connection tests fail, 6 new MCP tests fail, and test_cloud_api_util.py fails at collection (no clear_connection).
• ruff check, ruff format --check and pyrefly check (0 errors) pass.

This change was made with AI assistance and reviewed by me.

[octavia-bot]

Note

📝 PR Converted to Draft

More info...

Thank you for creating this PR. As a policy to protect our engineers' time, Airbyte requires all PRs to be created first in draft status. Your PR has been automatically converted to draft status in respect for this policy.

As soon as your PR is ready for formal review, you can proceed to convert the PR to "ready for review" status by clicking the "Ready for review" button at the bottom of the PR page.

To skip draft status in future PRs, please include [ready] in your PR title or add the skip-draft-status label when creating your PR.

[github-actions]

👋 Welcome to PyAirbyte!

Thank you for your contribution from theluckystrike/PyAirbyte! We're excited to have you in the Airbyte community.

💡 Show Tips and Tricks

Testing This PyAirbyte Version

You can test this version of PyAirbyte using the following:

# Run PyAirbyte CLI from this branch:
uvx --from 'git+https://github.com/theluckystrike/PyAirbyte.git@fix/1385-clear-cloud-connection' pyairbyte --help

# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/theluckystrike/PyAirbyte.git@fix/1385-clear-cloud-connection'

PR Slash Commands

As needed or by request, Airbyte Maintainers can execute the following slash commands on your PR:

• /fix-pr - Fixes most formatting and linting issues
• /uv-lock - Updates uv.lock file
• /test-pr - Runs tests with the updated PyAirbyte
• /prerelease - Builds and publishes a prerelease version to PyPI
• /evals - Runs the Cloud MCP evals that use the MCP tools this PR changed (/evals full=true runs the full suite)

📚 Show Repo Guidance

Helpful Resources

• Contributing Guidelines
• PyAirbyte Documentation
• API Reference

If you have any questions, feel free to ask in the PR comments or join our community:

• Airbyte Slack - Join the #pyairbyte channel
• GitHub Discussions

📝 Edit this welcome message.