Legend Saju

This is not a wrapper that passes a few Saju characters to an LLM. It is an East Asian metaphysics engine that returns calculation formulas, schools of thought, sources, and uncertainty in a structured way.

The same birth date is calculated across multiple traditions. There are no hidden LLM calls anywhere in the calculation path.

777 source-linked knowledge items · 720 Da Liu Ren charts · 9,495 observed Korean name hanja · 0 model calls in the calculation path

Legend Saju handles calculations from different traditions — Saju (Four Pillars) and Myeongri study, Zi Wei Dou Shu, Qi Men Dun Jia, Da Liu Ren, Cheolpan Shinsoo, and Seongmyeonghak — in a single engine. When conventions differ, it does not force them into one conclusion, and when a birth time is unknown, it does not fabricate an arbitrary time.

The fastest way to get started

The current public version provides both a local STDIO MCP and an HTTPS remote MCP. The local server runs on Node.js 20 or later with no separate API key.

Connect the remote server without installing anything

The public MCP endpoint is:

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

In Codex, you can connect with:

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

The remote server never stores your inputs and never calls a model API. The public endpoint enforces request size, per-minute, and concurrency limits. If you do not want to send a birth date or name to an external server, use the local option below.

Install as a plugin

In Codex and the ChatGPT desktop app, you can install a plugin that bundles the MCP connection with natural-language usage instructions. First, add this repository as a plugin source.

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

Then install Legend Saju from the Plugins screen. This route uses the public remote MCP, so it needs neither Node.js nor a separate API key. Appearing in the public Plugins Directory of ChatGPT on the web requires a separate submission and review step.

Connect with one line from Codex

Run this in your terminal:

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

Check that it is connected:

codex mcp list

Restart Codex; when you see legend-saju under /mcp, installation is complete. From then on, you can ask ordinary questions without naming a tool or a JSON schema.

Born July 30, 2000, at 8:44 a.m., female. Take an overall look at my career, wealth, marriage, and the next three years.

Male, July 14, 1999, 11:24 a.m., and female, July 30, 2000, 8:44 a.m. Please look at compatibility and a likely marriage timing together.

My name is Kim Sang-su, and the hanja are 金相, Seo. Please analyze the nameology basis separately from Saju.

Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share the same Codex MCP configuration. For details, see OpenAI's MCP guide.

Connect from other MCP clients

Any client that supports STDIO MCP can use the run configuration below. The configuration file's location differs by client.

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

If you want to pin a local source, build the repository and run the CLI wrapper directly.

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

For the local setup, run npm ci && npm run build once in the repository root.

Can I use it directly in ChatGPT web?

An HTTPS remote MCP server is ready. Having a public URL and being listed in the ChatGPT plugins directory, however, are two different steps. You can use the URL above in clients that offer developer mode or native remote MCP support. To expose it to regular users as an installable plugin, a separate registration and review process is still pending.

Related MCP server: mcp-luopan

What the MCP does

The MCP server provides exactly three read-only tools.

Because there are three tools does not mean the metaphysics engine provides only three features. The three tools are small gateways into a large registry — they look at it, search it, and execute it, without changing its size.

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

Legend Saju MCP itself reads no OpenAI or Anthropic API key and calls no model. The dialog and its explanations are handled by the existing model session of the client you use — Codex, Claude, or another one.

What is the difference between MCP and the bundled plugin?

• Connecting only MCP lets you use the registry and its three tools right away.

• The Codex plugin in plugins/legend-saju/ bundles the MCP configuration together with natural-language usage guidelines. It strengthens the host model so users do not have to pick capability IDs or input schemas.

• The calculation capability is not downsized into the plugin. Both MCP and plugin use the same public engine entry point.

Natural-language input

The intended interface of this project is a conversation, not a form or an intent menu. The model extracts only the unambiguous facts from the conversation, finds the required calculation, and then explains the evidence returned by the engine.

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

If you say the birth time is unknown, the engine does not silently substitute noon. It returns the candidate charts separately, including both conventions for the day boundary at the Hour of Zi.

Reproduce for developers

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 or newer is required. This repository is ESM-only and is not published to npm yet.

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);

The return value is not a final written fortune, but a structured basis for calculation and interpretation.

{
  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;
}

Why we built this

Many metaphysics-oriented AI services begin with a prompt; Legend Saju begins one level lower, with the calculation and the rationale.

