Add workflow update tools

Author: backslash-f

README.md

@@ -18,6 +18,10 @@ Minimal MCP server for discovering Xcode Cloud products and workflows, then retr
 | 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: ...` |
+| Enable or disable a workflow | `set_workflow_enabled` | "Disable workflow `abc123` while we are testing new settings." | `operation.type: set_workflow_enabled`, `workflow.general.isEnabled: false` |
+| Update name, description, or clean mode | `update_workflow_general` | "Rename workflow `abc123` to `Feature Branch v2` and adjust its description." | `changedFields: [name, description]`, updated `workflow.general` |
+| Update start conditions explicitly | `update_workflow_start_conditions` | "Change workflow `abc123` so pull-request builds no longer auto-cancel." | updated `workflow.startConditions.pullRequest.autoCancel: false` |
+| Replace the workflow action list | `update_workflow_actions` | "Remove the archive action from workflow `abc123`, then add it back once the experiment is done." | `actionCount: 4` after removal, then `actionCount: 5` after restore |
 | 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: [...]` |
@@ -77,6 +81,10 @@ codex mcp add xcode-cloud \
 - `list_workflows(productId, limit?)`
 - `get_workflow_details(workflowId)`
 - `list_build_runs(workflowId, limit?, status?)`
+- `set_workflow_enabled(workflowId, enabled)`
+- `update_workflow_general(workflowId, name?, description?, clean?)`
+- `update_workflow_start_conditions(workflowId, branchStartCondition?, manualBranchStartCondition?, pullRequestStartCondition?, manualPullRequestStartCondition?, scheduledStartCondition?, tagStartCondition?, manualTagStartCondition?)`
+- `update_workflow_actions(workflowId, actions)`
 - `get_build_issues(buildRunId? workflowId? buildNumber? buildSelector?)`
 - `get_build_logs(buildRunId? workflowId? buildNumber? buildSelector?, maxCharacters?)`
 - `materialize_build_logs(buildRunId? workflowId? buildNumber? buildSelector?)`
