sully-termux-mcp

sully-termux-mcp 是一个基于 Node.js 20+ 的 TypeScript ESM 网关，用于在 Termux 中运行 MCP 工具。生产环境的默认配置刻意保持精简：仅监听回环地址，要求 32 字节的 Bearer 令牌，并暴露一个独立的、经过认证的管理 API。

快速开始

npm ci
npm run build
node dist/cli.js setup
node dist/cli.js start
node dist/cli.js status
node dist/cli.js pair                 # explicit user action; prints both tokens

生成的配置文件为 ~/.config/sully-mcp/config.json，权限为 0600；数据、任务输出和脱敏审计日志位于 ~/.local/share/sully-mcp，权限为 0700。切勿将配对 JSON 粘贴到日志或工单中。

对于手机控制，请安装 Termux:API 命令包（pkg install termux-api），并从相同的签名来源安装 Termux:API 配套 Android 应用（例如，两者都来自 F-Droid，或两者都来自 GitHub）。当两个包来自不同签名来源时，Android 将不会传递 API 调用。安装或更新 Termux:API 后，请重启网关，以便重建其命令清单。

MCP 端点为 http://127.0.0.1:8765/mcp。此版本支持稳定的 2025-11-25 和 2025-06-18 基于会话的协议，使用 initialize、notifications/initialized、tools/list 和 tools/call。2026-07-28 传输协议在实现其所需的路由头和响应封装之前，有意不进行通告。DELETE /mcp 关闭 2025 会话。

Related MCP server: Python MCP Toolkit Server

管理

POST /admin/v1 使用 admin Bearer 令牌，并接受 { "action": "status", "params": {} }。操作包括 status、doctor、permissions、capabilities、jobs.list、jobs.output、jobs.cancel、jobs.cleanup、profiles.list、profiles.upsert、profiles.remove、upstreams.list、upstreams.import、upstreams.update、upstreams.remove、gateway.stop、tokens.rotate 和 pair.revoke。所有响应均为 {ok:true,result} 或 {ok:false,error}。机密信息仅在显式的 tokens.rotate 响应或显式的 pair CLI 命令中返回。

permissions 和 doctor 包含一个集中的 Termux:API 检查清单，按设备、通信、媒体、交互和自动化分组。命令可用性在启动时检测；Android 运行时权限状态报告为 unknown，并且 Termux:API 的相同签名来源要求是明确的。

工具与限制

内置工具包括有界的 echo_safe、fs_read、fs_write、fs_list、fs_metadata、fs_find、fs_copy、fs_move、命令配置文件、shell 任务、任务状态/输出/取消/清理，以及检测到的 Termux:API 命令（包括类型化位置、相机、通知、toast、剪贴板、短信、TTS、音量和手电筒输入）。较少见的 API 命令暴露有界的原始 args，并附带用法/帮助提示；请查阅已安装命令的 --help 以获取确切选项。shell_exec 始终以 shell:false 生成 bash -lc；命令配置文件和 stdio 上游使用可执行文件加参数数组，且 shell:false。任务在重启后保持为 interrupted 状态，最多捕获 8 MiB，每次输出请求最多返回 64 KiB。请求限制为 1 MiB，响应限制为 4 MiB；工具并发默认值为四。

HTTP 上游必须使用 HTTPS，或使用精确字面回环主机 127.0.0.1/::1 的 HTTP（不允许 DNS 别名或空白）。解析到私有、链路本地或元数据范围的 HTTPS 目标将被拒绝。重定向、URL 凭据、片段和非白名单工具将被拒绝。HTTP 和 stdio 上游工具带有前缀（id__tool），并可通过 allowedTools、readOnly 和 prefix 进行限制。

Termux 生命周期

正常的 sully-mcp start/restart 生命周期在可用时获取 termux-wake-lock，stop 释放它。将 termux-boot/sully-termux-mcp 安装为 ~/.termux/boot/sully-termux-mcp 并使其可执行，以便重启后启动。Android 电池优化仍可能停止 Termux；应用程序应将不可用的网关视为可恢复的。

支持的 CLI 命令：setup、start、stop、restart、status、logs、doctor、permissions、pair、update 和 uninstall --yes。

发布完整性

npm run release -- --version 0.2.0 需要 MCP_RELEASE_ED25519_PRIVATE_KEY，并在写入 sully-termux-mcp-0.2.0.tar.gz、其 SHA-256、清单和 Ed25519 签名之前运行构建。scripts/install-command.txt 中的 App 命令将固定的 GitHub Release 归档、哈希、清单和签名下载到临时目录，将归档与其固定的预期哈希进行比较，使用其内联公钥验证 Ed25519 签名，然后才运行已验证归档的 scripts/install-local.sh。本地安装程序检查 Node 20+，运行 npm ci --omit=dev 和构建，并原子地交换 versions/<version>/current 符号链接，在失败时保留之前的当前目标。它还在 Termux 的 $PREFIX/bin（或 ~/.local/bin）中创建真实的 sully-mcp 包装器，并且从不使用未经验证的 curl | sh 管道。私有签名密钥由发布操作员通过 MCP_RELEASE_ED25519_PRIVATE_KEY 临时提供，并且永远不会提交。

安全模型

本地监听器仅接受回环主机。MCP 和管理凭据是独立的 64 位十六进制随机值，并使用恒定时间比较进行比较。配置以 UTF-8 写入，并具有严格的权限。服务器不会从 /health、工具列表、正常错误、审计记录或任务元数据中返回令牌。审计条目经过脱敏且有界。副作用工具永远不会自动重试。破坏性上游工具必须由调用方显式列入白名单。

此仓库根据从 SULLYTEST2 继承的 PolyForm 非商业许可证 1.0.0 进行许可。