feat(mcp): add workspace sync status UI tool

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

Summary

Add show_workspace_sync_status as a workspace-level interactive MCP dashboard now targeting main after the prerequisite interactive UI PRs landed. The tool fetches real Airbyte Cloud workspace connections and recent sync jobs, then renders bounded agent text plus Prefab UI content: summary metrics, a status pie chart, and a connection table with drill-down affordances.

The dashboard follows the mainline MCP UI registration pattern: show_ tool naming, INTERACTIVE_UI_ANNOTATION, PrefabAppConfig, register_interactive_tools(), and imports shared sync-history formatting from _sync_history_ui.py. The pie chart pins the demo-critical colors: Succeeded = green (#22c55e), Canceled = yellow (#eab308), and No syncs = grey (#94a3b8).

Drill-down is implemented with a Prefab SendMessage button plus per-row suggested_tool_call, e.g. show_connection_sync_history(connection_id="..."), so the agent can invoke the per-connection sync-history UI from #1042. This is intended for AJ's Snowflake Summit demo workflow.

Validation

• Merged current origin/main into this branch; PR is mergeable with no conflicts after the latest push.
• From the repo root: UV_PYTHON=3.10 uv run ruff format airbyte/mcp/interactive/__init__.py airbyte/mcp/interactive/_sync_history_ui.py airbyte/mcp/interactive/_workspace_sync_status_ui.py tests/unit_tests/test_mcp_workspace_sync_status.py tests/unit_tests/test_mcp_connector_registry.py — 5 files left unchanged.
• From the repo root: UV_PYTHON=3.10 uv run ruff check airbyte/mcp/interactive/__init__.py airbyte/mcp/interactive/_sync_history_ui.py airbyte/mcp/interactive/_workspace_sync_status_ui.py tests/unit_tests/test_mcp_workspace_sync_status.py tests/unit_tests/test_mcp_connector_registry.py — passed.
• From the repo root: UV_PYTHON=3.10 uv run pyrefly check airbyte/mcp/interactive/__init__.py airbyte/mcp/interactive/_sync_history_ui.py airbyte/mcp/interactive/_workspace_sync_status_ui.py tests/unit_tests/test_mcp_workspace_sync_status.py tests/unit_tests/test_mcp_connector_registry.py — 0 errors.
• From the repo root: UV_PYTHON=3.10 uv run pytest tests/unit_tests/test_mcp_workspace_sync_status.py tests/unit_tests/test_mcp_connector_registry.py -q — 27 passed.
• Earlier sandbox CLI validation fetched real workspace connections, asserted structured_content contains $prefab, and JSON-serialized the Prefab payload successfully.
• Goose Desktop evidence confirms the pie chart renders with Succeeded green, Canceled yellow, and No syncs grey, and that Ask for sync history renders the follow-up per-connection sync-history widget inline: feat(mcp): add workspace sync status UI tool #1043 (comment)

Link to Devin session: https://app.devin.ai/sessions/67a83acc838848baa6a5c06bf8b94744
Requested by: Aaron ("AJ") Steers (@aaronsteers)

Summary by CodeRabbit

• New Features

  • Added a workspace sync status dashboard summarizing recent sync outcomes, per-connection health, workspace metrics, searchable/filterable table, detail cards, and quick actions; available as interactive UI or bounded text-only output.

• Documentation

  • Clarified MCP UI tool guidance: capture evidence via MCPJam or Goose Desktop and verify server-side payload contract.

• Tests

  • Added unit tests validating dashboard summaries, UI content, actions, and text-only mode.

[devin-ai-integration]

Completed Goose Desktop runtime evidence for the pie-chart update.

Goose Desktop assertions

• Passed: Goose called show_workspace_sync_status through pyairbyte-local and rendered the workspace dashboard.
• Passed: The dashboard displayed the status pie/donut chart and legend with Succeeded green, Canceled yellow, and No syncs grey/slate.
• Passed: Selecting Gmail → Noop Destination (Gong Test) opened a row detail panel with a suggested show_connection_sync_history(connection_id="...") drill-down call.
• Passed: Clicking Ask for sync history triggered the follow-up drill-down and rendered the per-connection sync-history widget inline.

Evidence/privacy note

A full annotated Goose Desktop recording was captured in the Devin session and will be attached in the user-facing report. I did not embed the raw recording directly in this public PR comment because it contains sandbox workspace/connection IDs. The screenshot that shows the suggested tool call is redacted.

---

Devin session

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: f932afac-92ba-4f60-ba26-5f82a3ea81e0

📥 Commits

Reviewing files that changed from the base of the PR and between 0299eda and a1646dd.

📒 Files selected for processing (2)

• airbyte/mcp/interactive/_workspace_sync_status_ui.py
• tests/unit_tests/test_mcp_workspace_sync_status.py

🚧 Files skipped from review as they are similar to previous changes (1)

• airbyte/mcp/interactive/_workspace_sync_status_ui.py

---

📝 Walkthrough

Walkthrough

Adds show_workspace_sync_status, an MCP interactive tool that summarizes recent connection syncs, computes workspace metrics, and returns bounded text or a Prefab UI dashboard with metric cards, status pie chart, alerts, and a searchable connection table; exports the tool and adds unit tests and docs updates.

Changes

Workspace Sync Status Interactive Dashboard

Layer / File(s)	Summary
Constants and defaults airbyte/mcp/interactive/_workspace_sync_status_ui.py	Module constants for recent time windows, success-rate thresholds, and status-to-pie-chart label/color/variant mappings.
Data model and computed properties airbyte/mcp/interactive/_workspace_sync_status_ui.py	WorkspaceConnectionSyncStatus dataclass with per-connection metadata, latest/recent counts, computed is_problem and success_rate.
Core MCP tool & orchestration airbyte/mcp/interactive/_workspace_sync_status_ui.py	show_workspace_sync_status entry point: loads workspace, limits connections/jobs, summarizes connections, computes workspace metrics, builds bounded text previews, and returns metadata/raw_result.
Per-connection summarization airbyte/mcp/interactive/_workspace_sync_status_ui.py	_summarize_connection queries recent sync logs, selects latest displayed job, computes recent success/failure counts, aggregates records/bytes, detects running jobs, and suggests follow-up tool calls.
Helpers & metric aggregation airbyte/mcp/interactive/_workspace_sync_status_ui.py	_sync_status_value, _build_workspace_metric_summary, and _build_agent_text to normalize statuses, compute workspace-level metrics, and create bounded agent text outputs.
UI rendering and builders airbyte/mcp/interactive/_workspace_sync_status_ui.py	_build_workspace_sync_status_app constructs Prefab UI (metric cards, pie chart, alert, searchable table, detail card) alongside _connection_status_to_row, _status_pie_rows, _status_pie_chart_style, _status_pie_style, and _connection_detail.
Module export and API wiring airbyte/mcp/interactive/__init__.py	Imports and adds show_workspace_sync_status to __all__ to expose the tool via airbyte.mcp.interactive.
Tests: behavior and registry integration tests/unit_tests/test_mcp_workspace_sync_status.py, tests/unit_tests/test_mcp_connector_registry.py	New test module with synthetic doubles validates summaries, UI content, metadata and suppress_ui; existing registry test extended to assert visibility and module mapping for the new tool.
Docs: MCP UI development guidance AGENTS.md	Updates instructions to capture retesting evidence with “MCPJam or Goose Desktop” and to verify the server-side payload contract when recording human-reviewable evidence.

Sequence Diagram

sequenceDiagram
  participant Agent as Agent/Context
  participant Tool as show_workspace_sync_status
  participant CloudAPI as Airbyte Cloud API
  participant UIBuilder as Prefab UI Builder
  participant Result as ToolResult

  Agent->>Tool: call(workspace_id, max_connections, max_jobs_per_connection, recent_hours, agent_context, suppress_ui)
  Tool->>CloudAPI: load workspace & list connections(limit)
  CloudAPI-->>Tool: workspace + connection list
  loop per connection
    Tool->>CloudAPI: fetch recent sync logs(limit per connection, from_tail)
    CloudAPI-->>Tool: sync logs & job statuses
    Tool->>Tool: _summarize_connection -> WorkspaceConnectionSyncStatus
  end
  Tool->>Tool: _build_workspace_metric_summary
  Tool->>UIBuilder: _build_workspace_sync_status_app (metrics, pie, table, detail)
  UIBuilder-->>Tool: structured_content (Prefab view)
  Tool->>Result: return bounded text + structured_content (or text-only if suppress_ui)
  Result-->>Agent: ToolResult with metadata and optional UI

Loading

Estimated Code Review Effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly Related PRs

• airbytehq/PyAirbyte#1042: Adds or interacts with show_connection_sync_history, which the new tool references via “Ask for sync history” actions.
• airbytehq/PyAirbyte#1040: Prior work establishing interactive/UI-tool plumbing and registry visibility gating that this PR extends.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(mcp): add workspace sync status UI tool' accurately and concisely summarizes the main change—a new MCP interactive dashboard for workspace sync status.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch devin/1780460965-workspace-sync-status

---

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.}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

