AzkiDeck-mcp-server

Многопользовательский MCP-ретрансляционный сервер для AzkiDeck: позволяет MCP-клиентам (Claude Desktop / Claude Code и т.д.) подключаться в любое время и в любом месте к приложению AzkiDeck на телефоне пользователя (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 核心)

Возможности

• Мультитенантная изоляция: учётные данные — это тенант. Учётные данные генерируются и хранятся в мобильном приложении (используется токен локального моста приложения), сервер хранит только SHA-256 хэш; устройства, инструменты и буферы разных тенантов полностью изолированы.

• Агрегация нескольких устройств: один и тот же токен может использоваться на нескольких телефонах (iPhone + Android), списки инструментов автоматически дедуплицируются и объединяются, вызовы маршрутизируются на самое недавно активное устройство.

• Офлайн-повторная отправка: если устройство переподключается в течение 10 минут после разрыва, повторно отправляются вызовы уведомлений за последние 5 минут (прогресс автоматически сжимается до последнего, уведомления, очищенные через clear, не повторяются); если окно превышено, устройство считается офлайн и повторная отправка не выполняется.

• Публичный/приватный двойной режим: в публичном режиме достаточно указать адрес для сопряжения; в приватном режиме также требуется ключ развёртывания; переключение возможно во время работы, при переключении можно потребовать повторную аутентификацию всех сопряжённых устройств.

• Минимальные зависимости: во время выполнения только одна зависимость ws; Node ≥ 22.13 (используется встроенный node:sqlite).

Related MCP server: Remote Control MCP (Electrobun)

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

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

Для публичного развёртывания необходимо включить TLS (встроенные TLS_CERT/TLS_KEY или обратный прокси Caddy/nginx), подробнее см. docs/deployment.md.

Настройка на телефоне

1. Приложение → Инструменты → AI-мост уведомлений: убедитесь, что он включён (токен находится здесь)

2. Режим ретрансляции (страница настроек): укажите адрес сервера, учётные данные автоматически используют токен моста; если сервер в приватном режиме, также укажите ключ развёртывания

3. Когда приложение показывает «Ретрансляция подключена», сопряжение завершено

Подключение MCP-клиента

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

Несколько клиентов (компьютер, ноутбук, CI) могут использовать один и тот же токен.

Отладка с фейковым устройством (без телефона)

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

Управление

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 управления во время выполнения (включается переменной окружения ADMIN_TOKEN):

Конфигурация (переменные окружения)

Модель безопасности

• Сервер никогда не хранит учётные данные в открытом виде (SHA-256 хэш), сравнение выполняется с помощью алгоритма постоянного времени

• Для публичного развёртывания обязательно используйте TLS; токен имеет 128-битную энтропию, 401 ограничивается по IP-адресу источника

• Отзыв учётных данных вступает в силу немедленно: онлайн-устройства отключаются, MCP-сторона получает 401, и автоматическое восстановление невозможно

• Приватный режим ограничивает «кто может сопрягаться» только теми, у кого есть ключ развёртывания; переключение require_reauth может принудительно потребовать повторную аутентификацию всех сопряжённых устройств

Отношение к режиму локальной сети

Оба режима могут быть включены одновременно, они не влияют друг на друга.

Разработка

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

Детали протокола см. в docs/protocol.md (спецификация реализации на телефоне).

Лицензия

Apache-2.0