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 사주를 설치하면 된다. 이 방식은 공개 원격 MCP를 사용하므로 Node.js나 별도 API키가 필요없다. ChatGPT 웹의 Pluggins 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분 여자입니다직업, 재물, 결married, 앞으로 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와 플러그인 모두 같은 공개 엔진 진입점을 사용한다.

자연어 입력

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

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는 출생지 메타데이터로 보존하지만, 기본 차트가 근사 진태양시 보늜적으로 적용하지는 않는다. 이 누락은 기능 및 입력 감사 메타데이터에 기록된다.

wrong한 출생 정보는 구조화된 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 互換 interface이다. 콘텐츠 작성, 프롬프트, 게시 자동화는 계산 코어에 마구 뒤섞지 않는다.

성능

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

npm run benchmark

현재 Apple Silicon 도구와 Node 26에서 최적화 기준은 四柱 원단 query 중앙값 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를 참조하십시오.