tests/unit_tests/test_mcp_workspace_sync_status.py (1)

88-204: ⚡ Quick win

Nice, thorough fixture-driven test. One optional gap: every fixture connection has exactly one completed job, so the running-job branch (running_job_id, latest_status == "running") and the suppress_ui=True path are never exercised — and those are exactly the branches tied to the latest_display_result question above. Would you consider adding a connection whose newest job is still running plus a suppress_ui=True assertion to lock in that behavior? wdyt?

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/unit_tests/test_mcp_workspace_sync_status.py` around lines 88 - 204,
Add a fixture connection whose newest sync result has status
JobStatusEnum.RUNNING and a non-null running_job_id so the running-job branch is
exercised: create another _ConnectionLike with a _SyncResultLike entry having
status=JobStatusEnum.RUNNING, start_time=now - timedelta(minutes=5) and set
running_job_id (or latest_status == "running" field) as needed; then call
show_workspace_sync_status as before and add an assertion that the returned
raw_result includes the suppress_ui flag (raw_result["suppress_ui"] is True) to
lock in the suppress-UI path behavior. Reference the existing test
helpers/_types: _ConnectionLike, _SyncResultLike, JobStatusEnum and the function
show_workspace_sync_status to locate where to add this new connection and
assertion.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@airbyte/mcp/interactive/_workspace_sync_status_ui.py`:
- Around line 266-276: _current logic in _summarize_connection always picks
latest_result over latest_completed_result making the completed fallback
unreachable; change latest_display_result to prefer latest_completed_result when
the newest run is not completed: detect the terminal/completed status of
latest_result (use _sync_status_value(latest_result) or the status enum/value
used elsewhere) and if it indicates an in-progress/non-final state, set
latest_display_result = latest_completed_result, otherwise keep latest_result;
update related derived vars (latest_status, latest_records, latest_bytes,
latest_start_time) to use the selected latest_display_result.
- Around line 503-515: Pie slice colors can drift because PieChart maps palette
slots to slice index, so when status_pie_rows filters out zero-count statuses
the remaining slices shift; fix by ensuring status_pie_rows always includes all
status categories with count 0 (so indices remain stable) before passing to
PieChart (or alternatively rebuild _STATUS_PIE_CHART_STYLE to compute palette
order based on the filtered status ordering), and apply the same change for the
other PieChart usage that builds status rows elsewhere; reference
status_pie_rows, PieChart, and _STATUS_PIE_CHART_STYLE when making the change.

