@ebowwa/mcp-ios-devices 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+/**
+ * @ebowwa/mcp-ios-devices
+ * MCP server for iOS device control
+ *
+ * Provides 80+ tools for:
+ * - Physical device management (devicectl, libimobiledevice)
+ * - Simulator control (simctl)
+ * - App installation and management
+ * - Process management
+ * - Logging and diagnostics
+ * - File system access
+ * - Screenshots and location spoofing
+ * - Backup and restore
+ */
+import './tools/device.js';
+import './tools/process.js';
+import './tools/app.js';
+import './tools/log.js';
+import './tools/file.js';
+import './tools/simulator.js';
+import './tools/backup.js';
+import './tools/location.js';
+import './tools/screenshot.js';
+import './tools/diagnostics.js';
+import './tools/profile.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+/**
+ * @ebowwa/mcp-ios-devices
+ * MCP server for iOS device control
+ *
+ * Provides 80+ tools for:
+ * - Physical device management (devicectl, libimobiledevice)
+ * - Simulator control (simctl)
+ * - App installation and management
+ * - Process management
+ * - Logging and diagnostics
+ * - File system access
+ * - Screenshots and location spoofing
+ * - Backup and restore
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+// Import registry
+import { tools } from './registry.js';
+// Import all tool modules (side effects - they register themselves)
+import './tools/device.js';
+import './tools/process.js';
+import './tools/app.js';
+import './tools/log.js';
+import './tools/file.js';
+import './tools/simulator.js';
+import './tools/backup.js';
+import './tools/location.js';
+import './tools/screenshot.js';
+import './tools/diagnostics.js';
+import './tools/profile.js';
+// Create MCP server
+const server = new Server({
+    name: '@ebowwa/mcp-ios-devices',
+    version: '1.0.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Handle list tools request
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema
+                ? zodToJsonSchema(tool.inputSchema)
+                : { type: 'object', properties: {} },
+        })),
+    };
+});
+// Handle tool execution
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const tool = tools.find((t) => t.name === name);
+    if (!tool) {
+        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+    }
+    try {
+        // Validate input
+        const validatedArgs = tool.inputSchema?.parse(args) ?? args;
+        // Execute tool
+        const result = await tool.handler(validatedArgs);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            const messages = error.errors.map((e) => e.message).join(', ');
+            throw new McpError(ErrorCode.InvalidParams, `Invalid parameters: ${messages}`);
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new McpError(ErrorCode.InternalError, `Tool execution failed: ${errorMessage}`);
+    }
+});
+/**
+ * Convert Zod schema to JSON Schema for MCP
+ */
+function zodToJsonSchema(schema) {
+    if (schema instanceof z.ZodObject) {
+        const properties = {};
+        const required = [];
+        for (const [key, value] of Object.entries(schema.shape)) {
+            properties[key] = zodToJsonSchema(value);
+            if (!(value instanceof z.ZodOptional)) {
+                required.push(key);
+            }
+        }
+        return {
+            type: 'object',
+            properties,
+            required: required.length > 0 ? required : undefined,
+        };
+    }
+    if (schema instanceof z.ZodString) {
+        return { type: 'string', description: schema.description };
+    }
+    if (schema instanceof z.ZodNumber) {
+        return { type: 'number', description: schema.description };
+    }
+    if (schema instanceof z.ZodBoolean) {
+        return { type: 'boolean', description: schema.description };
+    }
+    if (schema instanceof z.ZodArray) {
+        return {
+            type: 'array',
+            items: zodToJsonSchema(schema.element),
+            description: schema.description,
+        };
+    }
+    if (schema instanceof z.ZodEnum) {
+        return {
+            type: 'string',
+            enum: schema.options,
+            description: schema.description,
+        };
+    }
+    if (schema instanceof z.ZodOptional) {
+        return zodToJsonSchema(schema.unwrap());
+    }
+    if (schema instanceof z.ZodDefault) {
+        return zodToJsonSchema(schema._def.innerType);
+    }
+    if (schema instanceof z.ZodLiteral) {
+        return { type: 'string', enum: [schema.value] };
+    }
+    if (schema instanceof z.ZodUnion) {
+        return {
+            oneOf: schema.options.map(zodToJsonSchema),
+        };
+    }
+    return { type: 'object' };
+}
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('iOS Devices MCP server running');
+}
+main().catch((error) => {
+    console.error('Server error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/registry.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tool registry for MCP server
+ * Separated to avoid circular dependencies
+ */
+import { z } from 'zod';
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: z.ZodType<any>;
+    handler: (params: any) => Promise<any>;
+}
+export declare const tools: ToolDefinition[];
+/**
+ * Register a tool
+ */
+export declare function registerTool(options: ToolDefinition): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.js

@@ -0,0 +1,13 @@
+/**
+ * Tool registry for MCP server
+ * Separated to avoid circular dependencies
+ */
+// Tool registry
+export const tools = [];
+/**
+ * Register a tool
+ */
+export function registerTool(options) {
+    tools.push(options);
+}
+//# sourceMappingURL=registry.js.map

package/dist/tools/app.d.ts

@@ -0,0 +1,6 @@
+/**
+ * App Management Tools
+ * Install, uninstall, and manage apps on iOS devices
+ */
+export {};
+//# sourceMappingURL=app.d.ts.map

package/dist/tools/app.js

@@ -0,0 +1,53 @@
+/**
+ * App Management Tools
+ * Install, uninstall, and manage apps on iOS devices
+ */
+import { z } from 'zod';
+import { registerTool } from '../registry.js';
+import { DeviceCtl } from '@ebowwa/ios-devices';
+const deviceCtl = new DeviceCtl();
+registerTool({
+    name: 'ios_list_apps',
+    description: 'List all installed apps on a device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+    }),
+    handler: async ({ deviceId }) => {
+        return deviceCtl.listApps(deviceId);
+    },
+});
+registerTool({
+    name: 'ios_install_app',
+    description: 'Install an app (.app or .ipa) on the device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        appPath: z.string().describe('Path to .app or .ipa file'),
+    }),
+    handler: async ({ deviceId, appPath }) => {
+        return deviceCtl.installApp(deviceId, appPath);
+    },
+});
+registerTool({
+    name: 'ios_uninstall_app',
+    description: 'Uninstall an app from the device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        bundleId: z.string().describe('App bundle identifier'),
+    }),
+    handler: async ({ deviceId, bundleId }) => {
+        return deviceCtl.uninstallApp(deviceId, bundleId);
+    },
+});
+registerTool({
+    name: 'ios_get_app_icon',
+    description: 'Get the icon for an app',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        bundleId: z.string().describe('App bundle identifier'),
+        outputPath: z.string().optional().describe('Path to save icon'),
+    }),
+    handler: async ({ deviceId, bundleId, outputPath }) => {
+        return deviceCtl.getAppIcon(deviceId, bundleId, outputPath);
+    },
+});
+//# sourceMappingURL=app.js.map

