Документация on mtapi — Android HTTP bridge

Быстрый старт

Mon, 01 Jan 0001 00:00:00 +0000

📖 Быстрый старт

Что такое mtapi

mtapi — HTTP-сервер (Go) внутри Android APK. WebView загружает http://127.0.0.1:7788, JS вызывает fetch('/battery') → Go → JNI → Android API → JSON. Без Termux, Shizuku, root.

Установка

1. Скачай APK: release

2. Установи (разреши «неизвестные источники»)

3. Открой mtapi — WebView загрузит dashboard

Первый запрос

В Console Eval (FAB 🐞 → Console) введи:

fetch("/battery").then(r => r.json()).then(j => log(j))

Результат — в JS Logs + Network tab.

API endpoints

Mon, 01 Jan 0001 00:00:00 +0000

🔌 API endpoints

Все — GET, JSON. Вызов: fetch("/endpoint").then(r => r.json()).then(j => log(j))

Basic (16)

Endpoint	Returns
`/ping`	pong
`/battery`	level, charging
`/wifi`	ssid, rssi
`/device`	model, sdk
`/location`	lat, lon
`/clipboard`	text
`/clipboard?op=set&text=hello`	set clipboard
`/toast?text=hello`	show toast
`/notify?title=Hi&body=There`	notification
`/vibrate?ms=200`	vibrate
`/torch?on=1`	flashlight on
`/torch?on=0`	off
`/torch/brightness?level=50`	set brightness
`/torch/brightness?level=0`	reset
`/tts?text=hello`	text-to-speech
`/share?title=Hi&text=There`	share intent

Contacts / SMS (3)

Endpoint	Returns
`/contacts?limit=0`	contacts (0=all)
`/calllog?limit=0`	call log
`/sms?limit=0`	SMS

System (6)

Endpoint	Returns
`/system`	device info
`/cpu/detail`	CPU cores
`/thermal`	temperatures
`/memory`	RAM
`/storage`	disks
`/kernel`	kernel version

Network (8)

Endpoint	Returns
`/network`	connectivity
`/wifi/detailed`	WiFi detail
`/bluetooth`	BT state
`/telephony`	SIM/carrier
`/wifi/scan`	WiFi scan
`/net/ping?host=8.8.8.8&count=3`	ping
`/net/dns?host=example.com`	DNS
`/net/fetch?url=https%3A%2F%2Fapi.ipify.org%3Fformat%3Djson`	fetch URL

Display / Audio (7)

Endpoint	Returns
`/display`	screen info
`/display/brightness`	brightness
`/display/color`	color mode
`/audio`	volume levels
`/microphone`	mic state
`/audio/volume?stream=2`	set volume
`/audio/ringer`	ringer mode

Sensors (4)

Endpoint	Returns
`/sensors`	list
`/sensors/read?name=accelerometer&ms=200`	read
`/sensors/stream?name=accelerometer&hz=10`	stream
`/sensors/stream/stop?name=accelerometer`	stop

Hardware (4)

Endpoint	Returns
`/features`	hw features
`/camera/list`	cameras
`/camera/snapshot`	snapshot
`/microphone/record?seconds=3`	record

Apps (2)

Endpoint	Returns
`/app/list`	installed apps
`/app/launch?pkg=com.android.settings`	launch app

Detailed (5)

Endpoint	Returns
`/battery/detailed`	battery detail
`/location/detailed`	location detail
`/locale`	locale
`/calendar?days=7`	calendar
`/alarm/next`	next alarm

Files / Audio play (5)

Endpoint	Returns
`/files/save?name=test.txt&data=hello`	save file
`/audio/play?uri=/system/media/audio/notifications/Hello.ogg`	play
`/audio/play/stop`	stop
`/tts/voices`	TTS voices
`/tts/stop`	stop TTS

Watch (4)

Endpoint	Returns
`/clipboard/watch?hz=2`	watch clipboard
`/clipboard/watch/stop`	stop
`/location/watch?hz=1`	watch location
`/location/watch/stop`	stop

Debug overlay

Mon, 01 Jan 0001 00:00:00 +0000

🐞 Debug overlay (7 табов)

FAB 🐞 (16×16) в header mtapi → overlay. Topbar: ⚙️ (back) + 7 табов + 🐞 (side panel).

7 табов

Tab	Что
Logs	JS Logs (V/D/I/W/E/F фильтры, search, copy, clear, timer 2с, scrollbar)
Console	Console Eval — textarea (multiline, Ctrl+Enter), ▶ 📋 🗑 ? 🌳
Errors	Persistent errors (localStorage)
Logcat	6 колонок: Time \| PID \| TID \| L \| Tag \| Message. Цвета. Фильтры. Copy. Clear
DevTools	adb инструкции + /devtools/json + Load app.js
System	Performance (таблица) + System info (uptime, port, JS heap, processes)
Network	Requests (fetch logged). Verbose, copy, clear

