Refactor workflow runs list to use MCP tool calls

[jtcorbett]

TL;DR

Refactored the workflow runs listing command to use MCP tool calls instead of direct API client calls.

What changed?

• Replaced the direct API client approach with MCP tool calls to retrieve workflow runs
• Added a new _list_workflow_runs_async function that uses the MCP App and gen_client to communicate with the server
• Improved status filtering and display logic to work with both object and dictionary response formats
• Enhanced error handling and formatting of workflow run information
• Updated the workflow data processing to handle different response formats more robustly

How to test?

# List workflow runs from a server
mcp-agent cloud workflows runs <server_id_or_url>

# Filter by status
mcp-agent cloud workflows runs <server_id_or_url> --status running

# Limit results
mcp-agent cloud workflows runs <server_id_or_url> --limit 10

# Change output format
mcp-agent cloud workflows runs <server_id_or_url> --format json

Summary by CodeRabbit

• New Features

  • Add status filtering for workflow runs with common aliases (e.g., timeout → timed_out).
  • Add an optional limit to constrain the number of results.
  • Allow server selection via direct URL or config-based server ID.

• Refactor

  • Text output updated: columns show Workflow ID, Name, Status, Run ID, Created (Principal removed).
  • Consistent JSON/YAML/Text rendering and improved date formatting.

• Bug Fixes

  • Clearer error handling when server info or workflow data is missing.

[coderabbitai]

Caution

Review failed

The pull request is closed.

Walkthrough

Implements an async CLI workflow-runs listing that resolves server URL from direct input or config, calls an embedded MCPApp tool client to retrieve runs, parses and filters results by status and limit, and prints json/yaml/text; also removes workflow models from the MCP App API client and adds log_entries_list.

Changes

Cohort / File(s)	Summary
Workflows Runs CLI src/mcp_agent/cli/cloud/commands/workflows/runs/main.py	Replace decorator-based error handling with explicit try/except; add run_async-driven _list_workflow_runs_async; resolve server via direct URL or config (appServerInfo.serverUrl); register workflow_server (SSE) on an MCPApp instance and call generated client tool workflows-runs-list; parse result content (string → JSON, default []); add status alias mapping _get_status_filter and predicate _matches_status; apply optional limit; add _print_workflows_text that accepts dicts/objects, removes Principal column, updates Status display and created_at formatting; add helpers and unify JSON/YAML output conversion.
MCP App API client src/mcp_agent/cli/mcp_app/api_client.py	Remove workflow-related public models and API: WorkflowExecutionStatus, WorkflowInfo, ListWorkflowsResponse, and list_workflows method; remove Enum import. Add convenience property log_entries_list to GetAppLogsResponse returning self.logEntries or [].

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant CLI as CLI:list_workflow_runs
  participant Runner as run_async
  participant Impl as _list_workflow_runs_async
  participant Resolver as ServerResolver
  participant App as MCPApp
  participant Client as GeneratedClient
  participant Server as WorkflowServer

  User->>CLI: list_workflow_runs --server/--server-id --status --limit --format
  CLI->>Runner: run_async(_list_workflow_runs_async)
  Runner->>Impl: invoke/await
  Impl->>Resolver: resolve server-id or accept URL
  Resolver-->>Impl: serverUrl or raise CLIError

  Impl->>App: init MCPApp, register workflow_server (SSE)
  Impl->>Client: call tool "workflows-runs-list"
  Client->>Server: request runs
  Server-->>Client: runs response
  Client-->>Impl: result.content[0].text
  Impl->>Impl: parse text → JSON (or default [])
  Impl->>Impl: apply _get_status_filter / _matches_status
  Impl->>Impl: apply limit
  Impl-->>CLI: formatted output (json|yaml|text)
  CLI-->>User: printed results

  note over Impl: On errors -> raise CLIError (handled by CLI)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• Refactor workflow runs list to use MCP tool calls #439 — Similar refactor of workflows/runs/main.py to use async MCP tool calls, status filtering, and helpers.
• add workflow list and runs #430 — Updates the same CLI command with async listing, output formatting, and helper functions; likely part of the same refactor.

Suggested reviewers

• rholinshead
• saqadri

