Ubuntu 环境 MCP 工具

约 3626 字大约 12 分钟道无涯i

Ubuntu 环境 MCP 工具

这一组工具管理 ScriptX 内置 Root Chroot Ubuntu 的安装、运行时、命令任务、SSH 配置、挂载、rc.local 与备份恢复。

当前源码在这一组注册了 19 个工具。工具名大小写敏感；调用参数以本页表格和 MCP 客户端实时拿到的 input schema 为准。

使用前先知道

所有工具都通过 ScriptX 设置页启动的内置 MCP 服务暴露，不是脚本侧的 mcpServer 对象。
所有返回值至少包含 ok、message、result。不要只判断 HTTP 状态码。
带 projectDir 的分析工具通常要求先在 ScriptX 中缓存 APK，并使用 get_analysis_state / list_apk_workspaces 得到的真实工作区名。
安装、卸载、停止运行时和恢复备份等有副作用的工具，必须按参数表显式传入 confirm: true。

`linux_backup_export`

在 Ubuntu 已停止且挂载已卸载时导出完整 RootFS，并将非敏感运行配置写入备份清单。SSH 密码永远不写入备份。

显示名称：导出 Ubuntu RootFS

参数

参数	类型	必填	可填值 / 范围	说明
`destination`	`string`	是	-	目标 .tar.gz 路径，仅允许共享存储或 /data/local/tmp/ScriptX。
`confirm`	`boolean`	是	仅 `true`	必须为 true。

返回值

返回统一 MCP 结果对象：ok 表示调用是否成功，message 是可读说明，具体数据放在 result。分析尚未准备好、后端安装中或需要先缓存 APK 时，ok 可能为 false，应先读 message 与 result 中的状态字段再决定下一步。

示例

{"name":"linux_backup_export","arguments":{"confirm":true,"destination":"/storage/emulated/0/ScriptX/ubuntu.tar.gz"}}

`linux_backup_import`

验证 tar.gz 路径后在临时目录解压并原子替换 RootFS；必须先停止 Ubuntu。

显示名称：导入 Ubuntu RootFS

参数

参数	类型	必填	可填值 / 范围	说明
`archive`	`string`	是	-	备份 .tar.gz 路径。
`confirm`	`boolean`	是	仅 `true`	必须为 true，确认覆盖当前 RootFS。

返回值

示例

{"name":"linux_backup_import","arguments":{"confirm":true,"archive":"/storage/emulated/0/ScriptX/ubuntu.tar.gz"}}

`linux_cancel_job`

取消正在下载、安装、配置或执行的 Linux 任务；已经完成的任务保持原状态。为避免留下半删除状态，Ubuntu 卸载任务不能取消。

显示名称：取消 Linux 任务

参数

参数	类型	必填	可填值 / 范围	说明
`jobId`	`string`	是	-	要取消的任务 ID。

返回值

示例

{"name":"linux_cancel_job","arguments":{"jobId":"..."}}

`linux_exec`

在 Ubuntu Chroot 内执行命令，返回退出码、stdout/stderr、超时和截断状态。命令无法通过 cwd 逃出 RootFS。

显示名称：执行 Ubuntu 命令

参数

参数	类型	必填	可填值 / 范围	说明
`command`	`string`	是	-	要交给 Ubuntu Bash 执行的命令。
`cwd`	`string`	否	-	Ubuntu 内的绝对工作目录，默认 /root。
`timeoutSeconds`	`integer`	否	1 ~ 3600；默认 `60`	超时秒数，范围 1-3600，默认 60。
`maxOutputChars`	`integer`	否	1000 ~ 200000；默认 `100000`	每个输出流最多返回的字符数，范围 1000-200000，默认 100000。
`wait`	`boolean`	否	`true` / `false`；默认 `true`	是否等待执行完成，默认 true；false 时返回 jobId 后用 linux_get_job 查询。

返回值

示例

{"name":"linux_exec","arguments":{"command":"python3 --version && node --version","cwd":"/root","timeoutSeconds":60,"wait":true}}

`linux_get_job`

按 jobId 查询安装、卸载、配置或命令任务；省略 jobId 时返回最近任务列表。

显示名称：查询 Linux 任务

参数

参数	类型	必填	可填值 / 范围	说明
`jobId`	`string`	否	-	linux_install、linux_uninstall、linux_exec 或 linux_provision 返回的任务 ID。

