fix: preserve session creation guidance

Author: KazuCocoa

scripts/audit-tool-footprint.mjs

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 
-const MAX_DISCOVERY_CHARS = 40_000;
+const MAX_DISCOVERY_CHARS = 42_000;
 const ESTIMATED_CHARS_PER_TOKEN = 4;
 const LARGEST_TOOL_COUNT = 10;
 

src/tests/tools/llm-wording.test.ts

@@ -145,16 +145,27 @@ describe('LLM-facing MCP tool wording', () => {
       /create.*attach.*detach.*delete.*list.*select/i
     );
 
-    expect(actionDescription).toMatch(/DEFAULT MODE/i);
+    expect(actionDescription).toMatch(/DEFAULT\/LOCAL MODE/i);
     expect(actionDescription).toMatch(/no separate Appium process is needed/i);
-    expect(actionDescription).toMatch(/select_device tool FIRST/i);
+    expect(actionDescription).toMatch(
+      /select_device first.*explicit target capabilities.*appium:udid/i
+    );
     expect(actionDescription).toMatch(/do NOT pass remoteServerUrl/i);
     expect(actionDescription).toMatch(/NEVER invent a localhost URL/i);
-    expect(actionDescription).toMatch(/prepare_ios_simulator.*before create/i);
+    expect(actionDescription).toMatch(
+      /prepare_ios_simulator.*appium_prepare_ios_real_device/i
+    );
+    expect(actionDescription).toMatch(
+      /full returned capabilitiesHint as capabilities/i
+    );
     expect(actionDescription).toMatch(/REMOTE SERVER MODE/i);
     expect(actionDescription).toMatch(
       /only when the user explicitly provides/i
     );
+    expect(actionDescription).toMatch(/skip select_device/i);
+    expect(actionDescription).toMatch(
+      /platform=general.*requires remoteServerUrl/i
+    );
     expect(actionDescription).toMatch(/without taking ownership/i);
     expect(actionDescription).toMatch(
       /without deleting the real remote session/i
@@ -181,7 +192,10 @@ describe('LLM-facing MCP tool wording', () => {
     );
     expect(description).toMatch(/NEVER use.*REMOTE.*remoteServerUrl/i);
     expect(description).toMatch(
-      /prepare_ios_simulator.*appium_session_management.*create/i
+      /prepare_ios_simulator.*appium_prepare_ios_real_device/i
+    );
+    expect(description).toMatch(
+      /full capabilitiesHint.*appium_session_management.*create/i
     );
     expect(description).toMatch(/Remote devices.*session capabilities/i);
 

src/tools/session/select-device.ts

@@ -83,7 +83,8 @@ export default function selectDevice(server: any): void {
     description:
       'LOCAL servers ONLY; NEVER use for REMOTE/remoteServerUrl. ASK THE USER Android or iOS—do not assume. ' +
       'Call without deviceUdid to list: one result auto-selects; for multiple results ask the user, then call again with the chosen deviceUdid. ' +
-      'For iOS require iosDeviceType and run prepare_ios_simulator before appium_session_management create. ' +
+      'For iOS require iosDeviceType. After selection run prepare_ios_simulator for a simulator or appium_prepare_ios_real_device for a real device, ' +
+      'then pass its full capabilitiesHint to appium_session_management create. ' +
       'Remote devices are selected through session capabilities.',
     parameters: z
       .object({
@@ -292,14 +293,18 @@ function selectIOSDevice(
  */
 function formatIOSSelectionResponse(
   deviceName: string,
-  deviceUdid: string
+  deviceUdid: string,
+  iosDeviceType: 'simulator' | 'real'
 ): ContentResult {
+  const prepareTool =
+    iosDeviceType === 'simulator'
+      ? 'prepare_ios_simulator'
+      : 'appium_prepare_ios_real_device';
   return textResult(
     JSON.stringify(
       {
         message: `✅ Device selected: ${deviceName} (${deviceUdid})`,
-        instructions:
-          '🚀 You can now call the prepare_ios_simulator tool to boot and setup WDA on the simulator or the appium_prepare_ios_real_device tool to setup WDA on ios real device.',
+        instructions: `🚀 Next call ${prepareTool}, then JSON-serialize its full capabilitiesHint as capabilities for appium_session_management with action=create.`,
         platform: 'ios',
         capabilities: {
           'appium:udid': deviceUdid,
@@ -400,7 +405,11 @@ async function handleIOSDeviceSelection(
     if (!selected.ok) {
       return selected.result;
     }
-    return formatIOSSelectionResponse(selected.device.info.name, deviceUdid);
+    return formatIOSSelectionResponse(
+      selected.device.info.name,
+      deviceUdid,
+      iosDeviceType!
+    );
   }
 
   // Auto-select when only one device is available
@@ -411,7 +420,8 @@ async function handleIOSDeviceSelection(
     }
     return formatIOSSelectionResponse(
       selected.device.info.name,
-      devices[0].udid
+      devices[0].udid,
+      iosDeviceType!
     );
   }
 

src/tools/session/session.ts

@@ -24,25 +24,28 @@ const schema = z.object({
   action: z
     .enum(SESSION_ACTIONS)
     .describe(
-      'Action. DEFAULT MODE: create without remoteServerUrl uses an embedded driver; no separate Appium process is needed. ' +
-        'Run select_device tool FIRST, pass platform, do NOT pass remoteServerUrl, and NEVER invent a localhost URL. ' +
-        'For iOS simulators, run prepare_ios_simulator before create. ' +
-        'REMOTE SERVER MODE: only when the user explicitly provides a URL; create with that URL/capabilities. ' +
+      'Action. DEFAULT/LOCAL MODE: create without remoteServerUrl uses an embedded driver; no separate Appium process is needed. ' +
+        'Normally run select_device first and pass its platform; explicit target capabilities such as appium:udid can be used instead. ' +
+        'Do NOT pass remoteServerUrl for local create, and NEVER invent a localhost URL. ' +
+        'For a selected iOS simulator run prepare_ios_simulator; for a selected iOS real device run appium_prepare_ios_real_device. ' +
+        'Then JSON-serialize the full returned capabilitiesHint as capabilities for create. ' +
+        'REMOTE SERVER MODE: only when the user explicitly provides a URL; skip select_device and create with that URL/capabilities. ' +
+        'platform=general is remote-only and requires remoteServerUrl. ' +
         'attach requires URL + sessionId (+ platformName capabilities) and connects without taking ownership. ' +
         'detach forgets an attached session without deleting the real remote session. delete stops; list shows; select activates.'
     ),
   platform: z
     .enum(DRIVER_MODE_PLATFORMS)
     .optional()
     .describe(
-      'Required for create; match select_device locally. Use general for other remote drivers.'
+      'Required for create. For local create, match select_device when used. general is for other remote drivers and requires remoteServerUrl.'
     ),
   capabilities: z
     .string()
     .optional()
     .describe(
-      'JSON W3C capabilities. create merges iOS/Android defaults or passes general through. ' +
-        'Serialize full capabilitiesHint values. attach must include platformName.'
+      'JSON-stringified W3C capabilities. create merges these over iOS/Android defaults or passes general through. ' +
+        'When using a capabilitiesHint, serialize the full object without dropping boolean or numeric values. attach must include platformName.'
     ),
   remoteServerUrl: z
     .string()