@midscene/ios 1.7.5-beta-20260421030751.0 → 1.7.5

package/dist/es/cli.mjs

@@ -1,7 +1,7 @@
 import { createReportCliCommands, getMidsceneLocationSchema, z } from "@midscene/core";
-import { CLIError, runToolsCLI } from "@midscene/shared/cli";
+import { reportCLIError, runToolsCLI } from "@midscene/shared/cli";
 import { getDebug } from "@midscene/shared/logger";
-import { BaseMidsceneTools } from "@midscene/shared/mcp";
+import { BaseMidsceneTools } from "@midscene/shared/mcp/base-tools";
 import { Agent } from "@midscene/core/agent";
 import { mergeAndNormalizeAppNameMapping, normalizeForComparison } from "@midscene/shared/utils";
 import node_assert from "node:assert";
@@ -1320,17 +1320,46 @@ async function agentFromWebDriverAgent(opts) {
     await device.connect();
     return new IOSAgent(device, opts);
 }
+function mcp_tools_define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
 const debug = getDebug('mcp:ios-tools');
+const iosInitArgShape = {
+    deviceId: z.string().optional().describe('iOS device UDID (optional when WDA auto-detect is sufficient)'),
+    wdaHost: z.string().optional().describe('WebDriverAgent host, defaults to localhost'),
+    wdaPort: z.number().optional().describe('WebDriverAgent port'),
+    useWDA: z.boolean().optional().describe('Whether to reuse an existing WebDriverAgent session'),
+    wdaMjpegPort: z.number().optional().describe('WebDriverAgent MJPEG streaming port')
+};
 class IOSMidsceneTools extends BaseMidsceneTools {
     createTemporaryDevice() {
         return new IOSDevice({});
     }
-    async ensureAgent() {
+    async ensureAgent(opts) {
+        const hasOpts = !!opts && Object.keys(opts).length > 0;
+        const nextSignature = hasOpts ? JSON.stringify(opts) : void 0;
+        if (this.agent && hasOpts && nextSignature !== this.lastOptsSignature) {
+            try {
+                await this.agent.destroy?.();
+            } catch (error) {
+                debug('Failed to destroy agent during cleanup:', error);
+            }
+            this.agent = void 0;
+        }
         if (this.agent) return this.agent;
-        debug('Creating iOS agent with WebDriverAgent');
+        debug('Creating iOS agent with WebDriverAgent options:', opts || {});
         this.agent = await agentFromWebDriverAgent({
-            autoDismissKeyboard: false
+            autoDismissKeyboard: false,
+            ...opts ?? {}
         });
+        this.lastOptsSignature = nextSignature;
         return this.agent;
     }
     preparePlatformTools() {
@@ -1338,15 +1367,17 @@ class IOSMidsceneTools extends BaseMidsceneTools {
             {
                 name: 'ios_connect',
                 description: 'Connect to iOS device or simulator via WebDriverAgent',
-                schema: {},
-                handler: async ()=>{
-                    const agent = await this.ensureAgent();
+                schema: this.getAgentInitArgSchema(),
+                cli: this.getAgentInitArgCliMetadata(),
+                handler: async (args)=>{
+                    const initArgs = this.extractAgentInitParam(args);
+                    const agent = await this.ensureAgent(initArgs);
                     const screenshot = await agent.page.screenshotBase64();
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: 'Connected to iOS device'
+                                text: `Connected to iOS device${initArgs?.deviceId ? `: ${initArgs.deviceId}` : ''}`
                             },
                             ...this.buildScreenshotContent(screenshot)
                         ],
@@ -1362,13 +1393,22 @@ class IOSMidsceneTools extends BaseMidsceneTools {
             }
         ];
     }
+    constructor(...args){
+        super(...args), mcp_tools_define_property(this, "initArgSpec", {
+            namespace: 'ios',
+            shape: iosInitArgShape,
+            cli: {
+                preferBareKeys: true
+            },
+            adapt: (extracted)=>extracted
+        }), mcp_tools_define_property(this, "lastOptsSignature", void 0);
+    }
 }
 const tools = new IOSMidsceneTools();
 runToolsCLI(tools, 'midscene-ios', {
     stripPrefix: 'ios_',
-    version: "1.7.5-beta-20260421030751.0",
+    version: "1.7.5",
     extraCommands: createReportCliCommands()
 }).catch((e)=>{
-    if (!(e instanceof CLIError)) console.error(e);
-    process.exit(e instanceof CLIError ? e.exitCode : 1);
+    process.exit(reportCLIError(e));
 });

package/dist/es/index.mjs

@@ -8,7 +8,7 @@ import { getDebug } from "@midscene/shared/logger";
 import { mergeAndNormalizeAppNameMapping, normalizeForComparison } from "@midscene/shared/utils";
 import { WDAManager, WebDriverClient } from "@midscene/webdriver";
 import { Agent } from "@midscene/core/agent";
-import { BaseMidsceneTools } from "@midscene/shared/mcp";
+import { BaseMidsceneTools } from "@midscene/shared/mcp/base-tools";
 import { overrideAIConfig } from "@midscene/shared/env";
 import { exec } from "node:child_process";
 import { platform } from "node:os";
@@ -1326,17 +1326,46 @@ async function agentFromWebDriverAgent(opts) {
     await device.connect();
     return new IOSAgent(device, opts);
 }
+function mcp_tools_define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
 const debug = getDebug('mcp:ios-tools');
+const iosInitArgShape = {
+    deviceId: z.string().optional().describe('iOS device UDID (optional when WDA auto-detect is sufficient)'),
+    wdaHost: z.string().optional().describe('WebDriverAgent host, defaults to localhost'),
+    wdaPort: z.number().optional().describe('WebDriverAgent port'),
+    useWDA: z.boolean().optional().describe('Whether to reuse an existing WebDriverAgent session'),
+    wdaMjpegPort: z.number().optional().describe('WebDriverAgent MJPEG streaming port')
+};
 class IOSMidsceneTools extends BaseMidsceneTools {
     createTemporaryDevice() {
         return new IOSDevice({});
     }
-    async ensureAgent() {
+    async ensureAgent(opts) {
+        const hasOpts = !!opts && Object.keys(opts).length > 0;
+        const nextSignature = hasOpts ? JSON.stringify(opts) : void 0;
+        if (this.agent && hasOpts && nextSignature !== this.lastOptsSignature) {
+            try {
+                await this.agent.destroy?.();
+            } catch (error) {
+                debug('Failed to destroy agent during cleanup:', error);
+            }
+            this.agent = void 0;
+        }
         if (this.agent) return this.agent;
-        debug('Creating iOS agent with WebDriverAgent');
+        debug('Creating iOS agent with WebDriverAgent options:', opts || {});
         this.agent = await agentFromWebDriverAgent({
-            autoDismissKeyboard: false
+            autoDismissKeyboard: false,
+            ...opts ?? {}
         });
+        this.lastOptsSignature = nextSignature;
         return this.agent;
     }
     preparePlatformTools() {
@@ -1344,15 +1373,17 @@ class IOSMidsceneTools extends BaseMidsceneTools {
             {
                 name: 'ios_connect',
                 description: 'Connect to iOS device or simulator via WebDriverAgent',
-                schema: {},
-                handler: async ()=>{
-                    const agent = await this.ensureAgent();
+                schema: this.getAgentInitArgSchema(),
+                cli: this.getAgentInitArgCliMetadata(),
+                handler: async (args)=>{
+                    const initArgs = this.extractAgentInitParam(args);
+                    const agent = await this.ensureAgent(initArgs);
                     const screenshot = await agent.page.screenshotBase64();
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: 'Connected to iOS device'
+                                text: `Connected to iOS device${initArgs?.deviceId ? `: ${initArgs.deviceId}` : ''}`
                             },
                             ...this.buildScreenshotContent(screenshot)
                         ],
@@ -1368,6 +1399,16 @@ class IOSMidsceneTools extends BaseMidsceneTools {
             }
         ];
     }
+    constructor(...args){
+        super(...args), mcp_tools_define_property(this, "initArgSpec", {
+            namespace: 'ios',
+            shape: iosInitArgShape,
+            cli: {
+                preferBareKeys: true
+            },
+            adapt: (extracted)=>extracted
+        }), mcp_tools_define_property(this, "lastOptsSignature", void 0);
+    }
 }
 const execAsync = promisify(exec);
 const debugUtils = getDebug('ios:utils');

package/dist/es/mcp-server.mjs

@@ -1,4 +1,4 @@
-import { BaseMCPServer, BaseMidsceneTools, createMCPServerLauncher } from "@midscene/shared/mcp";
+import { BaseMCPServer, createMCPServerLauncher } from "@midscene/shared/mcp";
 import { Agent } from "@midscene/core/agent";
 import { getDebug } from "@midscene/shared/logger";
 import { mergeAndNormalizeAppNameMapping, normalizeForComparison } from "@midscene/shared/utils";
@@ -9,6 +9,7 @@ import { sleep } from "@midscene/core/utils";
 import { DEFAULT_WDA_PORT } from "@midscene/shared/constants";
 import { createImgBase64ByFormat } from "@midscene/shared/img";
 import { WDAManager, WebDriverClient } from "@midscene/webdriver";
+import { BaseMidsceneTools } from "@midscene/shared/mcp/base-tools";
 const defaultAppNameMapping = {
     微信: 'com.tencent.xin',
     企业微信: 'com.tencent.ww',
@@ -1319,17 +1320,46 @@ async function agentFromWebDriverAgent(opts) {
     await device.connect();
     return new IOSAgent(device, opts);
 }
+function mcp_tools_define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
 const debug = getDebug('mcp:ios-tools');
+const iosInitArgShape = {
+    deviceId: z.string().optional().describe('iOS device UDID (optional when WDA auto-detect is sufficient)'),
+    wdaHost: z.string().optional().describe('WebDriverAgent host, defaults to localhost'),
+    wdaPort: z.number().optional().describe('WebDriverAgent port'),
+    useWDA: z.boolean().optional().describe('Whether to reuse an existing WebDriverAgent session'),
+    wdaMjpegPort: z.number().optional().describe('WebDriverAgent MJPEG streaming port')
+};
 class IOSMidsceneTools extends BaseMidsceneTools {
     createTemporaryDevice() {
         return new IOSDevice({});
     }
-    async ensureAgent() {
+    async ensureAgent(opts) {
+        const hasOpts = !!opts && Object.keys(opts).length > 0;
+        const nextSignature = hasOpts ? JSON.stringify(opts) : void 0;
+        if (this.agent && hasOpts && nextSignature !== this.lastOptsSignature) {
+            try {
+                await this.agent.destroy?.();
+            } catch (error) {
+                debug('Failed to destroy agent during cleanup:', error);
+            }
+            this.agent = void 0;
+        }
         if (this.agent) return this.agent;
-        debug('Creating iOS agent with WebDriverAgent');
+        debug('Creating iOS agent with WebDriverAgent options:', opts || {});
         this.agent = await agentFromWebDriverAgent({
-            autoDismissKeyboard: false
+            autoDismissKeyboard: false,
+            ...opts ?? {}
         });
+        this.lastOptsSignature = nextSignature;
         return this.agent;
     }
     preparePlatformTools() {
@@ -1337,15 +1367,17 @@ class IOSMidsceneTools extends BaseMidsceneTools {
             {
                 name: 'ios_connect',
                 description: 'Connect to iOS device or simulator via WebDriverAgent',
-                schema: {},
-                handler: async ()=>{
-                    const agent = await this.ensureAgent();
+                schema: this.getAgentInitArgSchema(),
+                cli: this.getAgentInitArgCliMetadata(),
+                handler: async (args)=>{
+                    const initArgs = this.extractAgentInitParam(args);
+                    const agent = await this.ensureAgent(initArgs);
                     const screenshot = await agent.page.screenshotBase64();
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: 'Connected to iOS device'
+                                text: `Connected to iOS device${initArgs?.deviceId ? `: ${initArgs.deviceId}` : ''}`
                             },
                             ...this.buildScreenshotContent(screenshot)
                         ],
@@ -1361,6 +1393,16 @@ class IOSMidsceneTools extends BaseMidsceneTools {
             }
         ];
     }
+    constructor(...args){
+        super(...args), mcp_tools_define_property(this, "initArgSpec", {
+            namespace: 'ios',
+            shape: iosInitArgShape,
+            cli: {
+                preferBareKeys: true
+            },
+            adapt: (extracted)=>extracted
+        }), mcp_tools_define_property(this, "lastOptsSignature", void 0);
+    }
 }
 class IOSMCPServer extends BaseMCPServer {
     createToolsManager() {
@@ -1369,7 +1411,7 @@ class IOSMCPServer extends BaseMCPServer {
     constructor(toolsManager){
         super({
             name: '@midscene/ios-mcp',
-            version: "1.7.5-beta-20260421030751.0",
+            version: "1.7.5",
             description: 'Control the iOS device using natural language commands'
         }, toolsManager);
     }

package/dist/lib/cli.js

@@ -24,7 +24,7 @@ var __webpack_exports__ = {};
 const core_namespaceObject = require("@midscene/core");
 const cli_namespaceObject = require("@midscene/shared/cli");
 const logger_namespaceObject = require("@midscene/shared/logger");
-const mcp_namespaceObject = require("@midscene/shared/mcp");
+const base_tools_namespaceObject = require("@midscene/shared/mcp/base-tools");
 const agent_namespaceObject = require("@midscene/core/agent");
 const utils_namespaceObject = require("@midscene/shared/utils");
 const defaultAppNameMapping = {
@@ -1344,17 +1344,46 @@ async function agentFromWebDriverAgent(opts) {
     await device.connect();
     return new IOSAgent(device, opts);
 }
+function mcp_tools_define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
 const debug = (0, logger_namespaceObject.getDebug)('mcp:ios-tools');
-class IOSMidsceneTools extends mcp_namespaceObject.BaseMidsceneTools {
+const iosInitArgShape = {
+    deviceId: core_namespaceObject.z.string().optional().describe('iOS device UDID (optional when WDA auto-detect is sufficient)'),
+    wdaHost: core_namespaceObject.z.string().optional().describe('WebDriverAgent host, defaults to localhost'),
+    wdaPort: core_namespaceObject.z.number().optional().describe('WebDriverAgent port'),
+    useWDA: core_namespaceObject.z.boolean().optional().describe('Whether to reuse an existing WebDriverAgent session'),
+    wdaMjpegPort: core_namespaceObject.z.number().optional().describe('WebDriverAgent MJPEG streaming port')
+};
+class IOSMidsceneTools extends base_tools_namespaceObject.BaseMidsceneTools {
     createTemporaryDevice() {
         return new IOSDevice({});
     }
-    async ensureAgent() {
+    async ensureAgent(opts) {
+        const hasOpts = !!opts && Object.keys(opts).length > 0;
+        const nextSignature = hasOpts ? JSON.stringify(opts) : void 0;
+        if (this.agent && hasOpts && nextSignature !== this.lastOptsSignature) {
+            try {
+                await this.agent.destroy?.();
+            } catch (error) {
+                debug('Failed to destroy agent during cleanup:', error);
+            }
+            this.agent = void 0;
+        }
         if (this.agent) return this.agent;
-        debug('Creating iOS agent with WebDriverAgent');
+        debug('Creating iOS agent with WebDriverAgent options:', opts || {});
         this.agent = await agentFromWebDriverAgent({
-            autoDismissKeyboard: false
+            autoDismissKeyboard: false,
+            ...opts ?? {}
         });
+        this.lastOptsSignature = nextSignature;
         return this.agent;
     }
     preparePlatformTools() {
@@ -1362,15 +1391,17 @@ class IOSMidsceneTools extends mcp_namespaceObject.BaseMidsceneTools {
             {
                 name: 'ios_connect',
                 description: 'Connect to iOS device or simulator via WebDriverAgent',
-                schema: {},
-                handler: async ()=>{
-                    const agent = await this.ensureAgent();
+                schema: this.getAgentInitArgSchema(),
+                cli: this.getAgentInitArgCliMetadata(),
+                handler: async (args)=>{
+                    const initArgs = this.extractAgentInitParam(args);
+                    const agent = await this.ensureAgent(initArgs);
                     const screenshot = await agent.page.screenshotBase64();
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: 'Connected to iOS device'
+                                text: `Connected to iOS device${initArgs?.deviceId ? `: ${initArgs.deviceId}` : ''}`
                             },
                             ...this.buildScreenshotContent(screenshot)
                         ],
@@ -1386,15 +1417,24 @@ class IOSMidsceneTools extends mcp_namespaceObject.BaseMidsceneTools {
             }
         ];
     }
+    constructor(...args){
+        super(...args), mcp_tools_define_property(this, "initArgSpec", {
+            namespace: 'ios',
+            shape: iosInitArgShape,
+            cli: {
+                preferBareKeys: true
+            },
+            adapt: (extracted)=>extracted
+        }), mcp_tools_define_property(this, "lastOptsSignature", void 0);
+    }
 }
 const tools = new IOSMidsceneTools();
 (0, cli_namespaceObject.runToolsCLI)(tools, 'midscene-ios', {
     stripPrefix: 'ios_',
-    version: "1.7.5-beta-20260421030751.0",
+    version: "1.7.5",
     extraCommands: (0, core_namespaceObject.createReportCliCommands)()
 }).catch((e)=>{
-    if (!(e instanceof cli_namespaceObject.CLIError)) console.error(e);
-    process.exit(e instanceof cli_namespaceObject.CLIError ? e.exitCode : 1);
+    process.exit((0, cli_namespaceObject.reportCLIError)(e));
 });
 for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];
 Object.defineProperty(exports, '__esModule', {

package/dist/lib/index.js

@@ -1363,18 +1363,47 @@ async function agentFromWebDriverAgent(opts) {
     await device.connect();
     return new IOSAgent(device, opts);
 }
-const mcp_namespaceObject = require("@midscene/shared/mcp");
+const base_tools_namespaceObject = require("@midscene/shared/mcp/base-tools");
+function mcp_tools_define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
 const debug = (0, logger_namespaceObject.getDebug)('mcp:ios-tools');
-class IOSMidsceneTools extends mcp_namespaceObject.BaseMidsceneTools {
+const iosInitArgShape = {
+    deviceId: core_namespaceObject.z.string().optional().describe('iOS device UDID (optional when WDA auto-detect is sufficient)'),
+    wdaHost: core_namespaceObject.z.string().optional().describe('WebDriverAgent host, defaults to localhost'),
+    wdaPort: core_namespaceObject.z.number().optional().describe('WebDriverAgent port'),
+    useWDA: core_namespaceObject.z.boolean().optional().describe('Whether to reuse an existing WebDriverAgent session'),
+    wdaMjpegPort: core_namespaceObject.z.number().optional().describe('WebDriverAgent MJPEG streaming port')
+};
+class IOSMidsceneTools extends base_tools_namespaceObject.BaseMidsceneTools {
     createTemporaryDevice() {
         return new IOSDevice({});
     }
-    async ensureAgent() {
+    async ensureAgent(opts) {
+        const hasOpts = !!opts && Object.keys(opts).length > 0;
+        const nextSignature = hasOpts ? JSON.stringify(opts) : void 0;
+        if (this.agent && hasOpts && nextSignature !== this.lastOptsSignature) {
+            try {
+                await this.agent.destroy?.();
+            } catch (error) {
+                debug('Failed to destroy agent during cleanup:', error);
+            }
+            this.agent = void 0;
+        }
         if (this.agent) return this.agent;
-        debug('Creating iOS agent with WebDriverAgent');
+        debug('Creating iOS agent with WebDriverAgent options:', opts || {});
         this.agent = await agentFromWebDriverAgent({
-            autoDismissKeyboard: false
+            autoDismissKeyboard: false,
+            ...opts ?? {}
         });
+        this.lastOptsSignature = nextSignature;
         return this.agent;
     }
     preparePlatformTools() {
@@ -1382,15 +1411,17 @@ class IOSMidsceneTools extends mcp_namespaceObject.BaseMidsceneTools {
             {
                 name: 'ios_connect',
                 description: 'Connect to iOS device or simulator via WebDriverAgent',
-                schema: {},
-                handler: async ()=>{
-                    const agent = await this.ensureAgent();
+                schema: this.getAgentInitArgSchema(),
+                cli: this.getAgentInitArgCliMetadata(),
+                handler: async (args)=>{
+                    const initArgs = this.extractAgentInitParam(args);
+                    const agent = await this.ensureAgent(initArgs);
                     const screenshot = await agent.page.screenshotBase64();
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: 'Connected to iOS device'
+                                text: `Connected to iOS device${initArgs?.deviceId ? `: ${initArgs.deviceId}` : ''}`
                             },
                             ...this.buildScreenshotContent(screenshot)
                         ],
@@ -1406,6 +1437,16 @@ class IOSMidsceneTools extends mcp_namespaceObject.BaseMidsceneTools {
             }
         ];
     }
+    constructor(...args){
+        super(...args), mcp_tools_define_property(this, "initArgSpec", {
+            namespace: 'ios',
+            shape: iosInitArgShape,
+            cli: {
+                preferBareKeys: true
+            },
+            adapt: (extracted)=>extracted
+        }), mcp_tools_define_property(this, "lastOptsSignature", void 0);
+    }
 }
 const env_namespaceObject = require("@midscene/shared/env");
 const external_node_child_process_namespaceObject = require("node:child_process");

package/dist/lib/mcp-server.js

@@ -1359,17 +1359,47 @@ async function agentFromWebDriverAgent(opts) {
     await device.connect();
     return new IOSAgent(device, opts);
 }
+const base_tools_namespaceObject = require("@midscene/shared/mcp/base-tools");
+function mcp_tools_define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
 const debug = (0, logger_namespaceObject.getDebug)('mcp:ios-tools');
-class IOSMidsceneTools extends mcp_namespaceObject.BaseMidsceneTools {
+const iosInitArgShape = {
+    deviceId: core_namespaceObject.z.string().optional().describe('iOS device UDID (optional when WDA auto-detect is sufficient)'),
+    wdaHost: core_namespaceObject.z.string().optional().describe('WebDriverAgent host, defaults to localhost'),
+    wdaPort: core_namespaceObject.z.number().optional().describe('WebDriverAgent port'),
+    useWDA: core_namespaceObject.z.boolean().optional().describe('Whether to reuse an existing WebDriverAgent session'),
+    wdaMjpegPort: core_namespaceObject.z.number().optional().describe('WebDriverAgent MJPEG streaming port')
+};
+class IOSMidsceneTools extends base_tools_namespaceObject.BaseMidsceneTools {
     createTemporaryDevice() {
         return new IOSDevice({});
     }
-    async ensureAgent() {
+    async ensureAgent(opts) {
+        const hasOpts = !!opts && Object.keys(opts).length > 0;
+        const nextSignature = hasOpts ? JSON.stringify(opts) : void 0;
+        if (this.agent && hasOpts && nextSignature !== this.lastOptsSignature) {
+            try {
+                await this.agent.destroy?.();
+            } catch (error) {
+                debug('Failed to destroy agent during cleanup:', error);
+            }
+            this.agent = void 0;
+        }
         if (this.agent) return this.agent;
-        debug('Creating iOS agent with WebDriverAgent');
+        debug('Creating iOS agent with WebDriverAgent options:', opts || {});
         this.agent = await agentFromWebDriverAgent({
-            autoDismissKeyboard: false
+            autoDismissKeyboard: false,
+            ...opts ?? {}
         });
+        this.lastOptsSignature = nextSignature;
         return this.agent;
     }
     preparePlatformTools() {
@@ -1377,15 +1407,17 @@ class IOSMidsceneTools extends mcp_namespaceObject.BaseMidsceneTools {
             {
                 name: 'ios_connect',
                 description: 'Connect to iOS device or simulator via WebDriverAgent',
-                schema: {},
-                handler: async ()=>{
-                    const agent = await this.ensureAgent();
+                schema: this.getAgentInitArgSchema(),
+                cli: this.getAgentInitArgCliMetadata(),
+                handler: async (args)=>{
+                    const initArgs = this.extractAgentInitParam(args);
+                    const agent = await this.ensureAgent(initArgs);
                     const screenshot = await agent.page.screenshotBase64();
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: 'Connected to iOS device'
+                                text: `Connected to iOS device${initArgs?.deviceId ? `: ${initArgs.deviceId}` : ''}`
                             },
                             ...this.buildScreenshotContent(screenshot)
                         ],
@@ -1401,6 +1433,16 @@ class IOSMidsceneTools extends mcp_namespaceObject.BaseMidsceneTools {
             }
         ];
     }
+    constructor(...args){
+        super(...args), mcp_tools_define_property(this, "initArgSpec", {
+            namespace: 'ios',
+            shape: iosInitArgShape,
+            cli: {
+                preferBareKeys: true
+            },
+            adapt: (extracted)=>extracted
+        }), mcp_tools_define_property(this, "lastOptsSignature", void 0);
+    }
 }
 class IOSMCPServer extends mcp_namespaceObject.BaseMCPServer {
     createToolsManager() {
@@ -1409,7 +1451,7 @@ class IOSMCPServer extends mcp_namespaceObject.BaseMCPServer {
     constructor(toolsManager){
         super({
             name: '@midscene/ios-mcp',
-            version: "1.7.5-beta-20260421030751.0",
+            version: "1.7.5",
             description: 'Control the iOS device using natural language commands'
         }, toolsManager);
     }

package/dist/types/index.d.ts

@@ -3,9 +3,10 @@ import type { ActionParam } from '@midscene/core';
 import type { ActionReturn } from '@midscene/core';
 import { Agent } from '@midscene/core/agent';
 import { AgentOpt } from '@midscene/core/agent';
-import { BaseMidsceneTools } from '@midscene/shared/mcp';
+import { BaseMidsceneTools } from '@midscene/shared/mcp/base-tools';
 import { DeviceAction } from '@midscene/core';
 import type { ElementInfo } from '@midscene/shared/extractor';
+import { InitArgSpec } from '@midscene/shared/mcp/base-tools';
 import { InterfaceType } from '@midscene/core';
 import { IOSDeviceInputOpt } from '@midscene/core/device';
 import { IOSDeviceOpt } from '@midscene/core/device';
@@ -13,7 +14,7 @@ import { overrideAIConfig } from '@midscene/shared/env';
 import { PlaygroundPlatformDescriptor } from '@midscene/playground';
 import { Point } from '@midscene/core';
 import { Size } from '@midscene/core';
-import { ToolDefinition } from '@midscene/shared/mcp';
+import type { ToolDefinition } from '@midscene/shared/mcp/types';
 import { WebDriverClient } from '@midscene/webdriver';
 import { z } from '@midscene/core';
 
@@ -177,13 +178,17 @@ export declare class IOSDevice implements AbstractInterface {
     destroy(): Promise<void>;
 }
 
+declare type IOSInitArgs = Pick<IOSDeviceOpt, 'deviceId' | 'wdaHost' | 'wdaPort' | 'useWDA' | 'wdaMjpegPort'>;
+
 /**
  * iOS-specific tools manager
  * Extends BaseMidsceneTools to provide iOS WebDriverAgent connection tools
  */
-export declare class IOSMidsceneTools extends BaseMidsceneTools<IOSAgent> {
+export declare class IOSMidsceneTools extends BaseMidsceneTools<IOSAgent, IOSInitArgs> {
+    protected readonly initArgSpec: InitArgSpec<IOSInitArgs>;
+    private lastOptsSignature?;
     protected createTemporaryDevice(): IOSDevice;
-    protected ensureAgent(): Promise<IOSAgent>;
+    protected ensureAgent(opts?: IOSInitArgs): Promise<IOSAgent>;
     /**
      * Provide iOS-specific platform tools
      */