Skip to main content
Glama
legend-saju

legend-saju

by SihyeonJeon

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.

CI License TypeScript

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.

Tool

Role

legend_saju_manifest

Check which calculation methods, sources, and data ranges exist in the current engine

legend_saju_capabilities

Find calculation methods that match a natural-language question

legend_saju_resolve

Take a question and inputs, then run all relevant calculations together

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.

Asset

Scope

Multilingual metaphysics knowledge store

36 domains, 777 evidence items

Saju glossary

777 items in Korean–Hanja–Chinese–Japanese

Zi Wei Dou Shu glossary

214 items ordered by language

The Book of the Month

120 day-master × month-table cells with 66 executable exception branches

Zi Wei & palaces and stars

163 structured rules and 3 separate transformation profiles

Da Liu Ren

60 day pillars × 12 heaven Generals, a closed 720-chart transmission table

Cheolpan Shinsoo question-time path

1,500 hexagram marks, 144 pre-heaven rows, 2,028 life rows

Korean Seongmyeonghak

9,495 observed Supreme Court name hanja and 2,003 stroke-variation observations

81-number collection with explicit limits

All 81 rows with source comparisons

Dream-study dataset

988 Zhou-Gong dream-reading items, 211 Artemidorus passages, 5 cross-cultural review seeds

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

System

Current implementation boundary

Almanac & Saju natal chart

Gregorian–lunar–intercalary-month conversion, four pillars, ongoing luck cycles, day boundaries

Myeongri

month, roots, hidden stems, ten gods, combinations–clashes–punishments, 3 ways to select the favorite god, and the 120-column month table

Zi Wei Dou Shu

12 palaces, triangles, and multidimensional narrative, multiple “four transformations”, flying star, overlapping luck periods

Da Liu Ren

closed 60 day–pillar → 12 sphere table and explicitly outlined transmission method

Quin Men Dun Jia

hour-pan, nine palaces, nine stars, eight gates, eight poles, under angle / under envoy, and voids

Cheolpan Shinsoo

three versions of the imperial cycles, a separate 14-series question-hour table, pre-natal numbers, and the 10-year container

Korean Seiikura

2, comma 9, story of name hanja, unicode & style decomposition, five-grid for the user's stated stroke rule, and the explicit 81-number boundaries

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.

Available Tools

9 tools
legend_saju_analyze_compatibilityAnalyze two-person compatibilityA
Read-only
Inspect

Use this when the user asks 궁합, 결혼 가능성, relationship compatibility, or wants two birth charts compared. Requires both people's birth data.

Inputs: birth (required), question (required), partnerBirth (required), maxClaims, +4 more. Returns: mode, error, claims, routes, +23 more

legend_saju_analyze_nameAnalyze a Korean nameA
Read-only
Inspect

Use this for 작명, 성명학, 81수, 이름 한자, 인명용 한자, 획수, or 파자 questions. It keeps legal Hanja observations, declared stroke standards, and birth-based naming guidance separate.

Inputs: question (required), name, birth, maxClaims, +4 more. Returns: mode, error, claims, routes, +23 more

legend_saju_capabilitiesFind a calculation methodA
Read-only
Inspect

Use this when a user asks which Saju, Myeongri, Zi Wei, Qimen, Daliuren, I Ching, Tieban, Dang Saju, Tojeong, Feng Shui, naming, dream, or other traditional calculation method fits a specialized question. Do not use it for an ordinary fortune reading.

Inputs: limit, query, systems. Returns: hits, error, query, capabilityCount, +1 more

legend_saju_cast_divinationCast a traditional divination chartA
Read-only
Inspect

Use this for 기문둔갑, 대육임, 주역, 점괘, or a concrete decision cast from a question time or six line values. Do not use it for a general natal fortune reading.

Inputs: question (required), birth, maxClaims, lineValues, +3 more. Returns: mode, error, claims, routes, +23 more

legend_saju_interpret_dreamInterpret a dream from audited traditionsA
Read-only
Inspect

Use this for 해몽, 꿈풀이, or dream interpretation. It currently handles five cross-culturally audited concepts and returns both shared motifs and conflicting conditions with primary-source excerpts; it does not turn the remaining raw corpus into invented meanings.

