# 토정비결 MCP (mcp-tojeong)

생년월일로 해당 연도의 **토정비결(土亭祕訣)** 운세를 조회하는 MCP 서버.
작괘(作卦)로 3자리 괘(卦)를 산출하고, 그 괘의 **총운(總運)** 과 **12개월 월별운** 원문을 그대로 반환한다.
헤르메스(Hermes) 에이전트·텔레그램 연동을 염두에 둔 **결정론(deterministic)·외부 API 0·오프라인** 서버.

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

## 원칙
- **결정론.** 같은 생년월일·같은 당년 → 항상 같은 괘·같은 운세. 난수·추정·시각 의존 없음.
- **외부 API 0.** 음양력 변환·간지 산출까지 전부 로컬. 어떤 입력도 외부로 내보내지 않는다.
- **순수 데이터.** 원문(총운·월별운)만 반환하고 의미 부여는 하지 않는다 — 해석은 상위 레이어(AI/SKILL) 몫.
- **검증 가능.** 조견표(수리)는 임의 나열이 아니라 표준 수표에서 산출되며, 테스트가 "생성 표 = 공식 = 공개 대조표"를 강제한다.

## 작괘(作卦) 공식

| 괘 | 공식 | 나머지 0 처리 |
|---|---|---|
| 상괘(上卦) | (한국나이 + **태세수**) % 8 | 0 → 8 |
| 중괘(中卦) | (당년 생월의 날수 + **월건수**) % 6 | 0 → 6 |
| 하괘(下卦) | (음력 생일 + **일진수**) % 3 | 0 → 3 |

**중괘의 날수 = 당년 생월의 실제 대소(대월 30 / 소월 29).** 전거는
**한국민족문화대백과사전(한국학중앙연구원) '토정비결' 항목**의 작괘법 원문이다 —
"당년 생월수를 놓되 달이 크면 30이요, 달이 적으면 29를 놓고 거기에 다시 생월의 월건수를
놓은 다음 6으로 제하고 남은 수로 중괘를 만든다." 유파에 따라 달리 적는 곳이 있어,
**이 서버가 무엇을 따르는지 여기 못 박는다.**

> 2026-08-04 교정 — `lunarMonthDays()` 가 `getLunarMonthDays()` 를 인자 없이 불러
> **언제나 29** 를 냈다. 당년 생월이 대월인 사람은 중괘가 한 칸 어긋난 값을 받고 있었다.
> 같은 뿌리에서 나온 공개 예시 하나(음1975-07-25 / 2024 → 861)도 함께 교정했다(→ 811).
> 발견: zeostest 가 이 엔진을 PHP 로 이식하며 세운 등가 게이트.

- **한국나이** = 당년(當年) − 음력 출생년 + 1 (토정비결은 음력 체계이므로 출생년은 **음력 연도** 기준. 양력 입력도 음력 변환 후의 연도를 쓴다 — 해 경계 출생자, 예: 양력 1월 초 출생은 음력 전년으로 계산될 수 있다.)
- **날수** = 당년 음력 생월이 대월(大月)이면 30, 소월(小月)이면 29
- **태세수·월건수·일진수**는 출생 시점이 아니라 **당년(當年)의 해당 연·월·일 간지(干支)** 기준이다.
- 괘코드 = 상·중·하 3자리 결합 (예: 2·1·2 → `212`), 총 8×6×3 = **144괘**.

### 조견표(早見表) — 수리 산출과 출처

조견표는 임의 나열이 아니라 두 개의 표준 수표에서 결정론적으로 산출된다. `src/ganji.js`가 진실 출처이며, `npm run build:jogyeonpyo`로 `data/jogyeonpyo.json`(60갑자 완전 표)을 생성한다.

- **선천수(先天數)**: 甲己子午=9 · 乙庚丑未=8 · 丙辛寅申=7 · 丁壬卯酉=6 · 戊癸辰戌=5 · 巳亥=4
- **중천수(中天數)**: 甲己辰戌丑未=11 · 乙庚申酉=10 · 丙辛亥子=9 · 丁壬寅卯=8 · 戊癸巳午=7

| 수 | 조합 |
|---|---|
| 태세수(太歲數) | 中天數(천간) + 中天數(지지) |
| 월건수(月建數) | 先天數(천간) + 先天數(지지) |
| 일진수(日辰數) | 先天數(천간) + 中天數(지지) |

