AzkiDeck-mcp-server

AzkiDeck 的多租户 MCP 中继服务器:让 MCP 客户端(Claude Desktop / Claude Code 等)随时随地连到用户手机上的 AzkiDeck App(Android / iOS),把通知推上手表、安装表盘/快应用、管理通知图标——不再要求手机与电脑处于同一局域网。

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 核心)

Eigenschaften

• Multi-Tenant-Isolation:Die Anmeldedaten sind der Mandant. Die Anmeldedaten werden von der mobilen App generiert und gehalten (Wiederverwendung des LAN-Bridge-Tokens der App); der Server speichert nur den SHA-256-Hash; Geräte, Tools und Puffer verschiedener Mandanten sind vollständig isoliert.

• Multi-Geräte-Aggregation:Derselbe Anmeldedatensatz kann mehrere Telefone (iPhone + Android) anhängen; die Tool-Liste wird automatisch dedupliziert und zusammengeführt, Aufrufe werden an das zuletzt aktive Gerät weitergeleitet.

• Offline-Nachlieferung:Wenn ein Gerät innerhalb von 10 Minuten wieder verbunden wird, werden Benachrichtigungsaufrufe der letzten 5 Minuten nachgeliefert (Fortschrittsaufrufe werden automatisch auf den neuesten Eintrag komprimiert; durch clear gelöschte Benachrichtigungen werden nicht nachgeliefert); außerhalb des Fensters wird als offline gewertet und nicht nachgeliefert.

• Öffentlicher/privater Doppelmodus:Im öffentlichen Modus genügt die Angabe der Adresse zur Kopplung; im privaten Modus ist zusätzlich ein Bereitstellungsschlüssel erforderlich; während des Betriebs kann umgeschaltet werden, wobei optional eine erneute Authentifizierung bereits gekoppelter Geräte verlangt werden kann.

• Minimale Abhängigkeiten:Zur Laufzeit nur eine Abhängigkeit ws; Node ≥ 22.13 (verwendet eingebautes node:sqlite).

Related MCP server: Remote Control MCP (Electrobun)

Schnellstart

# 需要 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 命令

Bei öffentlicher Bereitstellung muss TLS aktiviert sein (eingebautes TLS_CERT/TLS_KEY oder Reverse-Proxy mit Caddy/nginx), siehe docs/deployment.md.

Konfiguration auf dem Telefon

1. App → Werkzeugkasten → AI-Benachrichtigungsbrücke: bestätigen, dass sie aktiviert ist (das Token befindet sich hier)

2. Relay-Modus (Einstellungsseite): Serveradresse eintragen, die Anmeldedaten übernehmen automatisch das Brücken-Token; wenn der Server im privaten Modus ist, muss zusätzlich der Bereitstellungsschlüssel eingetragen werden

3. Die App zeigt „Relay verbunden" an, die Kopplung ist abgeschlossen

MCP-Client-Anbindung

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

Mehrere Clients (Computer, Laptop, CI) können dasselbe Token gemeinsam nutzen.

Testgerät-Integration (ohne Telefon)

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

Verwaltung

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]

Laufzeit-Verwaltungs-API (aktiviert durch die Umgebungsvariable ADMIN_TOKEN):

Konfiguration (Umgebungsvariablen)

Sicherheitsmodell

• Der Server speichert niemals Anmeldedaten im Klartext (SHA-256-Hash), der Vergleich verwendet einen Algorithmus mit konstanter Zeit.

• Bei öffentlicher Bereitstellung bitte TLS erzwingen; das Token hat 128 Bit Entropie, 401 wird pro Quell-IP begrenzt.

• Widerruf der Anmeldedaten wirkt sofort: Online-Geräte werden gekickt, MCP-Seite erhält 401, und es erfolgt keine automatische Wiederherstellung.

• Der private Modus beschränkt „wer koppeln kann" auf Personen mit dem Bereitstellungsschlüssel; mit require_reauth kann beim Umschalten eine erneute Authentifizierung aller gekoppelten Geräte erzwungen werden.

Beziehung zum LAN-Modus

Beide können gleichzeitig aktiviert werden, ohne sich gegenseitig zu beeinflussen.

Entwicklung

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

Protokolldetails siehe docs/protocol.md (Implementierungsspezifikation für die Telefonseite).

Lizenz

Apache-2.0