# 당사주 MCP (dangsaju-mcp)

생년월일시로 **당사주(唐四柱)** 12성(星)을 산출하는 MCP 서버.
년성(초년)·월성(중년)·일성(말년)·시성(총운·평생)의 지지·별과 해당 시기 해설 원문을 그대로 반환한다.

> **데이터 전용 서버.** 해석·조언·페르소나는 이 서버가 만들지 않는다. 결정론적 구조화 데이터만 반환하며, 해석은 상위 레이어(SKILL/LLM)의 몫이다.

## 12성(星) 배속

12지지에 12성을 순서대로 고정 배속한다.

| 지지 | 별 | 지지 | 별 | 지지 | 별 |
|---|---|---|---|---|---|
| 자(子) | 천귀성(天貴星) | 진(辰) | 천간성(天奸星) | 신(申) | 천고성(天孤星) |
| 축(丑) | 천액성(天厄星) | 사(巳) | 천문성(天文星) | 유(酉) | 천인성(天刃星) |
| 인(寅) | 천권성(天權星) | 오(午) | 천복성(天福星) | 술(戌) | 천예성(天藝星) |
| 묘(卯) | 천파성(天破星) | 미(未) | 천역성(天驛星) | 해(亥) | 천수성(天壽星) |

## 작괘(作卦) — 12성 뽑는 법

년성을 출발점으로, 음력 생월·생일·시수만큼 지지를 순서대로 짚어 4성을 얻는다.

| 성 | 시기 | 산출 |
|---|---|---|
| **년성(年星)** | 초년 | 음력 출생년의 지지 |
| **월성(月星)** | 중년 | 년성에서 (생월−1)칸 이동 |
| **일성(日星)** | 말년 | 월성에서 (생일−1)칸 이동 |
| **시성(時星)** | 총운·평생 | 일성에서 (시수−1)칸 이동 (시수 子1~亥12) |

> 데이터의 `jang`(장년) 해설 필드는 보존하되 기본 4성 조합에서는 사용하지 않는다(주류 표기 정렬).

### 세기 규칙 (판본 분기점 명시)

- **inclusive(출발자리 포함)**: 출발 지지를 1로 세기 시작한다. 예) 丑에서 9칸 → 丑⑴寅⑵卯⑶辰⑷巳⑸午⑹未⑺申⑻酉⑼ = 酉.
- **순행 고정(남녀 동일)이 기본**: 현재 한국 당사주 주류는 남녀 모두 순행이다. `direction="forward"`(기본)에서는 성별과 무관하다.
- **남순여역(男順女逆)은 변형**: `direction="male_forward_female_backward"`로 지원한다. 이 모드에서만 `sex`가 필요하며 남자는 순행·여자는 역행한다.
- **윤달**: 평달로 정규화하여 월 번호를 그대로 쓴다(당사주 통례). `meta.leap_month_normalized`로 표기.
- 지지 순환은 12를 넘거나(순행) 0 미만(역행)이면 wrap한다.
- `meta.calc_trace`에 년성→월성→일성→시성 이동 경로를 남긴다(세기 규칙 검증·감사용).

**채택 근거 (1차 소스 완주 예시 재현):**
1차 소스 [다음 카페 황룡사 — 당사주 12천성 뽑는 방법](https://cafe.daum.net/sangwonsa/Rtkt/2)이 조견표 3종과 완주 예시 2건을 싣고, "현재 한국 당사주는 남녀 모두 순행이 기본, 남순여역은 변형"임을 명시한다.

- **앵커 A** — 을축(丑)년 음9월12일 오시(순행) → 천액·천인·천고·천권
- **앵커 B** — 갑인(寅)년 음7월26일 오시(순행) → 천권·천고·천인·천파
- **변형(역행) 참고** — 子(천귀)년 음3월 여자(역행) → 월성 戌 천예성 ([달마대사 당사주](https://soultest.kr/dangsaju/about))

두 앵커가 **inclusive 세기 + 순행**으로 정확히 재현된다. 테스트(`test/calc.test.js`)가 이를 강제한다.

### 시진(時辰)표

입력 `HH:MM`을 12지지 시진으로 변환한다. 경계는 :30(한국 통용 30분 보정), 2시간 간격.

| 시진 | 시각 | 시수 | 시진 | 시각 | 시수 |
|---|---|---|---|---|---|
| 자(子) | 23:30~01:30 | 1 | 오(午) | 11:30~13:30 | 7 |
| 축(丑) | 01:30~03:30 | 2 | 미(未) | 13:30~15:30 | 8 |
| 인(寅) | 03:30~05:30 | 3 | 신(申) | 15:30~17:30 | 9 |
| 묘(卯) | 05:30~07:30 | 4 | 유(酉) | 17:30~19:30 | 10 |
| 진(辰) | 07:30~09:30 | 5 | 술(戌) | 19:30~21:30 | 11 |
| 사(巳) | 09:30~11:30 | 6 | 해(亥) | 21:30~23:30 | 12 |

> 진태양시 등 정밀 보정은 적용하지 않는 단순 시진표다(당사주 통례).

### 생시 미상

`birth_time`을 입력하지 않으면 시성(총운·평생)을 제외한 **년·월·일성 3성만** 반환하고 `meta.time_unknown: true`로 표기한다.

## 도구(Tools)

### `dangsaju_reading` (주력)

| 입력 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| `birth_date` | string (YYYY-MM-DD) | (필수) | 생년월일 |
| `calendar` | `"solar"` \| `"lunar"` | `"solar"` | 입력 달력 종류 |
| `is_leap_month` | boolean | `false` | 음력 윤달 여부 (`calendar=lunar`일 때만 유효) |
| `birth_time` | string (HH:MM) | (없음) | 출생 시각. 미입력 시 3성만 반환 |
| `direction` | `"forward"` \| `"male_forward_female_backward"` | `"forward"` | 방향 규칙 (기본 순행 고정) |
| `sex` | `"male"` \| `"female"` | (없음) | 변형 모드(`male_forward_female_backward`)에서만 사용 |

출력: `stars{cho,cheong,mal,summary}` (각 별의 pillar·시기·지지·별명·한자·상징·총평·해당 시기 `reading`), 그리고 감사용 `meta`(방향, 음/양력 생일, 윤달 정규화, 시진 지지, 생시 미상 여부, `calc_trace`).

### `dangsaju_star_lookup` (보조)

지지(한글 `자`~`해` 또는 한자 `子`~`亥`) 또는 별 이름(`천귀성`/`天貴星`)으로 해당 별의 원문 전체를 조회한다. 브라우징·테스트·SKILL 개발용.

## 설치

```bash
npm install
npm test          # 픽스처 11종 검증
```

## MCP 클라이언트 등록

```json
{
  "mcpServers": {
    "dangsaju": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-dangsaju/src/index.js"]
    }
  }
}
```

## 데이터·해설문 출처

12성 해설문은 **전통 당사주 통설을 바탕으로 자체 집필(2026)** 한 것이다. 데이터 구조: `data/dangsaju_12stars.json` — `_meta`(스키마 설명) + 12지지 항목(키 `ja`~`hae`) → `{ jiji, star, hanja, symbol, summary, cho, cheong, jang, mal }`. 이 JSON이 단일 진실 출처(master)이며, 로더는 항목의 `jiji` 한자로 인덱싱하므로 키 스킴·`_meta` 유무에 견고하다.

## 라이선스

MIT © molpass