返回值

示例

{"name":"linux_get_job","arguments":{"jobId":"..."}}

`linux_get_state`

返回 Root Chroot Ubuntu 的安装状态、架构、挂载点和 Python/Node/Git/编译器能力。

显示名称：获取 Ubuntu 状态

参数

参数	类型	必填	可填值 / 范围	说明
`refresh`	`boolean`	否	`true` / `false`；默认 `false`	是否立即通过 Root 重新检查 RootFS 和挂载状态，默认 false。

返回值

示例

{"name":"linux_get_state","arguments":{"refresh":true}}

`linux_install`

默认异步安装并严格验证完整 Ubuntu 环境。先原子安装官方 Ubuntu Base，再安装 Python、Node.js、Git、编译与逆向工具；已有 Base 会被安全接管且不会覆盖。只有全部能力验证通过才会返回 100% 成功。

显示名称：安装 Ubuntu 环境

参数

参数	类型	必填	可填值 / 范围	说明
`confirm`	`boolean`	是	仅 `true`	必须显式为 true，确认将下载并安装 Ubuntu 环境。
`profile`	`string`	否	`full` / `base`；默认 `full`	full 或 base，默认 full。base 只安装并验证最小 RootFS。

返回值

示例

{"name":"linux_install","arguments":{"confirm":true,"profile":"full"}}

`linux_mounts_get`

返回自定义 Android 到 Ubuntu 的挂载点，不包含密码。默认挂载点是 /storage/emulated/0 -> /sdcard。

显示名称：获取 Ubuntu 挂载配置

参数：无。

返回值

示例

{"name":"linux_mounts_get","arguments":{}}

`linux_mounts_set`

替换全部自定义挂载点。目标路径不能覆盖 Ubuntu 系统目录；保存后在下一次启动或 linux_prepare 时生效。

显示名称：设置 Ubuntu 挂载配置

参数

参数	类型	必填	可填值 / 范围	说明
`mounts`	`array`	是	-	完整挂载数组。
`enabled`	`boolean`	否	`true` / `false`	是否启用挂载数组。
`confirm`	`boolean`	是	仅 `true`	必须为 true。
`restartIfRunning`	`boolean`	否	`true` / `false`；默认 `false`	Ubuntu 运行中是否保存后立即重启；默认 false。

返回值

示例

{"name":"linux_mounts_set","arguments":{"confirm":true,"enabled":true,"mounts":[{"source":"/storage/emulated/0","target":"/sdcard"}]}}

`linux_prepare`

幂等准备 /proc、/sys、/dev、共享存储、ScriptX 项目和 APK/SO 缓存挂载。

显示名称：修复 Ubuntu 挂载

参数：无。

返回值

示例

{"name":"linux_prepare","arguments":{}}

`linux_provision`

异步通过 apt 安装开发或逆向工具。profile 可选 development、reverse、full；需要显式确认。

显示名称：安装 Ubuntu 工具套件

参数

参数	类型	必填	可填值 / 范围	说明
`profile`	`string`	否	`development` / `reverse` / `full`；默认 `full`	development、reverse 或 full，默认 full。
`confirm`	`boolean`	是	仅 `true`	必须显式为 true，确认 apt 会下载并修改 Ubuntu RootFS。

返回值

示例

{"name":"linux_provision","arguments":{"profile":"full","confirm":true}}

`linux_rc_local_get`

读取 Ubuntu RootFS 内的 /etc/rc.local 内容。

显示名称：读取 Ubuntu rc.local

参数：无。

返回值

示例

{"name":"linux_rc_local_get","arguments":{}}

`linux_rc_local_set`

写入并设置 /etc/rc.local 为可执行文件；启动初始化开关仍需单独打开。

显示名称：写入 Ubuntu rc.local

参数

参数	类型	必填	可填值 / 范围	说明
`content`	`string`	是	-	完整 rc.local 文本。
`confirm`	`boolean`	是	仅 `true`	必须为 true。

返回值

示例

{"name":"linux_rc_local_set","arguments":{"confirm":true,"content":"#!/bin/bash\n..."}}

`linux_runtime_configure`