**출처 (독립 3소스 교차 검증):**
- [badukworld.co.kr](http://www.badukworld.co.kr/tz3.html) — 작괘법 및 선천수·중천수 수표 원문
- [chunun.com](https://chunun.com/entry/토정비결-조견표) — 60갑자 태세수·월건수·일진수 대조표
- [myungmundang.net](http://www.myungmundang.net/tojong_main2popup.htm) — 계산 예시

테스트(`test/calc.test.js`)가 "생성 표 = 공식 = 공개 대조표 앵커" 등가를 강제한다.

음양력 변환과 연·월·일 간지 산출은 [`korean-lunar-calendar`](https://www.npmjs.com/package/korean-lunar-calendar)를 사용한다.

## 도구(Tools)

### `tojeong_fortune` (주력)

생년월일로 당년 토정비결 운세를 조회한다.

| 입력 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| `birth_date` | string (YYYY-MM-DD) | (필수) | 생년월일 |
| `calendar` | `"solar"` \| `"lunar"` | `"solar"` | 입력 달력 종류 |
| `is_leap_month` | boolean | `false` | 음력 윤달 여부 (`calendar=lunar`일 때만 유효) |
| `target_year` | integer | 현재 연도 | 운세를 보는 해(당년) |

출력: `gwae_code`, `gwae{sang,jung,ha}`, `chongun`, `months{1..12}`, 그리고 계산 감사(audit)용 `meta`(음/양력 생일, 윤달 정규화 여부, 한국나이, 태세·월건·일진 간지·수, 생월 날수).

> 윤달생은 평달로 간주하는 통례를 적용하며, 이때 `meta.leap_month_normalized: true`로 표기한다.
>
> 당년 생월이 소월(29일)인데 생일이 30일이면 말일(29일)로 당겨 계산하고 `meta.day_clamped: true`로 표기한다. 이는 문서화된 전통 규칙이 아니라 무음(silent) 오답을 막기 위한 구현 관례다.

### `tojeong_gwae_lookup` (보조)

괘코드(`111`~`863`, 상1-8·중1-6·하1-3)로 해당 괘의 총운·월별운 원문을 그대로 조회한다. 브라우징·테스트·SKILL 개발용.

## 설치

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

## MCP 클라이언트 등록

Claude Desktop `claude_desktop_config.json` 또는 헤르메스 에이전트 MCP 설정:

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

## 데이터·해석문 출처

144괘 한글 해석문은 개인 소장 자료(1998)를 기반으로 현대 맞춤법으로 윤문한 것이다. 데이터 구조: `{ "<괘코드>": { code, chongun, months } }`.

## 면책

토정비결은 조선 후기부터 이어진 세시풍속(歲時風俗)으로, 이 서버가 반환하는 운세는 **재미·참고용 전통 텍스트**이며 미래를 예측하거나 보장하지 않는다(과학적 사실 아님·운명론 아님). 중요한 의사결정의 근거로 삼지 말 것.

## About / 제작

**Hermes Agent용 MCP** — molpass의 바이브 코딩(vibe coding) 프로젝트.

- 아이디어·방향: **molpass (이정훈)** · https://zeolinex.com
- 기획: **Claude (Chat)**
- 개발: **Claude Code**

같은 모음:
- [mcp-saju](https://github.com/molpass/mcp-saju) · [mcp-qr](https://github.com/molpass/mcp-qr) · [mcp-biorhythm](https://github.com/molpass/mcp-biorhythm) · [mcp-astrology](https://github.com/molpass/mcp-astrology) · [mcp-ziwei](https://github.com/molpass/mcp-ziwei) · [mcp-numerology](https://github.com/molpass/mcp-numerology) · [mcp-liuren](https://github.com/molpass/mcp-liuren) · [mcp-qimen](https://github.com/molpass/mcp-qimen) · [mcp-taiyi](https://github.com/molpass/mcp-taiyi) · [mcp-weather](https://github.com/molpass/mcp-weather) · [mcp-newsfeed](https://github.com/molpass/mcp-newsfeed) · [mcp-bible](https://github.com/molpass/mcp-bible) · [mcp-gwansang](https://github.com/molpass/mcp-gwansang) · [mcp-lotto](https://github.com/molpass/mcp-lotto)
- **mcp-tojeong** (이 repo)

## 라이선스

MIT © molpass (코드·해석문 윤문).

- 음양력·간지 산출: [`korean-lunar-calendar`](https://www.npmjs.com/package/korean-lunar-calendar) (MIT).
- 조견표 수표는 위 [출처](#조견표早見表--수리-산출과-출처)의 공개 자료를 교차 검증해 재산출.