Android MCP Server

Instructions

Implementation Reference

• src/adb/file-manager.ts:21-60 (handler)

  The actual handler function that executes 'ls -la' via ADB and parses the output into a FileEntry array.

  export async function listFiles(remotePath: string, deviceId?: string): Promise<FileEntry[]> {
    const resolved = await deviceManager.resolveDeviceId(deviceId);
    const validPath = validateDevicePath(remotePath);
  
    const result = await adbShell(['ls', '-la', validPath], resolved);
  
    const entries: FileEntry[] = [];
    const lines = result.stdout.split('\n').filter(l => l.trim());
  
    for (const line of lines) {
      // Skip the 'total' line
      if (line.startsWith('total ')) continue;
  
      // Parse ls -la output: drwxr-xr-x 2 root root 4096 2024-01-01 00:00 dirname
      const match = line.match(
        /^([a-z\-ldrwxsSt@+]+)\s+\d+\s+\S+\s+\S+\s+(\d+)\s+(\d{4}-\d{2}-\d{2})\s+(\d{2}:\d{2})\s+(.+)$/
      );
  
      if (match) {
        const [, permissions, sizeStr, date, time, name] = match;
  
        let type: FileEntry['type'] = 'unknown';
        if (permissions.startsWith('d')) type = 'directory';
        else if (permissions.startsWith('l')) type = 'symlink';
        else if (permissions.startsWith('-')) type = 'file';
  
        entries.push({
          name: name.trim(),
          type,
          permissions,
          size: parseInt(sizeStr, 10),
          date,
          time,
        });
      }
    }
  
    log.info(`Listed ${entries.length} files`, { remotePath: validPath, deviceId: resolved });
    return entries;
  }

• src/controllers/file-tools.ts:8-28 (registration)

  The MCP tool registration for 'list_files', which defines its schema and connects the tool to the listFiles implementation.

  server.registerTool(
    'list_files',
    {
      description: 'List files and directories at a given path on the Android device. Returns file names, types, sizes, and permissions.',
      inputSchema: {
        path: z.string().describe('Absolute path on the Android device (e.g. /sdcard/Download)'),
        device_id: z.string().optional().describe('Device serial number'),
      },
    },
    async ({ path, device_id }) => {
      return await metrics.measure('list_files', device_id || 'default', async () => {
        const files = await listFiles(path, device_id);
        return {
          content: [{
            type: 'text' as const,
            text: JSON.stringify({ success: true, path, count: files.length, files }, null, 2),
          }],
        };
      });
    }
  );