SmartThings Rules Copilot

SmartThings Rules Copilot은 사용자의 SmartThings PAT로 Locations, Devices, Rules를조회하고 Claude Remote MCP 또는 ChatGPT GPT Actions에서 Rule을 초안·검토·관리할 수있게 하는 Cloudflare 기반 오픈소스 웹앱입니다.

이 프로젝트는 Samsung 또는 SmartThings의 공식 제품이 아닌 커뮤니티 프로젝트이며,현재 오픈 베타로 제공됩니다. 홈 자동화 변경은 실제 기기 동작에 영향을 줄 수 있으므로최종 Rule과 대상을 확인한 뒤 사용하세요.

호스팅된 웹앱: https://st-rules-copilot.woongts.workers.dev
개인정보 처리방침: https://st-rules-copilot.woongts.workers.dev/privacy.html

주요 기능

웹앱에서 SmartThings PAT 연결, 해제, 초기화
Locations, Devices, Rules 및 Rule 상세 조회
Rule reference 검색과 초안 JSON의 location/device/component/capability 참조 점검
Claude Remote MCP와 ChatGPT GPT Actions에 같은 13개 도구 제공
채팅 확인 기반 Rule 생성, 전체 교체 수정, 삭제, 활성화, 비활성화
실제 SmartThings 요청·응답과 같은 PAT의 재조회 결과 보고
GPT/Claude 연결 복구용 일회성 reconnect URL

안전 경계

SmartThings Rules API는 PAT/user-principal token으로만 호출합니다.
SmartApp token fallback은 지원하지 않습니다.
PAT는 브라우저 저장소에 넣지 않고 서버의 연결별 Durable Object에 암호화해 최대24시간 보관합니다.
PAT, Authorization header, client secret 및 OAuth token은 로그·오류 응답·일반 API응답에 노출하지 않습니다. OAuth token은 유효한 grant에 대한 표준 token endpoint 성공응답에서만 반환됩니다.
공식 GPT/Claude 지침은 최종 변경 내용과 대상을 보여주고 사용자의 명시적 확인을 받은 뒤Rule write 도구를 호출하도록 요구합니다. 서버는 외부 AI 채팅에서 실제 확인이 있었는지를독립적으로 검증하지 않습니다.
write 성공은 같은 PAT의 readback.confirmed=true로 확인된 경우에만 확정합니다.

자세한 경계는 보안·개인정보 문서와수용 조건을 참고하세요.

기술 구조

Vite + React + TypeScript
        │ static assets
        ▼
Cloudflare Worker + Hono
  ├─ Web/API
  ├─ OAuth Provider
  ├─ Remote MCP
  ├─ GPT Actions
  └─ SmartThings REST client
        │
        ├─ Durable Objects
        ├─ Workers KV
        └─ Workers Secrets

로컬 실행

Node.js 22 이상과 npm이 필요합니다.

npm install
Copy-Item worker/wrangler.example.jsonc worker/wrangler.jsonc
Copy-Item worker/.dev.vars.example worker/.dev.vars

worker/wrangler.jsonc의 APP_KV, OAUTH_KV placeholder를 개발용 namespace ID로교체하고 .dev.vars에 로컬 암호화 키를 설정합니다. 이 두 파일은 Git에서 제외됩니다.

npm run check
npm run dev

npm run check는 Worker/frontend typecheck, Worker Vitest, Worker dry-run build,frontend production build를 실행합니다.

자신의 Cloudflare 계정에 배포

이 방식은 개인 서버나 VPS에 설치하는 self-hosting이 아닙니다. 자신의 Cloudflare 계정에Worker, KV namespace, Durable Object를 배포하며 사용량, 할당량, 요금도 그 계정에귀속됩니다. 먼저 위의 로컬 실행 준비를 완료하세요.

Cloudflare에 로그인하고 두 KV namespace를 만듭니다.

Push-Location worker
npx wrangler login
npx wrangler kv namespace create st-rules-copilot-app
npx wrangler kv namespace create st-rules-copilot-oauth
Pop-Location

출력된 두 namespace ID를 기록합니다.

worker/wrangler.jsonc에서 name을 자신의 Worker 이름으로 바꾸고 APP_KV,OAUTH_KV의 placeholder를 방금 만든 namespace ID로 교체합니다. Claude만 사용할경우 GPT_ACTIONS_CLIENT_ID와 GPT_ACTIONS_REDIRECT_URIS는 비워 두어도 됩니다.Durable Object는 첫 배포 때 설정의 migration을 통해 생성됩니다.
Production 암호화 키를 Cloudflare secret으로 등록합니다. .dev.vars는 로컬 개발전용이며 Production에는 사용되지 않습니다. 아래 명령은 32-byte 난수를 화면에출력하지 않고 Wrangler에 바로 전달합니다.
```
Push-Location worker
node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('base64'))" | npx wrangler secret put ST_TOKEN_ENC_KEY
Pop-Location
```
실제 secret과 resource ID가 든 파일은 커밋하지 마세요.
저장소 루트에서 배포합니다.
```
npm run deploy:production
```
이 명령은 전체 검사를 통과한 뒤 기본 Worker를 배포합니다. Wrangler가 출력한workers.dev 주소의 홈페이지와 /privacy.html을 확인하세요.
사용할 AI 클라이언트를 연결합니다.
- Claude에서는 connector URL로 https://<worker-domain>/mcp를사용합니다. 자세한 절차는 Claude 연결 UX를 참고하세요.
- 자체 Custom GPT를 만들려면 GPT Actions UX에 따라 OAuth와Actions를 설정합니다. OpenAPI URL은https://<worker-domain>/action/openapi.json입니다. GPT Builder에반영할 Instructions는 npm run --silent instructions:gpt로 출력할 수 있습니다.

자체 GPT의 공유 URL을 받은 뒤 웹앱 버튼도 그 GPT를 열게 하려면 다시 배포합니다.

$env:VITE_GPT_DESTINATION_URL = "https://chatgpt.com/g/<your-gpt>"
npm run deploy:production
Remove-Item Env:VITE_GPT_DESTINATION_URL

VITE_GPT_DESTINATION_URL을 설정하지 않으면 웹앱의 GPT 버튼은 자신의 Worker와 연결한GPT가 아니라 이 프로젝트의 공식 Production GPT를 엽니다.

문서

문서 안내
Cloudflare 구조
SmartThings token과 Rules
MCP와 GPT Actions 계약
Claude 연결 UX
GPT Actions UX
보안·개인정보
수용 조건

기여와 보안 제보

기여 절차는 CONTRIBUTING.md를 참고하세요. 취약점이나 인증정보 노출은공개 Issue 대신 SECURITY.md의 비공개 제보 절차를 사용해 주세요.

라이선스

MIT License로 배포합니다. 포함된 제3자 아이콘과 상표의 별도 조건은Third-Party Notices를 참고하세요.

SmartThings Rules Copilot