Android MCP Server

Instructions

Implementation Reference

• src/adb/input-controller.ts:34-47 (handler)

  The handler implementation for the tap tool, which resolves device ID, checks rate limits, validates coordinates, and executes the ADB tap command.

  export async function tap(x: number, y: number, deviceId?: string): Promise<{ x: number; y: number }> {
    const resolved = await deviceManager.resolveDeviceId(deviceId);
    deviceManager.checkRateLimit(resolved);
  
    const coords = await normalizeCoordinates(x, y, resolved);
    validateCoordinate(coords.x, 'x');
    validateCoordinate(coords.y, 'y');
  
    await adbShell(['input', 'tap', String(coords.x), String(coords.y)], resolved);
    deviceManager.touchSession(resolved);
  
    log.info('Tap performed', { x: coords.x, y: coords.y, deviceId: resolved });
    return coords;
  }

• src/controllers/input-tools.ts:46-83 (registration)

  The MCP tool registration for 'tap', which handles input validation using zod, checks execution context, invokes the core tap handler, and performs post-action verification.

  server.registerTool(
    'tap',
    {
      description: 'Tap at specific coordinates on the Android screen. Coordinates can be absolute pixels or normalized (0-1 range, will be scaled to screen size).',
      inputSchema: {
        x: z.number().describe('X coordinate (pixels or 0-1 normalized)'),
        y: z.number().describe('Y coordinate (pixels or 0-1 normalized)'),
        device_id: z.string().optional().describe('Device serial number'),
      },
    },
    async ({ x, y, device_id }) => {
      return await metrics.measure('tap', device_id || 'default', async () => {
        const resolved = await deviceManager.resolveDeviceId(device_id);
        const execCtx = executionEngine.preExecutionCheck('tap', { x, y }, resolved);
  
        if (!execCtx.allowed) {
          return {
            content: [{
              type: 'text' as const,
              text: JSON.stringify({
                success: false,
                blocked: true,
                reason: execCtx.blockReason,
                _context: execCtx.recentContext,
              }, null, 2),
            }],
          };
        }
  
        const preHash = await capturePreActionState(resolved);
        const result = await tap(x, y, resolved);
        invalidateCaches(resolved);
        const verification = await verifyAction('tap', resolved, preHash);
  
        return buildVerifiedResponse({ tapped: result }, execCtx, verification);
      });
    }
  );