package/dist/tools/backup.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Backup & Restore Tools
+ * Create and restore device backups
+ */
+export {};
+//# sourceMappingURL=backup.d.ts.map

package/dist/tools/backup.js

@@ -0,0 +1,66 @@
+/**
+ * Backup & Restore Tools
+ * Create and restore device backups
+ */
+import { z } from 'zod';
+import { registerTool } from '../registry.js';
+import { LibIMobileDevice } from '@ebowwa/ios-devices';
+registerTool({
+    name: 'ios_create_backup',
+    description: 'Create a backup of the device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        directory: z.string().describe('Directory for backup'),
+        encrypt: z.boolean().optional().describe('Encrypt backup'),
+        password: z.string().optional().describe('Password for encrypted backup'),
+    }),
+    handler: async ({ deviceId, directory, encrypt, password }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        return lib.createBackup(directory, encrypt, password);
+    },
+});
+registerTool({
+    name: 'ios_restore_backup',
+    description: 'Restore a backup to the device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        directory: z.string().describe('Backup directory'),
+        password: z.string().optional().describe('Password for encrypted backup'),
+    }),
+    handler: async ({ deviceId, directory, password }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        return lib.restoreBackup(directory, password);
+    },
+});
+registerTool({
+    name: 'ios_list_backups',
+    description: 'List available backups',
+    inputSchema: z.object({}),
+    handler: async () => {
+        const lib = new LibIMobileDevice();
+        return lib.listBackups();
+    },
+});
+registerTool({
+    name: 'ios_get_backup_info',
+    description: 'Get information about a backup',
+    inputSchema: z.object({
+        directory: z.string().describe('Backup directory'),
+    }),
+    handler: async ({ directory }) => {
+        const lib = new LibIMobileDevice();
+        return lib.getBackupInfo(directory);
+    },
+});
+registerTool({
+    name: 'ios_unpack_backup',
+    description: 'Unpack a backup to a directory',
+    inputSchema: z.object({
+        directory: z.string().describe('Backup directory'),
+    }),
+    handler: async ({ directory }) => {
+        const lib = new LibIMobileDevice();
+        return lib.unpackBackup(directory);
+    },
+});
+//# sourceMappingURL=backup.js.map

