Legend Saju

사주 몇 글자를 LLM에 넘기는 래퍼가 아니다. 계산식, 유파, 출처, 불확실성을 구조화해 반환하는 동양 역학 엔진이다.

같은 생년월일을 여러 전통으로 계산한다. 계산 경로 안에는 숨겨진 LLM 호출이 없다.

출처가 연결된 지식 777건 · 대육임 720국 · 한국 인명용 한자 관측 9,495건 · 계산 경로 모델 호출 0회

Legend Saju는 사주·명리, 자미두수, 기문둔갑, 대육임, 철판신수, 성명학 등 서로 다른 전통의 계산을 하나의 엔진에서 다룬다. 유파가 다르면 억지로 하나의 결론으로 합치지 않고, 출생시간을 모르면 임의의 시각을 만들어내지 않는다.

가장 빠른 사용법

현재 공개 버전은 로컬 STDIO MCP와 HTTPS 원격 MCP를 함께 제공한다. 로컬 서버는 Node.js 20 이상이 설치돼 있으면 별도 API 키 없이 실행할 수 있다.

설치 없이 원격 서버 연결하기

공개 MCP 엔드포인트는 다음 주소다.

https://legend-saju-mcp-production.up.railway.app/mcp

Codex에서는 다음 명령으로 연결할 수 있다.

codex mcp add legend-saju-remote --url https://legend-saju-mcp-production.up.railway.app/mcp

원격 서버는 입력값을 저장하지 않으며 모델 API를 호출하지 않는다. 공개 엔드포인트에는 요청 크기, 분당 요청 수, 동시 실행 수 제한이 적용된다. 외부 서버에 생년월일이나 이름을 보내고 싶지 않다면 아래 로컬 방식을 사용하면 된다.

플러그인으로 설치하기

Codex와 ChatGPT 데스크톱에서는 MCP 연결과 자연어 사용 지침을 함께 묶은 플러그인을 설치할 수 있다. 먼저 이 저장소를 플러그인 소스로 추가한다.

codex plugin marketplace add SihyeonJeon/legend-saju --ref main

그다음 Plugins 화면에서 Legend Saju를 설치하면 된다. 이 방식은 공개 원격 MCP를 사용하므로 Node.js나 별도 API 키가 필요 없다. ChatGPT 웹의 공개 Plugins Directory 등록은 별도의 제출·검토 단계다.

Codex에서 한 줄로 연결하기

터미널에서 다음 명령을 실행한다.

codex mcp add legend-saju -- npx -y --package=github:SihyeonJeon/legend-saju#main legend-saju-mcp

연결 여부를 확인한다.

codex mcp list

Codex를 새로 시작한 뒤 /mcp에서 legend-saju가 보이면 설치가 끝난 것이다. 이제 도구 이름이나 JSON을 말할 필요 없이 평소처럼 질문하면 된다.

2000년 7월 30일 오전 8시 44분 여자야. 직업, 재물, 결혼과 앞으로 3년을 종합해서 봐줘.

남자 1999년 7월 14일 오전 11시 24분, 여자 2000년 7월 30일 오전 8시 44분이야. 궁합과 결혼 가능 시기를 함께 봐줘.

이름은 김상수, 한자는 金相洙야. 사주와 분리해서 성명학 근거도 분석해줘.

Codex CLI, Codex IDE 확장, ChatGPT 데스크톱 앱은 같은 Codex MCP 설정을 공유한다. 자세한 연결 방식은 OpenAI의 MCP 안내를 참고하면 된다.

다른 MCP 클라이언트에서 연결하기

STDIO MCP를 지원하는 클라이언트라면 아래 실행 설정을 사용할 수 있다. 설정 파일의 위치는 클라이언트마다 다르다.

{
  "mcpServers": {
    "legend-saju": {
      "command": "npx",
      "args": ["-y", "--package=github:SihyeonJeon/legend-saju#main", "legend-saju-mcp"]
    }
  }
}

로컬 소스를 고정해서 쓰고 싶다면 저장소를 빌드한 뒤 CLI 래퍼를 직접 실행한다.

{
  "mcpServers": {
    "legend-saju": {
      "command": "node",
      "args": ["/절대/경로/legend-saju/bin/legend-saju-mcp.js"]
    }
  }
}

로컬 방식은 저장소 루트에서 npm ci && npm run build를 한 번 실행해야 한다.

ChatGPT 웹에서 바로 쓸 수 있나

HTTPS 원격 MCP 서버는 준비됐다. 다만 공개 URL이 생긴 것과 ChatGPT 플러그인 디렉터리에 등록되는 것은 별개의 단계다. 개발자 모드나 원격 MCP 연결을 지원하는 클라이언트에서는 위 URL을 직접 사용할 수 있고, 일반 사용자에게 설치형 플러그인으로 노출하려면 별도의 등록·검토 과정이 남아 있다.

