feat(mcp): add billing_status, subscription_status, and is_account_locked to check_airbyte_cloud_workspace MCP tool

[Aaron ("AJ") Steers (aaronsteers)]

feat(mcp): add billing status to check_airbyte_cloud_workspace tool

Summary

Enhances the check_airbyte_cloud_workspace MCP tool to expose billing status information, allowing the Coral Agent to detect when syncs are disabled due to unpaid invoices.

Adds three new fields to CloudWorkspaceResult:

• payment_status: Organization payment status (e.g., 'okay', 'grace_period', 'disabled', 'locked')
• subscription_status: Organization subscription status (e.g., 'pre_subscription', 'subscribed')
• account_is_locked: Boolean indicating if the account is locked due to billing issues (defaults to False)

The billing data is fetched from the existing get_workspace_organization_info API endpoint. The payment_status and subscription_status fields gracefully degrade to None if billing info is unavailable (e.g., insufficient permissions), while account_is_locked defaults to False unless we have affirmative evidence of a locked state.

Updates since last revision

• Renamed can_run_syncs to account_is_locked with inverted logic per code review feedback
• account_is_locked is True only when payment_status in {'disabled', 'locked'} or subscription_status in {'unsubscribed'}
• Changed default from None to False - assumes account is not locked unless we detect a locked state
• Verified billing status strings match production values in OrganizationPaymentConfig.java enums

Review & Testing Checklist for Human

• Verify account_is_locked logic is correct: Should be True when payment_status is 'disabled'/'locked' OR subscription_status is 'unsubscribed'. Defaults to False when billing info is unavailable.
• Test with a workspace that has billing issues: Verify the tool correctly returns account_is_locked=True for a workspace with unpaid invoices (payment_status='disabled')
• Test with workspace-scoped credentials: Verify graceful degradation when ORGANIZATION_READER permission is not available (billing fields should be None, account_is_locked should be False)

Suggested test plan: Use the MCP tool against a test workspace with known billing status and verify the returned values match expectations.

Notes

• Requested by Aaron ("AJ") Steers (@aaronsteers)
• Link to Devin run: https://app.devin.ai/sessions/ffd06414843642b8a7161965d8882836

Summary by CodeRabbit

• New Features

  • Workspace and organization views now include payment status, subscription status, and an "account locked" flag.
  • Organization objects support lazy on‑demand loading of billing and contact information.

• Behavior

  • Sync eligibility now accounts for billing state; locked/disabled payments or unsubscribed status can block syncs.
  • Billing retrieval is tolerant of permission/API failures—unavailable billing fields remain blank without breaking views.

• Documentation

  • Workspace docs updated to include billing and sync‑eligibility details.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

💡 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/airbytehq/PyAirbyte.git@devin/1769624968-add-billing-status-to-mcp' pyairbyte --help

# Install PyAirbyte from this branch for development:
pip install 'git+https://github.com/airbytehq/PyAirbyte.git@devin/1769624968-add-billing-status-to-mcp'

PR Slash Commands

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

📚 Show Repo Guidance

Helpful Resources

• PyAirbyte Documentation
• API Reference

Community Support

Questions? Join the #pyairbyte channel in our Slack workspace.

📝 Edit this welcome message.

[devin-ai-integration]

The intent here is to fail gracefully - if billing info can't be fetched (e.g., due to permissions or API issues), we want to continue with None values rather than breaking the tool.

I can add logging here for debuggability. The pattern already exists in this codebase (see airbyte/mcp/registry.py which uses logger = logging.getLogger("airbyte.mcp")).

Aaron ("AJ") Steers (@aaronsteers) - Would you like me to add logging here, or is the silent fallback acceptable for this use case? Happy to add it if you prefer the extra debuggability.

[coderabbitai]

📝 Walkthrough

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding billing status fields to the check_airbyte_cloud_workspace MCP tool.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch devin/1769624968-add-billing-status-to-mcp

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

Devin Review found 1 potential issue.

View issue and 3 additional flags in Devin Review.

[devin-ai-integration]

Good catch! I've fixed this in commit 49c2e0f. The logic now correctly computes can_run_syncs when either status is available:

if payment_status or subscription_status:
    blocked_by_payment = payment_status in {"disabled", "locked"}
    blocked_by_subscription = subscription_status == "unsubscribed"
    can_run_syncs = not (blocked_by_payment or blocked_by_subscription)

This ensures that if payment_status='disabled' but subscription_status=None, can_run_syncs will correctly be False.

[devin-ai-integration]

