Add running build filters

Author: backslash-f

README.md

@@ -12,21 +12,24 @@ Minimal MCP server for discovering Xcode Cloud products and workflows, then retr
 
 ## Features
 
-- Discover Xcode Cloud products with `list_products`.
-- Discover workflows for a product with `list_workflows`.
-- Retrieve workflow configuration with `get_workflow_details`.
-- List recent workflow runs with `list_build_runs`.
-- Retrieve build issue counts with `get_build_issues`.
-- Retrieve and summarize text-like build logs with `get_build_logs`.
-- Materialize build logs into a local temp directory with `materialize_build_logs`.
-- Save extracted logs to a local temporary directory and return file paths for agent-side inspection.
-- Retrieve test summaries with `get_test_results`.
-- Retrieve only detected failed tests with `get_failed_tests`.
-- Retrieve screenshots, videos, result bundles, and test products with `get_test_artifacts`.
-- Clean up saved local log directories with `cleanup_saved_logs`.
+| Feature | Tool(s) | Example use | Example return |
+| --- | --- | --- | --- |
+| Discover products | `list_products` | "Show me the Xcode Cloud products available in this account." | `Demo App`, `productType: APP`, `createdDate: 2026-03-30T10:00:00Z` |
+| Discover workflows | `list_workflows` | "List the workflows for product `def456`." | `Feature Branch`, `description`, `isEnabled: true`, `containerFilePath: Chauffeur.xcodeproj` |
+| Inspect workflow configuration | `get_workflow_details` | "Show me the full workflow details for `abc123`, including environment and actions." | `general`, `environment`, `startConditions`, `actions`, `postActions` |
+| Monitor running or recent builds | `list_build_runs` | "Show me the running builds for workflow `abc123` so I can monitor them." | `number: 93`, `executionProgress: RUNNING`, `completionStatus: null`, `startedDate: ...` |
+| See build health quickly | `get_build_issues` | "What went wrong in the latest failing build for workflow `abc123`?" | `issueCounts: { errors: 1, testFailures: 3, warnings: 2 }` |
+| Read compact build log summaries | `get_build_logs` | "Retrieve logs of build `81` and summarize the failure." | `failedTests`, `highlights`, `excerpt`, `savedLogsDirectory` |
+| Materialize logs for local grep | `materialize_build_logs` | "Download the logs for build `81` so I can grep them locally." | `savedLogsDirectory: /var/folders/...`, `savedLogs: [...]` |
+| Summarize test outcomes | `get_test_results` | "Summarize the test results for the latest failing build." | `testFailures`, `issueCounts`, `summary` |
+| Jump straight to failed tests | `get_failed_tests` | "What tests failed in build `81`?" | `displayExpiryDateReturnsFormattedDateWhenExpiryDateExists()`, assertion message, saved log paths |
+| Retrieve UI test artifacts | `get_test_artifacts` | "Show me the screenshots and videos from the latest failing UI test run." | `screenshots`, `videos`, `resultBundles`, `downloadUrl` |
+| Clean up local temp files | `cleanup_saved_logs` | "Remove saved logs older than 24 hours." | `removedDirectories: [...]`, `retainedDirectories: [...]` |
 
 Build lookup is workflow-scoped. Retrieval tools accept a direct `buildRunId`, or a `workflowId` plus `buildNumber`, or a `workflowId` plus `buildSelector: "latest" | "latestFailing"`.
 
+`list_build_runs` also supports `status: "all" | "failed" | "succeeded" | "running" | "pending"`, so agents can poll active workflows without post-processing every run locally.
+
 ## Requirements
 
 - Node.js `20+`

src/tools/build-runs.ts

@@ -9,7 +9,7 @@ import {
 } from '../utils/build-locator.js';
 import { errorResponse, jsonResponse } from '../utils/tool-response.js';
 
