xc-mcp
Version:
MCP server that wraps Xcode command-line tools for iOS/macOS development workflows
101 lines • 10.5 kB
TypeScript
interface IdbUiGestureArgs {
udid?: string;
operation: 'swipe' | 'button';
direction?: 'up' | 'down' | 'left' | 'right';
startX?: number;
startY?: number;
endX?: number;
endY?: number;
duration?: number;
profile?: 'standard' | 'flick' | 'gentle';
buttonType?: 'HOME' | 'LOCK' | 'SIDE_BUTTON' | 'APPLE_PAY' | 'SIRI' | 'SCREENSHOT' | 'APP_SWITCH';
actionName?: string;
expectedOutcome?: string;
}
/**
* Perform gestures and hardware button presses - swipes, scrolls, and device controls for navigation
*
* **What it does:**
* Executes swipe gestures (directional or custom paths) and hardware button presses on iOS targets.
* Supports standard swipe directions (up, down, left, right) with automatic screen-relative path calculation
* using configurable profiles (flick, swipe, drag), custom swipe paths with precise start/end coordinates,
* and hardware button simulation (HOME, LOCK, SIRI, SCREENSHOT, APP_SWITCH). Automatically validates velocity
* to ensure iOS recognizes gestures as swipes (>6000 px/sec). Validates coordinates against device bounds and
* provides semantic action tracking.
*
* **Why you'd use it:**
* - Automate scroll and navigation gestures - swipe to reveal content, dismiss modals, page through carousels
* - Use optimized swipe profiles for different UIs - flick for fast page changes, swipe for standard scrolling, drag for slow interactions
* - Test hardware button interactions without physical device access - home button, lock, app switching
* - Execute precise custom swipe paths for complex gesture-based UIs (drawing, map navigation)
* - Track gesture-based test scenarios with semantic metadata (actionName, expectedOutcome)
*
* **Swipe Profiles (Empirically Tested):**
* - "standard": Default balance (75% distance, 200ms, 1475 points/sec) - perfect for general navigation
* - "flick": Fast page changes (85% distance, 120ms, 2775 points/sec) - use for carousel/rapid navigation
* - "gentle": Slow scrolling (50% distance, 300ms, 653 points/sec) - reliable but near-minimum threshold
*
* All coordinates in POINT space (393×852 for iPhone 16 Pro), NOT pixel space (1179×2556).
* All profiles tested and verified working on iOS 18.5 home screen.
*
* **Parameters:**
* - operation (required): "swipe" | "button"
* - direction (for swipe): "up" | "down" | "left" | "right" - auto-calculates screen-relative path
* - profile (for swipe): "standard" | "flick" | "gentle" - gesture profile (default: "standard")
* - startX, startY, endX, endY (for custom swipe): Precise POINT coordinates for swipe path
* - duration (optional, for swipe): Swipe duration in MILLISECONDS (e.g., 200 for 200ms, default: 200ms) - uses profile default if omitted
* - buttonType (for button): "HOME" | "LOCK" | "SIDE_BUTTON" | "APPLE_PAY" | "SIRI" | "SCREENSHOT" | "APP_SWITCH"
* - udid (optional): Target identifier - auto-detects if omitted
* - actionName, expectedOutcome (optional): Semantic tracking for test documentation
*
* **Returns:**
* Gesture execution status with operation details (direction/button, path coordinates for swipes),
* duration, velocity info, gesture context metadata, error details if failed, and verification guidance.
*
* **Example:**
* ```typescript
* // Standard swipe up (default profile, 1475 pts/sec)
* const result = await idbUiGestureTool({
* operation: 'swipe',
* direction: 'up',
* actionName: 'Scroll to Bottom',
* expectedOutcome: 'Reveal footer content'
* });
*
* // Flick swipe for fast page navigation (2775 pts/sec)
* await idbUiGestureTool({
* operation: 'swipe',
* direction: 'left',
* profile: 'flick',
* actionName: 'Go to Next Page'
* });
*
* // Gentle swipe for reliable slow scrolling (653 pts/sec)
* await idbUiGestureTool({
* operation: 'swipe',
* direction: 'down',
* profile: 'gentle',
* actionName: 'Slow Scroll',
* expectedOutcome: 'Smooth scrolling without jumps'
* });
*
* // Press home button to background app
* await idbUiGestureTool({ operation: 'button', buttonType: 'HOME' });
* ```
*
* **Full documentation:** See idb/ui-gesture.md for detailed parameters and button types
*
* @param args Tool arguments with operation type and gesture/button details
* @returns Tool result with gesture status and path information
*/
export declare function idbUiGestureTool(args: IdbUiGestureArgs): Promise<{
content: {
type: "text";
text: string;
}[];
isError: boolean;
}>;
export declare const IDB_UI_GESTURE_DOCS = "\n# idb-ui-gesture\n\n\uD83D\uDC46 **Perform gestures and hardware button presses** - swipes, scrolls, and device controls for navigation\n\n## What it does\n\nExecutes swipe gestures (directional or custom paths) and hardware button presses on iOS targets. Supports standard swipe directions (up, down, left, right) with automatic screen-relative path calculation using configurable profiles (flick, swipe, drag), custom swipe paths with precise start/end coordinates, and hardware button simulation (HOME, LOCK, SIRI, SCREENSHOT, APP_SWITCH). Automatically validates velocity to ensure iOS recognizes gestures as swipes (>6000 px/sec). Validates coordinates against device bounds and provides semantic action tracking.\n\n## Why you'd use it\n\n- Automate scroll and navigation gestures - swipe to reveal content, dismiss modals, page through carousels\n- Use optimized swipe profiles for different UIs - flick for fast page changes, swipe for standard scrolling, drag for slow interactions\n- Test hardware button interactions without physical device access - home button, lock, app switching\n- Execute precise custom swipe paths for complex gesture-based UIs (drawing, map navigation)\n- Track gesture-based test scenarios with semantic metadata (actionName, expectedOutcome)\n\n## Parameters\n\n### Required\n- **operation** (string): \"swipe\" | \"button\"\n\n### Swipe operation parameters\n- **direction** (string): \"up\" | \"down\" | \"left\" | \"right\" - auto-calculates screen-relative path\n- **profile** (string, default: \"standard\"): \"standard\" | \"flick\" | \"gentle\" - gesture profile\n- **startX, startY, endX, endY** (numbers): Precise POINT coordinates for custom swipe path\n- **duration** (number, default: 200): Swipe duration in MILLISECONDS (e.g., 200 for 200ms) - uses profile default if omitted\n\n### Button operation parameters\n- **buttonType** (string): \"HOME\" | \"LOCK\" | \"SIDE_BUTTON\" | \"APPLE_PAY\" | \"SIRI\" | \"SCREENSHOT\" | \"APP_SWITCH\"\n\n### Optional\n- **udid** (string): Target identifier - auto-detects if omitted\n- **actionName** (string): Semantic action name (e.g., \"Scroll to Bottom\")\n- **expectedOutcome** (string): Expected result (e.g., \"Reveal footer content\")\n\n## Swipe Profiles (Empirically Tested)\n\n- **standard**: Default balance (75% distance, 200ms, 1475 points/sec) - perfect for general navigation\n- **flick**: Fast page changes (85% distance, 120ms, 2775 points/sec) - use for carousel/rapid navigation\n- **gentle**: Slow scrolling (50% distance, 300ms, 653 points/sec) - reliable but near-minimum threshold\n\nAll coordinates in POINT space (393\u00D7852 for iPhone 16 Pro), NOT pixel space. All profiles tested and verified working on iOS 18.5 home screen.\n\n## Complete JSON Examples\n\n### Swipe Up (Scroll Down)\n```json\n{\"operation\": \"swipe\", \"direction\": \"up\", \"profile\": \"standard\", \"actionName\": \"Scroll Down\"}\n```\n\n### Swipe Down (Scroll Up)\n```json\n{\"operation\": \"swipe\", \"direction\": \"down\", \"profile\": \"standard\", \"actionName\": \"Scroll Up\"}\n```\n\n### Swipe Left (Navigate Forward)\n```json\n{\"operation\": \"swipe\", \"direction\": \"left\", \"profile\": \"standard\", \"actionName\": \"Go to Next Page\"}\n```\n\n### Swipe Right (Navigate Back)\n```json\n{\"operation\": \"swipe\", \"direction\": \"right\", \"profile\": \"standard\", \"actionName\": \"Go to Previous Page\"}\n```\n\n### Flick Swipe (Fast Page Navigation)\n```json\n{\"operation\": \"swipe\", \"direction\": \"left\", \"profile\": \"flick\", \"duration\": 120, \"actionName\": \"Fast Swipe to Next\"}\n```\n\n### Gentle Swipe (Slow Scrolling)\n```json\n{\"operation\": \"swipe\", \"direction\": \"up\", \"profile\": \"gentle\", \"duration\": 300, \"actionName\": \"Slow Scroll Down\"}\n```\n\n### Custom Swipe Path (Precise Coordinates)\n```json\n{\"operation\": \"swipe\", \"startX\": 196, \"startY\": 600, \"endX\": 196, \"endY\": 200, \"duration\": 200, \"actionName\": \"Custom Scroll\"}\n```\n\n### Press Home Button\n```json\n{\"operation\": \"button\", \"buttonType\": \"HOME\", \"actionName\": \"Background App\"}\n```\n\n### Press Lock Button\n```json\n{\"operation\": \"button\", \"buttonType\": \"LOCK\", \"actionName\": \"Lock Device\"}\n```\n\n### Press Side Button\n```json\n{\"operation\": \"button\", \"buttonType\": \"SIDE_BUTTON\", \"actionName\": \"Trigger Side Button Action\"}\n```\n\n### Press Siri Button\n```json\n{\"operation\": \"button\", \"buttonType\": \"SIRI\", \"actionName\": \"Activate Siri\"}\n```\n\n### Press Screenshot Button\n```json\n{\"operation\": \"button\", \"buttonType\": \"SCREENSHOT\", \"actionName\": \"Capture Screenshot\"}\n```\n\n### Press App Switch Button\n```json\n{\"operation\": \"button\", \"buttonType\": \"APP_SWITCH\", \"actionName\": \"Show App Switcher\"}\n```\n\n## Returns\n\nGesture execution status with operation details (direction/button, path coordinates for swipes), duration, velocity info, gesture context metadata, error details if failed, and verification guidance.\n\n## Examples\n\n### Standard swipe up (default profile)\n```typescript\nconst result = await idbUiGestureTool({\n operation: 'swipe',\n direction: 'up',\n actionName: 'Scroll to Bottom',\n expectedOutcome: 'Reveal footer content'\n});\n```\n\n### Flick swipe for fast page navigation\n```typescript\nawait idbUiGestureTool({\n operation: 'swipe',\n direction: 'left',\n profile: 'flick',\n actionName: 'Go to Next Page'\n});\n```\n\n### Press home button\n```typescript\nawait idbUiGestureTool({ operation: 'button', buttonType: 'HOME' });\n```\n\n## Related Tools\n\n- idb-ui-tap: For precise element tapping\n- idb-ui-describe: Find element coordinates\n";
export declare const IDB_UI_GESTURE_DOCS_MINI = "Perform gestures and button presses. Use rtfm({ toolName: \"idb-ui-gesture\" }) for docs.";
export {};
//# sourceMappingURL=ui-gesture.d.ts.map