AzkiDeck-mcp-server

El servidor de retransmisión MCP multi-tenant de AzkiDeck: permite que los clientes MCP (Claude Desktop / Claude Code, etc.) se conecten desde cualquier lugar al dispositivo móvil con la AzkiDeck App (Android / iOS) para enviar notificaciones al reloj, instalar esferas / aplicaciones rápidas y gestionar iconos de notificaciones — sin necesidad de que el teléfono y el ordenador estén en la misma red local.

MCP 客户端(Claude Desktop 等)
        │  POST /mcp  (Streamable HTTP, 无状态, Bearer 令牌)
        ▼
┌─────────────────────────────────────────────┐
│            azkideck-mcp-server              │
│  node:http ─┬─ /mcp      → MCP 分发          │
│             ├─ /device   → 设备接入(WS)      │
│             ├─ /admin/*  → 管理面            │
│             └─ /healthz                     │
│  多租户:凭证即租户,SHA-256 哈希隔离         │
│  持久化:SQLite(node:sqlite,零原生依赖)     │
└─────────────────────────────────────────────┘
        ▲  wss://server/device (手机出站连接,绕开 NAT)
        │  register → mcp-request/response ↔ replay
   Android / iOS App(复用 App 内已有的 MCP 核心)

Características

• Aislamiento multi-tenant: la credencial es la tenant. La credencial la genera y la conserva la App del teléfono (reutiliza el token de puente de red local de la App); el servidor solo almacena el hash SHA-256; los dispositivos, herramientas y colas de cada tenant están completamente aislados.

• Agregación de múltiples dispositivos: una misma credencial admite varios teléfonos (iPhone + Androide), las herramientas se deduplican automáticamente y las llamadas se rutan al dispositivo activo más recíste.

• Reenvío ofline: si el dispositivo se reconcata dentro de los 10 minutos, se reenvía las llamadas de notifciación de los últimos 5 minutos (las de progreso se comprimen en la últma; las notifcaciones eliminadas con clear no se renvíes); si se supera la ventana, se trata como ofiine y no se renvían.

• Modo público/privado dual: en modo público solo require la dirección para vinclarse; en el modo privado se require ademas una clave de despliegue; se puede cambir en caliente, y al cambiar se puede optionar si se reautentican los disposivos ya vinculados.

• Dependencias m'nimas: en tiempo de ejecución solo se necesita ws; Node ≥ 22.13 (sando node:sqlite integra).

Related MCP server: Remote Control MCP (Electrobun)

Inicio rápido

# 需要 Node.js ≥ 22.13。尚未发布到 npm registry,从源码安装:
git clone https://github.com/AzumaChiaki/AzkiDeck-mcp-server.git
cd AzkiDeck-mcp-server
npm ci && npm run build

node dist/cli.js serve     # 默认监听 0.0.0.0:8787
# 可选:npm link 注册全局 azkideck-mcp-server 命令

Para un despliegue por internet (>en) debemos forzar TLS (con TLS_CERT/TLS_KEY integrados, o con un proxy reverso Caddy/nginx); ver docs/deployment.md.

Configuración en el teléfono

1. App → 连接中心 → puente de notificaciones (AI): confirmar que está activado (el token está aquí)

2. En el modo de retransmisión (página de ajustes): rellenar la dirección del servidor; la credencial se reutiliza automáticamente el token de puente; si el servidor está en modo privado, indicar también la clave de despliegue.

3. El teléfono muestra "relay conectado" y el emparejamiento ha terminado.

Conexión de un cliente MCP

claude mcp add --scope user --transport http azki-watch \
  https://你的服务器/mcp --header "Authorization: Bearer <手机 App 里的令牌>"

Varios clientes (ordenador, portátil, CI) pueden compartir el mismo token.

Pruebas de integración con mock dispositivo ( sin móvil)

azkideck-mcp-server serve &
node scripts/fake-device.mjs --server ws://127.0.0.1:8787 --credential <任意32位hex>
# 之后 Claude 里调用 send_notification,假设备终端会打印 payload

Gestión

azkideck-mcp-server tenants list                    # 租户列表
azkideck-mcp-server tenants create                  # 预置租户(AUTO_REGISTER=false 时)
azkideck-mcp-server tenants revoke <id前缀>         # 撤销
azkideck-mcp-server tenants allow <id前缀>          # 恢复
azkideck-mcp-server mode get                        # 查看公开/私有模式
azkideck-mcp-server mode set private --key <hex> [--reauth]

API de administración en tiempo de ejecución (se habilita definiendo la variable de entorno ADMIN_TOKEN):

Configuración (variables de entorno)

Modelo de seguridad

• El servidor nunca almacena las credenciales en texto plano (SHA-256 hash), compara con un algoritmo de tiempo constante.

• En despliegues públicos se recomienda forzar TLS; el token tiene 128 bits de entropía; los errores 401 se limitan por IP de origen.

• La revocación de credencial tiene efecto inmediato: los dispositivos en línea son expulsados, en el lado MCP recibe 401 y no se recuperan solos.

• El modo privado reduce a "quién puede vincularse" a los que tienen la clave de despliegue; al cambiar require_reauth se puede obligar a redeterminar todos los dispositivos ya vinculados.

Relación con el modo de red local

Ambas se pueden activarle a la vez sin interferir.

Desarrollo

npm install
npm run dev        # tsx watch
npm test           # vitest(含 e2e:真实端口 + 假设备)
npm run lint && npm run typecheck

Los detalles del protocolo están en docs/protocol.md (especificación de implementación del lado del móvil).

License

Apache-2.0