Lifesign — User Status & Health Telemetry Server

Lightweight HTTP service: receives device status + health data reported from mobile devices and exposes it to AI agents via MCP (Model Context Protocol). Single process, single port.

✨ Features

• 📱 Mobile Reporting: iOS Shortcut POST /ingest pushes battery/location/network/health snapshots

• 🤖 MCP Gateway: /mcp mounted in the same process, directly readable by AI agents like Hermes

• 🏗️ Single Port, Single Process: Upload + query + MCP all reuse port 8764, no secondary HTTP hop

• 🐳 Docker Ready: GitHub Actions automatically builds images, 1Panel one-click Compose deployment

Related MCP server: Rouse Context

🏗️ Architecture

手机 (iOS 快捷指令)
   │ POST https://<your-domain>/user-status/ingest   ← 仅上传经反代
   ▼
1Panel OpenResty (反向代理)
   │ proxy_pass → <host-ip>:8764/ingest
   ▼
┌──────────────────────────────┐
│ FastAPI + FastMCP 同一进程    │
│  (单端口 8764)               │
│                              │
│  POST /ingest   手机上传      │
│  GET  /query_all  agent读取  │
│  /mcp  MCP 网关 (同进程)      │
└──────┬───────────────────────┘
       │ 本机回环 http://127.0.0.1:8764/mcp
       ▼
   Hermes Agent (AI)

• Mobile Upload: Public HTTPS via reverse proxy → 8764/ingest

• AI Reading: Local loopback direct connection to 8764/mcp (not via public network)

• Shared Memory: MCP tools directly read app.store, no serialization or secondary requests needed

🔌 Endpoints

🔑 Identity and Configuration

Only two shared secrets for identity verification (identity markers, not field-level authorization), both overridable via environment variables:

⚠️ Production deployment must override default secrets via environment variables, do not use default values from the repository.

🚀 Quick Start

Local Run

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
./run.sh start      # 后台启动 :8764
./run.sh status
./run.sh stop

Docker Run

# 本地构建
docker build -t lifesign:local .
docker run -d --name lifesign -p 8764:8764 \
  -e USER_STATUS_PHONE_KEY='<phone-key>' \
  -e USER_STATUS_AGENT_KEY='<agent-key>' \
  lifesign:local

1Panel Compose Deployment (Recommended)

1. In 1Panel → Container → Orchestration, create a new orchestration and paste docker-compose.yml;

2. The image is automatically built by GitHub Actions and pushed to GHCR, pulled directly during deployment;

3. Only one port 8764 needs to be exposed, the rest is handled by the reverse proxy.

Sending Data from Mobile

# 经公网反代（手机端快捷指令用这个）
curl -s -X POST https://<your-domain>/user-status/ingest \
  -H "Authorization: Bearer <phone-key>" \
  -H "Content-Type: application/json" \
  -d '{"deviceStage":{"battery":{"percentage":87,"is_charging":true}}}'

# 或内网直连
curl -s -X POST http://<host-ip>:8764/ingest \
  -H "Authorization: Bearer <phone-key>" \
  -H "Content-Type: application/json" \
  -d '{"deviceStage":{"battery":{"percentage":87,"is_charging":true}}}'

Hermes MCP Configuration (config.yaml)

mcp_servers:
  user-status:
    type: streamable-http
    url: http://127.0.0.1:8764/mcp   # 本机回环，不走公网
    connect_timeout: 10
    timeout: 30

Verification: hermes mcp test user-status; after restarting Hermes, tools are registered as mcp_user_status_*.

🐳 Docker Image Build (GitHub Actions)

The repository includes .github/workflows/docker-build.yml:

• Trigger: push to main / manual workflow_dispatch / tag push

• Artifact: ghcr.io/<owner>/lifesign:latest and :<git-sha> dual tags

• Platforms: linux/amd64, linux/arm64

• Note: The image is private (private repository → private GHCR package). When deploying with 1Panel, you need to add GHCR login credentials (ghcr.io username + PAT) in the Docker configuration.

✅ Testing

. .venv/bin/activate
python -m pytest tests/ -v

🗂️ Project Structure

lifesign/
├── app/
│   ├── main.py            # FastAPI 入口（挂载 MCP 网关）
│   ├── mcp_server.py      # FastMCP 工具定义（get_status/get_battery/...）
│   ├── store.py           # 线程安全内存存储
│   ├── models/status.py   # Pydantic 数据模型
│   └── routers/           # /ingest 与 /query_all 路由
├── config/clients.example.yaml   # 身份配置模板（真实文件勿提交）
├── panel_api.py           # 1Panel API 签名请求辅助脚本
├── docker-compose.yml     # 1Panel Compose 部署编排
├── Dockerfile
├── run.sh                 # 本机后台启停
└── tests/

📜 License

MIT