"
+```
+
+> [!IMPORTANT]
+> Bearer 토큰은 `Authorization` 헤더에 넣으세요. URL이나 쿼리 문자열에 접근 토큰을 넣지 마세요.
+
+## MCP 도구
+
+### `list_devices()`
+
+연결된 Android 기기 목록을 반환합니다. 에이전트 버전, 연결 시간, 대기 중인 명령 수 등의 연결 정보도 포함합니다.
+
+### `run_shell({ cmd, deviceId?, timeoutMs? })`
+
+Android shell uid(`2000`) 권한으로 명령을 실행하고 stdout, stderr, 종료 코드, 실행 시간 정보를 반환합니다. 여러 기기가 동시에 연결된 경우에만 `deviceId`가 필요합니다.
+
+```text
+run_shell({ "cmd": "getprop ro.product.model" })
+```
+
+전체 도구 계약은 [`docs/USAGE.md`](docs/USAGE.md#5-tool-reference)를 참고하세요.
+
+## 저장소 구조
+
+```text
+app/ Android Kotlin 에이전트
+server/cmd/relay/ MCP + WebSocket 릴레이
+server/cmd/publicserver/ 공개 버전/APK 서버
+cli/ rish-mcp-setup npm 패키지
+docs/ 설계, 사용법, 릴리스 문서
+before/ 레거시 Shizuku + Node/TypeScript 구현
+```
+
+## 소스에서 빌드
+
+### Go 서버
+
+```bash
+cd server
+go build ./...
+go test ./...
+```
+
+### 서버 컨테이너
+
+```bash
+docker build --target relay -t rishmcp-relay server
+docker build --target publicserver -t rishmcp-public server
+```
+
+### Android 디버그 빌드
+
+저장소 루트에서 실행합니다.
+
+```bash
+docker build -t rishmcp-android-build -f app/Dockerfile.build app
+
+docker run --rm -v "$PWD/app:/work" -w /work rishmcp-android-build \
+ gradle --no-daemon testDebugUnitTest assembleDebug
+```
+
+디버그 APK 출력 경로:
+
+```text
+app/app/build/outputs/apk/debug/app-debug.apk
+```
+
+공식 서명 빌드는 엄격한 `agent-vMAJOR.MINOR.PATCH` 태그를 사용하는 [Android 릴리스 워크플로](.github/workflows/release.yml)에서 생성됩니다.
+
+## 배포
+
+Traefik/Dokploy용 Compose 설정이 포함되어 있습니다.
+
+```bash
+cp .env.example .env
+# MCP_HOST / PUBLIC_MCP_HOST를 수정하고 두 비밀값을 교체하세요.
+openssl rand -hex 32
+
+docker network create dokploy-network # 필요한 경우 한 번만
+docker compose up -d --build
+curl -fsS "https://${MCP_HOST}/healthz"
+```
+
+릴레이는 셸 접근 비밀값과 기기 트래픽을 처리합니다. 별도의 공개 서버는 릴레이 토큰을 받지 않으며 릴리스 메타데이터와 APK만 제공합니다.
+
+환경 변수, OAuth, 리버스 프록시 설정, 문제 해결은 [`docs/USAGE.md`](docs/USAGE.md)를 참고하세요.
+
+## 보안 모델
+
+> [!WARNING]
+> `AI_TOKEN`은 연결된 기기에 원격 `adb shell` 접근 권한을 제공하는 것과 사실상 같습니다. SSH 개인 키와 비슷한 수준의 고가치 자격 증명으로 취급하세요.
+
+- 명령은 root가 아니라 **shell uid 2000**으로 실행됩니다.
+- Android 에이전트가 릴레이에 먼저 연결하며, 기기에 인바운드 셸 서비스를 열지 않습니다.
+- 실제 배포에서는 **HTTPS/WSS**를 사용하세요.
+- `AI_TOKEN`, `DEVICE_TOKEN`은 외부에 노출하지 말고 유출 가능성이 있으면 교체하세요.
+- 범위는 의도적으로 **단일 사용자 / 기기 소유자 운영**이며 멀티테넌트 원격 기기 플랫폼을 목표로 하지 않습니다.
+
+취약점은 [`SECURITY.md`](SECURITY.md)의 안내에 따라 비공개로 제보해 주세요.
+
+## 릴리스 채널
+
+| 채널 | 의미 |
+| --- | --- |
+| `agent-v*` | 현재 Android 리라이트 아티팩트 |
+| `v0.2.0`–`v0.5.0` | 레거시 Shizuku 앱, 현재 리라이트와 호환되지 않음 |
+| npm `rish-mcp-setup` | 릴레이/클라이언트 설정 전용. Android APK는 설치하지 않음 |
+
+승격 조건과 서명 세부 정보는 [`docs/RELEASES.md`](docs/RELEASES.md)에 있습니다.
+
+## 문서
+
+| 문서 | 내용 |
+| --- | --- |
+| [`docs/USAGE.md`](docs/USAGE.md) | 배포, 페어링, MCP 도구, OAuth, 프로토콜, 문제 해결 |
+| [`docs/DESIGN.md`](docs/DESIGN.md) | 현재 아키텍처와 구현 범위 |
+| [`docs/RELEASES.md`](docs/RELEASES.md) | 릴리스 채널, 서명, 승격 조건 |
+| [`plan.md`](plan.md) | 리라이트 이유와 프로젝트 방향 |
+| [`cli/README.md`](cli/README.md) | `rish-mcp-setup` CLI 레퍼런스 |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | 기여 가이드 |
+
+## 기여
+
+이슈와 Pull Request를 환영합니다. 기여 전 [`CONTRIBUTING.md`](CONTRIBUTING.md)를 읽어 주세요.
+
+## 라이선스
+
+rish-mcp는 [MIT License](LICENSE)로 배포됩니다.
diff --git a/README.md b/README.md
index 01f923b..2dedfe0 100644
--- a/README.md
+++ b/README.md
@@ -1,195 +1,250 @@
+
+
# rish-mcp
+**Give AI assistants secure, self-hosted MCP access to your Android device's `adb shell` — without root, Shizuku, or a permanently attached PC.**
+
[](https://github.com/turin-dev/rish-mcp/actions/workflows/ci.yml)
[](https://github.com/turin-dev/rish-mcp/actions/workflows/codeql.yml)
+[](https://www.npmjs.com/package/rish-mcp-setup)
[](LICENSE)
-Expose an Android device's own shell (uid 2000, like `adb shell`) to AIs as an
-**MCP tool** — without VPN, adb-from-a-PC-forever, or sshd. The device holds a
-single **outbound** WebSocket to a relay on a public hostname you control; AIs
-call the relay's MCP endpoint.
+**English** · [한국어](README.ko.md)
-```
- 상시 WS (일반 기기)
-┌─────────┐ MCP ┌──────────────────┐ ◀───────────────── ┌──────────────┐
-│ AI │──HTTPS─▶│ Go relay + MCP │ │ Android 앱 │
-│(Claude) │ ◀───────│ 서버 │──FCM 웨이크업──────▶│ (저사양 기기) │
-└─────────┘ └──────────────────┘ (Google FCM 경유) └──────────────┘
- │
- │ 버전/체크섬 조회, APK 배포
- ▼
- ┌──────────────────┐
- │ 공식 버전 서버 │ (별도 바이너리/컨테이너, 무토큰)
- └──────────────────┘
-```
+
-> **This is a from-scratch rewrite in progress.** The previous Shizuku +
-> Node/TS implementation lives under [`before/`](before/) for reference. See
-> [`plan.md`](plan.md) for why it was rebuilt and [`docs/DESIGN.md`](docs/DESIGN.md)
-> for the current architecture and what's actually implemented vs. still
-> pending — read that before assuming anything below is production-ready.
+> [!WARNING]
+> **The rewrite is still in preview.** The Go relay and Android agent are usable for controlled testing, but the current Android rewrite has not completed the real-device stable-release gates. Read [Release channels](docs/RELEASES.md) before treating it as production-ready.
> [!CAUTION]
-> GitHub releases `v0.2.0` through `v0.5.0` contain the legacy Shizuku-based
-> application. They are not compatible release artifacts for this rewrite.
-> A signed rewrite preview is available as `agent-v0.1.0`, but it has not yet
-> passed the real-device stable-release gates. Use it only for controlled
-> testing; see [Release channels](docs/RELEASES.md) for the exact acceptance
-> boundary and promotion gates.
-
-## Why rewrite
-
-The old agent depended on [Shizuku](https://shizuku.rikka.app/) — a separate
-app the user had to install, understand, and grant permission to, which also
-meant devices that didn't support or know about Shizuku couldn't use rish-mcp
-at all. See [`plan.md`](plan.md) for the full rationale (Shizuku dependency,
-Wear OS performance, server code quality, no official version endpoint).
-
-## What's different this time
-
-- **No Shizuku.** The Android app pairs with its own `adbd` directly —
- wireless-debugging pairing on Android 11+, a PC+`adb tcpip` bridge below
- that. See [`docs/DESIGN.md` §3.1](docs/DESIGN.md#31-셸-접근-페어링-shizuku-대체).
-- **Go relay**, not Node/TS — same MCP tool contracts (`run_shell`,
- `list_devices`), same WS relay protocol, same OAuth model, rewritten for
- concurrency/memory efficiency and a single static binary.
-- **Hybrid connection model** (planned): normal phones/tablets keep an
- always-on WebSocket; low-spec devices (Wear OS) are meant to move to an
- FCM-wake + short session model instead. **Not implemented yet** — it needs
- a Firebase project this repo doesn't have configured. Every device
- currently uses the always-on path.
-
-## Status
-
-| Piece | State |
-|---|---|
-| Go relay (`server/cmd/relay`) — MCP tools, WS relay, static bearer + OAuth | ✅ built, tested |
-| Official version server (`server/cmd/publicserver`) | ✅ built, tested |
-| Android `AdbShellClient` (ADB pairing, shell exec) | ✅ built, tested (unit-testable parts only — no device to pair against in this environment) |
-| `ConnectionManager` / `AgentService` / `MainActivity` (pairing UI) | ✅ built, compiles — **not verified against a real device** |
-| Low-spec hybrid connection + FCM wake | ⛔ blocked — needs a Firebase project (see `docs/DESIGN.md` §7) |
-| Docker packaging for the Go binaries | ✅ `server/Dockerfile` (`--target relay` / `--target publicserver`) |
-| docker-compose / reverse-proxy deploy config | ✅ `docker-compose.yml` (Traefik/Dokploy) |
-| Signed rewrite APK | 🧪 `agent-v0.1.0` preview published — stable promotion pending real-device gates |
-
-## Components
-
-- `server/cmd/relay` — Go. Streamable-HTTP **MCP server** (`run_shell`,
- `list_devices`) + **WS relay** the Android device connects to. Static
- bearer or OAuth for AIs, shared token for the device.
-- `server/cmd/publicserver` — Go. Separate, secret-free binary: reports the
- current agent version and serves the APK. No route to the relay.
-- `app/` — Android (Kotlin). One installable APK: pairs with the device's own
- `adbd` to run commands as shell uid, a foreground service holds the
- outbound WS, auto-starts on boot.
-
-## Quick start: relay server and MCP client
-
-The npm package deliberately handles only server/client setup. It does not
-download, build, install, or update the Android APK.
+> GitHub releases `v0.2.0` through `v0.5.0` belong to the legacy Shizuku-based implementation. The rewrite uses the separate `agent-v*` release channel. The current signed preview is `agent-v0.1.0`.
+
+## What is rish-mcp?
+
+rish-mcp exposes an Android device's own shell (`uid 2000`, equivalent to `adb shell`) as MCP tools for AI clients.
+
+The Android agent opens an **outbound-only WebSocket** to a relay you control. AI clients connect to that relay through **MCP over Streamable HTTP** and authenticate with a bearer token. The device does not need to accept inbound Internet connections, so the setup works behind NAT/CGNAT.
+
+```text
+ outbound WebSocket
+┌──────────────┐ MCP/HTTPS ┌──────────────────────┐ ◀────────────────── ┌──────────────┐
+│ AI client │ ────────────▶ │ Go relay + MCP │ │ Android agent│
+│ Claude, etc. │ ◀──────────── │ server/cmd/relay │ ── shell command ─▶ │ adb shell │
+└──────────────┘ └──────────────────────┘ ◀── result/output ── └──────────────┘
+ │
+ │ version metadata / APK
+ ▼
+ ┌──────────────────────┐
+ │ Public version server│
+ │ server/cmd/publicserver
+ └──────────────────────┘
+```
+
+The previous Node/TypeScript + Shizuku implementation is kept under [`before/`](before/) for reference. See [`plan.md`](plan.md) for the rewrite rationale and [`docs/DESIGN.md`](docs/DESIGN.md) for the architecture.
+
+## Highlights
+
+- **No root and no Shizuku** — the Android app talks directly to the device's own `adbd`.
+- **MCP-native** — exposes `list_devices` and `run_shell` through a remote Streamable HTTP MCP endpoint.
+- **Outbound-only agent connection** — no inbound port needs to be opened on the phone.
+- **Self-hosted relay** — keep shell-access credentials and command traffic on infrastructure you control.
+- **Go relay** — compact deployment, straightforward concurrency, and a single server binary per target.
+- **Android Kotlin agent** — wireless-debugging pairing on Android 11+, with an `adb tcpip` fallback for older devices.
+- **Separate public update service** — release metadata/APK serving stays outside the shell-access trust boundary.
+
+## Project status
+
+| Component | Status |
+| --- | --- |
+| Go relay (`server/cmd/relay`) — MCP, WebSocket relay, bearer auth + OAuth | ✅ Built and tested |
+| Public version server (`server/cmd/publicserver`) | ✅ Built and tested |
+| Android `AdbShellClient` — pairing and shell execution | ✅ Built; unit-testable parts tested |
+| Android UI/service — `MainActivity`, `AgentService`, `ConnectionManager` | 🧪 Builds successfully; real-device validation still in progress |
+| Signed rewrite APK | 🧪 `agent-v0.1.0` preview available |
+| Docker packaging / Compose deployment | ✅ Available |
+| Low-spec hybrid mode + FCM wake | ⛔ Planned; requires Firebase configuration |
+
+## Quick start
+
+### 1. Set up the relay
+
+The easiest path is the npm setup utility. Docker is required for the server action.
```bash
-# interactive menu: install relay server or create MCP client config
+# interactive setup
npx rish-mcp-setup
-# non-interactive relay install/update
+# or install/update the relay non-interactively
npx rish-mcp-setup --yes --action server
+```
+
+The installer creates or reuses `AI_TOKEN` and `DEVICE_TOKEN`, stores them under `~/.config/rish-mcp/relay.env`, and runs the `rish-mcp-relay` container.
+
+For reverse-proxy, Compose, and manual deployment options, see [`docs/USAGE.md`](docs/USAGE.md).
+
+### 2. Install and pair the Android agent
+
+Use a signed `agent-v*` artifact from [GitHub Releases](https://github.com/turin-dev/rish-mcp/releases) and follow the release notes.
+
+On **Android 11+**, enable **Developer options → Wireless debugging → Pair device with pairing code**, then enter the pairing information in the rish-mcp app. On older Android versions, use the documented PC-assisted `adb tcpip` flow.
+
+Detailed pairing instructions are in [`docs/USAGE.md`](docs/USAGE.md#3-pair-the-android-agent).
+
+### 3. Connect an MCP client
-# non-interactive MCP client config
+Create a client configuration automatically:
+
+```bash
npx rish-mcp-setup --yes --action client \
--url https://mcp.example.com/mcp \
--token "$AI_TOKEN"
```
-The server action requires Docker. The client action writes a standard
-`mcpServers` entry under `~/.config/rish-mcp/client.json`. Android agent
-artifacts are distributed separately through the signed `agent-v*` GitHub
-release channel; local Android builds remain documented below.
+Or configure a compatible MCP client manually:
-See [`cli/README.md`](cli/README.md) for all npm setup options.
+```json
+{
+ "mcpServers": {
+ "phone": {
+ "type": "http",
+ "url": "https://mcp.example.com/mcp",
+ "headers": {
+ "Authorization": "Bearer "
+ }
+ }
+ }
+}
+```
-## Build
+For Claude CLI, the equivalent setup is:
```bash
-# server (both binaries)
-cd server && go build ./... && go test ./...
+claude mcp add --transport http phone https://mcp.example.com/mcp \
+ --header "Authorization: Bearer "
+```
+
+> [!IMPORTANT]
+> Put the bearer token in the `Authorization` header. Do not place access tokens in URLs or query strings.
+
+## MCP tools
-# server Docker images
+### `list_devices()`
+
+Lists connected Android devices, including connection metadata such as agent version, connection age, and pending command count.
+
+### `run_shell({ cmd, deviceId?, timeoutMs? })`
+
+Runs a command as Android shell uid (`2000`) and returns stdout, stderr, exit code, and timing information. `deviceId` is only required when more than one device is connected.
+
+```text
+run_shell({ "cmd": "getprop ro.product.model" })
+```
+
+See [`docs/USAGE.md`](docs/USAGE.md#5-tool-reference) for the full tool contract.
+
+## Repository layout
+
+```text
+app/ Android Kotlin agent
+server/cmd/relay/ MCP + WebSocket relay
+server/cmd/publicserver/ Public version/APK server
+cli/ rish-mcp-setup npm package
+docs/ Design, usage, and release documentation
+before/ Legacy Shizuku + Node/TypeScript implementation
+```
+
+## Build from source
+
+### Go servers
+
+```bash
+cd server
+go build ./...
+go test ./...
+```
+
+### Server containers
+
+```bash
docker build --target relay -t rishmcp-relay server
docker build --target publicserver -t rishmcp-public server
+```
+
+### Android debug build
+
+From the repository root:
-# Android unit tests + debug APK (run from the repository root)
+```bash
docker build -t rishmcp-android-build -f app/Dockerfile.build app
+
docker run --rm -v "$PWD/app:/work" -w /work rishmcp-android-build \
gradle --no-daemon testDebugUnitTest assembleDebug
-# output: app/app/build/outputs/apk/debug/app-debug.apk
```
-Official signed rewrite APKs are built by the tag-driven
-[Android release workflow](.github/workflows/release.yml) from strict
-`agent-vMAJOR.MINOR.PATCH` tags. The workflow verifies tag/version metadata,
-builds and tests the release APK, signs it with the repository's official
-key, verifies the signature, publishes a SHA-256 checksum, and creates a
-GitHub **prerelease**. Do not promote that prerelease to stable until the
-real-device acceptance gates in [`docs/RELEASES.md`](docs/RELEASES.md) are
-recorded.
+Debug APK output:
+
+```text
+app/app/build/outputs/apk/debug/app-debug.apk
+```
+
+Official signed builds are produced by the tag-driven [Android release workflow](.github/workflows/release.yml) using strict `agent-vMAJOR.MINOR.PATCH` tags.
-## Deploy
+## Deployment
-For a Dokploy host with an external Traefik network, copy `.env.example` to
-`.env`, set the two hostnames and generate `AI_TOKEN`/`DEVICE_TOKEN`, then run:
+A Compose configuration for Traefik/Dokploy is included:
```bash
cp .env.example .env
-# edit .env and replace both secrets
+# Edit MCP_HOST / PUBLIC_MCP_HOST and replace both secrets.
openssl rand -hex 32
-docker network create dokploy-network # once, if it does not exist
+docker network create dokploy-network # once, if needed
docker compose up -d --build
curl -fsS "https://${MCP_HOST}/healthz"
```
-`docker-compose.yml` keeps the trust boundary explicit: the relay receives
-shell-access secrets and serves MCP/agent traffic, while the separate
-publicserver serves only release metadata and the APK. For all variables and
-manual Docker deployment, see [`docs/USAGE.md`](docs/USAGE.md).
+The relay receives shell-access secrets and device traffic. The separate public server receives no relay token and only serves release metadata and the APK.
-## Use from an AI (MCP client)
+See [`docs/USAGE.md`](docs/USAGE.md) for environment variables, OAuth, reverse-proxy settings, and troubleshooting.
-Same tool surface as before — this part of the contract didn't change:
+## Security model
-```json
-{
- "mcpServers": {
- "phone": {
- "type": "http",
- "url": "https://mcp.example.com/mcp",
- "headers": { "Authorization": "Bearer " }
- }
- }
-}
-```
+> [!WARNING]
+> `AI_TOKEN` effectively grants remote `adb shell` access to connected devices. Treat it like an SSH private key or other high-value credential.
+
+- Commands run as **shell uid 2000**, not root.
+- The Android agent initiates the connection to the relay; it does not expose an inbound shell service.
+- Use **HTTPS/WSS** in real deployments.
+- Keep `AI_TOKEN` and `DEVICE_TOKEN` secret and rotate them if they may have leaked.
+- Scope is intentionally **single-user / owner-operated**, not a multi-tenant remote-device platform.
+
+Please report vulnerabilities privately as described in [`SECURITY.md`](SECURITY.md).
+
+## Release channels
+
+| Channel | Meaning |
+| --- | --- |
+| `agent-v*` | Current Android rewrite artifacts |
+| `v0.2.0`–`v0.5.0` | Legacy Shizuku application; incompatible with the rewrite |
+| npm `rish-mcp-setup` | Relay/client setup utility only; it does **not** install the Android APK |
+
+Promotion requirements and signing details live in [`docs/RELEASES.md`](docs/RELEASES.md).
+
+## Documentation
+
+| Document | Contents |
+| --- | --- |
+| [`docs/USAGE.md`](docs/USAGE.md) | Deployment, pairing, MCP tools, OAuth, protocol details, troubleshooting |
+| [`docs/DESIGN.md`](docs/DESIGN.md) | Current architecture and implementation boundaries |
+| [`docs/RELEASES.md`](docs/RELEASES.md) | Release channels, signing, and promotion gates |
+| [`plan.md`](plan.md) | Rewrite rationale and project direction |
+| [`cli/README.md`](cli/README.md) | `rish-mcp-setup` CLI reference |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Contribution guide |
+
+## Contributing
+
+Issues and pull requests are welcome. Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) before contributing.
+
+## License
-- `list_devices()` — connected devices, agent version, connection age, and
- pending-command count.
-- `run_shell({cmd, deviceId?, timeoutMs?})` — run a command as shell uid;
- returns stdout, stderr, exit code.
-
-Full tool reference, OAuth flow, and the WS relay protocol are documented in
-[`docs/USAGE.md`](docs/USAGE.md).
-
-## Security notes
-
-- `AI_TOKEN` is a master key for shell access to the device. Treat it like an
- SSH private key.
-- The Android device only trusts the relay it dials; it never accepts
- inbound connections.
-- No root is required or used — shell access is uid 2000, same ceiling as
- `adb shell`.
-- Scope is the **owner's own device** for personal automation, same as
- before — see `plan.md`'s explicit "multi-tenant 아님" non-goal.
-
-Please report vulnerabilities privately as described in
-[`SECURITY.md`](SECURITY.md). Contributions are welcome under the
-[`MIT License`](LICENSE); see [`CONTRIBUTING.md`](CONTRIBUTING.md) before
-opening a pull request.
+rish-mcp is licensed under the [MIT License](LICENSE).