Sakura-MCP-Server

Sakura-MCP-Server — это защищённый удалённый MCP-шлюз для Life Dashboard, Home Assistant и DSH. Сервис основан на официальном MCP TypeScript SDK v2 и предоставляет конечную точку Streamable HTTP: https://ваш-домен/mcp.

Текущие возможности

• Двойная аутентификация: Bearer API Key и Authentik JWT (OIDC); обе используют общую модель разрешений на основе scope.

• RFC 9728 Protected Resource Metadata: /.well-known/oauth-protected-resource/mcp.

• Stateless MCP transport на каждый запрос: аутентификация и разрешения инструментов никогда не переиспользуются между клиентскими сессиями.

• Бизнес-инструменты регистрируются только после настройки соответствующего адаптера:

  • Home Assistant: запрос состояния сущностей, управление сущностями из белого списка, активация сценариев из белого списка;

  • внутренний API Life Dashboard: чтение общего обзора жизни, сводки рабочих пространств DSH, отправка follow-up в DSH;

  • журнал аудита в формате JSON Lines.

• Docker, Nginx, GitHub CI и автоматическое создание GitHub Release по тегам v*.

Агентам никогда не раскрываются токен Home Assistant, токен Authentik, ключ сопряжения DSH или Shell сервера.

Related MCP server: Home Assistant MCP Server

Локальный запуск

Требуется Node.js 22+. Если Windows PowerShell запрещает npm.ps1, используйте npm.cmd.

cd D:\Sakura-MCP-Server
Copy-Item .env.example .env
# 编辑 .env：至少替换 PUBLIC_BASE_URL 和 MCP_API_KEYS 中的示例 secret
npm.cmd install
npm.cmd run check
npm.cmd run build
npm.cmd start

Проверка работоспособности:

Invoke-RestMethod http://127.0.0.1:3000/health

Формат API Key и Scope

MCP_API_KEYS — это список записей через запятую, формат:

MCP_API_KEYS=cline-prod:一个至少32字节的随机密钥:life:read|home:read|dsh:summary,automation:另一个随机密钥:home:control

Генерация ключа:

node -e "console.log(require('node:crypto').randomBytes(32).toString('base64url'))"

Доступные scopes: life:read, home:read, home:control, todo:read, todo:write, dsh:summary, dsh:details, dsh:followup.

Клиенту необходимо указать в настройках удалённого сервиса MCP:

URL: https://mcp.example.com/mcp
Authorization: Bearer <分配给该 Agent 的密钥>

Поля конфигурации UI у разных агентов отличаются; если агент поддерживает Streamable HTTP MCP с заголовком Authorization, указанный выше URL подойдёт. Создавайте отдельный API Key для каждого агента и выдавайте только необходимые scopes.

Authentik OIDC / OAuth

После полной настройки AUTHENTIK_ISSUER, AUTHENTIK_AUDIENCE и AUTHENTIK_JWKS_URI сервис проверяет издателя, аудиторию, срок действия и подпись JWT; стандартный claim scope (или claim, указанный в AUTHENTIK_SCOPE_CLAIM) сопоставляется с MCP scopes.

Текущая реализация — это MCP Resource Server, который принимает Bearer JWT, выпущенные Authentik с аудиторией, предназначенной исключительно для MCP-сервиса. Удалённому OAuth-клиенту также потребуется создать в Authentik OAuth 2.1 Provider с включёнными Authorization Code + PKCE, точным redirect URI, сопоставлением scope и аудиторией. Не пересылайте полученный JWT пользователя MCP в Home Assistant или Life Dashboard; адаптеры должны использовать собственные сервисные учётные данные.

Конфигурация бизнес-адаптеров

Home Assistant

Задайте HOME_ASSISTANT_URL и выделенный токен с минимальными правами. Операции записи регистрируются/выполняются только для ресурсов, явно перечисленных в соответствующих переменных белого списка:

HOME_ASSISTANT_CONTROLLABLE_ENTITIES=light.living_room,switch.coffee_machine
HOME_ASSISTANT_ALLOWED_SCENES=scene.good_night

Life Dashboard / DSH

Существующий config.php — это браузерный OIDC-шлюз, и MCP Server не может имитировать браузер для вызова. Добавьте в Life Dashboard выделенный внутренний сервисный API с отдельным сервисным токеном и минимальным набором возвращаемых полей. В проекте зарезервировано:

GET  /internal/mcp/overview
GET  /internal/mcp/dsh/workspaces
POST /internal/mcp/dsh/followups

Соответствующие инструменты регистрируются только после настройки LIFE_DASHBOARD_INTERNAL_URL и LIFE_DASHBOARD_INTERNAL_TOKEN. DSH по-прежнему должен использовать существующие ограничения: одноразовое сопряжение, HMAC, защита от повтора, явная авторизация для деталей, лимит 8 000 символов и очередь команд на 120 секунд.

Развёртывание с Docker и Nginx

На сервере:

cp .env.example .env
# 填写真实配置，并 chmod 600 .env
mkdir -p data
docker compose up -d --build

Контейнер по умолчанию привязан только к локальному адресу сервера 127.0.0.1:3000. Используйте nginx-mcp.conf.example для настройки HTTPS-обратного прокси; необходимо сохранять заголовок Authorization. В production открыт только порт 443, порт 3000 не должен быть доступен напрямую.

Релизы

Пуш в main запускает проверку типов, модульные тесты и сборку Docker. После создания и пуша семантического тега автоматически выполняются тесты, npm pack и создание GitHub Release:

git tag v0.1.0
git push origin v0.1.0

Текущие ограничения и следующие шаги

Первая версия уже включает протокол MCP, аутентификацию, разрешения, адаптер HA и каркас развёртывания. После того как вы предоставите домен сервера, информацию об Authentik Provider и внутренний API Life Dashboard, следующими шагами станут: реальное тестирование браузерной OAuth-авторизации, PHP-внутренний API Life Dashboard, инструменты To Do/календаря и проверка production-развёртывания.