Sakura-MCP-Server

Sakura-MCP-Server es una pasarela MCP remota segura para Life Dashboard, Home Assistant y DSH. El servicio se basa en el SDK oficial de MCP TypeScript v2 y ofrece un endpoint Streamable HTTP: https://tu-dominio/mcp.

Capacidades actuales

• Doble autenticación: Bearer API Key y Authentik JWT (OIDC); ambos comparten el modelo de permisos por scope.

• Metadatos de recurso protegido RFC 9728: /.well-known/oauth-protected-resource/mcp.

• Transporte MCP sin estado por petición: la autenticación y los permisos de las herramientas nunca se reutilizan entre sesiones de cliente.

• Las herramientas de negocio solo se registran si el Adapter correspondiente está configurado:

  • Home Assistant: consultar estado de entidades, controlar entidades en lista blanca, activar escenas en lista blanca;

  • API interna de Life Dashboard: leer resumen general de vida, resumen del espacio de trabajo DSH, enviar follow-up de DSH;

  • Registro de auditoría en JSON Lines.

• Docker, Nginx, GitHub CI y creación automática de GitHub Release con tags v*.

No se exponen al Agent el Token de Home Assistant, el Token de Authentik, la clave de emparejamiento de DSH ni el Shell del servidor.

Related MCP server: Home Assistant MCP Server

Inicio local

Requiere Node.js 22+. Si Windows PowerShell bloquea npm.ps1, usa 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

Verifica el health check:

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

Formato de API Key y Scope

MCP_API_KEYS es una lista de entradas separadas por comas, con el formato:

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

Genera una clave:

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

Scopes disponibles: life:read, home:read, home:control, todo:read, todo:write, dsh:summary, dsh:details, dsh:followup.

El cliente debe rellenar en la configuración del servicio remoto MCP:

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

Los campos de configuración de la UI varían según el Agent; siempre que admita Streamable HTTP MCP con cabecera de petición Authorization, puede usar la URL anterior. Crea una API Key distinta para cada Agent y concédele únicamente el scope necesario.

Authentik OIDC / OAuth

Con AUTHENTIK_ISSUER, AUTHENTIK_AUDIENCE y AUTHENTIK_JWKS_URI completamente configurados, el servicio verifica el emisor, la audiencia, la expiración y la firma del JWT; el claim estándar scope (o el claim especificado por AUTHENTIK_SCOPE_CLAIM) se mapea a los scopes MCP.

La implementación actual es un Resource Server MCP que acepta Bearer JWT emitidos por Authentik cuya audiencia está dedicada exclusivamente al servicio MCP. El cliente OAuth remoto también necesita crear un Provider OAuth 2.1 en Authentik, habilitando Authorization Code + PKCE, redirect URI exacta, mapeo de scopes y audiencia. No reenvíes el JWT de usuario MCP recibido a Home Assistant ni a Life Dashboard; los Adapters deben usar sus propias credenciales de servicio.

Configuración de los Adapters de negocio

Home Assistant

Configura HOME_ASSISTANT_URL y un Token dedicado con permisos mínimos. Las operaciones de escritura solo se registran/ejecutan si el recurso correspondiente está listado explícitamente en las variables de lista blanca:

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

Life Dashboard / DSH

El config.php actual es una pasarela OIDC para navegador; el MCP Server no puede hacerse pasar por el navegador para invocarla. Añade posteriormente en Life Dashboard una API de servicio interna dedicada, con un service token independiente y campos de retorno mínimos. Este proyecto reserva:

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

Las herramientas correspondientes solo se registran tras configurar LIFE_DASHBOARD_INTERNAL_URL y LIFE_DASHBOARD_INTERNAL_TOKEN. DSH debe seguir manteniendo el emparejamiento único existente, HMAC, protección contra replay, autorización explícita de detalles, y los límites de 8.000 caracteres y cola de comandos de 120 segundos.

Despliegue con Docker y Nginx

En el servidor:

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

El contenedor por defecto solo se vincula a 127.0.0.1:3000 del propio servidor. Usa nginx-mcp.conf.example para configurar el proxy inverso HTTPS; es obligatorio conservar la cabecera de petición Authorization. En producción solo abre el puerto 443; no expongas el 3000 directamente.

Publicación

Al hacer push a main se ejecutan la comprobación de tipos, las pruebas unitarias y la construcción de Docker. Al crear y subir un tag semántico se ejecutan automáticamente las pruebas, npm pack y la creación de GitHub Release:

git tag v0.1.0
git push origin v0.1.0

Limitaciones actuales y siguientes pasos

La primera versión ya completa el protocolo MCP, la autenticación, los permisos, el adaptador de HA y el esqueleto de despliegue. Cuando me proporciones el dominio del servidor, la información del Provider de Authentik y la API interna de Life Dashboard, los siguientes pasos serán completar las pruebas de interoperabilidad de autorización OAuth real en navegador, la API interna PHP de Life Dashboard, las herramientas de To Do/calendario y la validación del despliegue en producción.