Poem

I hop and hum: async calls leap,
Servers answered from burrows deep.
Filters sift and outputs gleam,
JSON, YAML—choose your stream.
Nibble logs, then off I bound, tail a-sweep. 🐰✨

Tip

👮 Agentic pre-merge checks are now available in preview!

Pro plan users can now enable pre-merge checks in their settings to enforce checklists before merging PRs.

• Built-in checks – Quickly apply ready-made checks to enforce title conventions, require pull request descriptions that follow templates, validate linked issues for compliance, and more.
• Custom agentic checks – Define your own rules using CodeRabbit’s advanced agentic capabilities to enforce organization-specific policies and workflows. For example, you can instruct CodeRabbit’s agent to verify that API documentation is updated whenever API schema files are modified in a PR. Note: Upto 5 custom checks are currently allowed during the preview period. Pricing for this feature will be announced in a few weeks.

Example:

reviews:
  pre_merge_checks:
    custom_checks:
      - name: "Undocumented Breaking Changes"
        mode: "warning"
        instructions: |
          Pass/fail criteria: All breaking changes to public APIs, CLI flags, environment variables, configuration keys, database schemas, or HTTP/GraphQL endpoints must be documented in the "Breaking Change" section of the PR description and in CHANGELOG.md. Exclude purely internal or private changes (e.g., code not exported from package entry points or explicitly marked as internal).

Please share your feedback with us on this Discord post.

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9f12b3a and 1cc42d1.

📒 Files selected for processing (2)

• src/mcp_agent/cli/cloud/commands/workflows/runs/main.py (5 hunks)
• src/mcp_agent/cli/mcp_app/api_client.py (0 hunks)

✨ Finishing Touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch Refactor_workflow_runs_list_to_use_MCP_tool_calls

---

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

[jtcorbett]

• Update workflows commands UI to be more consistant with the rest of the CLI #432
• Refactor workflow runs list to use MCP tool calls #439 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (8)

src/mcp_agent/cli/cloud/commands/workflows/runs/main.py (8)

50-52: Normalize SSE URL to avoid double slashes and '/sse/sse' edge cases.

Using rstrip prevents '...//sse' and handles trailing '/sse/' cleanly.

-            sse_url = (
-                f"{server_url}/sse" if not server_url.endswith("/sse") else server_url
-            )
+            base_url = server_url.rstrip("/")
+            sse_url = base_url if base_url.endswith("/sse") else f"{base_url}/sse"

---

53-58: Set sane timeouts and least-privilege tool access for the transient server entry.

Prevents hanging on dead SSE streams and avoids exposing unnecessary tools.

             context.server_registry.registry["workflow_server"] = MCPServerSettings(
                 name="workflow_server",
                 description=f"Deployed MCP server {server_url}",
                 url=sse_url,
                 transport="sse",
+                read_timeout_seconds=30,
+                http_timeout_seconds=10,
+                allowed_tools={"workflows-runs-list"},
             )

---

77-78: Validate that --limit is a positive integer.

Avoids surprising slices when negative (tail of list) or zero (empty).

-                if limit:
-                    workflows = workflows[:limit]
+                if limit is not None:
+                    if limit <= 0:
+                        raise CLIError("--limit must be a positive integer")
+                    workflows = workflows[:limit]

---

85-85: Pass the normalized status to the printer.

Keeps the “Filtered by status” display consistent with the filter actually applied.

-                    _print_workflows_text(workflows, status, server_id_or_url)
+                    _print_workflows_text(
+                        workflows,
+                        status_filter if status else None,
+                        server_id_or_url,
+                    )

---

123-136: Add common status aliases (success/succeeded/complete → completed).

Improves UX parity with typical user input.

     status_map = {
         "running": "running",
         "failed": "failed",
         "timed_out": "timed_out",
         "timeout": "timed_out",  # alias
         "canceled": "canceled",
         "cancelled": "canceled",  # alias
         "terminated": "terminated",
         "completed": "completed",
+        "success": "completed",
+        "succeeded": "completed",
+        "complete": "completed",
         "continued": "continued",
         "continued_as_new": "continued",
     }

---

