Add better session default documentation and auto-reconsile xor conflicts gracefully

Author: cameroncooke

.smithery/index.cjs

@@ -121,4 +121,4 @@ XcodeBuildMCP provides 70 tools organized into 13 workflow groups for comprehens
 
 ---
 
-*This documentation is automatically generated by `scripts/update-tools-docs.ts` using static analysis. Last updated: 2026-01-02*
+*This documentation is automatically generated by `scripts/update-tools-docs.ts` using static analysis. Last updated: 2026-01-03*

docs/TOOLS.md

@@ -231,7 +231,7 @@ describe('list_devices plugin (device-shared)', () => {
         content: [
           {
             type: 'text',
-            text: "Connected Devices:\n\n✅ Available Devices:\n\n📱 Test iPhone\n   UDID: test-device-123\n   Model: iPhone15,2\n   Product Type: iPhone15,2\n   Platform: iOS 17.0\n   Connection: USB\n\nNext Steps:\n1. Build for device: build_device({ scheme: 'SCHEME', deviceId: 'DEVICE_UDID' })\n2. Run tests: test_device({ scheme: 'SCHEME', deviceId: 'DEVICE_UDID' })\n3. Get app path: get_device_app_path({ scheme: 'SCHEME' })\n\nNote: Use the device ID/UDID from above when required by other tools.\n",
+            text: "Connected Devices:\n\n✅ Available Devices:\n\n📱 Test iPhone\n   UDID: test-device-123\n   Model: iPhone15,2\n   Product Type: iPhone15,2\n   Platform: iOS 17.0\n   Connection: USB\n\nNext Steps:\n1. Build for device: build_device({ scheme: 'SCHEME', deviceId: 'DEVICE_UDID' })\n2. Run tests: test_device({ scheme: 'SCHEME', deviceId: 'DEVICE_UDID' })\n3. Get app path: get_device_app_path({ scheme: 'SCHEME' })\n\nNote: Use the device ID/UDID from above when required by other tools.\nHint: Save a default device with session-set-defaults { deviceId: 'DEVICE_UDID' }.\n",
           },
         ],
       });

src/mcp/tools/device/__tests__/list_devices.test.ts

@@ -395,6 +395,8 @@ export async function list_devicesLogic(
       responseText += "2. Run tests: test_device({ scheme: 'SCHEME', deviceId: 'DEVICE_UDID' })\n";
       responseText += "3. Get app path: get_device_app_path({ scheme: 'SCHEME' })\n\n";
       responseText += 'Note: Use the device ID/UDID from above when required by other tools.\n';
+      responseText +=
+        "Hint: Save a default device with session-set-defaults { deviceId: 'DEVICE_UDID' }.\n";
     } else if (uniqueDevices.length > 0) {
       responseText +=
         'Note: No devices are currently available for testing. Make sure devices are:\n';

src/mcp/tools/device/list_devices.ts

@@ -164,6 +164,10 @@ describe('discover_projs plugin', () => {
           { type: 'text', text: 'Discovery finished. Found 1 projects and 1 workspaces.' },
           { type: 'text', text: 'Projects found:\n - /workspace/MyApp.xcodeproj' },
           { type: 'text', text: 'Workspaces found:\n - /workspace/MyWorkspace.xcworkspace' },
+          {
+            type: 'text',
+            text: "Hint: Save a default with session-set-defaults { projectPath: '...' } or { workspacePath: '...' }.",
+          },
         ],
         isError: false,
       });

src/mcp/tools/project-discovery/__tests__/discover_projs.test.ts

@@ -76,6 +76,10 @@ describe('list_schemes plugin', () => {
    or for iOS: build_sim({ projectPath: "/path/to/MyProject.xcodeproj", scheme: "MyProject", simulatorName: "iPhone 16" })
 2. Show build settings: show_build_settings({ projectPath: "/path/to/MyProject.xcodeproj", scheme: "MyProject" })`,
           },
+          {
+            type: 'text',
+            text: 'Hint: Consider saving a default scheme with session-set-defaults { scheme: "MyProject" } to avoid repeating it.',
+          },
         ],
         isError: false,
       });
@@ -295,6 +299,10 @@ describe('list_schemes plugin', () => {
    or for iOS: build_sim({ workspacePath: "/path/to/MyProject.xcworkspace", scheme: "MyApp", simulatorName: "iPhone 16" })
 2. Show build settings: show_build_settings({ workspacePath: "/path/to/MyProject.xcworkspace", scheme: "MyApp" })`,
           },
+          {
+            type: 'text',
+            text: 'Hint: Consider saving a default scheme with session-set-defaults { scheme: "MyApp" } to avoid repeating it.',
+          },
         ],
         isError: false,
       });