保存 SSH、启动初始化、自动启动和挂载点配置。密码只写入 Android Keystore，不会出现在返回值中；省略 password 表示保留原密码。Ubuntu 正在运行时默认只保存配置，下一次启动生效；传 restartIfRunning=true 才会显式停止并重启以立即应用。

显示名称：配置 Ubuntu 运行时

参数

参数	类型	必填	可填值 / 范围	说明
`confirm`	`boolean`	是	仅 `true`	必须为 true。
`sshEnabled`	`boolean`	否	`true` / `false`	是否启用 SSH。
`sshPort`	`integer`	否	1 ~ 65535	SSH 端口 1-65535。
`sshUser`	`string`	否	-	Linux 用户名。
`allowRootLogin`	`boolean`	否	`true` / `false`	是否允许 root 密码登录。
`password`	`string`	否	-	新密码；至少 6 个字符，省略表示保留。
`initEnabled`	`boolean`	否	`true` / `false`	启动时执行 /etc/rc.local。
`initAsync`	`boolean`	否	`true` / `false`	是否后台执行 rc.local。
`autoStartOnAppLaunch`	`boolean`	否	`true` / `false`	ScriptX 进程启动时是否自动启动 Ubuntu。
`mountsEnabled`	`boolean`	否	`true` / `false`	是否启用自定义挂载。
`mounts`	`array`	否	-	挂载数组，每项包含 source、target、enabled、readOnly、id。
`restartIfRunning`	`boolean`	否	`true` / `false`；默认 `false`	Ubuntu 运行中是否保存后立即重启；默认 false。

返回值

示例

{"name":"linux_runtime_configure","arguments":{"confirm":true,"sshEnabled":true,"sshPort":2222,"sshUser":"root","password":"******","restartIfRunning":false}}

`linux_runtime_restart`

先停止并卸载 Ubuntu，再按照当前配置重新挂载、执行初始化并启动 SSH。

显示名称：重启 Ubuntu 运行时

参数

参数	类型	必填	可填值 / 范围	说明
`confirm`	`boolean`	是	仅 `true`	必须为 true。
`force`	`boolean`	否	`true` / `false`；默认 `false`	停止阶段是否使用 SIGKILL，默认 false。

返回值

示例

{"name":"linux_runtime_restart","arguments":{"confirm":true}}

`linux_runtime_start`

准备挂载点，按配置执行 /etc/rc.local，并按配置启动 SSH。终端窗口不是 Ubuntu 生命周期的控制器。

显示名称：启动 Ubuntu 运行时

参数：无。

返回值

示例

{"name":"linux_runtime_start","arguments":{}}

`linux_runtime_state`

检查 Ubuntu 后台进程、挂载点、SSH 状态和局域网地址。不会返回 SSH 密码。

显示名称：获取 Ubuntu 运行时状态

参数

参数	类型	必填	可填值 / 范围	说明
`refresh`	`boolean`	否	`true` / `false`	是否立即检查 Root 进程和挂载点。

返回值

示例

{"name":"linux_runtime_state","arguments":{"refresh":true}}

`linux_runtime_stop`

停止 SSH，终止属于 Ubuntu RootFS 的后台进程并卸载挂载点。强制停止可能中断应用，请显式确认。

显示名称：停止 Ubuntu 运行时

参数

参数	类型	必填	可填值 / 范围	说明
`confirm`	`boolean`	是	仅 `true`	必须为 true。
`force`	`boolean`	否	`true` / `false`；默认 `false`	是否使用 SIGKILL，默认 false。

返回值

示例

{"name":"linux_runtime_stop","arguments":{"confirm":true,"force":false}}

`linux_uninstall`

异步卸载固定路径下的 Ubuntu RootFS。默认同时删除 Ubuntu Base 下载缓存，但始终保留 ScriptX 项目、用户脚本和 APK/SO 分析缓存。卸载开始后不能取消。

显示名称：卸载 Ubuntu 环境

参数

参数	类型	必填	可填值 / 范围	说明
`confirm`	`boolean`	是	仅 `true`	必须显式为 true，确认永久删除 Ubuntu RootFS。
`removeDownloadCache`	`boolean`	否	`true` / `false`；默认 `true`	是否删除约 30 MB 的 Ubuntu Base 下载缓存，默认 true。

返回值

示例

{"name":"linux_uninstall","arguments":{"confirm":true,"removeDownloadCache":true}}