146-151: Prefer exact match (with a safe fallback) for status matching to reduce false positives.

Substring matching alone can misclassify unexpected values.

-    workflow_status = workflow.get("execution_status", "")
-    if isinstance(workflow_status, str):
-        return status_filter.lower() in workflow_status.lower()
+    workflow_status = workflow.get("execution_status", "")
+    if isinstance(workflow_status, str):
+        status_val = workflow_status.lower()
+        target = status_filter.lower()
+        return status_val == target or status_val.endswith(target)
     return False

---

270-271: Rich color name: use orange1 instead of orange.

'orange' isn't a standard Rich color name; 'orange1' is.

-    elif "timeout" in status_str or "timed_out" in status_str:
-        return "[orange]⏰ Timed Out[/orange]"
+    elif "timeout" in status_str or "timed_out" in status_str:
+        return "[orange1]⏰ Timed Out[/orange1]"

---

233-236: Normalize created_at for dict inputs to ensure consistent JSON/YAML output.

Prevents non-serializable datetime objects sneaking into dict-based paths.

-    if isinstance(workflow, dict):
-        return workflow
+    if isinstance(workflow, dict):
+        w = dict(workflow)
+        ca = w.get("created_at")
+        if hasattr(ca, "isoformat"):
+            w["created_at"] = ca.isoformat()
+        return w

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 2666061 and 9f12b3a.

📒 Files selected for processing (1)

• src/mcp_agent/cli/cloud/commands/workflows/runs/main.py (5 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/mcp_agent/cli/cloud/commands/workflows/runs/main.py (5)

src/mcp_agent/cli/core/utils.py (1)

• run_async (16-31)

src/mcp_agent/cli/exceptions.py (1)

• CLIError (4-9)

src/mcp_agent/config.py (2)

• MCPServerSettings (52-113)
• LoggerSettings (535-580)

src/mcp_agent/mcp/gen_client.py (1)

• gen_client (16-41)

src/mcp_agent/cli/cloud/commands/utils.py (3)

• setup_authenticated_client (18-32)
• validate_output_format (35-48)
• resolve_server (51-77)

[saqadri]

Looks like our WorkflowExecutionStatus got nuked? Can you restore?

[saqadri]

One important comment, rest lgtm

[jtcorbett]

Merge activity

• Sep 9, 7:02 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Sep 9, 7:03 PM UTC: @jtcorbett merged this pull request with Graphite.

[graphite-app]

This line contains a potential bug due to redundant attribute access. The expression calls getattr(workflow, "created_at", None) twice, which is inefficient and could cause errors if the first call returns a falsy value but the attribute doesn't exist.

Consider refactoring to:

created_at_value = getattr(workflow, "created_at", None)
"created_at": created_at_value.isoformat() if created_at_value and hasattr(created_at_value, 'isoformat') else None,

This approach safely handles all cases: when the attribute doesn't exist, when it exists but is None/falsy, and when it exists and has an isoformat method.

Suggested change

	"created_at": getattr(workflow, "created_at", None).isoformat() if getattr(workflow, "created_at", None) else None,
	"created_at": created_at_value.isoformat() if (created_at_value := getattr(workflow, "created_at", None)) and hasattr(created_at_value, 'isoformat') else None,

Spotted by Diamond



Is this helpful? React 👍 or 👎 to let us know.

[graphite-app]

The current status matching logic has a potential issue with false positives. Using status_filter.lower() in workflow_status.lower() performs substring matching, which means a status filter of running would incorrectly match statuses like not_running_anymore.

Consider using exact matching instead:

# More precise matching options:
return workflow_status.lower() == status_filter.lower()

# Or if matching against enum-style values:
return workflow_status.lower().endswith(status_filter.lower())

This would ensure that only workflows with the exact requested status are returned to the user.

Suggested change

	workflow_status = workflow.get("execution_status", "")
	if isinstance(workflow_status, str):
	return status_filter.lower() in workflow_status.lower()
	return False
	workflow_status = workflow.get("execution_status", "")
	if isinstance(workflow_status, str):
	return workflow_status.lower() == status_filter.lower()
	return False

Spotted by Diamond



Is this helpful? React 👍 or 👎 to let us know.