sully-termux-mcp

sully-termux-mcp는 Termux에서 MCP 도구를 실행하기 위한 Node.js 20+ TypeScript ESM 게이트웨이입니다. 프로덕션 기본값은 의도적으로 작게 유지됩니다. 루프백 주소에서만 수신하며, 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)를 설치하고, 동일한 서명 소스(예: 둘 다 F-Droid에서, 또는 둘 다 GitHub에서)에서 Termux:API 동반 Android 앱을 설치하세요. 두 패키지가 서로 다른 서명 소스에서 오면 Android는 API 호출을 전달하지 않습니다. Termux:API를 설치하거나 업데이트한 후 게이트웨이를 다시 시작하여 명령 인벤토리가 다시 빌드되도록 하세요.

MCP 엔드포인트는 http://127.0.0.1:8765/mcp입니다. 이 릴리스는 initialize, notifications/initialized, tools/list, tools/call을 사용하는 안정적인 2025-11-25 및 2025-06-18 세션 기반 프로토콜을 지원합니다. 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, 명령 프로필, 셸 작업, 작업 상태/출력/취소/정리, 그리고 감지된 Termux:API 명령(유형화된 위치, 카메라, 알림, 토스트, 클립보드, SMS, TTS, 볼륨, 손전등 입력 포함)이 포함됩니다. 덜 일반적인 API 명령은 사용법/도움말 힌트와 함께 제한된 원시 args를 노출합니다. 정확한 옵션은 설치된 명령의 --help를 참조하세요. shell_exec는 항상 shell:false로 bash -lc를 생성합니다. 명령 프로필과 stdio 업스트림은 shell:false로 실행 파일과 인수 배열을 사용합니다. 작업은 재시작 후 interrupted로 유지되며, 최대 8 MiB를 캡처하고, 출력 요청당 최대 64 KiB를 반환합니다. 요청은 1 MiB로, 응답은 4 MiB로 제한됩니다. 도구 동시성은 기본적으로 4입니다.

HTTP 업스트림은 HTTPS를 사용해야 하며, 정확한 리터럴 루프백 호스트 127.0.0.1/::1(DNS 별칭이나 공백 없음)에 대한 HTTP만 허용됩니다. 개인, 링크-로컬 또는 메타데이터 범위로 확인되는 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에 따라 라이선스가 부여됩니다.