# uitree-local — 本地 Uitree Portal 工具链

为**精简为本地-only** 的 Uitree Portal APK（v0.7.24）配套的 MCP server、CLI agent 与
skills。全部流量走本机（HTTP 8080 / WebSocket 8081），无任何云端依赖。

- MCP server 基于 **mcp 2.x SDK，实现 2026-07-28 最新协议**：
  无状态（无 handshake / Session-Id）、`server/discover` 服务发现、JSON Schema 2020-12。
- 27 个工具覆盖：UI 树读取、截图、点按/滑动/按键、输入、剪贴板、App 管理、文件、
  APK 安装、防休眠。
- `agent/` 提供自然语言任务循环（OpenAI 兼容 LLM，可选 vision），与 MCP 共用同一套工具。

> 官方 `api.uitree.ai/v1/mcp` 是托管闭源服务（`dr_sk_` key 计费）。
> 本项目是自建替代：MCP server + skills + agent 全部在本地跑，直连 Portal APK 的本地 API。

## 目录结构

```
mcp-server/
├── pyproject.toml            # mcp>=2.0.0, websocket-client, httpx; pytest dev
├── src/uitree_mcp/
│   ├── portal_client.py      # Portal HTTP/WS 客户端（token 解析 + adb forward 自动）
│   ├── tools.py              # 27 个工具定义（MCP server 与 agent 共用）
│   ├── server.py             # MCP server（stdio / streamable-http）
│   └── agent.py              # CLI agent（LLM 循环 + vision 截图）
├── skills/uitree/SKILL.md # opencode/anthropic 风格 skill
├── agent/                    # agent 说明与示例
└── tests/                    # 17 个单测（假 Portal + 假 LLM，无需真机）
```

## 安装 & 运行

前置：`adb devices` 可见设备（如 `emulator-5554`）；Portal APK 已安装并启用无障碍服务；
token 自动解析（显式 > `UITREE_TOKEN` > adb content provider），端口自动 forward。

```bash
cd mcp-server
uv sync

# 1) MCP server（stdio —— 供 Claude Desktop / opencode 等客户端接入）
uv run uitree-mcp
# 客户端配置示例（claude mcp add / opencode mcp add）：
#   uitree-local: {"type": "stdio", "command": "uv", "args": ["run", "--project", "/path/to/mcp-server", "uitree-mcp"]}

# 2) MCP server（streamable-http，2026-07-28 无状态）
uv run uitree-mcp --transport streamable-http --port 8083
# 客户端连接: http://127.0.0.1:8083/mcp

# 3) CLI agent（自然语言任务；LLM 用 OpenAI 兼容端点，Ollama 也可）
UITREE_LLM_BASE=https://api.openai.com/v1 UITREE_LLM_MODEL=gpt-4o \
UITREE_LLM_API_KEY=sk-... \
uv run uitree-agent "打开设置，滑动到存储，截图汇报占用情况"

# Ollama 本地：
UITREE_LLM_BASE=http://localhost:11434/v1 UITREE_LLM_MODEL=llama3.2-vision \
UITREE_LLM_VISION=1 uv run uitree-agent "看下当前屏幕有什么"
```

## 验证

```bash
uv run pytest tests/            # 17 个单测（无需设备）
curl -s http://127.0.0.1:8080/ping -H "Authorization: Bearer $KEY"   # → pong
uv run uitree-mcp --transport streamable-http --port 8083 &       # 手工联调
```

## 关键设计

- **单一工具源**：`tools.py` 的 ToolDef 同时驱动 MCP server（`server.py` 把 schema
  逐字映射为 wire inputSchema）与 agent（进程内直调，零 MCP 往返）。
- **token 安全**：token 不出本机；`uitree-mcp` 也可用 `--token` 显式传入，避免 adb shell。
- **WS 专有能力**：`install_apk`、`set_keep_awake` 走 WebSocket JSON-RPC（`{id, method, params}`）。
- **协议最新**：mcp 2.x 为 2026-07-28 规范重写的 SDK（`MCPServer` 取代 `FastMCP`），
  自动处理 `server/discover`、响应缓存、无状态 HTTP。