小U同学连接MT管理器 APK MCP 服务手册
=========================================
> 适用场景：在 Deepin/UOS 系统上，让小U同学（UOS AI）通过 MCP 协议
> 连接手机上的 MT 管理器 APK MCP 服务，从而分析、修改手机上的 APK 文件。
>
> 前置条件：
> - 电脑和手机在同一个局域网
> - 手机上已安装 MT 管理器（最新版）
> - 电脑上已安装 UOS AI（小U同学）3.0 及以上版本
一、在手机上启动 MT APK MCP 服务
----------------------------------
1. 打开手机上的 MT管理器
2. 从左侧滑出侧拉栏，进入"工具"→"APK MCP"
3. 点击"启动"按钮
4. 启动后，查看页面显示的地址：
- 本地地址：http://127.0.0.1:8787/mcp（仅手机本机可用）
- 局域网地址：http://192.168.x.x:8787/mcp（电脑连接用，复制这个地址）
5. 保持手机屏幕常亮，或开启悬浮球保活，防止服务断开
二、在电脑上安装 MCP 桥接依赖
------------------------------
打开终端，执行以下命令：
pip3 install --break-system-packages mcp httpx
三、创建桥接脚本
----------------
将以下脚本保存到用户家目录，文件名为 mt-apk-mcp-bridge.py：
--------------------------------------------------------------------------------
#!/usr/bin/env python3
"""小U同学 ↔ MT APK MCP 桥接脚本（优化版 v2）"""
import json, sys, asyncio, httpx, os, logging
# ===== 请修改下面的 MCP 地址为手机上显示的局域网地址 =====
MCP_URL = "http://192.168.x.x:8787/mcp"
# =======================================================
LOG_FILE = os.path.expanduser("~/.cache/deepin/uos-ai-agent/mt-apk-bridge.log")
logging.basicConfig(
filename=LOG_FILE, level=logging.INFO,
format="%(asctime)s [%(levelname)s] %(message)s"
)
# 持久化连接池，支持大文件传输
transport = httpx.AsyncHTTPTransport(retries=2, http2=True)
limits = httpx.Limits(
max_keepalive_connections=5,
max_connections=10
)
client = httpx.AsyncClient(
transport=transport,
limits=limits,
timeout=httpx.Timeout(300.0, connect=15.0, pool=10.0, read=300.0, write=300.0)
)
async def main():
logging.info("桥接脚本启动，目标: %s", MCP_URL)
while True:
line = sys.stdin.readline()
if not line:
break
line = line.strip()
if not line:
continue
try:
request = json.loads(line)
except json.JSONDecodeError:
continue
method = request.get("method", "unknown")
req_id = request.get("id", None)
is_notification = "id" not in request or request ["id"] is None
try:
response = await client.post(
MCP_URL,
json=request,
headers={"Content-Type": "application/json"}
)
# 通知类请求（无id）不需要返回体
if is_notification:
logging.info("通知已发送: %s (HTTP %s)", method, response.status_code)
continue
# 有返回体的请求
content_type = response.headers.get("content-type", "")
if "application/json" in content_type or response.status_code == 200:
result = response.json()
sys.stdout.write(json.dumps(result, ensure_ascii=False) + "\n")
sys.stdout.flush()
if "error" in result:
logging.error("错误 #%s: %s", req_id, result ["error"])
else:
logging.info("成功 #%s: %s", req_id, method)
else:
logging.info("已处理 #%s: %s (HTTP %s)", req_id, method, response.status_code)
except httpx.TimeoutException:
err = {"jsonrpc":"2.0","id":req_id,"error":{"code":-32001,"message":"请求超时"}}
if not is_notification:
sys.stdout.write(json.dumps(err, ensure_ascii=False) + "\n")
sys.stdout.flush()
logging.error("超时 #%s: %s", req_id, method)
except Exception as e:
err = {"jsonrpc":"2.0","id":req_id,"error":{"code":-32000,"message":str(e)}}
if not is_notification:
sys.stdout.write(json.dumps(err, ensure_ascii=False) + "\n")
sys.stdout.flush()
logging.error("异常 #%s: %s - %s", req_id, method, e)
if __name__ == "__main__":
try:
asyncio.run(main())
finally:
asyncio.run(client.aclose())
--------------------------------------------------------------------------------
保存后，小U同学会自动赋予执行权限。
四、配置小U同学的 MCP 服务
--------------------------
方法一：通过 UI 界面添加（推荐）
1. 打开小U同学（UOS AI）
2. 点击左侧"MCP&Skills"
3. 点击"我的MCP服务"
4. 点击右上角"添加MCP服务"
5. 在弹出的 JSON 配置框中输入（小U同学会自动把 ~ 替换为当前用户的家目录路径）：
{
"mcpServers": {
"mt-apk-mcp": {
"command": "python3",
"args": ["~/mt-apk-mcp-bridge.py"],
"descriptions": {
"zh": "MT APK MCP 服务 - 分析和修改 APK 文件",
"en": "MT APK MCP Service - Analyze and modify APK files"
}
}
}
}
6. 点击确定保存
7. 在服务列表中，找到 mt-apk-mcp，将右侧开关开启
方法二：直接修改配置文件（如果 UI 添加无效）
mkdir -p ~/.local/share/deepin/uos-ai-agent/default-agent/mcp-servers/
将以下内容写入 uosai-user-mcp.json：
{
"mcpServers": {
"mt-apk-mcp": {
"command": "python3",
"args": ["~/mt-apk-mcp-bridge.py"],
"descriptions": {
"zh": "MT APK MCP 服务 - 分析和修改 APK 文件",
"en": "MT APK MCP Service - Analyze and modify APK files",
"generic": "MT APK MCP Service - Analyze and modify APK files"
}
}
}
}
然后重启小U同学的后台服务：
pkill -f uos-aiagent-mcp
nohup /usr/bin/uos-aiagent-mcp > /dev/null 2>&1 &
五、验证连接
------------
1. 验证桥接脚本
在终端中执行以下命令测试桥接：
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | timeout 10 python3 ~/mt-apk-mcp-bridge.py
如果返回包含工具列表的 JSON 数据，说明桥接成功。
2. 验证小U同学
a. 打开小U同学
b. 选择"MCP&Skills"助手
c. 发送消息："列出当前可用的 APK 文件"
d. 如果 AI 成功调用工具并返回结果，说明配置完成
六、常见问题
------------
Q1：开启服务开关没反应
- 检查配置文件是否正确（路径：~/.local/share/deepin/uos-ai-agent/...）
- 重启后台代理：pkill -f uos-aiagent-mcp 然后重新打开小U同学
Q2：提示 "405 Method Not Allowed"
- 说明小U同学用 SSE 协议（GET）去连接了，需要改用桥接脚本（stdio方式）
- 请确认配置中使用的是 "command" 字段，而不是 "url" 字段
Q3：调用工具时超时或卡住
- 检查手机和电脑是否在同一个局域网
- 检查手机上 MT 的 APK MCP 服务是否仍在运行
- 可以尝试重启手机上的 MCP 服务
Q4：桥接脚本启动后立即断开（Connection closed）
- 通常是 httpx 版本兼容性问题
- 检查桥接脚本中的 Limits 参数是否被支持
- 执行 pip3 install --upgrade httpx 更新 httpx 库
Q5：连接失败，手机无法访问
- 在电脑上执行 ping 手机IP地址 测试网络连通性
- 检查手机防火墙是否阻止了连接
- 确认 MT 的 APK MCP 页面显示的地址是局域网地址（不是 127.0.0.1）
Q6：AI 调用工具名不存在（如 mt_apk_edit_commit）
- 这是 AI 自己编造的工具名，重新描述需求让 AI 使用正确的工具
- 正确的构建工具是 mt_apk_build
七、工作原理
------------
小U同学 (UOS AI) ←── stdio JSON-RPC ──→ mt-apk-mcp-bridge.py
↓
Streamable HTTP (POST)
↓
MT 管理器 APK MCP 服务
(Android 手机)
- 小U同学：通过 stdio 启动桥接脚本，收发 JSON-RPC 消息
- 桥接脚本：将 stdio 消息转为 HTTP POST 请求，转发给手机
- MT APK MCP：在手机上处理 APK 分析/修改请求，返回结果
- 优化：连接池复用、300秒超时、HTTP/2支持
八、卸载方法
------------
如果不再使用，执行以下步骤：
rm ~/mt-apk-mcp-bridge.py
echo '{"mcpServers":{}}' > ~/.local/share/deepin/uos-ai-agent/default-agent/mcp-servers/uosai-user-mcp.json
pkill -f uos-aiagent-mcp
九、可用工具一览（共26个）
--------------------------
类别 工具 功能
---- ---- ----
查找与打开 mt_apk_list_available_apks 列出可打开的 APK
mt_apk_open 打开 APK 创建工作区
阅读与检索 mt_apk_list 列出 APK 结构
mt_apk_search 搜索 APK 内容
mt_apk_read_text 读取文本内容
mt_apk_read_bytes 读取原始字节
mt_apk_dex_outline_class 查看 Dex 类结构
mt_apk_dex_xref 查找代码引用
mt_apk_resource_read 读取资源值
mt_apk_resource_xref 查找资源引用
分析 so 库 mt_apk_native_inspect 查看 ELF 信息
mt_apk_native_read_items 读取 ELF 详情
mt_apk_native_map_address 地址映射
mt_apk_native_xref 查找地址引用
mt_apk_native_disassemble 反汇编
mt_apk_native_function_cfg 函数控制流图
修改与打包 mt_apk_edit_open 创建编辑会话
mt_apk_edit_text 修改文本/Smali
mt_apk_edit_resource 修改资源值
mt_apk_patch_bytes 字节补丁
mt_apk_native_patch_instructions 修改 so 指令
mt_apk_native_patch_string 修改 so 字符串
mt_apk_edit_check 检查编辑状态
mt_apk_build 重新打包 APK
（注意：没有 mt_apk_edit_commit 这个工具）
清理 mt_apk_close 关闭临时工作区
翻页 mt_apk_continue 继续翻页
> 小U同学会根据您的需求自动选择合适的工具，无需手动选择。
手册版本：v2.1 | 更新日期：2026-08-15
暂无评论