---

Nitpick comments:
In `@tests/unit_tests/test_mcp_workspace_sync_status.py`:
- Around line 88-204: Add a fixture connection whose newest sync result has
status JobStatusEnum.RUNNING and a non-null running_job_id so the running-job
branch is exercised: create another _ConnectionLike with a _SyncResultLike entry
having status=JobStatusEnum.RUNNING, start_time=now - timedelta(minutes=5) and
set running_job_id (or latest_status == "running" field) as needed; then call
show_workspace_sync_status as before and add an assertion that the returned
raw_result includes the suppress_ui flag (raw_result["suppress_ui"] is True) to
lock in the suppress-UI path behavior. Reference the existing test
helpers/_types: _ConnectionLike, _SyncResultLike, JobStatusEnum and the function
show_workspace_sync_status to locate where to add this new connection and
assertion.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 8d164d95-4df3-4cb3-87b7-46647e8741c8

📥 Commits

Reviewing files that changed from the base of the PR and between da03d99 and ab6a231.

📒 Files selected for processing (5)

• AGENTS.md
• airbyte/mcp/interactive/__init__.py
• airbyte/mcp/interactive/_workspace_sync_status_ui.py
• tests/unit_tests/test_mcp_connector_registry.py
• tests/unit_tests/test_mcp_workspace_sync_status.py

[devin-ai-integration]

Goose Desktop test: 360px pie chart + status filtering

Ran Goose Desktop against the configured sandbox workspace with max_connections=5, max_jobs_per_connection=2, and recent_hours=24 to verify the latest chart/filter change.

Assertions:

• Passed: Goose called show_workspace_sync_status and rendered the workspace dashboard widget.
• Passed: the larger status pie chart rendered with Succeeded (2), Canceled (1), No syncs (2), and All filter controls.
• Passed: clicking Canceled (1) changed the active filter to Canceled, reduced the table to one row, and updated the selected detail card to a canceled connection.
• Passed: clicking All restored the five-row mixed-status table.

Caveat: an earlier larger invocation (max_connections=20, max_jobs_per_connection=10) left Goose waiting for content, so I used a smaller verified slice for the recorded interaction. The detailed recording/screenshots include sandbox identifiers, so I kept those artifacts in the Devin session instead of posting them publicly.

Devin session: https://app.devin.ai/sessions/67a83acc838848baa6a5c06bf8b94744

[devin-ai-integration]

Goose Desktop evidence: compact workspace layout

Ran Goose Desktop 1.36.0 against the local pyairbyte-local MCP stdio extension with real Devin sandbox data to verify the latest layout change.

• Passed: Goose invoked show_workspace_sync_status and rendered the Workspace sync status widget inline.
• Passed: The summary metric cards rendered on the left while the 360px status pie chart rendered on the right in the same top band.
• Passed: The top-right chart section showed All, Succeeded (2), Canceled (1), and No syncs (2) filter controls.
• Passed: Clicking Canceled (1) updated the active filter and reduced the table/detail to one canceled connection.
• Passed: Clicking All restored five rows with mixed succeeded, canceled, and no-sync statuses.

Caveat: the latest github-code-quality update is coverage-only: this branch is at 67% coverage vs 65% on main; no concrete behavioral regression was reported.

---

Devin session