🌙 사주 MCP 대시보드

기반 프로젝트 (Original): hjsh200219/fortuneteller (MIT License, by Hoshin)
라이선스: CC BY-NC 4.0 (원본 MIT 고지 포함, 상업적 이용 불가)

한국 전통 사주팔자 분석 엔진(MCP 서버)을 바탕으로, 브라우저에서 동작하는 프리미엄 Web GUI 대시보드를 제공합니다.

✨ 주요 기능

원본 대비 추가된 기능 (VinylStage Fork)

• 파일 기반 데이터 영구 저장: 분석 결과를 로컬 JSON 파일로 저장/불러오기/삭제

• 100점 만점 명리 스코어링: 용신 매칭, 상호작용, 길흉 비율을 반영한 자체 알고리즘

• 최근 분석 보관함: 과거 분석 이력을 리스트로 관리, 클릭 한 번으로 재조회

• 기간 연장(병합): 원하는 연도까지 추가 분석 후 기존 데이터에 병합, 차트 시각화

• 점수 가이드 모달: 100점 알고리즘 원리 투명하게 공개

• 명식 기준 시간 드롭다운: 자시~해시(12지신) 기반 시간 입력 방식

기존 핵심 기능

• 만세력 기반 사주 연산 (완전 로컬, API 외부 의존성 없음)

• 연운/월운/대운 분석

• 오행·용신·격국 시각화

• MCP(Model Context Protocol) SSE 서버 — Claude Desktop 연동 지원

Related MCP server: Saju Fortune-Telling MCP Server

🚀 빠른 시작

요구 사항

• Node.js: v24 이상 (.nvmrc 참고)

• Yarn: v4+ (corepack enable 후 사용)

설치 및 실행

# 1. 의존성 설치
corepack enable
yarn install

# 2. 백엔드(MCP Core) + 프론트엔드 빌드
yarn build
cd frontend && yarn build && cd ..

# 3. 통합 서버 실행
yarn start:http

브라우저에서 👉 http://localhost:3000 접속

🏗️ 아키텍처

fortuneteller/
├── src/                  # MCP 서버 + 사주 연산 코어
│   ├── lib/              # saju.ts, wol_un.ts, se_un.ts, yong_sin.ts 등
│   ├── server-http.ts    # 초경량 HTTP 서버 (MCP SSE + REST API + 정적 파일 서빙)
│   └── index.ts          # MCP stdio 엔트리포인트
├── frontend/             # Vite SPA (TypeScript)
│   ├── src/
│   │   ├── main.ts       # 메인 앱 로직 (대시보드, 히스토리, 차트)
│   │   ├── score.ts      # 100점 스코어링 알고리즘
│   │   └── style.css     # 글래스모피즘 다크 테마
│   └── index.html
└── data/                 # 사용자 분석 데이터 (.gitignore 제외)

• Frontend: 사주 연산 코어(src/lib/)를 브라우저에서 직접 임포트 → Zero-Latency 연산

• Backend: Node.js 내장 http 모듈만 사용한 초경량 서버 (Express 없음)

• Data API: GET/POST/PUT/DELETE /api/data — 로컬 파일 기반 영구 저장

📜 라이선스

이 저장소의 새로운 기여분은 CC BY-NC 4.0 라이선스를 따릅니다.
원본 코드의 MIT 라이선스 고지는 LICENSE 파일에 포함되어 있습니다.

• ✅ 자유로운 사용, 수정, 배포 가능

• ✅ 출처 표기 필수 (원본 저자: Hoshin, 포크: VinylStage)

• ❌ 상업적 이용 불가