Related MCP server: mcp-luopan

MCP가 하는 일

MCP 서버는 읽기 전용 도구 세 개를 제공한다.

도구가 세 개라고 해서 역학 기능이 세 개인 것은 아니다. 세 도구는 거대한 기능 레지스트리를 살펴보고, 찾고, 실행하는 작은 관문이다.

사용자의 자연어 질문
        ↓
호스트 모델이 입력을 정리하고 계산법을 탐색
        ↓
Legend Saju MCP가 결정론적 계산 수행
        ↓
출처·유파·충돌·누락 정보가 포함된 구조화 결과
        ↓
호스트 모델이 사람이 읽기 쉬운 한국어로 설명

Legend Saju MCP 자체는 OpenAI나 Anthropic API 키를 읽지 않으며 모델을 호출하지 않는다. 대화와 설명에는 사용 중인 Codex·Claude·기타 클라이언트의 기존 모델 세션이 쓰인다.

MCP와 동봉 플러그인의 차이

• MCP만 연결하면 계산 엔진과 세 도구를 바로 사용할 수 있다.

• plugins/legend-saju/의 Codex 플러그인에는 MCP 설정과 자연어 사용 지침이 함께 들어 있다. 사용자가 capability ID나 입력 스키마를 고르지 않도록 호스트 모델의 처리 방식을 보강한다.

• 계산 능력은 플러그인 안에 축소 복사돼 있지 않다. MCP와 플러그인 모두 같은 공개 엔진 진입점을 사용한다.

자연어 입력

이 프로젝트가 의도한 인터페이스는 접수 폼이나 intent 메뉴가 아니라 대화다. 모델은 대화에서 확실한 정보만 추출하고, 필요한 계산법을 찾은 뒤, 엔진이 돌려준 근거를 설명한다.

2004년 8월 3일 양력 남자고 태어난 시간은 몰라.
경기도 구리에서 태어났어. 앞으로 3년 직업과 돈을 봐줘.

출생시간을 모른다고 말하면 엔진은 정오를 임의로 넣지 않는다. 자시의 날짜 경계 두 방식까지 포함한 후보 차트를 분리해 반환한다.

개발자로 실행하기

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 전용이며 아직 npm에는 배포하지 않았다.

import { resolve } from "./dist/index.js";

