feat: add customWorkflows support in config

Allow users to define named workflow groups in config.yaml mapping to
explicit tool lists, then reference them from enabledWorkflows like
built-in workflows.

- New customWorkflows config field (schema, parsing, normalization)
- Tool registry resolves custom workflow tool names to manifest IDs
- Conflict detection for built-in workflow name collisions
- Unknown tool names logged as warnings and skipped

Author: cameroncooke

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- Added support for `customWorkflows` in `.xcodebuildmcp/config.yaml`, so user-defined workflow names can be referenced from `enabledWorkflows` and mapped to explicit tool lists.
+
 ### Fixed
 
 - Fixed `swift_package_build`, `swift_package_test`, and `swift_package_clean` swallowing compiler diagnostics on failure by treating empty stderr as falsy, so stdout diagnostics are included in the error response ([#243](https://github.com/getsentry/XcodeBuildMCP/issues/243)).
@@ -309,4 +313,3 @@ Please note that the UI automation features are an early preview and currently i
 - Initial release of XcodeBuildMCP
 - Basic support for building iOS and macOS applications
 
-

config.example.yaml

@@ -1,5 +1,10 @@
 schemaVersion: 1
 enabledWorkflows: ['simulator', 'ui-automation', 'debugging']
+customWorkflows:
+  my-workflow:
+    - build_run_sim
+    - record_sim_video
+    - screenshot
 experimentalWorkflowDiscovery: false
 disableSessionDefaults: false
 incrementalBuildsEnabled: false

docs/CONFIGURATION.md

@@ -39,6 +39,11 @@ schemaVersion: 1
 
 # Workflow selection
 enabledWorkflows: ["simulator", "ui-automation", "debugging"]
+customWorkflows:
+  my-workflow:
+    - build_run_sim
+    - record_sim_video
+    - screenshot
 experimentalWorkflowDiscovery: false
 
 # Session defaults
@@ -147,6 +152,25 @@ enabledWorkflows: ["simulator", "ui-automation", "debugging"]
 
 See [TOOLS.md](TOOLS.md) for available workflows and their tools.
 
+### Custom workflows
+
+You can define your own workflow names in config and reference them from `enabledWorkflows`.
+Each custom workflow is a list of tool names (MCP names), and only those tools are loaded for that workflow.
+
+```yaml
+enabledWorkflows: ["my-workflow"]
+customWorkflows:
+  my-workflow:
+    - build_run_sim
+    - record_sim_video
+    - screenshot
+```
+
+Notes:
+- Built-in implicit workflows are unchanged. Session-management tools are still auto-included, and the doctor workflow is still auto-included when `debug: true`.
+- Custom workflow names are normalized to lowercase.
+- Unknown tool names are ignored and logged as warnings.
+
 To access Xcode IDE tools (Xcode 26+ `xcrun mcpbridge`), enable `xcode-ide`. This workflow exposes `xcode_ide_list_tools` and `xcode_ide_call_tool` for MCP clients. See [XCODE_IDE_MCPBRIDGE.md](XCODE_IDE_MCPBRIDGE.md).
 
 ### Experimental workflow discovery
@@ -281,6 +305,7 @@ Notes:
 |--------|------|---------|
 | `schemaVersion` | number | Required (`1`) |
 | `enabledWorkflows` | string[] | `["simulator"]` |
+| `customWorkflows` | Record<string, string[]> | `{}` |
 | `experimentalWorkflowDiscovery` | boolean | `false` |
 | `disableSessionDefaults` | boolean | `false` |
 | `sessionDefaults` | object | `{}` |

src/mcp/tools/workflow-discovery/__tests__/manage_workflows.test.ts

@@ -5,7 +5,7 @@ vi.mock('../../../../utils/tool-registry.ts', () => ({
   getRegisteredWorkflows: vi.fn(),
   getMcpPredicateContext: vi.fn().mockReturnValue({
     runtime: 'mcp',
-    config: { debug: false },
+    config: { debug: false, customWorkflows: {} },
     runningUnderXcode: false,
   }),
 }));
@@ -15,6 +15,7 @@ vi.mock('../../../../utils/config-store.ts', () => ({
     debug: false,
     experimentalWorkflowDiscovery: false,
     enabledWorkflows: [],
+    customWorkflows: {},
   }),
 }));
 

src/utils/__tests__/config-store.test.ts

@@ -112,6 +112,35 @@ describe('config-store', () => {
     expect(updated.enabledWorkflows).toEqual(['device']);
   });
 
