scrcpy-mcp: Instructions file for Codex

AGENTS.md

Guidelines for AI coding agents working on scrcpy-mcp.

Project Overview

scrcpy-mcp is a Model Context Protocol (MCP) server that provides AI agents with vision and control over Android devices via ADB and scrcpy. It exposes tools for device management, input, screenshots, and more.

Project Documentation

• docs/ROADMAP.md - Implementation roadmap with phases and milestones
• docs/PLAN.md - Detailed implementation plan with architecture and tool specifications
• docs/AUDIO_PLAN.md - Audio streaming design (phases, protocol facts, task checklist)
• docs/CONTRIBUTING.md - Contributor workflow

Build/Lint/Test Commands

# Build the project
npm run build

# Development mode (run directly with tsx)
npm run dev

# Run the built server
npm start

# Run MCP Inspector for testing
npm run inspect

# Lint check
npm run lint

# Lint with auto-fix
npm run lint:fix

# Type check
npx tsc --noEmit

# Run all tests
npm run test

# Run integration tests only
npm run test:integration

# Run a single test file
npx vitest run tests/example.test.ts

# Run tests matching a pattern
npx vitest run --testNamePattern "device"

Project Structure

src/
├── index.ts           # Entry point, server setup, tool registration
├── utils/
│   ├── adb.ts         # ADB utility functions (exec, device detection, etc.)
│   ├── audio.ts       # Audio hub, playback sink, recording/clip encoder sinks
│   ├── ffmpeg.ts      # ffmpeg/ffplay binary resolution
│   ├── scrcpy.ts      # scrcpy session lifecycle, control protocol, video decode
│   ├── mjpeg.ts       # HTTP MJPEG server and ffplay viewer launcher
│   └── constants.ts   # Shared constants (protocol types, env vars, keycodes)
└── tools/
    ├── apps.ts        # App management (start, stop, install, uninstall, list, current)
    ├── audio.ts       # Audio streaming, recording, and clip capture tools
    ├── clipboard.ts   # Clipboard get/set (scrcpy + ADB fallback)
    ├── device.ts      # Device management (list, info, screen, panels, rotation, WiFi)
    ├── files.ts       # File push/pull/list
    ├── input.ts       # Touch/keyboard/scroll input (scrcpy + ADB fallback)
    ├── session.ts     # scrcpy session start/stop
    ├── shell.ts       # Arbitrary ADB shell command execution
    ├── ui.ts          # UI hierarchy dump and element finder
    ├── video.ts       # MJPEG video stream start/stop
    └── vision.ts      # Screenshot and recording