replicant-mcp

Instructions

Implementation Reference

• src/tools/ui-action.ts:31-46 (handler)

  Main handler function for the 'ui-action' tool, which dispatches to specific operation handlers (tap, input, scroll).

  export async function handleUiActionTool(
    input: UiActionInput,
    context: ServerContext,
  ): Promise<Record<string, unknown>> {
    const device = await context.deviceState.ensureDevice(context.adb);
  
    const handler = operations[input.operation];
    if (!handler) {
      throw new ReplicantError(
        ErrorCode.INVALID_OPERATION,
        `Unknown operation: ${input.operation}`,
        "Valid operations: tap, input, scroll",
      );
    }
    return handler(input, context, device.id);
  }

• src/tools/ui-action.ts:6-17 (schema)

  Input schema definition for the 'ui-action' tool using Zod.

  export const uiActionInputSchema = z.object({
    operation: z.enum(["tap", "input", "scroll"]),
    x: z.number().optional(),
    y: z.number().optional(),
    elementIndex: z.number().optional(),
    text: z.string().optional(),
    direction: z.enum(["up", "down", "left", "right"]).optional(),
    amount: z.number().min(0).max(1).optional(),
    deviceSpace: z.boolean().optional(),
  });
  
  export type UiActionInput = z.infer<typeof uiActionInputSchema>;

• src/tools/ui-action.ts:115-141 (registration)

  Definition object for registering the 'ui-action' tool with the MCP server.

  export const uiActionToolDefinition = {
    name: "ui-action",
    description: "Interact with app UI: tap, input, scroll.",
    inputSchema: {
      type: "object",
      properties: {
        operation: {
          type: "string",
          enum: ["tap", "input", "scroll"],
        },
        x: { type: "number" },
        y: { type: "number" },
        elementIndex: { type: "number" },
        text: { type: "string" },
        direction: { type: "string", enum: ["up", "down", "left", "right"] },
        amount: { type: "number", minimum: 0, maximum: 1, description: "Scroll fraction (0-1, default: 0.5)" },
        deviceSpace: { type: "boolean", description: "Treat x/y as device coordinates (skip scaling)" },
      },
      required: ["operation"],
    },
    annotations: {
      readOnlyHint: false,
      destructiveHint: true,
      idempotentHint: false,
      openWorldHint: false,
    },
  };