Console Eval команды

Полный список — JS Console.

DOM inspector

Mon, 01 Jan 0001 00:00:00 +0000

🌳 DOM floating

Кнопка 🌳 в Console Eval → floating окно (DOM tree + info panel).

Возможности

Feature	Как
Select element	`domInspect()` → клик по странице → info
Root toggle	▣ (overlay) / 🌐 (page) — auto при открытии/закрытии debug
Auto-refresh	3с (skip если не изменилось, save open+scroll)
8-edge resize	Тянуть любой край/угол (n/s/e/w + 4 corners)
Splitter	⋮⋮ между tree и info (dblclick — reset)
Minimize	– (свернуть до header)
Drag	Header (mouse + touch)
Select U+25A3	▣ (toggle, magenta когда ON)
Copy HTML	📋 (outerHTML → clipboard, toast)
AI Snap	✨ (markdown: selector, HTML, CSS 24, parent, children, task)

DOM tree

Клик по <summary> — toggle. data-tag на каждом узле. Клик по узлу (inspect ON) — подсветка в дереве.

Browser

Mon, 01 Jan 0001 00:00:00 +0000

🌐 Browser overlay

Кнопка ⚙️ в header mtapi → iframe + toolbar. Default: /help.

Toolbar

Кнопка	Что
⚙️	Back to MTAPI (закрыть browser)
←	Назад (история)
[url]	Input (Enter → navigate)
→	Вперёд
↻	Reload
🐞	Debug (наш overlay)

Загрузка страниц

Метод	Что	Работает
Android.httpGet	Java DNS, no CORS, no X-Frame-Options	любой сайт
/proxy-url?url=...	Go fetch, strips X-Frame-Options	любой сайт (HTML)
fetch → srcdoc	JS fetch → iframe srcdoc	CORS-friendly
iframe.src	Прямая загрузка	X-Frame-friendly

Reverse proxy