• Deterministic core: the same input produces the same numeric result without an LLM.

• Tradition-preserving: different schools and different Zi Wei transformation tables survive as separate results.

• Unknown birth time: an unknown time is handled as a list of candidates, never guessed as noon.

• Source tracking: every capability records maturity levels, evidence roles, schools, source IDs, and missing dimensions.

• No destiny score: never flatten the evidence and conflicts of several systems into one single number.

What is actually inside

This repository does not only expose a model-calling interface; it also publishes the underlying data and rules.

All auditable data lives in data/. The knowledge required at runtime is shipped with the engine and does not depend on any remote database or hidden lookup service.

The extraction outputs are frozen per file. The only optimized computation path among the Zi Wei Dou Shu arrangements matched the previous output byte for byte. See docs/PARITY.md for details.

Implementation scope

Rather than trusting the fixed number of capabilities in the README, call getEngineManifest() to inspect the current registry.

Birth times are interpreted as local civil time. timezone and longitudeE are preserved as birth-place metadata, but the baseline chart does not silently apply an approximate true-solar-time adjustment. That missing features is recorded in the capability and input-audit metadata.

If the birth data is invalid, the engine responds via a structured blocked path so a correction can be requested along with other results. A nonexistent targetDate or questionDateTime makes date-based calculations impossible to run safely, so those requests are rejected outright.

One open entry

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

resolve({ question, ...inputs }) queries the current registry, routes the question, triggers the runnable calculators, and returns the missing inputs without hiding them. requestedCapabilities accepts an open string rather than a closed enum, so adding a new module does not compel changing every client's schema.

If you pass a name as name to resolveAsync, a separate full Korean orthographic path opens. It compares the actual first and last hanja against a snapshot of 9,745 name-character observations, and keeps legal usage, assigned readings, candidate stroke counts, Unicode and style decomposition, the user-specified five-grid method, and the 81-number comparison in distinct layers of evidence.

The existing synchronous resolve remains compatible for computation-only consumers. The async version lazy-loads the large Korean-name dataset only when a name is given, so it neither adds startup overhead nor alters the ordinary Saju flow.

analyze(input) is the typed birth-details API. query({ intent, ... }) is a 26-intent compatibility surface used by earlier content bots. Content writing, calling, prompt generation, and publishing automation do not mix with the calculation core.

Performance

A reproducible benchmark is included.

npm run benchmark

On current Apple Silicon hardware running Node 26, the measured optimization baseline is a median of 1.13 ms for a natal-chart query, about 600 ms median for a full specification that includes the birth time, and 63.1 ms median for a cold-import in a fresh process. These are environmental numbers, not single-value guarantees. See PERFORMANCE.md for the latest benchmarks and methodology.

If you do not know the birth time

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

The engine outputs the stable element, the poles that change, and every candidate hour/chart separately. It may compare candidates against known backward events, but it never arbitrarily labels a single birth time as the “correct” one.

Methodology, not mysticism

The project distinguishes:

1. Calendrical and natal-chart calculation

2. Structural observation

3. Interpretation according to a tradition

4. Synthesis across systems

5. Human- or LLM-written narration

Before presenting it to a user as a determinable prediction, you should read both the methodology and the capabilities.

The repository also includes "how it was actually built" with the development order, multilingual research queries, and reproducible agent-work instructions. Maintainers will find a public GitHub release checklist in docs/RELEASING.md.

Public release status

The supported distribution target is the open GitHub source. packages/* is dependent but blocked from npm publishing. npm run release:check ensures that the public files match the source snapshot and that no hard-coded secrets have leaked. License and data re-distribution boundaries are documented in DATA_LICENSES.md and release-boundary.json.

Roadmap

• An optional input form for people who avoid MCP clients.

• Stabilize the hosted remote MCP and add optional authentication.

• A dedicated birth-onboarding screen that is private by default.

• A separate licensed dream-data pack.

• New primary sources and exact splits for extra lineage.

Responsible use

Legend Saju reproduces and compares traditional systems. Passing the software tests only means the documented calculations are reproduced — not that the science they originate from is proven predictive. Do not use it as a substitute for medical, legal, financial, or mental-health professionals.

License

The project code is Apache-2.0. External libraries and datasets have their own terms. See DATA_LICENSES.md and THIRD_PARTY_NOTICES.md.