Sakura-MCP-Server

Sakura-MCP-Server は、Life Dashboard、Home Assistant、DSH 向けの安全なリモート MCP ゲートウェイです。このサービスは公式 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。

• リクエストごとにステートレスな MCP transport。認証とツール権限はクライアントセッション間で決して再利用されません。

• 対応する Adapter を設定した場合のみビジネスツールを登録：

  • Home Assistant：エンティティ状態の照会、ホワイトリスト登録済みエンティティの制御、ホワイトリスト登録済みシーンの有効化；

  • Life Dashboard 内部 API：生活概要の読み取り、DSH ワークスペースサマリー、DSH follow-up の送信；

  • JSON Lines 監査ログ。

• Docker、Nginx、GitHub CI、および v* タグによる GitHub Release の自動作成。

Home Assistant Token、Authentik Token、DSH ペアリングキー、サーバー Shell が Agent に公開されることはありません。

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 的密钥>

Agent によって UI の設定フィールドは異なります。Authorization リクエストヘッダーをサポートする Streamable HTTP MCP であれば、上記の URL を使用できます。各 Agent ごとに異なる API Key を作成し、必要な scope のみを付与してください。

Authentik OIDC / OAuth

完全な AUTHENTIK_ISSUER、AUTHENTIK_AUDIENCE、AUTHENTIK_JWKS_URI を設定すると、サービスは JWT の発行者、オーディエンス、有効期限、署名を検証します。標準の scope claim（または AUTHENTIK_SCOPE_CLAIM で指定された claim）は MCP scopes にマッピングされます。

現在の実装は MCP Resource Server であり、Authentik が発行し、オーディエンスが MCP サービス専用の Bearer JWT を受け入れます。リモート OAuth クライアントは、Authentik で OAuth 2.1 Provider を作成し、Authorization Code + PKCE、正確な redirect URI、scope マッピング、オーディエンスを有効にする必要もあります。受け取った MCP ユーザー JWT を Home Assistant や Life Dashboard に転送しないでください。Adapter は独自のサービス資格情報を使用する必要があります。

ビジネス Adapter の設定

Home Assistant

HOME_ASSISTANT_URL と専用の最小権限 Token を設定します。書き込み操作は、対応するホワイトリスト変数にリソースが明示的にリストされている場合にのみ登録・成功します：

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 を追加し、独立した service token を使用し、返すフィールドは最小限に保ってください。このプロジェクトでは以下を予約しています：

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 リクエストヘッダーを保持する必要があります。本番環境では 443 のみを開放し、3000 を直接公開しないでください。

リリース

main へのプッシュで型チェック、ユニットテスト、Docker ビルドが実行されます。セマンティックバージョンのタグを作成してプッシュすると、テスト、npm pack、GitHub Release の作成が自動的に実行されます：

git tag v0.1.0
git push origin v0.1.0

現在の制限と次のステップ

第一版では、MCP プロトコル、認証、権限、HA Adapter、デプロイの骨組みが完成しています。サーバーのドメイン、Authentik Provider 情報、Life Dashboard 内部 API が提供され次第、次のステップとして、実際の OAuth ブラウザ認可の相互運用テスト、Life Dashboard PHP 内部 API、To Do／カレンダーツール、本番デプロイの検証を完了します。