saju-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,80 @@
+# Saju MCP Server — Korean Four Pillars Astrology for AI
+
+> Calculate Korean Saju (사주/四柱) birth charts from Claude, ChatGPT, Cursor, or any MCP-compatible AI assistant.
+
+**Zero API keys. Zero cost. Pure calculation engine.**
+
+Saju is Korea's traditional Four Pillars of Destiny astrology — mapping birth year, month, day, and hour into Heavenly Stems and Earthly Branches to reveal personality, strengths, and compatibility through the Five Elements (Wood, Fire, Earth, Metal, Water). Over **518,400 unique chart combinations** vs. Western astrology's 12 Sun signs.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `calculate_saju` | Full birth chart: Four Pillars (Hanja + Korean), Day Master, zodiac animal, Five Elements balance |
+| `get_day_master` | Personality profile for any of the 10 Day Masters (甲乙丙丁戊己庚辛壬癸) |
+| `check_compatibility` | Two-person compatibility: element harmony, Six Harmony/Six Clash, elemental complements |
+| `list_stems_and_branches` | Reference: all 10 Heavenly Stems (천간) and 12 Earthly Branches (지지) |
+
+## Installation
+
+### Claude Desktop / Cursor
+
+Add to your MCP config (`claude_desktop_config.json` or Cursor MCP settings):
+
+```json
+{
+  "mcpServers": {
+    "saju": {
+      "command": "npx",
+      "args": ["-y", "saju-mcp-server"]
+    }
+  }
+}
+```
+
+### Manual
+
+```bash
+npm install -g saju-mcp-server
+saju-mcp
+```
+
+## Example Usage
+
+Ask your AI assistant:
+
+- *"What's the Saju chart for someone born July 18, 1993?"*
+- *"Compare compatibility between a person born 1995-10-26 and 1997-02-14"*
+- *"What does a 庚 (Gyeong) Day Master personality look like?"*
+- *"List all the Heavenly Stems and their elements"*
+
+### Sample Output — `calculate_saju`
+
+```
+Four Pillars: 癸酉 己未 庚子 ??
+Day Master: 庚 (Gyeong) — Yang Metal — "The Sword"
+Zodiac: Rooster (酉)
+Elements: Wood 0 · Fire 0 · Earth 2 · Metal 2 · Water 2
+Dominant: Earth | Weakest: Wood & Fire
+```
+
+## What is Saju?
+
+**Saju (사주, 四柱)** — literally "Four Pillars" — is Korea's ancient astrology system. Each pillar contains a Heavenly Stem (천간) and Earthly Branch (지지), creating an eight-character birth chart that encodes:
+
+- **Day Master** — your core personality archetype (10 types)
+- **Five Elements** — Wood, Fire, Earth, Metal, Water balance
+- **Zodiac Animal** — one of 12 animals from the Earthly Branches
+- **Energy Flow** — ascending or descending life pattern
+
+Used by millions in Korea for personality insight, relationship compatibility, career guidance, and life timing.
+
+## For Deeper Readings
+
+This MCP server provides the **calculation engine** — pure Four Pillars math with no AI interpretation. For full AI-powered destiny readings, compatibility reports, and Korean name generation:
+
+**[sajufromseoul.com](https://sajufromseoul.com)** — Free Saju readings, compatibility analysis, and Korean astrology blog.
+
+## License
+
+MIT — Built by [Saju from Seoul](https://sajufromseoul.com)

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "saju-mcp-server",
+  "version": "1.0.0",
+  "description": "Korean Four Pillars (Saju/사주) astrology MCP server — calculate birth charts, Day Masters, Five Elements, and compatibility. No API keys needed.",
+  "type": "module",
+  "main": "server.js",
+  "bin": {
+    "saju-mcp": "./server.js"
+  },
+  "scripts": {
+    "start": "node server.js"
+  },
+  "files": [
+    "server.js",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "saju",
+    "korean-astrology",
+    "four-pillars",
+    "birth-chart",
+    "five-elements",
+    "day-master",
+    "compatibility",
+    "korean-fortune",
+    "bazi",
+    "sajufromseoul"
+  ],
+  "author": "Saju from Seoul <contact@sajufromseoul.com> (https://sajufromseoul.com)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heungmangoo-art/saju-mcp-server"
+  },
+  "homepage": "https://sajufromseoul.com"
+}

