# Legend Saju
**모든 답이 결정적 계산에서 시작하는 동양 술수(命·卜·相) 엔진.**
계산식, 유파, 출처, 불확실성을 구조화해 반환한다.
[](https://github.com/SihyeonJeon/legend-saju/actions/workflows/ci.yml)
[](LICENSE)
[](https://www.typescriptlang.org/)
[English](README.en.md) · [기여하기](CONTRIBUTING.md) · [원격 MCP](https://saju.tripsight.co.kr/mcp)
> 같은 생년월일을 여러 전통으로 계산한다. 계산 경로 안에는 숨겨진 LLM 호출이 0회다.
**출처가 연결된 지식 777건 · 대육임 720국 · 한국 인명용 한자 관측 9,495건 · 계산 경로 모델 호출 0회**
Legend Saju는 사주·명리, 자미두수, 기문둔갑, 대육임, 철판신수, 성명학, 해몽까지 명(命)·복(卜)·상(相) 삼술의 계산을 하나의 엔진에서 다룬다. 유파가 다르면 각각의 결과로 나란히 보존하고, 출생시간을 모르면 후보 차트를 분리해 계산한다.
## 가장 빠른 사용법
설치 없이 연결할 수 있는 HTTPS MCP 주소다.
```text
https://saju.tripsight.co.kr/mcp
```
공식 MCP Registry 이름은 `io.github.SihyeonJeon/legend-saju`다. 기존 주소 `https://legend-saju-mcp-production.up.railway.app/mcp`도 같은 서버로 연결된다.
### Claude Code
아래 명령은 모든 프로젝트에서 쓸 수 있도록 사용자 범위에 연결한다.
```bash
claude mcp add --transport http --scope user legend-saju https://saju.tripsight.co.kr/mcp
claude mcp list
```
Claude Code를 열고 `/mcp`에서 `legend-saju`가 연결됐는지 확인한 다음 평소처럼 질문하면 된다.
### ChatGPT 개발자 모드
1. ChatGPT의 **Settings → Security and login**에서 **Developer mode**를 켠다.
2. [ChatGPT Plugins](https://chatgpt.com/plugins)에서 `+`를 누른다.
3. 이름과 설명을 입력하고 **Connection**에 위 MCP 주소를 `/mcp`까지 포함해 넣는다.
4. 연결을 만든 뒤 `legend_saju_read_fortune`, `legend_saju_analyze_compatibility`, `legend_saju_card_natal` 등이 발견되는지 확인한다.
5. 새 대화의 도구 메뉴에서 연결을 선택하고 자연어로 질문한다.
ChatGPT에서는 계산 결과가 카드 위젯(ChatGPT Apps)으로 렌더링된다. 원국 카드, 영역별 운세 카드, 궁합 카드, 대운 타임라인 네 종류가 질문 유형에 맞춰 뜬다. 위젯 렌더링은 웹(chatgpt.com)에서 가장 안정적이다.
개발자 모드 사용 가능 여부는 계정과 워크스페이스 정책에 따라 다를 수 있다. 자세한 절차는 [OpenAI의 플러그인 연결 안내](https://developers.openai.com/plugins/deploy/connect-chatgpt)를 참고하면 된다.
### Codex
MCP만 바로 연결하려면 다음 두 줄이면 된다.
```bash
codex mcp add legend-saju-remote --url https://saju.tripsight.co.kr/mcp
codex mcp list
```
MCP 연결과 자연어 사용 지침을 함께 설치하려면 저장소를 플러그인 소스로 추가하고 Plugins 화면에서 **Legend Saju**를 설치한다.
```bash
codex plugin marketplace add SihyeonJeon/legend-saju --ref main
```
원격 서버는 입력값을 저장 없이 처리하고 모델 API 호출 0회를 유지한다. 요청 크기, 분당 요청 수, 동시 실행 수 제한은 적용된다.
### 로컬에서 실행하기
생년월일이나 이름을 외부 서버로 보내고 싶지 않다면 Node.js 20 이상이 설치된 컴퓨터에서 STDIO 방식으로 실행한다.
```bash
git clone https://github.com/SihyeonJeon/legend-saju.git
cd legend-saju
npm ci
npm run build
```
저장소 루트에서 사용하는 클라이언트에 맞는 명령을 실행한다. `$PWD`는 셸이 현재 절대경로로 바꿔 저장한다.
```bash
codex mcp add legend-saju -- node "$PWD/bin/legend-saju-mcp.js"
claude mcp add --transport stdio --scope user legend-saju -- node "$PWD/bin/legend-saju-mcp.js"
```
설치 뒤에는 도구 이름이나 JSON을 말할 필요 없이 평소처럼 질문하면 된다.
> 양력 1990년 1월 1일 정오 출생이야. 직업, 재물, 결혼과 앞으로 3년을 종합해서 봐줘.
> 두 사람의 생년월일시를 줄게. 양쪽 원국 전체로 궁합과 결혼 시기를 함께 봐줘.
> 이름 한자를 줄게. 사주와 분리해서 성명학 근거도 분석해줘.
### 다른 MCP 클라이언트에서 연결하기
원격 HTTP MCP를 지원하는 클라이언트라면 아래 설정을 사용할 수 있다. 설정 파일의 위치는 클라이언트마다 다르다.
```json
{
"mcpServers": {
"legend-saju": {
"type": "http",
"url": "https://saju.tripsight.co.kr/mcp"
}
}
}
```
로컬 소스를 고정해서 쓰고 싶다면 저장소를 빌드한 뒤 CLI 래퍼를 직접 실행한다.
```json
{
"mcpServers": {
"legend-saju": {
"command": "node",
"args": ["/절대/경로/legend-saju/bin/legend-saju-mcp.js"]
}
}
}
```
로컬 STDIO 방식은 위 빌드를 한 번 마친 뒤 사용할 수 있다.
## MCP가 하는 일
MCP 서버는 사용자의 목적이 이름에 드러나는 읽기 전용 도구를 제공한다.
| 도구 | 역할 |
| --- | --- |
| `legend_saju_read_fortune` | 일반 사주, 총운, 재물·사업·직업·연애·건강운을 질문 범위에 맞춰 계산한다 |
| `legend_saju_analyze_compatibility` | 두 사람의 출생 정보를 비교한다 |
| `legend_saju_select_dates` | 명시적으로 택일을 요청한 경우에만 후보 날짜를 계산한다 |
| `legend_saju_cast_divination` | 기문·육임·주역처럼 질문 시각이나 괘가 필요한 계산을 수행한다 |
| `legend_saju_analyze_name` | 실제 이름 한자, 법원 인명용 한자 관측, 81수와 작명 정보를 분리해 계산한다 |
| `legend_saju_interpret_dream` | 의미 대조가 끝난 교차 전승 범위 안에서 꿈의 공통 모티프와 충돌 조건을 반환한다 |
| `legend_saju_manifest` | 현재 엔진에 들어 있는 계산법, 출처, 데이터 범위를 확인한다 |
| `legend_saju_capabilities` | 전문적인 질문에 맞는 세부 계산법을 찾는다 |
| `legend_saju_run_methods` | 이름을 지정한 유파·계산법이나 복합 계산을 한 실행 계획으로 묶는다 |
| `legend_saju_card_natal` | 네 기둥·오행 밸런스·왕쇠/격국/용신 판정·신살을 원국 카드 위젯으로 렌더링한다 |
| `legend_saju_card_fortune` | 총운·재물운·연애운 등 영역별 운세 카드 위젯을 렌더링한다 |
| `legend_saju_card_compatibility` | 두 사람의 일주와 합충 신호를 궁합 카드 위젯으로 렌더링한다 |
| `legend_saju_card_timeline` | 대운 타임라인 위젯을 렌더링하고 시기 질문의 연도를 표시한다 |
일상적인 운세 요청은 목적별 도구가 필요한 계산만 고른다. `detailLevel`은 계산 범위를 정하고 `outputMode`는 반환 형식을 정한다. 깊은 종합 분석은 `detailLevel: "expert"`로 계산하되 기본 응답은 읽기 좋은 `consumer` 형식을 유지한다. 지식 자산·원문·출처가 필요할 때 같은 입력을 `outputMode: "evidence"`로 호출한다.
카드 도구의 계산 값은 전부 서버가 채우고, 해석 문장과 점수는 호스트 모델이 작성해 카드의 `narrative`·`text` 필드로 전달한다. 카드에는 해석 작성 주체가 라벨로 표시된다.
```text
사용자의 자연어 질문
↓
호스트 모델이 입력을 정리하고 계산법을 탐색
↓
Legend Saju MCP가 결정론적 계산 수행
↓
근거 ID가 연결된 요약·영역별 해석·타임라인
↓
호스트 모델이 근거와 경계를 보존해 대화로 전달
```
Legend Saju MCP 자체는 OpenAI나 Anthropic API 키 없이 동작하며 계산 경로의 모델 호출 0회를 유지한다. 대화와 설명에는 사용 중인 Codex·Claude·기타 클라이언트의 기존 모델 세션이 쓰인다.
## MCP와 동봉 플러그인의 차이
- **MCP만 연결**하면 계산 엔진과 목적별 도구를 바로 사용할 수 있다.
- [`plugins/legend-saju/`](plugins/legend-saju/README.md)의 **Codex 플러그인**에는 MCP 설정과 자연어 사용 지침이 함께 들어 있다. 사용자가 capability ID나 입력 스키마를 고르지 않도록 호스트 모델의 처리 방식을 보강한다.
- 계산 능력은 MCP와 플러그인이 같은 공개 엔진 진입점을 공유한다.
## 자연어 입력
이 프로젝트가 의도한 인터페이스는 대화다. 접수 폼과 intent 메뉴 대신, 모델이 대화에서 확실한 정보만 추출하고, 필요한 계산법을 찾은 뒤, 엔진이 돌려준 근거를 설명한다.
```text
1990년 1월 1일 양력이고 태어난 시간은 몰라.
앞으로 3년 직업과 돈을 봐줘.
```
출생시간을 모른다고 말하면 엔진은 자시의 날짜 경계 두 방식까지 포함한 후보 차트를 분리해 반환한다. 임의의 정오 대입 대신 후보군 전체를 유지한다.
## 개발자로 실행하기
```bash
git clone https://github.com/SihyeonJeon/legend-saju.git
cd legend-saju
npm ci
npm test
npm run build
npm run demo
```
Node.js 20 이상이 필요하며 ESM 전용이다.
```ts
import { resolve } from "./dist/index.js";
const result = resolve({
birth: {
year: 1990,
month: 1,
day: 1,
hour: 12,
minute: 0,
calendar: "solar",
gender: "여",
birthTimeAccuracy: "recorded"
},
question: "직업과 재물, 연애 결혼, 앞으로 3년",
timelineRange: { startYear: 2026, endYear: 2028 }
});
console.log(result.dossier?.claims);
console.log(result.dossier?.conflicts);
console.log(result.routes);
```
반환값은 계산과 해석의 근거 데이터다. 완성된 점사 문장 대신 claim, 충돌, 실행 경로가 돌아온다.
```ts
{
executionPlan: {
entryIntent: string;
domains: string[];
core: string[];
supporting: string[];
selected: string[];
};
selection: { requested: string[]; selected: string[]; unsupported: string[] };
routes: CapabilityPreflight[];
dossier?: {
claims: EngineClaim[];
conflicts: ClaimConflict[];
synthesis: DomainSynthesis[];
timeline?: LifeTimeline;
methodResults: Record