Inputs: dream (required), question (required), maxClaims, outputMode, +3 more. Returns: mode, error, claims, routes, +23 more

legend_saju_manifestInspect Legend SajuA
Read-only
Inspect

Return the live, source-traceable deterministic engine manifest. No model or network call.

Inputs: no named parameters. Returns: error, naming, version, knowledge, +6 more

legend_saju_read_fortuneRead a Saju fortuneA
Read-only
Inspect

Use this when the user says 사주 봐줘, 운세 봐줘, 올해 운세, 재물운, 사업운, 직업운, 연애운, 결혼운, 건강운, 개운법, 구체적 액션, or asks what to do over a future period. Read structuredContent, especially recommendations for action requests. Use detailLevel=expert for a deep one-call analysis; do not search capability IDs first.

Inputs: birth (required), question (required), asOfYear, maxClaims, +5 more. Returns: mode, error, claims, routes, +23 more

legend_saju_run_methodsRun specific or mixed traditional methodsA
Read-only
Inspect

Use this for expert, mixed-system, or named-method requests. It covers Myeongri details such as 십성·지장간·투간·통근·합충형파해·삼합·방합·육합·월령·격국·조후·억부·통관·병약·궁통보감·적천수·삼명통회·연해자평·종격·화격·특수격; Zi Wei 12궁·삼방사정·대한·유년·유월·유일·유시·생년사화·궁간사화·자화·비성·흠천사화·중주파; and Qimen, Daliuren, I Ching, Tieban, Dang Saju, Tojeong, Feng Shui, naming, 81-number, Hanja decomposition, and dream traditions. Pass discovered capability IDs together in requestedCapabilities, or let the server plan from the question. Use focused tools for ordinary single-goal requests.

Inputs: question (required), name, birth, dream, +18 more. Returns: mode, error, claims, routes, +23 more

legend_saju_select_datesSelect auspicious datesA
Read-only
Inspect

Use this only when the user explicitly asks for 택일, 좋은 날, 계약일, 이사일, 개업일, 수술일, or another date-selection task. Do not use it merely because a fortune request mentions this year.

Inputs: birth (required), question (required), targetDate (required), purpose, +4 more. Returns: mode, error, claims, routes, +23 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each focused tool has a clear primary intent: fortune readings, compatibility checks, date selection, divination, name analysis, and dream interpretation. The only real ambiguity is among the metadata/router tools (manifest, capabilities, and run_methods), which can be confused when an agent needs to distinguish listing capabilities from executing a specialized method.

    Naming Consistency4/5

    Seven of the nine tools follow a consistent verb_noun pattern: read_fortune, analyze_compatibility, select_dates, cast_divination, analyze_name, interpret_dream, and run_methods. The two noun-only names, manifest and capabilities, are a small deviation, but the shared legend_saju_ prefix keeps the overall naming recognizable.

    Tool Count5/5

    Nine tools is well-scoped for a server with such a broad traditional-calculus surface. It provides one focused entry point per major user intent plus introspection and expert-runner tools, without turning the tool list into an overwhelming flat API.

    Completeness5/5

    The surface covers discovery, ordinary fortune reading, relationship compatibility, date selection, divination, naming, dream interpretation, and mixed expert methods. There is no obvious missed lifecycle step: about every major request route lands on a dedicated tool or the catch-all run_methods tool.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables Korean Saju (Four Pillars of Destiny) calculation and myeongni-hak glossary lookup via MCP, allowing AI clients to compute accurate saju analysis and look up fortune-telling terms.
      4
      66 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides tools for Bazi (Chinese astrology) chart calculation and analysis, enabling LLMs to generate accurate birth charts, determine patterns, and answer follow-up questions based on actual calculations rather than model knowledge.
      2
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to cast deterministic BaZi, Zi Wei Dou Shu, and Western astrology natal charts from birth details, with no setup or API key.
      1
      57 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides stateless tools for calculating BaZi charts, casting I Ching hexagrams, drawing tarot cards, and generating Zi Wei twelve-palace charts. Agents can call these tools without an account or model key and interpret the structured results with their own model.
      MIT