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-launch 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

• bounded Android 11+ wireless ADB recovery

Related MCP server: android-mcp-tools

Deliberate non-capabilities

The public bridge is not an arbitrary remote shell. It does not expose generic shell execution, root, APK installation, delete, uninstall, or clear-data tools.

Verified actions follow observe -> one action -> bounded re-observation -> report; they are not silently replayed after ambiguous results.

Public export boundary

This repository does not contain real tunnel IDs, runtime credentials, owner-specific configuration, caches, private verification captures, or tunnel-client/cloudflared binaries.

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

Requirements

• Python 3.10+

• 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:

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

During public-release preparation on 2026-09-30, the focused public suite passed 216 tests across core ADB behavior, local vision, wireless reliability, Reflex, passive health, companion-owned integration, and Control Center logic.

Live ADB/device acceptance still depends on your own authorized device, OEM behavior, and local Android tooling.

Security model

Read SECURITY.md. Keep ADB authorization under the device owner's control and do not broaden the bridge into arbitrary shell execution merely for convenience.

License

Apache-2.0. See LICENSE and NOTICE.

Third-party components remain under their own licenses; see THIRD_PARTY_NOTICES.md.

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