Aaron ("AJ") Steers (@aaronsteers) Done! Simplified the logic with constants as you suggested:

LOCKED_PAYMENT_STATUSES: set[str] = {"disabled", "locked"}
LOCKED_SUBSCRIPTION_STATUSES: set[str] = {"unsubscribed"}

can_run_syncs = (
    payment_status
    and payment_status not in LOCKED_PAYMENT_STATUSES
) or (
    subscription_status
    and subscription_status not in LOCKED_SUBSCRIPTION_STATUSES
)

Also added a comment to the except block to address the CodeQL warning about empty except clauses.

[devin-ai-integration]

Devin Review found 1 new potential issue.

View issue and 6 additional flags in Devin Review.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@airbyte/mcp/cloud.py`:
- Around line 576-580: The current can_run_syncs boolean uses OR and therefore
allows syncs if either payment_status or subscription_status is non-locked;
change the logic to require both statuses to be non-blocking by using AND:
ensure can_run_syncs evaluates to True only when (payment_status is missing or
not in LOCKED_PAYMENT_STATUSES) AND (subscription_status is missing or not in
LOCKED_SUBSCRIPTION_STATUSES); update the inline comment near can_run_syncs to
reflect that both payment and subscription must permit syncs.

[github-actions]

PyTest Results (Fast Tests Only, No Creds)

326 tests  ±0   326 ✅ ±0   5m 37s ⏱️ -1s
  1 suites ±0     0 💤 ±0 
  1 files   ±0     0 ❌ ±0 

Results for commit c564c9a. ± Comparison against base commit 8a43e06.

♻️ This comment has been updated with latest results.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@airbyte/mcp/cloud.py`:
- Around line 574-577: The computed can_run_syncs currently evaluates to False
when both payment_status and subscription_status are None, but the type allows
None to represent "unknown"; change the logic so can_run_syncs is set to None
when billing info is unavailable (both payment_status and subscription_status
are None), otherwise compute the boolean as before using the existing expression
that checks against LOCKED_PAYMENT_STATUSES and LOCKED_SUBSCRIPTION_STATUSES
(refer to the can_run_syncs variable and the payment_status/subscription_status
symbols).

[devin-ai-integration]

Devin Review found 1 potential issue.

View issue and 3 additional flags in Devin Review.

[github-actions]

PyTest Results (Full)

396 tests  ±0   379 ✅ ±0   23m 24s ⏱️ -52s
  1 suites ±0    17 💤 ±0 
  1 files   ±0     0 ❌ ±0 

Results for commit c564c9a. ± Comparison against base commit 8a43e06.

♻️ This comment has been updated with latest results.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@airbyte/mcp/cloud.py`:
- Around line 171-182: Docstring for subscription_status omits the
'unsubscribed' value even though account_is_locked logic treats 'unsubscribed'
as locking; update the subscription_status docstring to include 'unsubscribed'
(e.g., "pre_subscription', 'subscribed', 'unsubscribed'") and ensure the
account_is_locked docstring references the same values consistently (mentioning
that 'unsubscribed' contributes to a locked state alongside payment_status
values like 'disabled'/'locked').

🧹 Nitpick comments (1)

airbyte/mcp/cloud.py (1)

42-44: Clarify the tuple rationale comment?

The “unhashable types” note feels a bit off for string constants. Would you consider rewording it to emphasize immutability or just drop the note for clarity, wdyt?

[Aldo Gonzalez (aldogonzalez8)]

APPROVED

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@airbyte/cloud/workspaces.py`:
- Around line 134-139: The early-return checks block re-fetching when
_organization_info_fetch_failed is True even if force_refresh is requested;
update the logic in the method that uses force_refresh,
_organization_info_fetch_failed, and _organization_info so that when
force_refresh is True you clear or reset _organization_info_fetch_failed (or run
the fetch path regardless) before returning; in short, check force_refresh first
(or set self._organization_info_fetch_failed = False when force_refresh is True)
so a forced refresh will actually attempt to re-fetch rather than immediately
returning {}.

🧹 Nitpick comments (1)

airbyte/cloud/workspaces.py (1)

149-152: Consider adding debug logging when fetch fails?

The silent failure is great for graceful degradation, but it might make debugging tricky when something goes wrong. Would adding a debug-level log message help with troubleshooting, wdyt?

except Exception as e:
    # Consider: import logging; logger = logging.getLogger(__name__)
    # logger.debug("Failed to fetch organization info: %s", e)
    self._organization_info_fetch_failed = True
    return {}