# 설치 스크립트 다운로드 및 실행
curl -fsSL https://raw.githubusercontent.com/hjsh200219/fortuneteller/main/install.sh | bash

# npm으로 전역 설치
npm install -g @hoshin/saju-mcp-server

# 또는 npx로 직접 실행
npx @hoshin/saju-mcp-server

# 저장소 클론
git clone https://github.com/hjsh200219/fortuneteller.git
cd fortuneteller

# 의존성 설치
npm install

# 개발 모드 실행
npm run dev

# 프로덕션 빌드
npm run build
npm start

{
  birthDate: "1990-03-15",
  birthTime: "10:30",
  calendar: "solar",
  isLeapMonth: false,
  gender: "male",
  analysisType: "basic" | "fortune" | "yongsin" | "school_compare" | "yongsin_method",

  // fortune 타입용 옵션
  fortuneType?: "general" | "career" | "wealth" | "health" | "love",

  // school_compare 타입용 옵션
  schools?: ["ziping", "dts", "qtbj", "modern", "shensha"],

  // yongsin_method 타입용 옵션
  method?: "strength" | "seasonal" | "mediation" | "disease"
}

{
  person1: {
    birthDate: "1990-03-15",
    birthTime: "10:30",
    calendar: "solar",
    isLeapMonth: false,
    gender: "male"
  },
  person2: {
    birthDate: "1992-07-20",
    birthTime: "14:30",
    calendar: "solar",
    isLeapMonth: false,
    gender: "female"
  }
}

{
  date: "2025-01-01",
  fromCalendar: "solar",
  toCalendar: "lunar",
  isLeapMonth?: false
}

{
  birthDate: "1990-03-15",
  birthTime: "10:30",
  calendar: "solar",
  isLeapMonth: false,
  gender: "male",
  targetDate: "2025-01-01"
}

{
  birthDate: "1990-03-15",
  birthTime: "10:30",
  calendar: "solar",
  isLeapMonth: false,
  gender: "male"
}

{
  birthDate: "1990-03-15",
  birthTime: "10:30",
  calendar: "solar",
  isLeapMonth: false,
  gender: "male",
  periodType: "year" | "month" | "hour" | "multi-year",

  // 기간 지정 (periodType에 맞는 형식)
  target?: "2025" | "2025-03" | "2025-01-01 14:00",

  // multi-year 타입용 옵션
  count?: 5  // 조회할 연도 개수 (기본값: 5)
}

{
  action: "get" | "set",

  // set 액션용 옵션
  preset?: "ziping" | "dts" | "qtbj" | "modern" | "shensha" | "balanced",

  // 또는 커스텀 가중치
  custom?: {
    ziping: 0.3,    // 자평명리 가중치 (0.0-1.0)
    dts: 0.2,       // 적천수 가중치
    qtbj: 0.2,      // 궁통보감 가중치
    modern: 0.2,    // 현대명리 가중치
    shensha: 0.1    // 신살중심 가중치
  }
}

fortuneteller/
├── src/
│   ├── index.ts              # MCP 서버 진입점 (stdio)
│   ├── server-http.ts        # HTTP 서버 진입점 (Railway 배포용)
│   ├── smithery.ts           # Smithery stateless export
│   ├── core/                 # 핵심 시스템
│   │   ├── server.ts            # MCP 서버 초기화
│   │   ├── tool-definitions.ts  # 7개 도구 정의
│   │   └── tool-handler.ts      # 도구 라우팅
│   ├── tools/                # MCP 도구 구현
│   │   ├── analyze_saju.ts      # 통합 사주 분석
│   │   ├── check_compatibility.ts
│   │   ├── convert_calendar.ts
│   │   ├── get_daily_fortune.ts
│   │   ├── get_dae_un.ts
│   │   ├── get_fortune_by_period.ts  # 통합 시간대별 운세
│   │   └── manage_settings.ts        # 통합 설정 관리
│   ├── lib/                  # 핵심 로직
│   │   ├── saju.ts           # 사주 계산 (진태양시 -30분 보정)
│   │   ├── calendar.ts       # 음양력 변환 (로컬 테이블)
│   │   ├── fortune.ts        # 운세 분석
│   │   ├── compatibility.ts  # 궁합 분석
│   │   ├── dae_un.ts         # 대운 계산
│   │   ├── yong_sin.ts       # 용신 선정
│   │   ├── ten_gods.ts       # 십성 계산
│   │   ├── sin_sal.ts        # 신살 탐지 (15개)
│   │   ├── day_master_strength.ts  # 일간 강약
│   │   ├── gyeok_guk.ts      # 격국 결정
│   │   └── ...               # 세운/월운/대운/일주 상세 분석 모듈
│   ├── data/                 # 정적 데이터
│   │   ├── heavenly_stems.ts      # 천간(天干) 10개
│   │   ├── earthly_branches.ts    # 지지(地支) 12개, 지장간 세력
│   │   ├── wuxing.ts              # 오행(五行) 상생상극
│   │   ├── solar_terms.ts         # 24절기 진입점
│   │   ├── solar_terms_complete.ts # 24절기 통합 (1900-2200)
│   │   ├── lunar_table.ts         # 음력 테이블 진입점
│   │   ├── manselyeok_table.ts    # 만세력 기준 테이블
│   │   └── longitude_table.ts     # 전국 162개 시군구 경도
│   ├── schemas/              # Zod 스키마 정의
│   ├── utils/                # 유틸리티 (날짜 처리 등)
│   ├── benchmark/            # 성능 벤치마크
│   └── types/                # 타입 정의
│       └── index.ts
├── scripts/                  # 검증·성능 테스트 스크립트
├── package.json
├── tsconfig.json
├── docker-compose.yml
├── railway.json              # Railway 배포 설정
├── smithery.yaml             # Smithery 마켓플레이스 설정
├── AGENTS.md                 # Claude Code 가이드
└── README.md

# 개발 모드 (hot reload)
npm run watch

# 린트 체크
npm run lint

# 코드 포맷팅
npm run format

# 테스트 실행
npm test

# API 문서 생성
npm run docs

# API 문서 로컬 서버 (http://localhost:8080)
npm run docs:serve

{
  "mcpServers": {
    "saju": {
      "command": "npx",
      "args": ["-y", "@hoshin/saju-mcp-server"]
    }
  }
}

npm install -g @hoshin/saju-mcp-server

{
  "mcpServers": {
    "saju": {
      "command": "saju-mcp-server"
    }
  }
}

{
  "mcpServers": {
    "saju": {
      "command": "node",
      "args": ["/path/to/saju-mcp-server/dist/index.js"]
    }
  }
}

# 이미지 빌드
docker build -t saju-mcp-server .

# 컨테이너 실행
docker run -it --rm saju-mcp-server

# 또는 docker-compose 사용
docker-compose up -d

# Smithery CLI로 설치
npx @smithery/cli install saju-mcp-server --client claude

curl -fsSL https://raw.githubusercontent.com/hjsh200219/fortuneteller/main/install.sh | bash

npm install -g @hoshin/saju-mcp-server

npx @hoshin/saju-mcp-server

{
  "mcpServers": {
    "saju": {
      "command": "npx",
      "args": ["-y", "@hoshin/saju-mcp-server"]
    }
  }
}

# Build image
docker build -t saju-mcp-server .

# Run container
docker run -it --rm saju-mcp-server

# Or use docker-compose
docker-compose up -d

# Install via Smithery CLI
npx @smithery/cli install saju-mcp-server --client claude