MCP工具

Requirements

• macOS Apple Silicon (M1/M2/M3/M4) — arm64 emulator images
• Python 3.11+
• Android SDK — platform-tools, emulator, system-images;android-34;google_apis_playstore;arm64-v8a
• A dedicated Gmail account for Play Store automation (do not use a personal account)

Install Android SDK tools via Homebrew:

brew install --cask android-commandlinetools

---

2. Install prerequisites

```bash

Setup — for the human (one time)

The human owner does this once. After it, the AI agent runs everything on its own.

Why does a human sign in? Google guards every new sign-in with 2-Step Verification — a "tap 35 on your phone" prompt that only the owner's real phone can approve. No agent can pass that. So the human signs in one time; the account then lives on the emulator and the agent uses it forever.

Navigates Play Store, searches, taps Install, polls pm list packages until confirmed.

Setup & Credential Management

```python

Install WhatsApp

curl -X POST localhost:7070/session/s1/install \ -H "Content-Type: application/json" -d '{"package_name": "com.whatsapp"}' ```

---

3. Install any app by package name

vrski_install_app("user_session_1", "com.ubercab") # Uber vrski_install_app("user_session_1", "com.zomato.app") # Zomato

Full Agent Session — Example Flow

A screenshot is auto-attached when the tree can't describe the screen.

"vision_hint": str | None, # set when you should reason from the screenshot

"screenshot_base64": str | None

The vision-backed view: salient tree + a screenshot, together. Use on WebView /

→ { "success", "matched_element": str | None, "error"?, "screenshot_base64"? }

vrski_type(session_id, text: str, clear_first: bool = True)

Python environment

python3.11 -m venv .venv source .venv/bin/activate pip install -r requirements.txt pip install -e . ```

Saves credentials to .env, then signs into Play Store automatically.

"has_credentials": bool, # true = email/password stored in .env

Signs in using saved credentials from .env (default) or explicit override.

Android SDK (platform-tools + emulator + a Play-Store system image)

brew install --cask android-commandlinetools

Path B — REST API (for harnesses without MCP)

The FastAPI server at :7070 is the underlying interface. Build a thin plugin for your harness that wraps it:

import httpx

class VrskiPlugin:
    def __init__(self, base="http://localhost:7070"):
        self.base = base
        self._session_id = None

    def start(self, session_id: str):
        r = httpx.post(f"{self.base}/session/start", json={"session_id": session_id})
        self._session_id = session_id
        return r.json()

    def get_screen(self) -> dict:
        return httpx.get(f"{self.base}/session/{self._session_id}/screen").json()

    def tap(self, text: str = None, element_id: str = None) -> dict:
        return httpx.post(f"{self.base}/session/{self._session_id}/action",
                          json={"type": "tap", "text": text, "element_id": element_id}).json()

    def type(self, text: str) -> dict:
        return httpx.post(f"{self.base}/session/{self._session_id}/action",
                          json={"type": "type", "text": text}).json()

    def install(self, package_name: str) -> dict:
        return httpx.post(f"{self.base}/session/{self._session_id}/install",
                          json={"package_name": package_name}, timeout=360).json()

---

MCP Tool Reference

All tools follow the same contract: they return a dict with "success": true/false. On failure they include "error" (string) and "screenshot_base64" (PNG, base64) so the agent can reason about why something failed.

REST API Reference

The FastAPI server (localhost:7070) is what the MCP server talks to internally. You can also hit it directly with curl during development.

POST  /session/start                       { "session_id": str }
POST  /session/{id}/end
GET   /session/{id}/status
GET   /session/{id}/screen                 ?include_screenshot=false
POST  /session/{id}/wait                   { "text"?, "element_id"?, "timeout": 15 }
POST  /session/{id}/action                 (see action shapes below)
POST  /session/{id}/install                { "package_name": str }
POST  /session/{id}/launch                 { "package_name": str }
POST  /session/{id}/close                  { "package_name": str }
POST  /session/{id}/uninstall              { "package_name": str }
GET   /session/{id}/apps                   → { "packages": [str] }
GET   /session/{id}/apps/{package_name}    → { "installed": bool }
POST  /session/{id}/auth/playstore         { "gmail"?: str, "password"?: str }   (omit → reads .env)
GET   /session/{id}/auth/playstore         → { "signed_in": bool, "account": str | None }
POST  /session/{id}/dismiss_popups
POST  /setup                               { "session_id": str, "email": str, "password": str }
GET   /setup/status                        ?session_id=...  → { "ready", "has_credentials", ... }

Action body shapes:

{ "type": "tap",       "text": "Log In" }
{ "type": "tap",       "element_id": "com.app:id/login_btn" }
{ "type": "tap",       "content_desc": "Search" }
{ "type": "tap",       "x": 540, "y": 960 }
{ "type": "type",      "text": "hello@gmail.com", "clear_first": true }
{ "type": "swipe",     "direction": "up", "distance": 500, "speed": 300 }
{ "type": "scroll_to", "text": "Privacy Policy" }
{ "type": "back" }
{ "type": "home" }
{ "type": "recent_apps" }

Curl examples: ```bash

"package": str,

→ { "success", "package_name", "duration_seconds", "error" | None }

vrski_launch_app(session_id, package_name: str) vrski_close_app(session_id, package_name: str) vrski_uninstall_app(session_id, package_name: str) vrski_is_installed(session_id, package_name: str) # → { "installed": bool } vrski_list_installed(session_id) # → { "packages": [str] } ```

Live integration (emulator must be running)

VRSKI_MOCK=0 python tests/test_ui.py ```

Tests use VRSKI_MOCK=1 / VRSKI_SIMULATE=true by default so CI passes without a connected device.

---