sully-termux-mcp

sully-termux-mcp es una puerta de enlace Node.js 20+ en TypeScript ESM para ejecutar herramientas MCP en Termux. El valor predeterminado de producción es deliberadamente pequeño: solo escucha en una dirección de bucle local, requiere un token Bearer de 32 bytes y expone una API de administración separada y autenticada.

Inicio rápido

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

La configuración generada es ~/.config/sully-mcp/config.json con modo 0600; los datos, la salida de trabajos y el registro de auditoría redactado se encuentran en ~/.local/share/sully-mcp con modo 0700. Nunca pegue JSON de emparejamiento en un registro o issue.

Para controles del teléfono, instale el paquete de comandos Termux:API (pkg install termux-api) e instale la aplicación complementaria Termux:API para Android desde la misma fuente de firma (por ejemplo, ambos desde F-Droid, o ambos desde GitHub). Android no entregará llamadas API cuando los dos paquetes provienen de fuentes de firma diferentes. Reinicie la puerta de enlace después de instalar o actualizar Termux:API para que se reconstruya su inventario de comandos.

El endpoint MCP es http://127.0.0.1:8765/mcp. Esta versión admite los protocolos estables basados en sesiones 2025-11-25 y 2025-06-18 con initialize, notifications/initialized, tools/list y tools/call. El transporte 2026-07-28 no se anuncia deliberadamente hasta que se implementen sus encabezados de enrutamiento requeridos y su envoltorio de respuesta. DELETE /mcp cierra una sesión de 2025.

Related MCP server: Python MCP Toolkit Server

Administración

POST /admin/v1 usa el token Bearer admin y acepta { "action": "status", "params": {} }. Las acciones incluyen 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 y pair.revoke. Todas las respuestas tienen {ok:true,result} o {ok:false,error}. Los secretos solo se devuelven en una respuesta explícita de tokens.rotate o en el comando CLI explícito pair.

permissions y doctor incluyen una lista de verificación centralizada de Termux:API agrupada por dispositivo, comunicación, medios, interacción y automatización. La disponibilidad de comandos se detecta al inicio; el estado de permisos de Android en tiempo de ejecución se informa como unknown, y el requisito de la misma fuente de firma para Termux:API es explícito.

Herramientas y límites

Las funciones integradas incluyen echo_safe acotado, fs_read, fs_write, fs_list, fs_metadata, fs_find, fs_copy, fs_move, perfiles de comandos, trabajos de shell, estado de trabajos/salida/cancelación/limpieza, y comandos detectados de Termux:API (incluidos ubicación tipada, cámara, notificación, toast, portapapeles, SMS, TTS, volumen y entrada de linterna). Los comandos API menos comunes exponen args sin procesar limitados con una pista de uso/ayuda; consulte la --help del comando instalado para opciones exactas. shell_exec siempre lanza bash -lc con shell:false; los perfiles de comando y los upstreams stdio usan un ejecutable y una matriz de argumentos con shell:false. Los trabajos sobreviven reinicios como interrupted, capturan como máximo 8 MiB y devuelven como máximo 64 KiB por solicitud de salida. Las solicitudes están limitadas a 1 MiB y las respuestas a 4 MiB; el concurso de herramientas por defecto es cuatro.

Los upstreams HTTP deben usar HTTPS, o HTTP en el host literal de bucle local 127.0.0.1/::1 (sin alias DNS ni espacios en blanco). Los destinos HTTPS que resuelven a rangos privados, de enlace local o de metadatos se rechazan. Redirecciones, credenciales en URL, fragmentos y herramientas no permitidas en la lista blanca se rechazan. Las herramientas HTTP y stdio upstream se prefijan (id__tool) y pueden restringirse con allowedTools, readOnly y prefix.

Ciclo de vida de Termux

El ciclo de vida normal de sully-mcp start/restart adquiere termux-wake-lock cuando está disponible y stop lo libera. Instale termux-boot/sully-termux-mcp como ~/.termux/boot/sully-termux-mcp y hágalo ejecutable para iniciar después del reinicio. La optimización de batería de Android aún puede detener Termux; la aplicación debe tratar una puerta de enlace no disponible como recuperable.

Comandos CLI compatibles: setup, start, stop, restart, status, doctor, permissions, pair, update y uninstall --yes.

Integridad de lanzamiento

npm run release -- --version 0.2.0 requiere MCP_RELEASE_ED25519_PRIVATE_KEY y ejecuta una compilación antes de escribir sully-termux-mcp-0.2.0.tar.gz, su hash SHA-256, manifest y firma Ed25519. El comando de aplicación en scripts/install-command.txt descarga el archivo de lanzamiento fijo de GitHub Release en un directorio temporal, compara el archivo con su hash esperado y verifica la firma Ed25519 con su clave pública integrada, antes de ejecutar el script de instalación verificada. Nunca uses curl | sh sin verificar. La clave privada de firma se suministra de forma transitoria mediante MCP_RELEASE_ED25519_PRIVATE_KEY por el operador de lanzamiento y nunca se compromete en el repositorio.

Modelo de seguridad

Solo se aceptan hosts de bucle local para el listener local. Las credenciales MCP y de administración son valores aleatorios de 64 hex independientes y se comparan con una comparación de tiempo constante. La configuración se escribe como UTF-8 con permisos restrictivos. El servidor no devuelve tokens desde /health, errores normales, registros de auditoría ni metadatos de trabajos. Las entradas de auditoría se redactan y limitan. Las herramientas con efectos secundarios nunca se reintentan automáticamente. Las herramientas de upstream de HTTP y stdio tienen prefijo (id__tool) y se pueden restringir con allowedTools, readOnly y prefix.

Este repositorio está bajo la Licencia No Comercial PolyForm 1.0.0 heredada de SULLYTEST2.