package/server.js

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// ============================================
+//  SAJU ENGINE — Four Pillars Calculation
+//  Self-contained: no external API needed
+// ============================================
+
+const HEAVENLY_STEMS = [
+  { hanja: "甲", korean: "갑", english: "Gap",    element: "Wood",  yin_yang: "Yang" },
+  { hanja: "乙", korean: "을", english: "Eul",    element: "Wood",  yin_yang: "Yin"  },
+  { hanja: "丙", korean: "병", english: "Byeong", element: "Fire",  yin_yang: "Yang" },
+  { hanja: "丁", korean: "정", english: "Jeong",  element: "Fire",  yin_yang: "Yin"  },
+  { hanja: "戊", korean: "무", english: "Mu",     element: "Earth", yin_yang: "Yang" },
+  { hanja: "己", korean: "기", english: "Gi",     element: "Earth", yin_yang: "Yin"  },
+  { hanja: "庚", korean: "경", english: "Gyeong", element: "Metal", yin_yang: "Yang" },
+  { hanja: "辛", korean: "신", english: "Sin",    element: "Metal", yin_yang: "Yin"  },
+  { hanja: "壬", korean: "임", english: "Im",     element: "Water", yin_yang: "Yang" },
+  { hanja: "癸", korean: "계", english: "Gye",    element: "Water", yin_yang: "Yin"  },
+];
+
+const EARTHLY_BRANCHES = [
+  { hanja: "子", korean: "자", english: "Ja",  animal: "Rat",     element: "Water", yin_yang: "Yang", hours: "23:00-01:00" },
+  { hanja: "丑", korean: "축", english: "Chuk",animal: "Ox",      element: "Earth", yin_yang: "Yin",  hours: "01:00-03:00" },
+  { hanja: "寅", korean: "인", english: "In",  animal: "Tiger",   element: "Wood",  yin_yang: "Yang", hours: "03:00-05:00" },
+  { hanja: "卯", korean: "묘", english: "Myo", animal: "Rabbit",  element: "Wood",  yin_yang: "Yin",  hours: "05:00-07:00" },
+  { hanja: "辰", korean: "진", english: "Jin", animal: "Dragon",  element: "Earth", yin_yang: "Yang", hours: "07:00-09:00" },
+  { hanja: "巳", korean: "사", english: "Sa",  animal: "Snake",   element: "Fire",  yin_yang: "Yin",  hours: "09:00-11:00" },
+  { hanja: "午", korean: "오", english: "O",   animal: "Horse",   element: "Fire",  yin_yang: "Yang", hours: "11:00-13:00" },
+  { hanja: "未", korean: "미", english: "Mi",  animal: "Goat",    element: "Earth", yin_yang: "Yin",  hours: "13:00-15:00" },
+  { hanja: "申", korean: "신", english: "Sin", animal: "Monkey",  element: "Metal", yin_yang: "Yang", hours: "15:00-17:00" },
+  { hanja: "酉", korean: "유", english: "Yu",  animal: "Rooster", element: "Metal", yin_yang: "Yin",  hours: "17:00-19:00" },
+  { hanja: "戌", korean: "술", english: "Sul", animal: "Dog",     element: "Earth", yin_yang: "Yang", hours: "19:00-21:00" },
+  { hanja: "亥", korean: "해", english: "Hae", animal: "Pig",     element: "Water", yin_yang: "Yin",  hours: "21:00-23:00" },
+];
+
+const DAY_MASTER_DESCRIPTIONS = {
+  "甲": { name: "Gap Wood (Yang)", image: "A tall tree", traits: "Leadership, ambition, directness, pioneering spirit. Like a great tree growing upward — principled, sometimes stubborn, always reaching." },
+  "乙": { name: "Eul Wood (Yin)", image: "Grass and vines", traits: "Flexibility, diplomacy, artistic grace, adaptability. Like a vine wrapping around obstacles — gentle but persistent." },
+  "丙": { name: "Byeong Fire (Yang)", image: "The Sun", traits: "Charisma, optimism, warmth, visibility. Like the sun — generous, bright, attracts attention naturally." },
+  "丁": { name: "Jeong Fire (Yin)", image: "A candle flame", traits: "Warmth, sensitivity, refinement, inner passion. Like a candle — intimate, perceptive, illuminates subtly." },
+  "戊": { name: "Mu Earth (Yang)", image: "A mountain", traits: "Stability, reliability, patience, grounding presence. Like a mountain — immovable, trustworthy, sheltering." },
+  "己": { name: "Gi Earth (Yin)", image: "Fertile farmland", traits: "Nurturing, practical, resourceful, steady growth. Like rich soil — cultivates others, modest but productive." },
+  "庚": { name: "Gyeong Metal (Yang)", image: "A sword / raw iron", traits: "Decisiveness, discipline, justice, sharpness. Like a blade — principled, cuts through ambiguity, perfectionistic." },
+  "辛": { name: "Sin Metal (Yin)", image: "A polished jewel", traits: "Refinement, sensitivity, aesthetic sense, high standards. Like a gem — beautiful under pressure, discerning." },
+  "壬": { name: "Im Water (Yang)", image: "The ocean / a great river", traits: "Wisdom, breadth, ambition, adaptability. Like the ocean — deep, powerful, encompassing." },
+  "癸": { name: "Gye Water (Yin)", image: "Rain / morning dew", traits: "Intuition, empathy, creativity, quiet depth. Like rainwater — nourishing, perceptive, flows into hidden places." },
+};
+
+// --- Core calculation functions ---
+
+function getSolarMonth(month, day) {
+  const boundaries = [
+    [12, 7, 11], [11, 7, 10], [10, 8, 9], [9, 8, 8],
+    [8, 7, 7],   [7, 7, 6],   [6, 6, 5],  [5, 6, 4],
+    [4, 5, 3],   [3, 6, 2],   [2, 4, 1],  [1, 6, 12],
+  ];
+  for (const [bm, bd, sajuMonth] of boundaries) {
+    if (month > bm || (month === bm && day >= bd)) return sajuMonth;
+  }
+  return 12;
+}
+
+function getYearPillar(year, month, day) {
+  let sajuYear = year;
+  if (month < 2 || (month === 2 && day < 4)) sajuYear = year - 1;
+  const stemIndex = (sajuYear - 4) % 10;
+  const branchIndex = (sajuYear - 4) % 12;
+  return {
+    stem: HEAVENLY_STEMS[stemIndex >= 0 ? stemIndex : stemIndex + 10],
+    branch: EARTHLY_BRANCHES[branchIndex >= 0 ? branchIndex : branchIndex + 12],
+  };
+}
+
+function getMonthPillar(yearStemIndex, month, day) {
+  const solarMonth = getSolarMonth(month, day);
+  const yearStemGroup = yearStemIndex % 5;
+  const monthStemStart = [2, 4, 6, 8, 0][yearStemGroup];
+  const monthStemIndex = (monthStemStart + (solarMonth - 1)) % 10;
+  const monthBranchIndex = (solarMonth + 1) % 12;
+  return { stem: HEAVENLY_STEMS[monthStemIndex], branch: EARTHLY_BRANCHES[monthBranchIndex], solarMonth };
+}
+
+function getDayPillar(year, month, day) {
+  const a = Math.floor((14 - month) / 12);
+  const y = year + 4800 - a;
+  const m = month + 12 * a - 3;
+  const jdn = day + Math.floor((153 * m + 2) / 5) + 365 * y +
+              Math.floor(y / 4) - Math.floor(y / 100) + Math.floor(y / 400) - 32045;
+  const dayIndex = (jdn - 2451551) % 60;
+  const adj = ((dayIndex % 60) + 60) % 60;
+  return { stem: HEAVENLY_STEMS[adj % 10], branch: EARTHLY_BRANCHES[adj % 12], dayIndex: adj };
+}
+
+function getHourPillar(dayStemIndex, hour) {
+  if (hour === null || hour === undefined) return null;
+  let bi;
+  if (hour >= 23 || hour < 1) bi = 0;
+  else if (hour < 3) bi = 1;  else if (hour < 5)  bi = 2;
+  else if (hour < 7) bi = 3;  else if (hour < 9)  bi = 4;
+  else if (hour < 11) bi = 5; else if (hour < 13) bi = 6;
+  else if (hour < 15) bi = 7; else if (hour < 17) bi = 8;
+  else if (hour < 19) bi = 9; else if (hour < 21) bi = 10;
+  else bi = 11;
+  const dg = dayStemIndex % 5;
+  const si = ([0, 2, 4, 6, 8][dg] + bi) % 10;
+  return { stem: HEAVENLY_STEMS[si], branch: EARTHLY_BRANCHES[bi] };
+}
+
+function analyzeElements(pillars) {
+  const counts = { Wood: 0, Fire: 0, Earth: 0, Metal: 0, Water: 0 };
+  const parts = [pillars.year, pillars.month, pillars.day];
+  if (pillars.hour) parts.push(pillars.hour);
+  for (const p of parts) { counts[p.stem.element]++; counts[p.branch.element]++; }
+  const sorted = Object.entries(counts).sort((a, b) => b[1] - a[1]);
+  return {
+    counts,
+    dominant: { element: sorted[0][0], count: sorted[0][1] },
+    weakest: { element: sorted[sorted.length - 1][0], count: sorted[sorted.length - 1][1] },
+    total: Object.values(counts).reduce((a, b) => a + b, 0),
+  };
+}
+
+function calculateSaju(year, month, day, hour = null, gender = "other") {
+  const yearPillar = getYearPillar(year, month, day);
+  const yearStemIndex = HEAVENLY_STEMS.indexOf(yearPillar.stem);
+  const monthPillar = getMonthPillar(yearStemIndex, month, day);
+  const dayPillar = getDayPillar(year, month, day);
+  const dayStemIndex = HEAVENLY_STEMS.indexOf(dayPillar.stem);
+  const hourPillar = hour !== null ? getHourPillar(dayStemIndex, hour) : null;
+
+  const pillars = { year: yearPillar, month: monthPillar, day: dayPillar, hour: hourPillar };
+  const elements = analyzeElements(pillars);
+
+  const yearYY = yearPillar.stem.yin_yang;
+  const energyFlow =
+    (yearYY === "Yang" && gender === "male") ||
+    (yearYY === "Yin" && gender === "female")
+      ? "Ascending" : "Descending";
+
+  const fmt = (p) => `${p.stem.hanja}${p.branch.hanja}`;
+  return {
+    pillars, elements, energyFlow, gender,
+    dayMaster: dayPillar.stem,
+    animal: yearPillar.branch.animal,
+    birthInfo: { year, month, day, hour },
+    display: {
+      hanja: [fmt(yearPillar), fmt(monthPillar), fmt(dayPillar), hourPillar ? fmt(hourPillar) : "??"].join(" "),
+      korean: [
+        `${yearPillar.stem.korean}${yearPillar.branch.korean}`,
+        `${monthPillar.stem.korean}${monthPillar.branch.korean}`,
+        `${dayPillar.stem.korean}${dayPillar.branch.korean}`,
+        hourPillar ? `${hourPillar.stem.korean}${hourPillar.branch.korean}` : "??",
+      ].join(" "),
+    },
+  };
+}
+
+function checkCompatibility(saju1, saju2) {
+  const generating = { Wood: "Fire", Fire: "Earth", Earth: "Metal", Metal: "Water", Water: "Wood" };
+  const controlling = { Wood: "Earth", Earth: "Water", Water: "Fire", Fire: "Metal", Metal: "Wood" };
+
+  const e1 = saju1.dayMaster.element;
+  const e2 = saju2.dayMaster.element;
+
+  let harmony = "Neutral";
+  if (generating[e1] === e2) harmony = "Generating (Person 1 feeds Person 2)";
+  else if (generating[e2] === e1) harmony = "Generating (Person 2 feeds Person 1)";
+  else if (e1 === e2) harmony = "Same element — mirror energy";
+  else if (controlling[e1] === e2) harmony = "Controlling (Person 1 challenges Person 2)";
+  else if (controlling[e2] === e1) harmony = "Controlling (Person 2 challenges Person 1)";
+
+  const b1 = saju1.pillars.year.branch.hanja;
+  const b2 = saju2.pillars.year.branch.hanja;
+  const sixHarmonies = [["子","丑"],["寅","亥"],["卯","戌"],["辰","酉"],["巳","申"],["午","未"]];
+  const sixClashes = [["子","午"],["丑","未"],["寅","申"],["卯","酉"],["辰","戌"],["巳","亥"]];
+
+  let zodiacRelation = "Neutral";
+  for (const [a, b] of sixHarmonies) {
+    if ((b1 === a && b2 === b) || (b1 === b && b2 === a)) { zodiacRelation = "Six Harmony (육합) — naturally complementary"; break; }
+  }
+  for (const [a, b] of sixClashes) {
+    if ((b1 === a && b2 === b) || (b1 === b && b2 === a)) { zodiacRelation = "Six Clash (육충) — tension that can spark growth"; break; }
+  }
+
+  const missing1 = Object.entries(saju1.elements.counts).filter(([, v]) => v === 0).map(([k]) => k);
+  const missing2 = Object.entries(saju2.elements.counts).filter(([, v]) => v === 0).map(([k]) => k);
+  const complements = [];
+  for (const el of missing1) { if (saju2.elements.counts[el] > 0) complements.push(`Person 2 supplies ${el} that Person 1 lacks`); }
+  for (const el of missing2) { if (saju1.elements.counts[el] > 0) complements.push(`Person 1 supplies ${el} that Person 2 lacks`); }
+
+  return {
+    dayMasterHarmony: harmony,
+    person1: { dayMaster: `${saju1.dayMaster.hanja} (${saju1.dayMaster.element} ${saju1.dayMaster.yin_yang})`, animal: saju1.animal },
+    person2: { dayMaster: `${saju2.dayMaster.hanja} (${saju2.dayMaster.element} ${saju2.dayMaster.yin_yang})`, animal: saju2.animal },
+    zodiacRelation,
+    elementalComplements: complements.length > 0 ? complements : ["No direct element gaps filled — look to month/day branches for subtler links"],
+  };
+}
+
+// ============================================
+//  MCP SERVER DEFINITION
+// ============================================
+
+const server = new McpServer({
+  name: "saju-from-seoul",
+  version: "1.0.0",
+});
+
+// --- Tool 1: calculate_saju ---
+server.tool(
+  "calculate_saju",
+  "Calculate Korean Four Pillars (Saju/사주) birth chart from a date of birth. Returns pillars in Hanja and Korean, Day Master, zodiac animal, Five Elements balance, and energy flow.",
+  {
+    year:   z.number().int().min(1900).max(2100).describe("Birth year (solar calendar, e.g. 1995)"),
+    month:  z.number().int().min(1).max(12).describe("Birth month (1-12, solar calendar)"),
+    day:    z.number().int().min(1).max(31).describe("Birth day (1-31, solar calendar)"),
+    hour:   z.number().int().min(0).max(23).optional().describe("Birth hour (0-23, optional — omit if unknown)"),
+    gender: z.enum(["male", "female", "other"]).optional().describe("Gender for energy flow calculation (default: other)"),
+  },
+  async ({ year, month, day, hour, gender }) => {
+    const saju = calculateSaju(year, month, day, hour ?? null, gender ?? "other");
+    return {
+      content: [{ type: "text", text: JSON.stringify(saju, null, 2) }],
+    };
+  }
+);
+
+// --- Tool 2: get_day_master ---
+server.tool(
+  "get_day_master",
+  "Look up the personality profile for any of the 10 Day Masters (일간/日干) in Korean Saju astrology. Pass a Heavenly Stem character (甲乙丙丁戊己庚辛壬癸) to get the archetype, image, and personality traits.",
+  {
+    stem: z.string().length(1).describe("Heavenly Stem in Hanja (one of: 甲乙丙丁戊己庚辛壬癸)"),
+  },
+  async ({ stem }) => {
+    const info = DAY_MASTER_DESCRIPTIONS[stem];
+    if (!info) {
+      return { content: [{ type: "text", text: `Unknown stem "${stem}". Valid stems: 甲 乙 丙 丁 戊 己 庚 辛 壬 癸` }] };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify({ stem, ...info }, null, 2) }],
+    };
+  }
+);
+
+// --- Tool 3: check_compatibility ---
+server.tool(
+  "check_compatibility",
+  "Compare two people's Saju charts for compatibility. Analyzes Day Master element harmony, zodiac (Six Harmony / Six Clash), and elemental complements.",
+  {
+    person1_year:   z.number().int(), person1_month: z.number().int(), person1_day: z.number().int(),
+    person1_hour:   z.number().int().optional(), person1_gender: z.enum(["male","female","other"]).optional(),
+    person2_year:   z.number().int(), person2_month: z.number().int(), person2_day: z.number().int(),
+    person2_hour:   z.number().int().optional(), person2_gender: z.enum(["male","female","other"]).optional(),
+  },
+  async (args) => {
+    const s1 = calculateSaju(args.person1_year, args.person1_month, args.person1_day, args.person1_hour ?? null, args.person1_gender ?? "other");
+    const s2 = calculateSaju(args.person2_year, args.person2_month, args.person2_day, args.person2_hour ?? null, args.person2_gender ?? "other");
+    const compat = checkCompatibility(s1, s2);
+    return {
+      content: [{ type: "text", text: JSON.stringify({ person1_chart: s1.display.hanja, person2_chart: s2.display.hanja, ...compat }, null, 2) }],
+    };
+  }
+);
+
+// --- Tool 4: list_stems_and_branches ---
+server.tool(
+  "list_stems_and_branches",
+  "Reference table: all 10 Heavenly Stems (천간) and 12 Earthly Branches (지지) with Hanja, Korean, English, element, and yin/yang.",
+  {},
+  async () => {
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({ heavenly_stems: HEAVENLY_STEMS, earthly_branches: EARTHLY_BRANCHES }, null, 2),
+      }],
+    };
+  }
+);
+
+// --- Start ---
+const transport = new StdioServerTransport();
+await server.connect(transport);