# XBrowser Controller - X浏览器深度控制技能

X浏览器（com.mmbox.xbrowser）的完整逆向理解、APK 改造能力、以及通过内置 MCP 服务器直接控制浏览器的能力。

掌握 404 个原生桥方法、APK 改造能力、439 个 MCP 工具，可通过 HTTP 直接操控 X浏览器。

## 功能特性

- 通过 MCP HTTP 服务器直接控制 X浏览器
- 8 个基础工具：状态查询、标签页信息、执行JS、获取HTML、获取文本、枚举桥方法、导航、刷新
- 27 个高级封装工具：系统信息、UI主题、弹窗、剪贴板、搜索、UA管理、代理、阅读模式、媒体/TTS、下载管理、文件管理、书签、账户、VIP、自动填充、站点策略、隐私、标签管理、手势、事件、QR扫描、分享、缩放、安全、用户脚本、开发者工具、广告拦截
- 404 个原生桥方法直接调用
- 支持局域网直连和 ADB 隧道两种连接方式
- 技能定义文件，可直接集成到 AI Agent 系统

## 前置条件

1. X浏览器增强版 APK（已内置 MCP HTTP 服务器，端口 8765）
2. Python 3.8+
3. 网络连接（局域网或 ADB）

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 启动 X浏览器 MCP 服务器

在 X浏览器增强版中，浏览器启动后自动监听端口 8765。

确认 MCP 服务器运行：
```bash
curl -X POST http://127.0.0.1:8765/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"xbrowser_status","arguments":{}}}'
```

### 3. 使用 Python 客户端

```python
from xbrowser_mcp_server import XBrowserClient

# 连接 X浏览器 MCP 服务器
client = XBrowserClient("http://127.0.0.1:8765/mcp")

# 查询状态
status = client.call_tool("xbrowser_status")
print(status)

# 导航到网页
client.call_tool("xbrowser_navigate", {"url": "https://www.baidu.com"})

# 获取页面内容
html = client.call_tool("xbrowser_get_html")
print(html)

# 执行 JavaScript
result = client.call_tool("xbrowser_eval_js", {"expression": "document.title"})
print(result)

# 获取 Cookie
cookies = client.call_tool("xbridge_GM_cookie_list", {"p1": "", "p2": "", "p3": "", "p4": ""})
print(cookies)

# TTS 语音朗读
client.call_tool("xbridge_TTS", {"p1": "你好，这是语音朗读测试"})
```

### 4. 命令行使用

```bash
# 查询状态
python xbrowser_mcp_server.py status

# 导航
python xbrowser_mcp_server.py navigate https://www.baidu.com

# 获取页面文本
python xbrowser_mcp_server.py text

# 执行JS
python xbrowser_mcp_server.py eval "document.title"
```

## 连接方式

### 局域网直连

```
POST http://192.168.1.5:8765/mcp
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"xbrowser_status","arguments":{}}}
```

### ADB 隧道（如局域网不通）

```bash
adb forward tcp:8765 tcp:8765
# 然后访问 http://127.0.0.1:8765/mcp
```

## 工具清单

### 一、基础工具（8个）

| 工具 | 参数 | 说明 |
|------|------|------|
| xbrowser_status | 无 | 返回 {running, port, webview} |
| xbrowser_tab_info | 无 | 返回当前标签页 {title, url, mbrowser} |
| xbrowser_eval_js | expression | 执行任意 JavaScript |
| xbrowser_get_html | 无 | 返回页面 HTML 源码 |
| xbrowser_get_text | 无 | 返回页面可见文本 |
| xbrowser_bridge_methods | 无 | 枚举全部 404 个桥方法名 |
| xbrowser_navigate | url | 导航到指定 URL |
| xbrowser_reload | 无 | 刷新当前页面 |

### 二、高级封装工具（27个）