package/dist/tools/device.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Device Management Tools
+ * Physical iOS device control via devicectl and libimobiledevice
+ */
+export {};
+//# sourceMappingURL=device.d.ts.map

package/dist/tools/device.js

@@ -0,0 +1,180 @@
+/**
+ * Device Management Tools
+ * Physical iOS device control via devicectl and libimobiledevice
+ */
+import { z } from 'zod';
+import { registerTool } from '../registry.js';
+import { DeviceCtl, LibIMobileDevice } from '@ebowwa/ios-devices';
+const deviceCtl = new DeviceCtl();
+// ============================================================================
+// Device Listing & Info
+// ============================================================================
+registerTool({
+    name: 'ios_list_devices',
+    description: 'List all connected iOS devices',
+    inputSchema: z.object({}),
+    handler: async () => {
+        return deviceCtl.listDevices();
+    },
+});
+registerTool({
+    name: 'ios_device_info',
+    description: 'Get detailed information about a specific device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID, name, or ECID'),
+    }),
+    handler: async ({ deviceId }) => {
+        return deviceCtl.getDeviceInfo(deviceId);
+    },
+});
+registerTool({
+    name: 'ios_device_lock_state',
+    description: 'Get the lock state of a device (locked/unlocked)',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+    }),
+    handler: async ({ deviceId }) => {
+        return deviceCtl.getLockState(deviceId);
+    },
+});
+registerTool({
+    name: 'ios_device_displays',
+    description: 'Get display information for a device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+    }),
+    handler: async ({ deviceId }) => {
+        return deviceCtl.getDisplays(deviceId);
+    },
+});
+// ============================================================================
+// Pairing
+// ============================================================================
+registerTool({
+    name: 'ios_pair_device',
+    description: 'Pair with an iOS device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+    }),
+    handler: async ({ deviceId }) => {
+        return deviceCtl.pair(deviceId);
+    },
+});
+registerTool({
+    name: 'ios_unpair_device',
+    description: 'Unpair from an iOS device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+    }),
+    handler: async ({ deviceId }) => {
+        return deviceCtl.unpair(deviceId);
+    },
+});
+// ============================================================================
+// Device Control
+// ============================================================================
+registerTool({
+    name: 'ios_reboot_device',
+    description: 'Reboot an iOS device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+    }),
+    handler: async ({ deviceId }) => {
+        return deviceCtl.reboot(deviceId);
+    },
+});
+registerTool({
+    name: 'ios_set_orientation',
+    description: 'Set device orientation',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        orientation: z.enum(['portrait', 'landscape', 'portrait-upside-down', 'landscape-left', 'landscape-right']),
+    }),
+    handler: async ({ deviceId, orientation }) => {
+        return deviceCtl.setOrientation(deviceId, orientation);
+    },
+});
+registerTool({
+    name: 'ios_respring',
+    description: 'Respring the device (restart SpringBoard UI)',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+    }),
+    handler: async ({ deviceId }) => {
+        return deviceCtl.respring(deviceId);
+    },
+});
+// ============================================================================
+// LibIMobileDevice Tools (Additional)
+// ============================================================================
+registerTool({
+    name: 'ios_get_device_name',
+    description: 'Get or set the device name',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        newName: z.string().optional().describe('New name (omit to get current name)'),
+    }),
+    handler: async ({ deviceId, newName }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        if (newName) {
+            return lib.setDeviceName(newName);
+        }
+        return lib.getDeviceName();
+    },
+});
+registerTool({
+    name: 'ios_get_device_date',
+    description: 'Get the current date/time from the device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+    }),
+    handler: async ({ deviceId }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        return lib.getDeviceDate();
+    },
+});
+registerTool({
+    name: 'ios_shutdown_device',
+    description: 'Shutdown the device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+    }),
+    handler: async ({ deviceId }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        return lib.shutdown();
+    },
+});
+registerTool({
+    name: 'ios_restart_device',
+    description: 'Restart the device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+    }),
+    handler: async ({ deviceId }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        return lib.restart();
+    },
+});
+registerTool({
+    name: 'ios_sleep_device',
+    description: 'Put the device to sleep',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+    }),
+    handler: async ({ deviceId }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        return lib.sleep();
+    },
+});
+registerTool({
+    name: 'ios_enter_recovery',
+    description: 'Put device into recovery mode',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+    }),
+    handler: async ({ deviceId }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        return lib.enterRecovery();
+    },
+});
+//# sourceMappingURL=device.js.map