+  it('resolves customWorkflows from overrides, config, then defaults', async () => {
+    const yaml = [
+      'schemaVersion: 1',
+      'customWorkflows:',
+      '  smoke:',
+      '    - build_run_sim',
+      '',
+    ].join('\n');
+
+    await initConfigStore({ cwd, fs: createFs(yaml) });
+    expect(getConfig().customWorkflows).toEqual({
+      smoke: ['build_run_sim'],
+    });
+
+    await initConfigStore({
+      cwd,
+      fs: createFs(yaml),
+      overrides: {
+        customWorkflows: {
+          quick: ['screenshot'],
+        },
+      },
+    });
+
+    expect(getConfig().customWorkflows).toEqual({
+      quick: ['screenshot'],
+    });
+  });
+
   it('merges namespaced session defaults profiles from file and overrides', async () => {
     const yaml = [
       'schemaVersion: 1',

src/utils/__tests__/project-config.test.ts

@@ -60,6 +60,10 @@ describe('project-config', () => {
       const yaml = [
         'schemaVersion: 1',
         'enabledWorkflows: simulator,device',
+        'customWorkflows:',
+        '  My-Workflow:',
+        '    - build_run_sim',
+        '    - SCREENSHOT',
         'debug: true',
         'axePath: "./bin/axe"',
         'sessionDefaults:',
@@ -78,6 +82,9 @@ describe('project-config', () => {
 
       const defaults = result.config.sessionDefaults ?? {};
       expect(result.config.enabledWorkflows).toEqual(['simulator', 'device']);
+      expect(result.config.customWorkflows).toEqual({
+        'my-workflow': ['build_run_sim', 'screenshot'],
+      });
       expect(result.config.debug).toBe(true);
       expect(result.config.axePath).toBe(path.join(cwd, 'bin', 'axe'));
       expect(defaults.workspacePath).toBe(path.join(cwd, 'App.xcworkspace'));
@@ -107,6 +114,29 @@ describe('project-config', () => {
       expect(result.config.macosTemplatePath).toBe('/opt/templates/macos');
     });
 
+    it('normalizes custom workflow entries while loading config', async () => {
+      const yaml = [
+        'schemaVersion: 1',
+        'customWorkflows:',
+        '  valid-workflow:',
+        '    - build_run_sim',
+        '  invalid-workflow: build_run_sim',
+        '  "":',
+        '    - screenshot',
+        '',
+      ].join('\n');
+
+      const { fs } = createFsFixture({ exists: true, readFile: yaml });
+      const result = await loadProjectConfig({ fs, cwd });
+
+      if (!result.found) throw new Error('expected config to be found');
+
+      expect(result.config.customWorkflows).toEqual({
+        'invalid-workflow': ['build_run_sim'],
+        'valid-workflow': ['build_run_sim'],
+      });
+    });
+
     it('should resolve file URLs in session defaults and top-level paths', async () => {
       const yaml = [
         'schemaVersion: 1',

src/utils/__tests__/tool-registry.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from 'vitest';
+import { createCustomWorkflowsFromConfig } from '../tool-registry.ts';
+import type { ResolvedManifest } from '../../core/manifest/schema.ts';
+
+function createManifestFixture(): ResolvedManifest {
+  return {
+    tools: new Map([
+      [
+        'build_run_sim',
+        {
+          id: 'build_run_sim',
+          module: 'mcp/tools/simulator/build_run_sim',
+          names: { mcp: 'build_run_sim' },
+          availability: { mcp: true, cli: true },
+          predicates: [],
+          nextSteps: [],
+        },
+      ],
+      [
+        'screenshot',
+        {
+          id: 'screenshot',
+          module: 'mcp/tools/ui-automation/screenshot',
+          names: { mcp: 'screenshot' },
+          availability: { mcp: true, cli: true },
+          predicates: [],
+          nextSteps: [],
+        },
+      ],
+    ]),
+    workflows: new Map([
+      [
+        'simulator',
+        {
+          id: 'simulator',
+          title: 'Simulator',
+          description: 'Built-in simulator workflow',
+          availability: { mcp: true, cli: true },
+          predicates: [],
+          tools: ['build_run_sim'],
+        },
+      ],
+    ]),
+  };
+}
+
+describe('createCustomWorkflowsFromConfig', () => {
+  it('creates custom workflows and resolves tool IDs', () => {
+    const manifest = createManifestFixture();
+
+    const result = createCustomWorkflowsFromConfig(manifest, {
+      'My-Workflow': ['build_run_sim', 'SCREENSHOT'],
+    });
+
+    expect(result.workflows).toEqual([
+      expect.objectContaining({
+        id: 'my-workflow',
+        tools: ['build_run_sim', 'screenshot'],
+      }),
+    ]);
+    expect(result.warnings).toEqual([]);
+  });
+
+  it('warns when built-in workflow names conflict or tools are unknown', () => {
+    const manifest = createManifestFixture();
+
+    const result = createCustomWorkflowsFromConfig(manifest, {
+      simulator: ['build_run_sim'],
+      quick: ['unknown_tool'],
+    });
+
+    expect(result.workflows).toEqual([]);
+    expect(result.warnings).toHaveLength(3);
+  });
+});

src/utils/config-store.ts

@@ -13,6 +13,7 @@ import { normalizeSessionDefaultsProfileName } from './session-defaults-profile.
 
 export type RuntimeConfigOverrides = Partial<{
   enabledWorkflows: string[];
+  customWorkflows: Record<string, string[]>;
   debug: boolean;
   experimentalWorkflowDiscovery: boolean;
   disableSessionDefaults: boolean;
@@ -35,6 +36,7 @@ export type RuntimeConfigOverrides = Partial<{
 
 export type ResolvedRuntimeConfig = {
   enabledWorkflows: string[];
+  customWorkflows: Record<string, string[]>;
   debug: boolean;
   experimentalWorkflowDiscovery: boolean;
   disableSessionDefaults: boolean;
@@ -66,6 +68,7 @@ type ConfigStoreState = {
 
 const DEFAULT_CONFIG: ResolvedRuntimeConfig = {
   enabledWorkflows: [],
+  customWorkflows: {},
   debug: false,
   experimentalWorkflowDiscovery: false,
   disableSessionDefaults: false,
@@ -377,6 +380,13 @@ function resolveConfig(opts: {
       envConfig,
       fallback: DEFAULT_CONFIG.enabledWorkflows,
     }),
+    customWorkflows: resolveFromLayers<Record<string, string[]>>({
+      key: 'customWorkflows',
+      overrides: opts.overrides,
+      fileConfig: opts.fileConfig,
+      envConfig,
+      fallback: DEFAULT_CONFIG.customWorkflows,
+    }),
     debug: resolveFromLayers({
       key: 'debug',
       overrides: opts.overrides,

src/utils/project-config.ts

@@ -17,6 +17,7 @@ export type ProjectConfig = RuntimeConfigFile & {
   sessionDefaultsProfiles?: Record<string, Partial<SessionDefaults>>;
   activeSessionDefaultsProfile?: string;
   enabledWorkflows?: string[];
+  customWorkflows?: Record<string, string[]>;
   debuggerBackend?: 'dap' | 'lldb-cli';
   [key: string]: unknown;
 };
@@ -153,6 +154,37 @@ function normalizeEnabledWorkflows(value: unknown): string[] {
   return [];
 }
 
+function normalizeCustomWorkflows(value: unknown): Record<string, string[]> {
+  if (!isPlainObject(value)) {
+    return {};
+  }
+
+  const normalized: Record<string, string[]> = {};
+
+  for (const [workflowName, workflowTools] of Object.entries(value)) {
+    const normalizedWorkflowName = workflowName.trim().toLowerCase();
+    if (!normalizedWorkflowName) {
+      continue;
+    }
+    if (Array.isArray(workflowTools)) {
+      normalized[normalizedWorkflowName] = workflowTools
+        .filter((toolName): toolName is string => typeof toolName === 'string')
+        .map((toolName) => toolName.trim().toLowerCase())
+        .filter(Boolean);
+      continue;
+    }
+    if (typeof workflowTools === 'string') {
+      normalized[normalizedWorkflowName] = workflowTools
+        .split(',')
+        .map((toolName) => toolName.trim().toLowerCase())
+        .filter(Boolean);
+      continue;
+    }
+  }
+
+  return normalized;
+}
+
 function resolveRelativeTopLevelPaths(config: ProjectConfig, cwd: string): ProjectConfig {
   const resolved: ProjectConfig = { ...config };
   const pathKeys = ['axePath', 'iosTemplatePath', 'macosTemplatePath'] as const;
@@ -197,12 +229,14 @@ function normalizeDebuggerBackend(config: RuntimeConfigFile): ProjectConfig {
 }
 
 function normalizeConfigForPersistence(config: RuntimeConfigFile): ProjectConfig {
-  const base = normalizeDebuggerBackend(config);
-  if (config.enabledWorkflows === undefined) {
-    return base;
+  let base = normalizeDebuggerBackend(config);
+  if (config.enabledWorkflows !== undefined) {
+    base = { ...base, enabledWorkflows: normalizeEnabledWorkflows(config.enabledWorkflows) };
+  }
+  if (config.customWorkflows !== undefined) {
+    base = { ...base, customWorkflows: normalizeCustomWorkflows(config.customWorkflows) };
   }
-  const normalizedWorkflows = normalizeEnabledWorkflows(config.enabledWorkflows);
-  return { ...base, enabledWorkflows: normalizedWorkflows };
+  return base;
 }
 
 function toProjectConfig(config: RuntimeConfigFile): ProjectConfig {
@@ -258,6 +292,10 @@ export async function loadProjectConfig(
       const normalizedWorkflows = normalizeEnabledWorkflows(parsed.enabledWorkflows);
       config = { ...config, enabledWorkflows: normalizedWorkflows };
     }
+    if (parsed.customWorkflows !== undefined) {
+      const normalizedCustomWorkflows = normalizeCustomWorkflows(parsed.customWorkflows);
+      config = { ...config, customWorkflows: normalizedCustomWorkflows };
+    }
 
     if (config.sessionDefaults) {
       const normalized = normalizeMutualExclusivity(config.sessionDefaults);

src/utils/runtime-config-schema.ts

@@ -5,6 +5,7 @@ export const runtimeConfigFileSchema = z
   .object({
     schemaVersion: z.literal(1).optional().default(1),
     enabledWorkflows: z.union([z.array(z.string()), z.string()]).optional(),
+    customWorkflows: z.record(z.string(), z.union([z.array(z.string()), z.string()])).optional(),
     debug: z.boolean().optional(),
     experimentalWorkflowDiscovery: z.boolean().optional(),
     disableSessionDefaults: z.boolean().optional(),