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* tag를 통한 GitHub Release 자동 생성.

Agent에 Home Assistant Token, Authentik Token, 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 的密钥>

Agent마다 UI 구성 필드가 다릅니다. Authorization 요청 헤더를 지원하는 Streamable HTTP MCP를 지원하기만 하면 위 URL을 사용할 수 있습니다. 각 Agent마다 다른 API Key를 생성하고 필요한 scope만 부여하세요.

Authentik OIDC / OAuth

AUTHENTIK_ISSUER, AUTHENTIK_AUDIENCE, AUTHENTIK_JWKS_URI를 모두 구성하면 서비스가 JWT의 발급자, 대상(audience), 만료 시간 및 서명을 검증합니다. 표준 scope claim(또는 AUTHENTIK_SCOPE_CLAIM으로 지정된 claim)이 MCP scopes로 매핑됩니다.

현재 구현은 MCP Resource Server로, Authentik이 발급하고 audience가 MCP 서비스 전용인 Bearer JWT를 수락할 수 있습니다. 원격 OAuth 클라이언트는 Authentik에서 OAuth 2.1 Provider를 생성하고 Authorization Code + PKCE, 정확한 redirect URI, scope 매핑 및 audience를 활성화해야 합니다. 수신한 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/캘린더 도구 및 프로덕션 배포 검증을 완료할 예정입니다.