-type BuildRunStatusFilter = 'all' | 'failed' | 'succeeded';
+type BuildRunStatusFilter = 'all' | 'failed' | 'pending' | 'running' | 'succeeded';
 
 /**
  * Register build run listing tools.
@@ -26,7 +26,7 @@ export function registerBuildRunTools(
       inputSchema: {
         workflowId: z.string(),
         limit: z.number().int().positive().max(200).optional(),
-        status: z.enum(['all', 'failed', 'succeeded']).optional(),
+        status: z.enum(['all', 'failed', 'pending', 'running', 'succeeded']).optional(),
       },
     },
     async ({
@@ -84,6 +84,18 @@ function filterBuildRuns(
     );
   }
 
+  if (status === 'pending') {
+    return buildRuns.filter(
+      (buildRun) => buildRun.attributes.executionProgress === 'PENDING',
+    );
+  }
+
+  if (status === 'running') {
+    return buildRuns.filter(
+      (buildRun) => buildRun.attributes.executionProgress === 'RUNNING',
+    );
+  }
+
   return buildRuns.filter(
     (buildRun) => buildRun.attributes.completionStatus === 'SUCCEEDED',
   );

tests/tools.test.ts

@@ -164,6 +164,57 @@ test('registered tools expose product, workflow, and build data', async () => {
     },
   };
 
+  const runningBuildRun: CiBuildRun = {
+    id: 'build-2',
+    type: 'ciBuildRuns',
+    attributes: {
+      number: 43,
+      createdDate: '2026-03-30T12:30:00Z',
+      startedDate: '2026-03-30T12:31:00Z',
+      executionProgress: 'RUNNING',
+      isPullRequestBuild: true,
+      issueCounts: {
+        analyzerWarnings: 0,
+        errors: 0,
+        testFailures: 0,
+        warnings: 0,
+      },
+    },
+    relationships: {
+      workflow: {
+        data: {
+          type: 'ciWorkflows',
+          id: 'workflow-1',
+        },
+      },
+    },
+  };
+
+  const pendingBuildRun: CiBuildRun = {
+    id: 'build-3',
+    type: 'ciBuildRuns',
+    attributes: {
+      number: 44,
+      createdDate: '2026-03-30T12:45:00Z',
+      executionProgress: 'PENDING',
+      isPullRequestBuild: true,
+      issueCounts: {
+        analyzerWarnings: 0,
+        errors: 0,
+        testFailures: 0,
+        warnings: 0,
+      },
+    },
+    relationships: {
+      workflow: {
+        data: {
+          type: 'ciWorkflows',
+          id: 'workflow-1',
+        },
+      },
+    },
+  };
+
   const logArtifact = createArtifact('artifact-1', 'build.log', 'LOG');
   const screenshotArtifact = createArtifact(
     'artifact-2',
@@ -195,7 +246,7 @@ test('registered tools expose product, workflow, and build data', async () => {
     },
     builds: {
       getById: async () => buildRun,
-      listForWorkflow: async () => [buildRun],
+      listForWorkflow: async () => [buildRun, runningBuildRun, pendingBuildRun],
       getActions: async () => [buildAction],
     },
     artifacts: {
@@ -240,6 +291,12 @@ test('registered tools expose product, workflow, and build data', async () => {
   const buildsPayload = parsePayload(
     await listBuildRuns!({ workflowId: 'workflow-1' }),
   );
+  const runningBuildsPayload = parsePayload(
+    await listBuildRuns!({ workflowId: 'workflow-1', status: 'running' }),
+  );
+  const pendingBuildsPayload = parsePayload(
+    await listBuildRuns!({ workflowId: 'workflow-1', status: 'pending' }),
+  );
   const workflowDetailsPayload = parsePayload(
     await getWorkflowDetails!({ workflowId: 'workflow-1' }),
   );
@@ -267,7 +324,11 @@ test('registered tools expose product, workflow, and build data', async () => {
   const cleanupPayload = parsePayload(await cleanupSavedLogs!({ maxAgeHours: 1 }));
 
   assert.equal(productsPayload.products[0].id, 'product-1');
-  assert.equal(buildsPayload.buildRuns[0].number, 42);
+  assert.equal(buildsPayload.buildRuns[0].number, 44);
+  assert.equal(runningBuildsPayload.buildRuns.length, 1);
+  assert.equal(runningBuildsPayload.buildRuns[0].executionProgress, 'RUNNING');
+  assert.equal(pendingBuildsPayload.buildRuns.length, 1);
+  assert.equal(pendingBuildsPayload.buildRuns[0].executionProgress, 'PENDING');
   assert.equal(workflowDetailsPayload.workflow.general.isEnabled, true);
   assert.equal(
     workflowDetailsPayload.workflow.environment.repository.repositoryName,