Metadata-Version: 2.4
Name: ubox-mcp-server
Version: 0.1.5
Summary: UBox MCP服务器 - 通过Model Context Protocol暴露UBox设备自动化能力
Requires-Python: <3.12,>=3.10
Requires-Dist: mcp>=1.20.0
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: ubox-py-sdk==0.2.21.post1
Description-Content-Type: text/markdown

# UBox MCP服务器

## 快速上手

```bash
# 安装提供的 wheel 文件
uv tool install --python 3.10.12 ubox_mcp_server-0.1.0-py3-none-any.whl --index-url https://pypi.tuna.tsinghua.edu.cn/simple
ubox-mcp-server \
  --ubox-secret-id your_id \
  --ubox-secret-key your_key \
  --ubox-mode normal
```

在cline中添加如下配置：

```json
{
  "mcpServers": {
    "ubox-mcp-server": {
      "transport": "http",
      "url": "http://localhost:8000/mcp",
      "description": "UBox MCP Server"
    }
  }
}
```

## 安装（来自打包文件）

```bash
# 安装提供的 wheel 文件
uv tool install --python 3.10.12 ubox_mcp_server-0.1.0-py3-none-any.whl --index-url https://pypi.tuna.tsinghua.edu.cn/simple
```

## 配置与启动

### 方式1：使用 .env 文件

```bash
# 创建配置文件
cat > .env << EOF
UBOX_SECRET_ID=your_secret_id
UBOX_SECRET_KEY=your_secret_key
UBOX_MODE=local
MCP_MODE=streamable-http
MCP_HOST=localhost
MCP_PORT=8000
EOF

# 启动（会自动读取当前目录的 .env 文件）
ubox-mcp-server
```

### 方式2：纯命令行（跨平台）

- macOS/Linux:

```bash
ubox-mcp-server \
  --ubox-secret-id your_id \
  --ubox-secret-key your_key \
  --ubox-mode normal \
  --mcp-mode streamable-http \
  --mcp-port 8000 \
  --log-level DEBUG
```

- Windows PowerShell:

```powershell
ubox-mcp-server `
  --ubox-secret-id your_id `
  --ubox-secret-key your_key `
  --ubox-mode normal `
  --mcp-mode streamable-http `
  --mcp-port 8000 `
  --log-level DEBUG
```

### 方式3：全部环境变量

```bash
export UBOX_SECRET_ID=your_secret_id
export UBOX_SECRET_KEY=your_secret_key
export UBOX_MODE=local
export MCP_MODE=streamable-http
export MCP_HOST=localhost
export MCP_PORT=8000

ubox-mcp-server
```

## 简单校验

```bash
# 列出工具
curl -X POST http://localhost:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

## 获取帮助

```bash
ubox-mcp-server --help
```

## 在 Cline 中使用（VS Code）

1) 启动服务器

- macOS/Linux:

```bash
ubox-mcp-server \
  --ubox-secret-id your_id \
  --ubox-secret-key your_key \
  --ubox-mode local \
  --mcp-mode streamable-http \
  --mcp-port 8000 \
  --log-level DEBUG
```

- Windows PowerShell:

```powershell
ubox-mcp-server `
  --ubox-mode local `
  --mcp-mode streamable-http `
  --mcp-port 8000 `
  --log-level DEBUG
```

2) 配置 Cline

- VS Code 命令面板 → “Cline: Configure MCP Servers” → 添加：

```json
{
  "mcpServers": {
    "ubox-mcp-server": {
      "transport": "http",
      "url": "http://localhost:8000/mcp",
      "description": "UBox MCP Server"
    }
  }
}
```

（如你的 Cline 支持 SSE，也可改为：）

```json
{
  "mcpServers": {
    "ubox-mcp-server": {
      "transport": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}
```

3) 使用与验证

- Cline 面板应显示 “ubox-mcp-server” 已连接
- 在对话中输入任务（如“获取设备列表”“连接设备并截图”），Cline 会调用对应工具

## 可配置项一览

以下所有配置可通过三种方式设置（优先级从高到低）：

1) 命令行参数（仅标注了有对应 --flag 的项）；2) 环境变量；3) .env 文件。

### UBox SDK

- UBox 运行模式
    - 环境变量/.env: `UBOX_MODE`（`local`|`normal`）默认 `local`
    - CLI: `--ubox-mode`
    - 必填: 否
- 本地模式 Base URL（当 `UBOX_MODE=local` 时生效）
    - 环境变量/.env: `UBOX_BASE_URL`（默认 `127.0.0.1:26000`）
    - CLI: `--ubox-base-url`
    - 必填: 否
- UBox 环境
    - 环境变量/.env: `UBOX_ENV`（`formal`|`test`，默认 `formal`）
    - CLI: `--ubox-env`
    - 必填: 否
- 默认设备可选参数（若你的流程需要默认值）
    - 环境变量/.env: `UBOX_DEFAULT_UDID`、`UBOX_DEFAULT_OS_TYPE`（默认 `android`）、`UBOX_AUTH_CODE`
    - CLI: 无

### MCP 服务器

- 运行模式
    - 环境变量/.env: `MCP_MODE`（`sse`|`streamable-http`，默认 `streamable-http`）
    - CLI: `--mcp-mode`
    - 必填: 否
- 主机地址
    - 环境变量/.env: `MCP_HOST`（默认 `localhost`）
    - CLI: `--mcp-host`
    - 必填: 否
- 端口
    - 环境变量/.env: `MCP_PORT`（默认 `8000`）
    - CLI: `--mcp-port`
    - 必填: 否
- 日志级别
    - 环境变量/.env: `LOG_LEVEL`（`DEBUG`|`INFO`|`WARNING`|`ERROR`，默认 `INFO`）
    - CLI: `--log-level`
    - 必填: 否
- 写入日志文件
    - 环境变量/.env: `LOG_TO_FILE`（`true`|`false`，默认 `false`）
    - CLI: 无
    - 必填: 否

 

