Yunkai Phone Bridge

A local-first Android MCP bridge for bounded device perception and interaction over ADB.

This repository is a sanitized public-source export of the PhoneBridge used in the Yunkai project. It keeps the important control boundaries: read-only inspection first, a narrow ADB action surface, semantic/reflex UI targeting, deterministic verification, local policy, and passive health/status surfaces.

Highlights

• Android device discovery and bounded ADB connectivity

• screenshots and UI hierarchy inspection

• allowlisted key and app/URI actions

• semantic/reflex UI observation and guarded verified taps

• passive health and runtime status

• capability manifest, permission state, and unified device contract adapter

• optional localhost-only vision fallback

• companion-owned local integration surface

• source-only Control Center helper

Related MCP server: ThumbAgent

Deliberate non-capabilities

The public bridge is not an arbitrary remote shell. Keep ADB authorization under the device owner's control and preserve the existing action, identity, policy, and verification gates.

Public export boundary

This repository does not contain real tunnel IDs, runtime credentials, owner-specific configuration, caches, local verification captures, or tunnel-client binaries. The private secure-tunnel launchers and bundled cloudflared executables are intentionally omitted from this first public source release.

The shared contract modules required by the bridge are included under yunkai_shared/.

Requirements

• Python 3.11+

• Android Platform Tools / adb installed locally

• an Android device you are authorized to control, with ADB debugging enabled and paired/authorized

• Python dependencies in requirements.txt

Quick start

git clone https://github.com/YunkaiLim/yunkai-phone-bridge.git
cd yunkai-phone-bridge
py -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
adb devices
cd PhoneBridge
python server_stdio.py

For the local HTTP entry point used by the original bridge:

cd PhoneBridge
python server.py

Optional local vision can be configured by copying PhoneBridge/phonebridge_vision.example.json to phonebridge_vision.json. Reflex policy has a separate checked-in example file.

Tests

From PhoneBridge/:

python -m unittest

The private working tree passed 217 unit tests immediately before this public export. Live ADB/device acceptance still depends on the user's own authorized device and local Android tooling.

Security model

Read SECURITY.md. Do not broaden this bridge into arbitrary shell execution merely for convenience; the narrow surface is intentional.

License

Apache-2.0. See LICENSE and NOTICE.

This project is independent source code and is not an official OpenAI product.