sully-termux-mcp

sully-termux-mcp — это шлюз Node.js 20+ TypeScript ESM для запуска инструментов MCP в Termux. Производственный режим по умолчанию намеренно минимален: он прослушивает только loopback-адрес, требует 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 для сопряжения в журнал или issue.

Для управления с телефона установите пакет команд Termux:API (pkg install termux-api) и установите сопутствующее Android-приложение Termux:API из того же источника подписи (например, оба из 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 или по явной команде CLI pair.

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, буфера обмена, SMS, TTS, громкости и фонарика). Менее распространённые команды API предоставляют ограниченные необработанные args с подсказкой по использованию/справке; обратитесь к --help установленной команды для точных параметров. shell_exec всегда запускает bash -lc с shell:false; профили команд и stdio-апстримы используют исполняемый файл и массив аргументов с shell:false. Задания переживают перезапуски как interrupted, захватывают не более 8 МиБ и возвращают не более 64 КиБ на запрос вывода. Запросы ограничены 1 МиБ, ответы — 4 МиБ; параллельность инструментов по умолчанию равна четырём.

HTTP-апстримы должны использовать HTTPS или HTTP на точном литеральном loopback-хосте 127.0.0.1/::1 (без DNS-алиасов и пробелов). HTTPS-адреса, разрешающиеся в частные, link-local или метаданные диапазоны, отклоняются. Перенаправления, учётные данные в 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. Команда App в scripts/install-command.txt загружает фиксированный архив GitHub Release, хэш, манифест и подпись во временный каталог, сравнивает архив с его закреплённым ожидаемым хэшем, проверяет подпись Ed25519 с помощью встроенного открытого ключа и только затем запускает scripts/install-local.sh из проверенного архива. Локальный установщик проверяет Node 20+, выполняет npm ci --omit=dev и сборку, а затем атомарно заменяет символическую ссылку versions/<version>/current, сохраняя предыдущую текущую цель при сбое. Он также создаёт настоящую обёртку sully-mcp в $PREFIX/bin Termux (или ~/.local/bin) и никогда не использует непроверенный конвейер curl | sh. Приватный ключ подписи передаётся временно через MCP_RELEASE_ED25519_PRIVATE_KEY оператором выпуска и никогда не фиксируется.

Модель безопасности

Для локального прослушивателя принимаются только loopback-хосты. Учётные данные MCP и администратора представляют собой независимые случайные 64-шестнадцатеричные значения и сравниваются с помощью сравнения за постоянное время. Конфигурация записывается в UTF-8 с ограничительными правами доступа. Сервер не возвращает токены из /health, списков инструментов, обычных ошибок, записей аудита или метаданных заданий. Записи аудита редактируются и ограничены. Инструменты с побочными эффектами никогда не повторяются автоматически. Деструктивные инструменты апстрима должны быть явно внесены в белый список вызывающей стороной.

Этот репозиторий лицензирован в соответствии с PolyForm Noncommercial License 1.0.0, перенесённой из SULLYTEST2.