@@ -145,6 +153,10 @@ List the workflows for product def456 and then summarize the latest build.
 Show me the full workflow details for workflow abc123, including environment, start conditions, actions, and whether it is enabled.
 ```
 
+```text
+Disable workflow abc123, remove the archive action, then restore the original action list after the experiment.
+```
+
 ## Workflow Details Behavior
 
 `get_workflow_details` returns the live workflow configuration exposed by App Store Connect, grouped into:
@@ -161,6 +173,21 @@ Notes:
 - `actions` includes action type, scheme, platform, destination, required-to-pass state, and test-plan details when present.
 - `postActions` is currently returned as an empty array with a note because the App Store Connect workflow payload does not expose separate post-actions in the observed API response.
 
+## Workflow Update Behavior
+
+The workflow update tools are intentionally explicit:
+
+- `set_workflow_enabled` only toggles `isEnabled`
+- `update_workflow_general` only changes `name`, `description`, and `clean`
+- `update_workflow_start_conditions` only changes the start-condition objects you pass
+- `update_workflow_actions` replaces the full `actions` array, so callers should fetch the current workflow first and then send the final desired action list
+
+Important restriction:
+
+- if the workflow has `Restrict Editing` enabled in Xcode Cloud, edits can fail even when the App Store Connect API key has `App Manager` access
+- for MCP edits to work reliably, disable the `Restrict Editing` checkbox for that workflow before using the write tools
+- if Apple still rejects the request after that, use a stronger API key role such as `Admin`
+
 ## Local Development
 
 Install dependencies:

src/api/base-client.ts

@@ -36,6 +36,26 @@ export class BaseAPIClient {
     return this.request<TData>(url.toString());
   }
 
+  protected async patch<TData, TBody>(
+    path: string,
+    body: TBody,
+  ): Promise<APIResponse<TData>>;
+  protected async patch<TData, TBody, TIncluded>(
+    path: string,
+    body: TBody,
+  ): Promise<APIResponse<TData, TIncluded>>;
+  protected async patch<TData, TBody, TIncluded>(
+    path: string,
+    body: TBody,
+  ): Promise<APIResponse<TData, TIncluded>> {
+    const url = new URL(path, this.baseUrl);
+
+    return this.request<TData, TIncluded>(url.toString(), {
+      method: 'PATCH',
+      body: JSON.stringify(body),
+    });
+  }
+
   protected async download(url: string): Promise<Uint8Array> {
     const response = await fetch(url, {
       headers: {
@@ -54,9 +74,12 @@ export class BaseAPIClient {
 
   private async request<TData, TIncluded = never>(
     url: string,
+    init?: RequestInit,
   ): Promise<APIResponse<TData, TIncluded>> {
     const response = await fetch(url, {
+      ...init,
       headers: {
+        ...(init?.headers ?? {}),
         Authorization: `Bearer ${this.auth.getToken()}`,
         'Content-Type': 'application/json',
       },

src/api/resources/workflows.ts

@@ -1,5 +1,11 @@
 import { BaseAPIClient } from '../base-client.js';
-import type { CiWorkflow, WorkflowIncludedResource } from '../types.js';
+import type {
+  CiWorkflow,
+  CiWorkflowAction,
+  WorkflowIncludedResource,
+} from '../types.js';
+
+type WorkflowAttributeUpdate = Partial<CiWorkflow['attributes']>;
 
 /**
  * Workflow endpoints.
@@ -40,4 +46,80 @@ export class WorkflowsClient extends BaseAPIClient {
       included: response.included ?? [],
     };
   }
+
+  /**
+   * Update one workflow.
+   */
+  async updateById(
+    workflowId: string,
+    attributes: WorkflowAttributeUpdate,
+  ): Promise<CiWorkflow> {
+    const response = await this.patch<
+      CiWorkflow,
+      {
+        data: {
+          type: 'ciWorkflows';
+          id: string;
+          attributes: WorkflowAttributeUpdate;
+        };
+      }
+    >(`/v1/ciWorkflows/${workflowId}`, {
+      data: {
+        type: 'ciWorkflows',
+        id: workflowId,
+        attributes,
+      },
+    });
+
+    return response.data;
+  }
+
+  /**
+   * Enable or disable one workflow.
+   */
+  async setEnabled(workflowId: string, isEnabled: boolean): Promise<CiWorkflow> {
+    return this.updateById(workflowId, { isEnabled });
+  }
+
+  /**
+   * Update general workflow fields.
+   */
+  async updateGeneral(
+    workflowId: string,
+    attributes: Pick<
+      WorkflowAttributeUpdate,
+      'clean' | 'description' | 'name'
+    >,
+  ): Promise<CiWorkflow> {
+    return this.updateById(workflowId, attributes);
+  }
+
+  /**
+   * Update workflow start conditions.
+   */
+  async updateStartConditions(
+    workflowId: string,
+    attributes: Pick<
+      WorkflowAttributeUpdate,
+      | 'branchStartCondition'
+      | 'manualBranchStartCondition'
+      | 'manualPullRequestStartCondition'
+      | 'manualTagStartCondition'
+      | 'pullRequestStartCondition'
+      | 'scheduledStartCondition'
+      | 'tagStartCondition'
+    >,
+  ): Promise<CiWorkflow> {
+    return this.updateById(workflowId, attributes);
+  }
+
+  /**
+   * Replace workflow actions explicitly.
+   */
+  async updateActions(
+    workflowId: string,
+    actions: CiWorkflowAction[],
+  ): Promise<CiWorkflow> {
+    return this.updateById(workflowId, { actions });
+  }
 }

src/api/types.ts

@@ -54,14 +54,14 @@ export interface CiWorkflow {
     isLockedForEditing?: boolean;
     clean: boolean;
     containerFilePath: string;
-    lastModifiedDate: string;
-    branchStartCondition?: Record<string, unknown>;
-    manualBranchStartCondition?: Record<string, unknown>;
-    pullRequestStartCondition?: Record<string, unknown>;
-    manualPullRequestStartCondition?: Record<string, unknown>;
-    tagStartCondition?: Record<string, unknown>;
-    manualTagStartCondition?: Record<string, unknown>;
-    scheduledStartCondition?: Record<string, unknown>;
+    lastModifiedDate: string | null;
+    branchStartCondition?: Record<string, unknown> | null;
+    manualBranchStartCondition?: Record<string, unknown> | null;
+    pullRequestStartCondition?: Record<string, unknown> | null;
+    manualPullRequestStartCondition?: Record<string, unknown> | null;
+    tagStartCondition?: Record<string, unknown> | null;
+    manualTagStartCondition?: Record<string, unknown> | null;
+    scheduledStartCondition?: Record<string, unknown> | null;
     actions?: CiWorkflowAction[];
   };
   relationships?: {

src/tools/discovery.ts

@@ -1,15 +1,9 @@
 import { z } from 'zod';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { AppStoreConnectClient } from '../api/client.js';
-import type {
-  CiMacOsVersion,
-  CiWorkflowAction,
-  CiXcodeVersion,
-  ScmRepository,
-  WorkflowIncludedResource,
-} from '../api/types.js';
 import { parseIdentifier } from '../utils/identifiers.js';
 import { errorResponse, jsonResponse } from '../utils/tool-response.js';
+import { formatWorkflowDetailsResponse } from '../utils/workflow-details.js';
 
 /**
  * Register discovery tools.
@@ -91,117 +85,10 @@ export function registerDiscoveryTools(
       try {
         const workflowIdentifier = parseIdentifier(workflowId, 'workflow');
         const { workflow, included } = await client.workflows.getById(workflowIdentifier);
-        const repository = findIncludedResource<ScmRepository>(
-          included,
-          workflow.relationships?.repository?.data?.id,
-          'scmRepositories',
-        );
-        const xcodeVersion = findIncludedResource<CiXcodeVersion>(
-          included,
-          workflow.relationships?.xcodeVersion?.data?.id,
-          'ciXcodeVersions',
-        );
-        const macOsVersion = findIncludedResource<CiMacOsVersion>(
-          included,
-          workflow.relationships?.macOsVersion?.data?.id,
-          'ciMacOsVersions',
-        );
-        const actions = workflow.attributes.actions ?? [];
-
-        return jsonResponse({
-          workflow: {
-            id: workflow.id,
-            general: {
-              name: workflow.attributes.name,
-              description: workflow.attributes.description ?? null,
-              isEnabled: workflow.attributes.isEnabled,
-              isLockedForEditing: workflow.attributes.isLockedForEditing ?? null,
-              clean: workflow.attributes.clean,
-              containerFilePath: workflow.attributes.containerFilePath,
-              lastModifiedDate: workflow.attributes.lastModifiedDate,
-            },
-            environment: {
-              repository: repository
-                ? {
-                    id: repository.id,
-                    ownerName: repository.attributes.ownerName ?? null,
-                    repositoryName: repository.attributes.repositoryName ?? null,
-                    scmProvider: repository.attributes.scmProvider ?? null,
-                    defaultBranch: repository.attributes.defaultBranch ?? null,
-                    httpCloneUrl: repository.attributes.httpCloneUrl ?? null,
-                    sshCloneUrl: repository.attributes.sshCloneUrl ?? null,
-                  }
-                : null,
-              xcodeVersion: xcodeVersion
-                ? {
-                    id: xcodeVersion.id,
-                    name: xcodeVersion.attributes.name ?? null,
-                    version: xcodeVersion.attributes.version ?? null,
-                    supportedTestDestinations:
-                      xcodeVersion.attributes.testDestinations?.length ?? 0,
-                  }
-                : null,
-              macOsVersion: macOsVersion
-                ? {
-                    id: macOsVersion.id,
-                    name: macOsVersion.attributes.name ?? null,
-                    version: macOsVersion.attributes.version ?? null,
-                  }
-                : null,
-            },
-            startConditions: {
-              branch: workflow.attributes.branchStartCondition ?? null,
-              manualBranch: workflow.attributes.manualBranchStartCondition ?? null,
-              pullRequest: workflow.attributes.pullRequestStartCondition ?? null,
-              manualPullRequest:
-                workflow.attributes.manualPullRequestStartCondition ?? null,
-              scheduled: workflow.attributes.scheduledStartCondition ?? null,
-              tag: workflow.attributes.tagStartCondition ?? null,
-              manualTag: workflow.attributes.manualTagStartCondition ?? null,
-            },
-            actions: actions.map(formatWorkflowAction),
-            postActions: [],
-            postActionsNote:
-              'The App Store Connect workflow payload did not expose separate post-actions, so this field is empty unless Apple adds that data.',
-          },
-        });
+        return jsonResponse(formatWorkflowDetailsResponse(workflow, included));
       } catch (error) {
         return errorResponse(error);
       }
     },
   );
 }
-
-function findIncludedResource<TResource extends WorkflowIncludedResource>(
-  resources: WorkflowIncludedResource[],
-  identifier: string | undefined,
-  type: TResource['type'],
-): TResource | undefined {
-  if (!identifier) {
-    return undefined;
-  }
-
-  return resources.find(
-    (resource): resource is TResource =>
-      resource.id === identifier && resource.type === type,
-  );
-}
-
-function formatWorkflowAction(action: CiWorkflowAction) {
-  return {
-    name: action.name,
-    actionType: action.actionType,
-    platform: action.platform ?? null,
-    scheme: action.scheme ?? null,
-    destination: action.destination ?? null,
-    buildDistributionAudience: action.buildDistributionAudience ?? null,
-    isRequiredToPass: action.isRequiredToPass ?? null,
-    testConfiguration: action.testConfiguration
-      ? {
-          kind: action.testConfiguration.kind ?? null,
-          testPlanName: action.testConfiguration.testPlanName ?? null,
-          testDestinations: action.testConfiguration.testDestinations ?? [],
-        }
-      : null,
-  };
-}