@ebowwa/mcp-ios-devices 1.0.0

package/dist/tools/simulator.js

@@ -0,0 +1,446 @@
+/**
+ * Simulator Tools
+ * Control iOS Simulator via simctl
+ */
+import { z } from 'zod';
+import { registerTool } from '../registry.js';
+import { SimCtl } from '@ebowwa/ios-devices';
+const simCtl = new SimCtl();
+// ============================================================================
+// Device Management
+// ============================================================================
+registerTool({
+    name: 'sim_list',
+    description: 'List simulators, device types, or runtimes',
+    inputSchema: z.object({
+        devices: z.boolean().optional().describe('List devices'),
+        deviceTypes: z.boolean().optional().describe('List device types'),
+        runtimes: z.boolean().optional().describe('List runtimes'),
+        available: z.boolean().optional().describe('Only available'),
+        search: z.string().optional().describe('Search term'),
+    }),
+    handler: async (options) => {
+        return simCtl.list(options);
+    },
+});
+registerTool({
+    name: 'sim_create',
+    description: 'Create a new simulator',
+    inputSchema: z.object({
+        name: z.string().describe('Simulator name'),
+        deviceTypeId: z.string().describe('Device type (e.g., com.apple.CoreSimulator.SimDeviceType.iPhone-16)'),
+        runtimeId: z.string().describe('Runtime (e.g., com.apple.CoreSimulator.SimRuntime.iOS-18-1)'),
+    }),
+    handler: async ({ name, deviceTypeId, runtimeId }) => {
+        return simCtl.create(name, deviceTypeId, runtimeId);
+    },
+});
+registerTool({
+    name: 'sim_clone',
+    description: 'Clone an existing simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Source simulator UDID'),
+        name: z.string().describe('Name for cloned simulator'),
+    }),
+    handler: async ({ udid, name }) => {
+        return simCtl.clone(udid, name);
+    },
+});
+registerTool({
+    name: 'sim_delete',
+    description: 'Delete one or more simulators',
+    inputSchema: z.object({
+        udids: z.union([z.string(), z.array(z.string())]).describe('Simulator UDID(s) to delete'),
+    }),
+    handler: async ({ udids }) => {
+        return simCtl.delete(udids);
+    },
+});
+registerTool({
+    name: 'sim_delete_unavailable',
+    description: 'Delete all unavailable simulators',
+    inputSchema: z.object({}),
+    handler: async () => {
+        return simCtl.deleteUnavailable();
+    },
+});
+registerTool({
+    name: 'sim_erase',
+    description: 'Erase a simulator (reset to factory state)',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+    }),
+    handler: async ({ udid }) => {
+        return simCtl.erase(udid);
+    },
+});
+registerTool({
+    name: 'sim_rename',
+    description: 'Rename a simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        name: z.string().describe('New name'),
+    }),
+    handler: async ({ udid, name }) => {
+        return simCtl.rename(udid, name);
+    },
+});
+// ============================================================================
+// Boot/Shutdown
+// ============================================================================
+registerTool({
+    name: 'sim_boot',
+    description: 'Boot a simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID (or "booted" for any booted)'),
+    }),
+    handler: async ({ udid }) => {
+        return simCtl.boot(udid);
+    },
+});
+registerTool({
+    name: 'sim_shutdown',
+    description: 'Shutdown a simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+    }),
+    handler: async ({ udid }) => {
+        return simCtl.shutdown(udid);
+    },
+});
+registerTool({
+    name: 'sim_shutdown_all',
+    description: 'Shutdown all simulators',
+    inputSchema: z.object({}),
+    handler: async () => {
+        return simCtl.shutdownAll();
+    },
+});
+// ============================================================================
+// App Management
+// ============================================================================
+registerTool({
+    name: 'sim_install',
+    description: 'Install an app on a simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        appPath: z.string().describe('Path to .app bundle'),
+    }),
+    handler: async ({ udid, appPath }) => {
+        return simCtl.install(udid, appPath);
+    },
+});
+registerTool({
+    name: 'sim_uninstall',
+    description: 'Uninstall an app from a simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        bundleId: z.string().describe('App bundle identifier'),
+    }),
+    handler: async ({ udid, bundleId }) => {
+        return simCtl.uninstall(udid, bundleId);
+    },
+});
+registerTool({
+    name: 'sim_get_app_container',
+    description: 'Get the path to an app container',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        bundleId: z.string().describe('App bundle identifier'),
+        containerType: z.string().optional().describe('Container type (app, data, groups, etc.)'),
+    }),
+    handler: async ({ udid, bundleId, containerType }) => {
+        return simCtl.getAppContainer(udid, bundleId, containerType);
+    },
+});
+// ============================================================================
+// App Execution
+// ============================================================================
+registerTool({
+    name: 'sim_launch',
+    description: 'Launch an app on a simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        bundleId: z.string().describe('App bundle identifier'),
+        waitForDebugger: z.boolean().optional().describe('Wait for debugger to attach'),
+        console: z.boolean().optional().describe('Show console output'),
+        env: z.record(z.string()).optional().describe('Environment variables'),
+        args: z.array(z.string()).optional().describe('Arguments'),
+    }),
+    handler: async ({ udid, bundleId, waitForDebugger, console, env, args }) => {
+        return simCtl.launch(udid, bundleId, { waitForDebugger, console, env, args });
+    },
+});
+registerTool({
+    name: 'sim_terminate',
+    description: 'Terminate an app on a simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        bundleId: z.string().describe('App bundle identifier'),
+    }),
+    handler: async ({ udid, bundleId }) => {
+        return simCtl.terminate(udid, bundleId);
+    },
+});
+registerTool({
+    name: 'sim_spawn',
+    description: 'Spawn a process on a simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        executable: z.string().describe('Executable path'),
+        args: z.array(z.string()).optional().describe('Arguments'),
+    }),
+    handler: async ({ udid, executable, args }) => {
+        return simCtl.spawn(udid, executable, args);
+    },
+});
+// ============================================================================
+// IO Operations
+// ============================================================================
+registerTool({
+    name: 'sim_screenshot',
+    description: 'Take a screenshot of a simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        outputPath: z.string().describe('Output file path'),
+        type: z.enum(['png', 'jpeg', 'tiff']).optional().default('png'),
+    }),
+    handler: async ({ udid, outputPath, type }) => {
+        return simCtl.screenshot(udid, outputPath, { type });
+    },
+});
+registerTool({
+    name: 'sim_record_video',
+    description: 'Record video of a simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        outputPath: z.string().describe('Output file path (.mp4)'),
+        codec: z.enum(['h264', 'hevc']).optional(),
+    }),
+    handler: async ({ udid, outputPath, codec }) => {
+        return simCtl.recordVideo(udid, outputPath, { codec });
+    },
+});
+// ============================================================================
+// Location
+// ============================================================================
+registerTool({
+    name: 'sim_set_location',
+    description: 'Set simulated location on a simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        latitude: z.number().describe('Latitude'),
+        longitude: z.number().describe('Longitude'),
+    }),
+    handler: async ({ udid, latitude, longitude }) => {
+        return simCtl.setLocation(udid, latitude, longitude);
+    },
+});
+registerTool({
+    name: 'sim_reset_location',
+    description: 'Reset simulated location',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+    }),
+    handler: async ({ udid }) => {
+        return simCtl.resetLocation(udid);
+    },
+});
+// ============================================================================
+// Status Bar
+// ============================================================================
+registerTool({
+    name: 'sim_status_bar_override',
+    description: 'Override status bar appearance',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        time: z.string().optional().describe('Time (e.g., "9:41")'),
+        dataNetwork: z.string().optional().describe('Data network type'),
+        wifiMode: z.enum(['active', 'searching', 'failed']).optional(),
+        cellularMode: z.enum(['active', 'searching', 'failed']).optional(),
+        batteryLevel: z.number().optional().describe('Battery level (0-100)'),
+        batteryState: z.enum(['charging', 'charged', 'discharging']).optional(),
+    }),
+    handler: async ({ udid, ...overrides }) => {
+        return simCtl.statusBar(udid, overrides);
+    },
+});
+registerTool({
+    name: 'sim_status_bar_clear',
+    description: 'Clear status bar overrides',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+    }),
+    handler: async ({ udid }) => {
+        return simCtl.clearStatusBar(udid);
+    },
+});
+// ============================================================================
+// URL & Notifications
+// ============================================================================
+registerTool({
+    name: 'sim_open_url',
+    description: 'Open a URL on a simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        url: z.string().describe('URL to open'),
+    }),
+    handler: async ({ udid, url }) => {
+        return simCtl.openURL(udid, url);
+    },
+});
+registerTool({
+    name: 'sim_push_notification',
+    description: 'Send a simulated push notification',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        bundleId: z.string().describe('App bundle identifier'),
+        payload: z.record(z.any()).describe('Push notification payload'),
+    }),
+    handler: async ({ udid, bundleId, payload }) => {
+        return simCtl.push(udid, bundleId, payload);
+    },
+});
+// ============================================================================
+// Privacy
+// ============================================================================
+registerTool({
+    name: 'sim_grant_privacy',
+    description: 'Grant privacy permission to an app',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        bundleId: z.string().describe('App bundle identifier'),
+        service: z.string().describe('Service name (e.g., camera, microphone, photos)'),
+    }),
+    handler: async ({ udid, bundleId, service }) => {
+        return simCtl.grantPrivacy(udid, bundleId, service);
+    },
+});
+registerTool({
+    name: 'sim_revoke_privacy',
+    description: 'Revoke privacy permission from an app',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        bundleId: z.string().describe('App bundle identifier'),
+        service: z.string().describe('Service name'),
+    }),
+    handler: async ({ udid, bundleId, service }) => {
+        return simCtl.revokePrivacy(udid, bundleId, service);
+    },
+});
+// ============================================================================
+// Keychain
+// ============================================================================
+registerTool({
+    name: 'sim_keychain_add',
+    description: 'Add item to simulator keychain',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        service: z.string().describe('Service name'),
+        account: z.string().describe('Account name'),
+        password: z.string().describe('Password'),
+    }),
+    handler: async ({ udid, service, account, password }) => {
+        return simCtl.keychainAdd(udid, service, account, password);
+    },
+});
+registerTool({
+    name: 'sim_keychain_reset',
+    description: 'Reset simulator keychain',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+    }),
+    handler: async ({ udid }) => {
+        return simCtl.keychainReset(udid);
+    },
+});
+// ============================================================================
+// Environment & Diagnostics
+// ============================================================================
+registerTool({
+    name: 'sim_getenv',
+    description: 'Get environment variable from simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        variable: z.string().optional().describe('Variable name (omit for all)'),
+    }),
+    handler: async ({ udid, variable }) => {
+        return simCtl.getenv(udid, variable);
+    },
+});
+registerTool({
+    name: 'sim_diagnose',
+    description: 'Collect simulator diagnostics',
+    inputSchema: z.object({
+        outputPath: z.string().optional().describe('Output path'),
+    }),
+    handler: async ({ outputPath }) => {
+        return simCtl.diagnose(outputPath);
+    },
+});
+// ============================================================================
+// Media & iCloud
+// ============================================================================
+registerTool({
+    name: 'sim_add_media',
+    description: 'Add media (photos/videos) to simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        mediaPaths: z.union([z.string(), z.array(z.string())]).describe('Path(s) to media files'),
+    }),
+    handler: async ({ udid, mediaPaths }) => {
+        return simCtl.addMedia(udid, mediaPaths);
+    },
+});
+registerTool({
+    name: 'sim_icloud_sync',
+    description: 'Trigger iCloud sync on simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+    }),
+    handler: async ({ udid }) => {
+        return simCtl.icloudSync(udid);
+    },
+});
+// ============================================================================
+// Pasteboard
+// ============================================================================
+registerTool({
+    name: 'sim_pbpaste',
+    description: 'Get pasteboard contents from simulator',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+    }),
+    handler: async ({ udid }) => {
+        return simCtl.pbpaste(udid);
+    },
+});
+// ============================================================================
+// UI
+// ============================================================================
+registerTool({
+    name: 'sim_set_appearance',
+    description: 'Set simulator appearance (light/dark mode)',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        appearance: z.enum(['light', 'dark']),
+    }),
+    handler: async ({ udid, appearance }) => {
+        return simCtl.setUI(udid, { appearance });
+    },
+});
+// ============================================================================
+// Runtime
+// ============================================================================
+registerTool({
+    name: 'sim_upgrade',
+    description: 'Upgrade simulator to a new runtime',
+    inputSchema: z.object({
+        udid: z.string().describe('Simulator UDID'),
+        runtimeId: z.string().describe('Target runtime ID'),
+    }),
+    handler: async ({ udid, runtimeId }) => {
+        return simCtl.upgrade(udid, runtimeId);
+    },
+});
+//# sourceMappingURL=simulator.js.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ebowwa/mcp-ios-devices",
+  "version": "1.0.0",
+  "description": "MCP server for iOS device control - devicectl, libimobiledevice, simctl",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "mcp-ios-devices": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "mcp",
+    "ios",
+    "device",
+    "devicectl",
+    "simctl",
+    "libimobiledevice",
+    "iphone",
+    "ipad",
+    "simulator",
+    "xcode"
+  ],
+  "author": "ebowwa",
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@ebowwa/ios-devices": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ebowwa/codespaces",
+    "directory": "packages/mcp/mcp-ios-devices"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,189 @@
+#!/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: z.ZodType<any>): any {
+  if (schema instanceof z.ZodObject) {
+    const properties: Record<string, any> = {};
+    const required: string[] = [];
+
+    for (const [key, value] of Object.entries(schema.shape)) {
+      properties[key] = zodToJsonSchema(value as z.ZodType<any>);
+      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);
+});

package/src/registry.ts

@@ -0,0 +1,23 @@
+/**
+ * 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>;
+}
+
+// Tool registry
+export const tools: ToolDefinition[] = [];
+
+/**
+ * Register a tool
+ */
+export function registerTool(options: ToolDefinition): void {
+  tools.push(options);
+}