package/dist/tools/diagnostics.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Diagnostics Tools
+ * Device diagnostics and information
+ */
+export {};
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/tools/diagnostics.js

@@ -0,0 +1,81 @@
+/**
+ * Diagnostics Tools
+ * Device diagnostics and information
+ */
+import { z } from 'zod';
+import { registerTool } from '../registry.js';
+import { LibIMobileDevice } from '@ebowwa/ios-devices';
+registerTool({
+    name: 'ios_get_diagnostics',
+    description: 'Get device diagnostics (WiFi, Battery, NAND, etc.)',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        type: z.enum(['All', 'WiFi', 'GasGauge', 'NAND', 'Battery', 'HDMI']).default('All'),
+    }),
+    handler: async ({ deviceId, type }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        return lib.getDiagnostics(type);
+    },
+});
+registerTool({
+    name: 'ios_get_ioreg',
+    description: 'Get IO Registry information',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        plane: z.enum(['IODeviceTree', 'IOPower', 'IOService']).optional(),
+    }),
+    handler: async ({ deviceId, plane }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        return lib.getIORegistry(plane);
+    },
+});
+registerTool({
+    name: 'ios_get_mobilegestalt',
+    description: 'Get MobileGestalt values from device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        keys: z.array(z.string()).describe('Keys to query'),
+    }),
+    handler: async ({ deviceId, keys }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        return lib.getMobileGestalt(...keys);
+    },
+});
+registerTool({
+    name: 'ios_mount_image',
+    description: 'Mount developer disk image on device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        imagePath: z.string().describe('Path to developer disk image'),
+        signaturePath: z.string().optional().describe('Path to signature file'),
+    }),
+    handler: async ({ deviceId, imagePath, signaturePath }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        return lib.mountImage(imagePath, signaturePath);
+    },
+});
+registerTool({
+    name: 'ios_start_debug_server',
+    description: 'Start debug server proxy for remote debugging',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        port: z.number().default(6666).describe('Port for debug server'),
+    }),
+    handler: async ({ deviceId, port }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        return lib.startDebugServerProxy(port);
+    },
+});
+registerTool({
+    name: 'ios_start_bluetooth_logger',
+    description: 'Start Bluetooth packet logging',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        outputPath: z.string().optional().describe('Output file path'),
+    }),
+    handler: async ({ deviceId, outputPath }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        return lib.startBluetoothLogging(outputPath);
+    },
+});
+//# sourceMappingURL=diagnostics.js.map

package/dist/tools/file.d.ts

@@ -0,0 +1,6 @@
+/**
+ * File System Tools
+ * Access files on iOS devices via AFC
+ */
+export {};
+//# sourceMappingURL=file.d.ts.map

package/dist/tools/file.js

@@ -0,0 +1,55 @@
+/**
+ * File System Tools
+ * Access files on iOS devices via AFC
+ */
+import { z } from 'zod';
+import { registerTool } from '../registry.js';
+import { DeviceCtl, LibIMobileDevice } from '@ebowwa/ios-devices';
+const deviceCtl = new DeviceCtl();
+registerTool({
+    name: 'ios_list_files',
+    description: 'List files in a directory on the device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        path: z.string().describe('Directory path to list'),
+    }),
+    handler: async ({ deviceId, path }) => {
+        return deviceCtl.listFiles(deviceId, path);
+    },
+});
+registerTool({
+    name: 'ios_copy_to_device',
+    description: 'Copy a file to the device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        source: z.string().describe('Local source path'),
+        destination: z.string().describe('Device destination path'),
+    }),
+    handler: async ({ deviceId, source, destination }) => {
+        return deviceCtl.copyToDevice(deviceId, source, destination);
+    },
+});
+registerTool({
+    name: 'ios_copy_from_device',
+    description: 'Copy a file from the device',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+        source: z.string().describe('Device source path'),
+        destination: z.string().describe('Local destination path'),
+    }),
+    handler: async ({ deviceId, source, destination }) => {
+        return deviceCtl.copyFromDevice(deviceId, source, destination);
+    },
+});
+registerTool({
+    name: 'ios_start_afc_shell',
+    description: 'Start an AFC shell for file system access',
+    inputSchema: z.object({
+        deviceId: z.string().describe('Device UDID'),
+    }),
+    handler: async ({ deviceId }) => {
+        const lib = new LibIMobileDevice({ udid: deviceId });
+        return lib.startAFCShell();
+    },
+});
+//# sourceMappingURL=file.js.map