每个工具通过 action 参数区分子操作，包括：系统信息、UI主题、弹窗、剪贴板、搜索、UA管理、代理、阅读模式、媒体/TTS、下载管理、文件管理、书签、账户、VIP、自动填充、站点策略、隐私、标签管理、手势、事件、QR扫描、分享、缩放、安全、用户脚本、开发者工具、广告拦截。

### 三、桥方法工具（404个）

命名规则：xbridge_<方法名>，参数按顺序传 p1, p2, p3...

常见可用桥方法：
- xbridge_getVersionCode -> 版本号
- xbridge_getBrowserInfoObj -> 浏览器信息
- xbridge_inChina -> 是否在中国
- xbridge_GM_cookie_list(p1,p2,p3,p4) -> 列出 Cookie（含 httpOnly）
- xbridge_getFaviconURI(p1) -> 获取网站图标
- xbridge_getElementRules(p1) -> 获取广告过滤规则
- xbridge_getSniffMediaResource -> 嗅探媒体资源
- xbridge_TTS(p1) -> 语音朗读文本

## 安全校验说明

约 1/4 的桥方法受 X8.p() 安全校验保护，只允许在以下页面调用：
- x:// 内部协议页面（如 x://settings）
- file:///android_asset/ 设置页
- xbext.com 域名

解决方案：先 xbrowser_navigate("x://settings") 再调用受限方法。

## APK 改造知识

### 工具链

```bash
# 编译 Java
javac -cp /opt/android-sdk/platforms/android-34/android.jar -d out com/mmbox/xbrowser/XBrowserMcpServer.java

# 转换为 DEX
java -cp /opt/android-sdk/build-tools/35.0.0/lib/d8.jar com.android.tools.r8.D8 \
  --output dex_out --lib /opt/android-sdk/platforms/android-34/android.jar \
  out/com/mmbox/xbrowser/*.class

# 反编译 DEX
java -cp /usr/share/java/baksmali.jar:... org.jf.baksmali.Main \
  disassemble -o smali_out dex_out/classes.dex

# 打包 APK
apktool b $DECODED_DIR -o output.apk

# 签名
java -jar /opt/android-sdk/build-tools/35.0.0/lib/apksigner.jar sign \
  --ks /tmp/debug.keystore --ks-pass pass:android \
  --out signed.apk unsigned.apk

# 安装
adb install -r signed.apk
```

### 修改点

1. Browser.smali -> onCreate() 注入 getInstance() -> setContext() -> start()
2. Of.smali -> 构造函数注入 getInstance() -> registerWebView(webView)
3. X8.smali -> 追加 enableMcpServer(boolean) 和 isMcpServerEnabled() 桥方法
4. assets/settings/general-setting.html -> 注入 MCP 开关 UI + JS

## 已知问题

| 问题 | 原因 | 解决 |
|------|------|------|
| requests.post(json=...) 失败 | 服务器 jsonGetString 不支持空格 | 用 data= 传 JSON + separators |
| 端口 8765 被占用 | 旧 Python MCP 残留 | pkill -f xbrowser_mcp 后再重启 |
| 局域网直连断 | 无线调试端口过期 | 重启浏览器或重建 ADB forward |

## 项目结构

```
xbrowser_controller/
├── README.md                  # 项目说明
├── LICENSE                    # MIT 许可证
├── xbrowser_mcp_server.py     # MCP 服务器客户端核心代码
├── skills.json                # 技能定义（8个预置工具）
├── requirements.txt           # Python 依赖
└── .gitignore
```

## 技能定义

skills.json 包含 8 个预置工具的完整定义，可直接集成到 AI Agent 系统：
- 查询X浏览器状态
- X浏览器导航
- X浏览器搜索
- 读取X浏览器页面内容
- 获取X浏览器Cookie
- 获取X浏览器信息
- X浏览器执行JS
- X浏览器语音朗读

## 注意事项

- 本工具仅用于合法的安全研究和学习
- 逆向和 APK 改造请遵守相关法律法规
- 使用本工具造成的任何后果由使用者自行承担

## 许可证

MIT License