linjian-peek-public

# Tool List [](https://dashboard.render.com/blueprint/new?repo=https://github.com/linzhi-524/linjian-peek-public) A self-deployed mobile state, screenshot and light control MCP tool. It consists of three parts: - `android/`: Android mobile app, responsible for uploading light life state, executing screenshot / return / home / open app / click / slide / notification / alarm and other commands after user explicit authorization. - `server/`: Zero-dependency Python backend, responsible for saving recent screenshots, command queue, command return and mobile life state. - `mcp/`: MCP service, exposing backend capabilities to MCP-enabled AI clients. The public version has been desensitized: no real token, server address, personal device ID or private text case. Please deploy yourself, set a strong random key, and only connect your own device. ## What can it do - **Light State**: Battery, charging status, network, screen on/off, current app, today's screen time, unlock times, Top app, city/weather note, permission status. - **See**: AI client requests screenshot, mobile end screenshots and uploads while authorization service is running. - **Control**: Open whitelist app, return, home, recent tasks, click, slide. - **Remind**: Send system notifications, set system alarms. - **Active Reminder**: Pop up notifications on the mobile device according to rules, including low battery, screen time, drink water, rest eyes, menstrual period approaching/ongoing. ## Security Boundary These capabilities are sensitive. The public version emphasizes "user self-deployment, self-authorization, self-device use" by default. - Do not submit real `LINJIAN_TOKEN` to the repository. - Do not make MCP service public for strangers to use. - Screenshots, read screen, click, slide should only be used on devices with explicit user consent and authorization. - Life state layer does not screenshot by default, only uploads light state. - It is recommended to be cautious with sensitive pages such as payment, chat, wallet, verification code, and do not automatically screenshot or click by default. - High-risk actions such as payment, ordering, deletion, sending messages should always be confirmed by the user. ## Quick Deployment ### 1. One-click Deployment to Render Click the **Deploy to Render** button above, or open: ```text https://dashboard.render.com/blueprint/new?repo=https://github.com/linzhi-524/linjian-peek-public ``` Deployment page suggestions: ```text Blueprint Name:随意取，例如 linjian-peek Branch：main Blueprint Path：留空 ``` After deployment, two services will be obtained: ```text linjian-peek-server → Android App fill this bare address linjian-peek-mcp → GPT / MCP client fill this address + /mcp ``` Example: ```text Android App Server URL：https://linjian-peek-server-xxxx.onrender.com MCP URL：https://linjian-peek-mcp-xxxx.onrender.com/mcp Old SSE：https://linjian-peek-mcp-xxxx.onrender.com/sse ``` `LINJIAN_TOKEN` will be automatically generated in the server service, and MCP will reference the same string. Android App needs to fill in the same token. See [`docs/render-one-click.md`](docs/render-one-click.md) for detailed steps. ### 2. Render Requires Card Binding: Hugging Face Spaces If Render Free also requires card binding verification, you can use Hugging Face Spaces Docker version. This solution combines mobile backend and MCP into one Space, only one external address is needed. Fill in: ```text Android App Server URL：https://your-username-your-Space-name.hf.space MCP URL：https://your-username-your-Space-name.hf.space/mcp Old SSE：https://your-username-your-Space-name.hf.space/sse ``` Quick steps: ```text 1. Hugging Face → New Space 2. SDK select Docker, Hardware select CPU Basic / Free 3. Upload all files in this repository 4. Settings → Variables and secrets 5. Add Secret: LINJIAN_TOKEN=your long random key 6. Wait for Build to complete, then open /health and /mcp_health to check ``` See [`docs/huggingface-spaces.md`](docs/huggingface-spaces.md) for detailed steps. ### 3. Manual Deployment of Backend Server Start `server/linjian_server.py` on Render / VPS / local machine. Environment variable example: ```bash LINJIAN_TOKEN=please replace with a long random key LINJIAN_KEEP=3 PORT=8513 ``` Render manual configuration: - Root Directory: `server` - Build Command: leave blank or `echo ok` - Start Command: `python linjian_server.py` - Env: `LINJIAN_TOKEN` ### 4. Manual Deployment of MCP Service ```bash cd mcp npm install npm start ``` Environment variable example: ```bash LINJIAN_URL=https://your-backend-address.onrender.com LINJIAN_TOKEN=same token as backend LINJIAN_DEFAULT_DEVICE=my-phone ``` Render manual configuration: - Root Directory: `mcp` - Build Command: `npm install` - Start Command: `npm start` - Env: `LINJIAN_URL`, `LINJIAN_TOKEN`, `LINJIAN_DEFAULT_DEVICE` ### 5. Android APK GitHub Actions will build Debug APK. You can also run it in an environment that supports Android SDK: ```bash bash android/build.sh ``` Build output: ```text android/PalmWindow-v0.1.8.apk ``` After installation, fill in the App: - Server URL: your backend address - Token: same `LINJIAN_TOKEN` as backend - Device ID: default `my-phone`, can be customized Then enable accessibility service, screenshot permission, notification permission, usage access permission. ## MCP Tools - `linjian_status`: Check backend online status. - `get_life_state`: Read light life state, does not screenshot by default. - `get_phone_state`: Read recent mobile state. - `peek_screen`: Request new screenshot and wait for return. - `latest_screen`: Read server's latest screenshot. - `list_known_apps`: List preset app package name whitelist. - `open_app`: Open specified app or package name. - `phone_home` / `phone_back` / `phone_recents`: System navigation. - `send_phone_command`: Send low-level command. - `send_notification`: Send system notification. - `set_alarm`: Set system alarm. ## v0.1.9 Features - Added `render.yaml`, supports Render Blueprint one-click deployment. - README top added Deploy to Render button. - Added `docs/render-one-click.md`, explains how to fill in Server / MCP two addresses. ## v0.1.8 Features - Life State life state layer. - Active Reminder active reminder rule layer. - Menstrual period reminder status and local reminder. - UI: settings / see / control / state / log bottom navigation. - Command return and log page. ## Follow-up Can Continue to Do - Screenshot diagnosis field: `screenshot_ready`, `last_screenshot_at`, `last_screenshot_error`. - `peek_screen(delay_seconds=3)`: Give user a delayed screenshot. - OCR lyric backup: music app lyric page screenshot and recognize current lyric. - Take-out / ordering consultant: only assist in selection, payment and final confirmation must be completed by user. - More detailed privacy whitelist / blacklist.