src/mcp/tools/project-discovery/__tests__/list_schemes.test.ts

@@ -263,6 +263,14 @@ export async function discover_projsLogic(
     );
   }
 
+  if (results.projects.length > 0 || results.workspaces.length > 0) {
+    responseContent.push(
+      createTextContent(
+        "Hint: Save a default with session-set-defaults { projectPath: '...' } or { workspacePath: '...' }.",
+      ),
+    );
+  }
+
   return {
     content: responseContent,
     isError: false,

src/mcp/tools/project-discovery/discover_projs.ts

@@ -36,6 +36,8 @@ const listSchemesSchema = z.preprocess(
 
 export type ListSchemesParams = z.infer<typeof listSchemesSchema>;
 
+const createTextBlock = (text: string) => ({ type: 'text', text }) as const;
+
 /**
  * Business logic for listing schemes in a project or workspace.
  * Exported for direct testing and reuse.
@@ -79,6 +81,7 @@ export async function listSchemesLogic(
 
     // Prepare next steps with the first scheme if available
     let nextStepsText = '';
+    let hintText = '';
     if (schemes.length > 0) {
       const firstScheme = schemes[0];
 
@@ -87,23 +90,23 @@ export async function listSchemesLogic(
 1. Build the app: build_macos({ ${projectOrWorkspace}Path: "${path}", scheme: "${firstScheme}" })
    or for iOS: build_sim({ ${projectOrWorkspace}Path: "${path}", scheme: "${firstScheme}", simulatorName: "iPhone 16" })
 2. Show build settings: show_build_settings({ ${projectOrWorkspace}Path: "${path}", scheme: "${firstScheme}" })`;
+
+      hintText =
+        `Hint: Consider saving a default scheme with session-set-defaults ` +
+        `{ scheme: "${firstScheme}" } to avoid repeating it.`;
+    }
+
+    const content = [
+      createTextBlock('✅ Available schemes:'),
+      createTextBlock(schemes.join('\n')),
+      createTextBlock(nextStepsText),
+    ];
+    if (hintText.length > 0) {
+      content.push(createTextBlock(hintText));
     }
 
     return {
-      content: [
-        {
-          type: 'text',
-          text: `✅ Available schemes:`,
-        },
-        {
-          type: 'text',
-          text: schemes.join('\n'),
-        },
-        {
-          type: 'text',
-          text: nextStepsText,
-        },
-      ],
+      content,
       isError: false,
     };
   } catch (error) {

src/mcp/tools/project-discovery/list_schemes.ts

@@ -59,54 +59,72 @@ describe('session-set-defaults tool', () => {
 
     it('should clear workspacePath when projectPath is set', async () => {
       sessionStore.setDefaults({ workspacePath: '/old/App.xcworkspace' });
-      await sessionSetDefaultsLogic({ projectPath: '/new/App.xcodeproj' });
+      const result = await sessionSetDefaultsLogic({ projectPath: '/new/App.xcodeproj' });
       const current = sessionStore.getAll();
       expect(current.projectPath).toBe('/new/App.xcodeproj');
       expect(current.workspacePath).toBeUndefined();
+      expect(result.content[0].text).toContain(
+        'Cleared workspacePath because projectPath was set.',
+      );
     });
 
     it('should clear projectPath when workspacePath is set', async () => {
       sessionStore.setDefaults({ projectPath: '/old/App.xcodeproj' });
-      await sessionSetDefaultsLogic({ workspacePath: '/new/App.xcworkspace' });
+      const result = await sessionSetDefaultsLogic({ workspacePath: '/new/App.xcworkspace' });
       const current = sessionStore.getAll();
       expect(current.workspacePath).toBe('/new/App.xcworkspace');
       expect(current.projectPath).toBeUndefined();
+      expect(result.content[0].text).toContain(
+        'Cleared projectPath because workspacePath was set.',
+      );
     });
 
     it('should clear simulatorName when simulatorId is set', async () => {
       sessionStore.setDefaults({ simulatorName: 'iPhone 16' });
-      await sessionSetDefaultsLogic({ simulatorId: 'SIM-UUID' });
+      const result = await sessionSetDefaultsLogic({ simulatorId: 'SIM-UUID' });
       const current = sessionStore.getAll();
       expect(current.simulatorId).toBe('SIM-UUID');
       expect(current.simulatorName).toBeUndefined();
+      expect(result.content[0].text).toContain(
+        'Cleared simulatorName because simulatorId was set.',
+      );
     });
 
     it('should clear simulatorId when simulatorName is set', async () => {
       sessionStore.setDefaults({ simulatorId: 'SIM-UUID' });
-      await sessionSetDefaultsLogic({ simulatorName: 'iPhone 16' });
+      const result = await sessionSetDefaultsLogic({ simulatorName: 'iPhone 16' });
       const current = sessionStore.getAll();
       expect(current.simulatorName).toBe('iPhone 16');
       expect(current.simulatorId).toBeUndefined();
+      expect(result.content[0].text).toContain(
+        'Cleared simulatorId because simulatorName was set.',
+      );
     });
 
-    it('should reject when both projectPath and workspacePath are provided', async () => {
-      const res = await plugin.handler({
+    it('should prefer workspacePath when both projectPath and workspacePath are provided', async () => {
+      const res = await sessionSetDefaultsLogic({
         projectPath: '/app/App.xcodeproj',
         workspacePath: '/app/App.xcworkspace',
       });
-      expect(res.isError).toBe(true);
-      expect(res.content[0].text).toContain('Parameter validation failed');
-      expect(res.content[0].text).toContain('projectPath and workspacePath are mutually exclusive');
+      const current = sessionStore.getAll();
+      expect(current.workspacePath).toBe('/app/App.xcworkspace');
+      expect(current.projectPath).toBeUndefined();
+      expect(res.content[0].text).toContain(
+        'Both projectPath and workspacePath were provided; keeping workspacePath and ignoring projectPath.',
+      );
     });
 
-    it('should reject when both simulatorId and simulatorName are provided', async () => {
-      const res = await plugin.handler({
+    it('should prefer simulatorId when both simulatorId and simulatorName are provided', async () => {
+      const res = await sessionSetDefaultsLogic({
         simulatorId: 'SIM-1',
         simulatorName: 'iPhone 16',
       });
-      expect(res.isError).toBe(true);
-      expect(res.content[0].text).toContain('Parameter validation failed');
-      expect(res.content[0].text).toContain('simulatorId and simulatorName are mutually exclusive');
+      const current = sessionStore.getAll();
+      expect(current.simulatorId).toBe('SIM-1');
+      expect(current.simulatorName).toBeUndefined();
+      expect(res.content[0].text).toContain(
+        'Both simulatorId and simulatorName were provided; keeping simulatorId and ignoring simulatorName.',
+      );
     });
   });
 });

src/mcp/tools/session-management/__tests__/session_set_defaults.test.ts

@@ -5,49 +5,124 @@ import { getDefaultCommandExecutor } from '../../../utils/execution/index.ts';
 import type { ToolResponse } from '../../../types/common.ts';
 
 const baseSchema = z.object({
-  projectPath: z.string().optional(),
-  workspacePath: z.string().optional(),
-  scheme: z.string().optional(),
-  configuration: z.string().optional(),
-  simulatorName: z.string().optional(),
-  simulatorId: z.string().optional(),
-  deviceId: z.string().optional(),
-  useLatestOS: z.boolean().optional(),
-  arch: z.enum(['arm64', 'x86_64']).optional(),
+  projectPath: z
+    .string()
+    .optional()
+    .describe(
+      'Xcode project (.xcodeproj) path. Mutually exclusive with workspacePath. Required for most build/test tools when workspacePath is not set.',
+    ),
+  workspacePath: z
+    .string()
+    .optional()
+    .describe(
+      'Xcode workspace (.xcworkspace) path. Mutually exclusive with projectPath. Required for most build/test tools when projectPath is not set.',
+    ),
+  scheme: z
+    .string()
+    .optional()
+    .describe(
+      'Xcode scheme. Required by most build/test tools. Use list_schemes to discover available schemes before setting.',
+    ),
+  configuration: z.string().optional().describe('Build configuration, e.g. Debug or Release.'),
+  simulatorName: z
+    .string()
+    .optional()
+    .describe(
+      'Simulator device name for simulator workflows. If simulatorId is also provided, simulatorId is preferred and simulatorName is ignored.',
+    ),
+  simulatorId: z
+    .string()
+    .optional()
+    .describe(
+      'Simulator UUID for simulator workflows. Preferred over simulatorName when both are provided.',
+    ),
+  deviceId: z.string().optional().describe('Physical device ID for device workflows.'),
+  useLatestOS: z
+    .boolean()
+    .optional()
+    .describe('When true, prefer the latest available OS for simulatorName lookups.'),
+  arch: z.enum(['arm64', 'x86_64']).optional().describe('Target architecture for macOS builds.'),
   suppressWarnings: z
     .boolean()
     .optional()
     .describe('When true, warning messages are filtered from build output to conserve context'),
 });
 
-const schemaObj = baseSchema
-  .refine((v) => !(v.projectPath && v.workspacePath), {
-    message: 'projectPath and workspacePath are mutually exclusive',
-    path: ['projectPath'],
-  })
-  .refine((v) => !(v.simulatorId && v.simulatorName), {
-    message: 'simulatorId and simulatorName are mutually exclusive',
-    path: ['simulatorId'],
-  });
+const schemaObj = baseSchema;
 
 type Params = z.infer<typeof schemaObj>;
 
 export async function sessionSetDefaultsLogic(params: Params): Promise<ToolResponse> {
+  const notices: string[] = [];
+  const current = sessionStore.getAll();
+  const nextParams: Partial<SessionDefaults> = { ...params };
+
+  const hasProjectPath =
+    Object.prototype.hasOwnProperty.call(params, 'projectPath') && params.projectPath !== undefined;
+  const hasWorkspacePath =
+    Object.prototype.hasOwnProperty.call(params, 'workspacePath') &&
+    params.workspacePath !== undefined;
+  const hasSimulatorId =
+    Object.prototype.hasOwnProperty.call(params, 'simulatorId') && params.simulatorId !== undefined;
+  const hasSimulatorName =
+    Object.prototype.hasOwnProperty.call(params, 'simulatorName') &&
+    params.simulatorName !== undefined;
+
+  if (hasProjectPath && hasWorkspacePath) {
+    delete nextParams.projectPath;
+    notices.push(
+      'Both projectPath and workspacePath were provided; keeping workspacePath and ignoring projectPath.',
+    );
+  }
+
+  if (hasSimulatorId && hasSimulatorName) {
+    delete nextParams.simulatorName;
+    notices.push(
+      'Both simulatorId and simulatorName were provided; keeping simulatorId and ignoring simulatorName.',
+    );
+  }
+
   // Clear mutually exclusive counterparts before merging new defaults
   const toClear = new Set<keyof SessionDefaults>();
-  if (Object.prototype.hasOwnProperty.call(params, 'projectPath')) toClear.add('workspacePath');
-  if (Object.prototype.hasOwnProperty.call(params, 'workspacePath')) toClear.add('projectPath');
-  if (Object.prototype.hasOwnProperty.call(params, 'simulatorId')) toClear.add('simulatorName');
-  if (Object.prototype.hasOwnProperty.call(params, 'simulatorName')) toClear.add('simulatorId');
+  if (Object.prototype.hasOwnProperty.call(nextParams, 'projectPath')) {
+    toClear.add('workspacePath');
+    if (current.workspacePath !== undefined) {
+      notices.push('Cleared workspacePath because projectPath was set.');
+    }
+  }
+  if (Object.prototype.hasOwnProperty.call(nextParams, 'workspacePath')) {
+    toClear.add('projectPath');
+    if (current.projectPath !== undefined) {
+      notices.push('Cleared projectPath because workspacePath was set.');
+    }
+  }
+  if (Object.prototype.hasOwnProperty.call(nextParams, 'simulatorId')) {
+    toClear.add('simulatorName');
+    if (current.simulatorName !== undefined) {
+      notices.push('Cleared simulatorName because simulatorId was set.');
+    }
+  }
+  if (Object.prototype.hasOwnProperty.call(nextParams, 'simulatorName')) {
+    toClear.add('simulatorId');
+    if (current.simulatorId !== undefined) {
+      notices.push('Cleared simulatorId because simulatorName was set.');
+    }
+  }
 
   if (toClear.size > 0) {
     sessionStore.clear(Array.from(toClear));
   }
 
-  sessionStore.setDefaults(params as Partial<SessionDefaults>);
-  const current = sessionStore.getAll();
+  sessionStore.setDefaults(nextParams as Partial<SessionDefaults>);
+  const updated = sessionStore.getAll();
+  const noticeText = notices.length > 0 ? `\nNotices:\n- ${notices.join('\n- ')}` : '';
   return {
-    content: [{ type: 'text', text: `Defaults updated:\n${JSON.stringify(current, null, 2)}` }],
+    content: [
+      {
+        type: 'text',
+        text: `Defaults updated:\n${JSON.stringify(updated, null, 2)}${noticeText}`,
+      },
+    ],
     isError: false,
   };
 }