Sakura-MCP-Server

Sakura-MCP-Server ist ein sicherer Remote-MCP-Gateway für Life Dashboard, Home Assistant und DSH. Der Dienst basiert auf dem offiziellen MCP TypeScript SDK v2 und bietet einen Streamable-HTTP-Endpunkt: https://deine-domain/mcp.

Aktuelle Funktionen

• Doppelte Authentifizierung per Bearer-API-Key und Authentik-JWT (OIDC); beide nutzen dasselbe Scope-Berechtigungsmodell.

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

• Zustandsloser MCP-Transport pro Anfrage: Authentifizierung und Tool-Berechtigungen werden niemals über Client-Sitzungen hinweg wiederverwendet.

• Geschäftstools werden nur registriert, wenn der entsprechende Adapter konfiguriert ist:

  • Home Assistant: Entitätsstatus abfragen, Whitelist-Entitäten steuern, Whitelist-Szenen aktivieren;

  • Life-Dashboard-interne API: Lebensübersicht lesen, DSH-Arbeitsbereichsübersicht, DSH-Follow-up senden;

  • JSON-Lines-Auditprotokoll.

• Docker, Nginx, GitHub CI und automatische GitHub-Release-Erstellung bei v*-Tags.

Home-Assistant-Token, Authentik-Token, DSH-Pairing-Schlüssel oder Server-Shell werden niemals gegenüber Agenten offengelegt.

Related MCP server: Home Assistant MCP Server

Lokaler Start

Erforderlich: Node.js 22+. Falls Windows PowerShell npm.ps1 blockiert, verwende 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

Health-Check verifizieren:

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

API-Key-Format und Scope

MCP_API_KEYS ist eine durch Kommas getrennte Liste von Einträgen im Format:

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

Schlüssel generieren:

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

Verfügbare Scopes: life:read, home:read, home:control, todo:read, todo:write, dsh:summary, dsh:details, dsh:followup.

Der Client muss in den MCP-Remote-Diensteinstellungen Folgendes eintragen:

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

Die UI-Konfigurationsfelder unterscheiden sich je nach Agent; solange er Streamable HTTP MCP mit Authorization-Request-Header unterstützt, kann die obige URL verwendet werden. Erstelle für jeden Agent einen eigenen API-Key und gewähre nur die benötigten Scopes.

Authentik OIDC / OAuth

Nach Konfiguration der vollständigen AUTHENTIK_ISSUER-, AUTHENTIK_AUDIENCE- und AUTHENTIK_JWKS_URI-Werte validiert der Dienst Aussteller, Audience, Ablaufzeit und Signatur des JWT; der Standard-scope-Claim (oder der durch AUTHENTIK_SCOPE_CLAIM angegebene Claim) wird auf MCP-Scopes abgebildet.

Die aktuelle Implementierung ist ein MCP-Resource Server, der von Authentik ausgestellte Bearer-JWTs akzeptiert, deren Audience ausschließlich für den MCP-Dienst bestimmt ist. Remote-OAuth-Clients müssen außerdem in Authentik einen OAuth-2.1-Provider erstellen, mit aktiviertem Authorization Code + PKCE, exakter Redirect-URI, Scope-Mapping und Audience. Leite empfangene MCP-Benutzer-JWTs nicht an Home Assistant oder Life Dashboard weiter; Adapter müssen ihre eigenen Dienst-Anmeldeinformationen verwenden.

Konfiguration der Geschäfts-Adapter

Home Assistant

Setze HOME_ASSISTANT_URL und ein dediziertes Token mit minimalen Berechtigungen. Schreiboperationen werden nur registriert/erfolgreich ausgeführt, wenn die Ressource explizit in der entsprechenden Whitelist-Variable aufgeführt ist:

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

Life Dashboard / DSH

Die vorhandene config.php ist ein Browser-OIDC-Gateway und kann vom MCP-Server nicht als Browser aufgerufen werden. Bitte ergänze in Life Dashboard später eine dedizierte interne Service-API mit unabhängigem Service-Token und minimalen Rückgabefeldern. Dieses Projekt reserviert:

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

Die entsprechenden Tools werden erst registriert, wenn LIFE_DASHBOARD_INTERNAL_URL und LIFE_DASHBOARD_INTERNAL_TOKEN konfiguriert sind. DSH sollte weiterhin die bestehenden Einschränkungen beibehalten: einmaliges Pairing, HMAC, Replay-Schutz, explizite Autorisierung für Details, 8.000 Zeichen und 120-Sekunden-Befehls-Warteschlange.

Docker- und Nginx-Bereitstellung

Auf dem Server:

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

Der Container bindet standardmäßig nur an 127.0.0.1:3000 auf dem Server selbst. Verwende nginx-mcp.conf.example für den HTTPS-Reverse-Proxy; der Authorization-Request-Header muss erhalten bleiben. In der Produktion nur Port 443 öffnen, Port 3000 nicht direkt exponieren.

Veröffentlichung

Ein Push auf main führt Typprüfung, Unit-Tests und Docker-Build aus. Nach dem Erstellen und Pushen eines semantischen Tags werden automatisch Tests, npm pack und die GitHub-Release-Erstellung ausgeführt:

git tag v0.1.0
git push origin v0.1.0

Aktuelle Einschränkungen und nächste Schritte

Die erste Version umfasst bereits das MCP-Protokoll, Authentifizierung, Berechtigungen, den HA-Adapter und das Bereitstellungsgerüst. Sobald du Server-Domain, Authentik-Provider-Informationen und die Life-Dashboard-interne API bereitstellst, umfassen die nächsten Schritte: Interoperabilitätstests für echte OAuth-Browser-Autorisierung, die Life-Dashboard-PHP-interne API, To-Do-/Kalender-Tools und die Validierung der Produktionsbereitstellung.