# mcp-numerology

이름과 생년월일을 받아 **수비학 핵심 수**(라이프패스·표현수·소울어지·성격수·생일수·성숙수)와
마스터/카르마 넘버를 계산하는 MCP 서버. 구조화 텍스트 + **요약 카드 PNG**를 반환한다.

> 구조·네이밍·PNG·설치 규약은 [`STANDARD.md`](STANDARD.md)를 따른다. `mcp-qr` skeleton 복제본.

---

## 계산 방식 (결정론적, 외부 의존 0)

표준 **피타고라스(Pythagorean)** 방식으로 직접 구현했다(같은 입력 → 같은 출력).

> 발주서가 지정한 `numerology-npm`은 npm에 존재하지 않고(404), 대체 패키지들도 요구 수를
> 깔끔히 못 채워, PM 결정에 따라 **자체 구현**으로 진행했다. 의존성 0, 전 과정 수기 검증 가능.

- **글자값**: A=1…I=9 반복. `Y`, `W`는 항상 자음으로 처리(컨텍스트 변형 미적용).
- **모음**: A, E, I, O, U.
- **마스터 넘버**(11/22/33): 환원하지 않고 보존.
- **카르마 부채**(13/14/16/19): 환원 마지막 두 자리 단계가 해당 값이면 표기.
- **Life Path**: 월·일·연을 각각 환원 → 합산 → 환원.

| 수 | 산출 |
|---|---|
| 라이프패스 (Life Path) | 생년월일 |
| 표현수 (Expression) | 이름 전체 글자합 |
| 소울어지 (Soul Urge) | 이름의 모음합 |
| 성격수 (Personality) | 이름의 자음합 |
| 생일수 (Birthday) | 태어난 날(日) |
| 성숙수 (Maturity) | 라이프패스 + 표현수 |

---

## 도구

### `get_numerology`

| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| `fullName` | string | ✅ | 이름. **라틴 알파벳 기준** — 한글 이름은 로마자로 표기 (예: 홍길동 → `Hong Gildong`) |
| `birthDate` | string `YYYY-MM-DD` | ✅ | 생년월일 |

> **한글 이름 처리**: 이름 기반 수(표현수/소울어지/성격수)는 라틴 알파벳 글자값으로 계산한다.
> 입력에 라틴 알파벳이 없으면(예: 순수 한글) 도구가 **로마자 표기를 요청하는 에러**를 반환한다.

**출력 (둘 다 반환)**:
1. 구조화 텍스트 — 각 수 + 마스터/카르마 여부 + 의미 키워드 + Life Path 환원 과정
2. 요약 카드 PNG (1080×640, 핵심 수 6개)

예제 출력: [`examples/numerology_example.png`](examples/numerology_example.png)
(`John Lennon` · `1940-10-09` → Life Path 6).

---

## 설치

```bash
git clone https://github.com/molpass/mcp-numerology.git
cd mcp-numerology
npm install && npm run build
```

예제 카드를 직접 생성해 보려면:

```bash
npm run example   # examples/numerology_example.png 재생성
```

> **폰트**: 한글 라벨을 위해 한글 가능 폰트가 필요하다.
> Windows는 Malgun Gothic 기본 탑재라 추가 설치 불필요. Linux는 Nanum/Noto CJK 권장.

---

## MCP 등록 (서버명 `numerology`)

```json
{
  "mcpServers": {
    "numerology": {
      "command": "node",
      "args": ["/abs/path/mcp-numerology/dist/index.js"]
    }
  }
}
```

> `/abs/path`는 클론한 실제 절대경로로 바꾼다.
> Windows 예: `"args": ["C:/Users/<you>/mcp-numerology/dist/index.js"]`

---

## 스킬

페어링 스킬: [`skill/numerology.skill.md`](skill/numerology.skill.md).

## About / 제작

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

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

자가 호스팅 [Hermes Agent](https://github.com/NousResearch/hermes-agent)에 도구로 붙여 쓰는 MCP 서버입니다.

같은 모음:
- [mcp-saju](https://github.com/molpass/mcp-saju) — 사주명리 만세력
- [mcp-qr](https://github.com/molpass/mcp-qr) — 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) — 한국 주요뉴스

## License

MIT