/proxy/PORT/* → localhost:PORT/* (whitelist: 5555, 3000, 8080). Same-origin → полный debug.

Native bridge

Mon, 01 Jan 0001 00:00:00 +0000

📱 Native bridge (Android)

JS-объект Android.* — JNI-мост в Java (MainActivity).

Методы

Метод	Что	Copy
`Android.getLogcat(n)`	logcat (n строк)
`Android.processList()`	running processes
`Android.getDeviceInfo()`	device info
`Android.httpGet(url)`	HTTP GET (Java DNS, no CORS)

Примеры

Android.getLogcat(20)

Android.processList()

Android.httpGet("https://html.duckduckgo.com/html/")

Ограничения

Android 11+: logcat для untrusted_app ограничен (SELinux) → Android.getLogcat() может вернуть пусто
httpGet: таймаут 10с, лимит 5MB

Архитектура

Mon, 01 Jan 0001 00:00:00 +0000

🏗️ Архитектура

┌─────────────────────────────────────┐
│ Android (телефон) │
│ ┌───────────────────────────────┐ │
│ │ mtapi APK (MainActivity) │ │
│ │ ┌─────────────────────────┐ │ │
│ │ │ WebView (WebViewClient)│ │ │
│ │ │ ← HTML/CSS/JS (UI) │ │ │
│ │ └─────────────────────────┘ │ │
│ │ ┌─────────────────────────┐ │ │
│ │ │ Go HTTP server (:7788) │ │ │
│ │ │ ← /battery, /camera... │ │ │
│ │ └─────────────────────────┘ │ │
│ │ ┌─────────────────────────┐ │ │
│ │ │ JNI bridge (Go↔Java) │ │ │
│ │ │ ← Android.* API │ │ │
│ │ └─────────────────────────┘ │ │
│ └───────────────────────────────┘ │
└─────────────────────────────────────┘

Компоненты

Файл	Язык	Что
`libmtapi-server.so`	Go	HTTP-сервер (60+ endpoints), proxy, help
`mtapi-debug.js`	JS	Debug overlay, browser, DOM floating, Console
`app.js`	JS	Main UI (endpoints, render, search)
`MainActivity.java`	Java	WebView, JNI bridge, Android.*
`index.html`	HTML	WebView UI
`style.css`	CSS	UI (тема, dark/light)

Flow

JS (WebView) → fetch('/battery')

→ Go HTTP (:7788) → JNI → Java → Android API

→ JSON → JS → render

Сборка

Mon, 01 Jan 0001 00:00:00 +0000

🔨 Сборка

Требования

Termux (Android)
Go 1.22+ (для .so)
Node 22+ (для тестов)
wta (для APK, из ~/w2a)

Команды

Команда	Что	Время
`make so`	Собрать .so (Go)	10с
`make test`	140 тестов	33с
`make apk`	Test + .so + APK	~75с
`make apk-fast`	.so + APK (без тестов)	~35с
`make install`	Собрать + установить	~75с
`make dump`	Инспекция APK	5с

wta (APK без Gradle)

APK собирается через wta — YAML → APK на телефоне. Без Android SDK.

CI

GitHub Actions (ubuntu-latest): Go (build/vet/test/gofmt) + JS tests (140). Timeout: 10/20 мин.

Тесты

Mon, 01 Jan 0001 00:00:00 +0000

✅ Тесты (140)

Структура

Сьют	Кол-во	Что
mtapi/*.test.js	118	app.js, debug, network, logcat, perf, jsdom, eslint
universal: dom	6	jsdom, getElementById, addEventListener
universal: braces	6	баланс скобок, no triple `});`
universal: syntax	6	no SyntaxError, loads in jsdom
universal: node	4	require() in Node, no top-level document

Команды

`make test`	Все 140 (33с)
`bash test/run-all.sh`	Все (33с, с --test-force-exit)
`node --test test/mtapi-debug-v2.test.js`	Один файл

CI

GitHub Actions: .github/workflows/ci.yml. Go (build/vet/test/gofmt) + JS tests (140). Timeout: go 10, js-tests 20.

Предыдущий баг: run-all.sh без --test-force-exit → hang 20+ мин (setInterval в attach()). Фикс: 33с.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

❓ FAQ

Почему fetch не работает в iframe?

CORS: iframe на другом origin → contentDocument = null, fetch блокируется. Решение: /proxy/PORT/ (same-origin) или /proxy-url.

Почему google.com не загружается в iframe?

X-Frame-Options: SAMEORIGIN. Решение: /proxy-url?url=https://google.com (strips header) или Android.httpGet (Java).

Почему DuckDuckGo в браузере?

Default — /help (TOC). Можно сменить: _browserNavigate("https://...").

Почему DNS fail в Go (JNI)?

Go в JNI наследует DNS от Java/WebView ([::1]:53). В Android — нет /etc/resolv.conf. Решение: Android.httpGet (Java DNS) вместо Go http.Get.

JS Console

Mon, 01 Jan 0001 00:00:00 +0000

🖥️ JS Console

Введи в Console Eval (FAB 🐞 → Console), нажми Run (или Ctrl+Enter).

DOM query

Command	Description
`$("#main")`	document.querySelector
`$$("details")`	array of elements
`$$("details").length`	count
`$$("button").map(b => b.id)`	map over nodes
`$("h1").textContent`	text

Inspect / Select

Command	Description
`inspect($("#main"))`	highlight + show in info panel
`inspect(document.body)`	inspect body
`domInspect()`	toggle select mode
`domInspectStop()`	exit select mode
`domShowFloating()`	open floating DOM tree
`_domRefresh()`	refresh tree
`_domToggleRoot()`	overlay <-> page

JS Logs

Command	Description
`log("test", 123, {a: 1})`	push to JS Logs (V)
`warn("careful")`	push (W)
`error("oops")`	push (E)
`MtapiDebug.buffer().length`	JS logs count
`MtapiDebug.errors()`	persistent errors array
`clearEval()`	clear output

Debug tabs

Command	Description
`MtapiDebug.open()`	open overlay
`MtapiDebug.close()`	close overlay
`MtapiDebug.setTab("logs")`	switch to Logs
`MtapiDebug.setTab("console")`	Console Eval
`MtapiDebug.setTab("errors")`	Errors
`MtapiDebug.setTab("logcat")`	Logcat
`MtapiDebug.setTab("devtools")`	DevTools
`MtapiDebug.setTab("system")`	System
`MtapiDebug.setTab("network")`	Network

Perf

Command	Description
`MtapiDebug.perf("my-test", 42)`	record perf metric
`MtapiDebug.time("x")`	start timer
`MtapiDebug.timeEnd("x")`	end timer + record
`MtapiDebug.selectElement("#main h1")`	select + inspect

Network (logged)

Command	Description
`fetch("/ping").then(r => r.json()).then(j => log(j))`	GET /ping
`fetch("/battery").then(r => r.json()).then(j => log(j))`	GET /battery
`fetch("/system").then(r => r.json()).then(j => log(j))`	GET /system
`fetch("/sensors").then(r => r.json()).then(j => log(j))`	GET /sensors

Native (APK only)

Command	Description
`Android.getLogcat(20)`	logcat (20 lines)
`Android.processList()`	running processes
`Android.getDeviceInfo()`	device info

Browser overlay

Command	Description
`_browserOpen()`	open (default /help)
`_browserOpen("https://example.com")`	open URL
`_browserNavigate("https://example.com")`	navigate
`_browserClose()`	close

AI Snap (advanced)

Command	Description
`inspect($("#main"))`	select first
`_aiSnap()`	markdown of selected
`_aiSnapWithRequest("make it red")`	markdown + task
`_captureElement()`	copy outerHTML

Help levels

Command	Description
`?`	quick (5-7)
`??`	cheatsheet (all)
`???`	full (examples + navigation)
`help()`	same as ?