xc-mcp/dist/tools/simctl/io.d.ts

MCP server that wraps Xcode command-line tools for iOS/macOS development workflows

import { ScreenshotSize } from '../../utils/screenshot-sizing.js';
interface SimctlIoToolArgs {
    udid?: string;
    operation: 'screenshot' | 'video';
    outputPath?: string;
    codec?: string;
    size?: ScreenshotSize;
    appName?: string;
    screenName?: string;
    state?: string;
}
/**
 * Capture screenshot or record video from a simulator
 *
 * Examples:
 * - Screenshot: udid: "device-123", operation: "screenshot" (saves 256×512 optimized PNG)
 * - Full size: udid: "device-123", operation: "screenshot", size: "full" (native resolution)
 * - Custom output: udid: "device-123", operation: "screenshot", outputPath: "/tmp/my_screenshot.png"
 * - Semantic naming: udid: "device-123", operation: "screenshot", appName: "MyApp", screenName: "LoginScreen", state: "Empty"
 * - Record video: udid: "device-123", operation: "video"
 * - Custom codec: udid: "device-123", operation: "video", codec: "h264"
 *
 * Operations:
 * - screenshot: Capture current screen (with tile-aligned sizing)
 * - video: Record simulator screen (stop with Ctrl+C)
 *
 * Screenshot size optimization (default: 'half' for 50% token savings):
 * - half: 256×512 pixels, 1 tile, 170 tokens (DEFAULT)
 * - full: Native resolution, 2 tiles, 340 tokens
 * - quarter: 128×256 pixels, 1 tile, 170 tokens
 * - thumb: 128×128 pixels, 1 tile, 170 tokens
 *
 * Codecs for video: h264, hevc, prores
 *
 * LLM Optimization:
 * For semantic naming, provide appName, screenName, and state to generate filenames like:
 * MyApp_LoginScreen_Empty_2025-01-23.png (enables agents to reason about screens)
 *
 * **Full documentation:** See simctl/io.md for detailed parameters and examples
 */
export declare function simctlIoTool(args: SimctlIoToolArgs): Promise<{
    content: {
        type: "text";
        text: string;
    }[];
    isError: boolean;
}>;
export declare const SIMCTL_IO_DOCS = "\n# simctl-io\n\nCapture screenshots or record videos from iOS simulators with automatic optimization.\n\n## What it does\n\nCaptures simulator screen as optimized PNG images or records video with configurable\ncodecs. Screenshots are automatically resized to tile-aligned dimensions for token\nefficiency and support semantic naming for AI agent reasoning.\n\n## Parameters\n\n- **udid** (string, optional): Simulator UDID (auto-detects booted device if omitted)\n- **operation** (string, required): \"screenshot\" or \"video\"\n- **outputPath** (string, optional): Custom file path (auto-generated if omitted)\n- **codec** (string, optional): Video codec - h264, hevc, or prores (default: h264)\n- **size** (string, optional): Screenshot size - half, full, quarter, thumb (default: half)\n- **appName** (string, optional): App name for semantic naming\n- **screenName** (string, optional): Screen/view name for semantic naming\n- **state** (string, optional): UI state for semantic naming\n\n## Screenshot Size Optimization\n\nScreenshots are automatically optimized for token efficiency:\n\n- **half** (default): 256\u00D7512 pixels, 1 tile, 170 tokens (50% savings)\n- **full**: Native resolution, 2 tiles, 340 tokens\n- **quarter**: 128\u00D7256 pixels, 1 tile, 170 tokens\n- **thumb**: 128\u00D7128 pixels, 1 tile, 170 tokens\n\n## Semantic Naming (LLM Optimization)\n\nProvide appName, screenName, and state to generate semantic filenames:\n- Format: `{appName}_{screenName}_{state}_{date}.png`\n- Example: `MyApp_LoginScreen_Empty_2025-01-23.png`\n- Enables AI agents to reason about screen context and track state progression\n\n## Returns\n\nJSON response with:\n- File path and size information\n- Screenshot optimization metadata (dimensions, token count, savings)\n- Coordinate transform for mapping resized coordinates to device\n- Semantic metadata when provided\n- Guidance for viewing and using the capture\n\n## Examples\n\n### Capture optimized screenshot (default 256\u00D7512)\n```typescript\nawait simctlIoTool({\n  udid: 'device-123',\n  operation: 'screenshot'\n})\n```\n\n### Capture full-size screenshot\n```typescript\nawait simctlIoTool({\n  udid: 'device-123',\n  operation: 'screenshot',\n  size: 'full'\n})\n```\n\n### Capture with semantic naming\n```typescript\nawait simctlIoTool({\n  udid: 'device-123',\n  operation: 'screenshot',\n  appName: 'MyApp',\n  screenName: 'LoginScreen',\n  state: 'Empty'\n})\n```\n\n### Record video with custom codec\n```typescript\nawait simctlIoTool({\n  udid: 'device-123',\n  operation: 'video',\n  codec: 'hevc'\n})\n```\n\n## Common Use Cases\n\n1. **UI testing**: Capture screenshots for visual regression testing\n2. **Bug reporting**: Record videos demonstrating issues\n3. **Documentation**: Create screenshots for app documentation\n4. **State tracking**: Use semantic naming to track UI state progression\n5. **Token optimization**: Use half/quarter sizes for LLM-based analysis\n\n## Coordinate Transform\n\nWhen screenshots are resized (size \u2260 'full'), a coordinate transform is provided:\n- **scaleX**: Multiply screenshot X coordinates by this to get device coordinates\n- **scaleY**: Multiply screenshot Y coordinates by this to get device coordinates\n- **guidance**: Human-readable scaling instructions\n\nThis enables accurate element tapping even with optimized screenshots.\n\n## Important Notes\n\n- **Auto-detection**: If udid is omitted, automatically uses the booted device\n- **Temp files**: Screenshots saved to /tmp unless custom path specified\n- **Video recording**: Press Ctrl+C to stop video recording\n- **Simulator must be booted**: Operations require running simulator\n- **File permissions**: Ensure output path is writable\n\n## Error Handling\n\n- **Simulator not booted**: Indicates simulator must be booted first\n- **Simulator not found**: Validates simulator exists in cache\n- **File path errors**: Reports if output path is not writable\n- **Invalid operation**: Validates operation is \"screenshot\" or \"video\"\n\n## Next Steps After Capture\n\n1. **View screenshot**: `open \"<file-path>\"`\n2. **Copy to clipboard**: `pbcopy < \"<file-path>\"`\n3. **Analyze with LLM**: Use optimized size for token-efficient analysis\n4. **Use coordinates**: Apply transform to map screenshot coords to device\n";
export declare const SIMCTL_IO_DOCS_MINI = "Capture screenshots or record video. Use rtfm({ toolName: \"simctl-io\" }) for docs.";
export {};
//# sourceMappingURL=io.d.ts.map