const result = resolve({
  birth: {
    year: 2000,
    month: 7,
    day: 30,
    hour: 8,
    minute: 44,
    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);

반환값은 완성된 점사 문장이 아니라 계산과 해석의 근거 데이터다.

{
  selection: { requested: string[]; selected: string[]; unsupported: string[] };
  routes: CapabilityPreflight[];
  dossier?: {
    claims: EngineClaim[];
    conflicts: ClaimConflict[];
    synthesis: DomainSynthesis[];
    timeline?: LifeTimeline;
    blockedSystems: { capabilityId: string; reason: string }[];
  };
  evidence: SajuEvidence[];
  nameAnalysis?: KoreanNameAnalysis;
  noModelCalls: true;
  interpretationBoundary: string;
}

왜 만들었나

많은 역학 AI 서비스는 프롬프트에서 시작한다. Legend Saju는 그보다 한 층 아래인 계산과 근거에서 시작한다.

• 결정론적 코어: 같은 입력은 LLM 없이 같은 계산 결과를 만든다.

• 유파 보존: 명리 관법이나 자미두수 사화표가 다르면 각각의 결과로 남긴다.

• 출생시간 미상 처리: 모르는 시각은 후보군으로 계산하며 정오로 꾸며내지 않는다.

• 출처 추적: 기능마다 성숙도, 근거 역할, 유파, 출처 ID, 빠진 차원을 기록한다.

• 운명 점수 없음: 여러 체계의 근거와 충돌을 하나의 숫자로 뭉개지 않는다.

실제로 들어 있는 자산

이 저장소는 모델 호출 인터페이스만 공개하는 것이 아니라, 어려운 데이터와 규칙 작업을 함께 공개한다.

검사 가능한 원본 데이터는 data/에 있다. 실행에 필요한 지식은 런타임에 포함되므로 원격 데이터베이스나 숨겨진 검색 서비스에 의존하지 않는다.

추출 결과는 파일 단위로 고정돼 있으며, 최적화된 유일한 계산 경로는 자미두수 144개 조합에서 기존 결과와 바이트 단위로 일치했다. 자세한 내용은 docs/PARITY.md에 기록돼 있다.

구현 범위

기능 수를 README의 고정 숫자로 믿기보다 getEngineManifest()로 현재 레지스트리를 확인하는 편이 정확하다.

출생시각은 현지 민간시로 해석한다. timezone과 longitudeE는 출생지 메타데이터로 보존하지만, 기본 차트가 근사 진태양시 보정을 몰래 적용하지는 않는다. 이 누락은 기능 및 입력 감사 메타데이터에 기록된다.

잘못된 출생 정보는 구조화된 blocked 경로로 반환돼 다른 결과와 함께 정정 요청을 할 수 있다. 존재할 수 없는 targetDate나 questionDateTime은 날짜 기반 계산 전체를 안전하게 진행할 수 없으므로 요청 자체를 거절한다.

하나의 열린 진입점

import { resolve } from "./dist/index.js";

resolve({ question, ...inputs })는 현재 레지스트리를 검색하고, 질문을 라우팅하고, 실행 가능한 계산기를 호출하고, 부족한 입력을 숨기지 않은 채 반환한다. requestedCapabilities는 닫힌 enum이 아닌 일반 문자열을 받는다. 따라서 엔진에 새 모듈을 추가해도 모든 클라이언트 스키마를 함께 바꿀 필요가 없다.

이름을 resolveAsync의 name으로 넘기면 별도의 한국 성명학 전체 경로가 열린다. 실제 성과 이름 한자를 9,495개 관측 스냅샷과 대조하고, 법적 사용 가능성, 배정 음, 관측 획수 후보, 유니코드, 자형 분해, 사용자가 밝힌 오격 계산법, 81수 대조를 서로 다른 근거 층으로 유지한다.

기존 동기식 resolve는 계산 전용 사용자와 호환된다. 비동기식은 이름이 들어왔을 때만 큰 성명학 데이터를 지연 로딩하므로 일반 사주 계산의 시작 비용을 늘리지 않는다.

analyze(input)는 타입이 정해진 출생 명세 API다. query({ intent, ... })는 기존 콘텐츠 봇이 사용하던 26개 intent 호환 인터페이스다. 콘텐츠 작성, 프롬프트, 게시 자동화는 계산 코어에 섞지 않는다.

성능

재현 가능한 벤치마크가 포함돼 있다.

npm run benchmark

현재 Apple Silicon 개발 장비와 Node 26에서 최적화 기준값은 사주 원국 질의 중앙값 1.13ms, 출생시간을 아는 전체 명세 중앙값 약 600ms, 새 프로세스 import 중앙값 63.1ms였다. 기기와 환경에 따라 달라질 수 있는 공학적 관측값이다. 최신 환경과 측정법은 PERFORMANCE.md를 참고한다.

출생시간을 모를 때

const result = analyze({
  birth: {
    year: 2004,
    month: 8,
    day: 3,
    calendar: "solar",
    gender: "남",
    birthTimeAccuracy: "unknown"
  },
  question: "전체 인생"
});

고정되는 기둥, 달라지는 관계, 모든 시주 후보를 분리해 반환한다. 과거 사건으로 후보를 비교할 수는 있어도 엔진이 혼자 하나의 출생시간을 정답으로 선언하지 않는다.

신비보다 방법론

이 프로젝트는 다음 단계를 구분한다.

1. 역법과 원국 계산

2. 구조 관찰

3. 유파에 따른 해석

4. 여러 체계의 종합

5. 인간 또는 LLM이 작성한 설명

제품 수준의 주장을 하기 전 방법론과 기능 경계를 읽어야 한다.

실제 개발 과정에는 개발 순서, 다국어 조사 쿼리, 재현 가능한 에이전트 작업 지시가 들어 있다. 유지관리자를 위한 GitHub 공개 점검표는 docs/RELEASING.md에 있다.

공개 상태

지원하는 배포 대상은 공개 GitHub 소스다. package.json은 private로 표시해 npm 게시를 막아 두었다. npm run release:check는 공개 파일이 소스 스냅샷과 일치하는지, 흔한 비밀값 패턴이 섞이지 않았는지 검사한다. 데이터의 출처와 공개 범위는 DATA_LICENSES.md와 release-boundary.json에 기록돼 있다.

앞으로 할 일

• MCP 클라이언트를 쓰지 않는 사람을 위한 선택형 입력 화면

• 원격 MCP 운영 안정화와 선택적 인증

• 기본 비공개로 동작하는 독립형 출생 정보 입력 화면

• 별도 라이선스의 해몽 데이터 팩

• 추가 원전 고정값과 유파별 독립 검토

책임 있는 사용

Legend Saju는 전통 역학 체계를 재현하고 비교한다. 소프트웨어 검증을 통과했다는 말은 문서화된 계산을 재현했다는 뜻이며, 과학적 예측력이 증명됐다는 뜻은 아니다. 의료·법률·재무·정신건강 전문가를 대신해 사용하지 않는다.

라이선스

프로젝트 코드는 Apache-2.0이다. 외부 라이브러리와 데이터셋은 각자의 이용 조건을 따른다. DATA_LICENSES.md와 THIRD_PARTY_NOTICES.md를 참고한다.