somyung-saju-mcp

MCP (Model Context Protocol) server for Korean Saju (사주팔자) child temperament analysis.

Lets AI assistants such as Claude calculate a child's Four Pillars of Destiny and return their innate temperament, learning style, and parenting guidance — as a framework for understanding a child, not a prediction of their future.

No API key. No network calls. All calculation runs locally.

Built by SoMyung, created by SungHa — a certified Myeongri Psychology Counselor (명리심리상담사 1급) with an MS in Decision Making and Applied Analytics, and a parent of three.

Tools

Install

npm install -g somyung-saju-mcp

Or run it without installing (see the npx config below).

Configure with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (%APPDATA%\Claude\claude_desktop_config.json on Windows).

Using npx — no install:

{
  "mcpServers": {
    "somyung-saju": {
      "command": "npx",
      "args": ["-y", "somyung-saju-mcp"]
    }
  }
}

If installed globally:

{
  "mcpServers": {
    "somyung-saju": {
      "command": "somyung-mcp"
    }
  }
}

Restart Claude Desktop after editing the config.

Configure with Claude Code

claude mcp add somyung-saju -- npx -y somyung-saju-mcp

Usage

Once configured, just ask:

• "My daughter was born on 2020-05-15 at 14:30. What's her temperament?"

• "Compare my two kids: son born 2018-03-20 10:00 and daughter born 2021-07-08 15:30"

• "What does the Fire element mean for a child?"

• "My son was born 2019-11-22, I don't know the time. What's his personality like?"

The assistant calls the right tool and interprets the structured result conversationally.

How it works

1. Birth data is parsed (date, optional time, gender).

2. Four Pillars (년주 / 월주 / 일주 / 시주) are calculated using solar terms (절기), so the month pillar is correct rather than approximated from the calendar month.

3. Five Element balance is computed across all eight characters — four heavenly stems (천간) and four earthly branches (지지).

4. A temperament profile is assembled: dominant and weakest elements, personality traits, learning style, social style, emotional patterns, and parenting tips.

5. The AI host receives structured data and gives a natural interpretation.

Four pillars, each drawn from the 60-term sexagenary cycle, yield 518,400 distinct profiles — about 32,400 times more granular than MBTI's 16 types.

Without a birth time, noon is used as an estimate and the response says so. Three pillars still give roughly 70% of the analysis: core temperament and element balance.

The five elements

Scope

This server describes innate temperament tendencies. It does not provide medical, psychiatric, or educational diagnosis, and does not predict future events.

Development

git clone https://github.com/ers123/somyung-saju-mcp.git
cd somyung-saju-mcp
npm install
npm run dev      # run with tsx (hot reload)
npm run build    # compile TypeScript
npm start        # run the compiled server

Publishing to Smithery

Smithery's web form takes a remote HTTP endpoint. This is a stdio server, so it is published as an MCPB bundle instead:

node scripts/build-mcpb.mjs
npx @smithery/cli mcp publish ./somyung-saju.mcpb -n <namespace>/somyung-saju

The build script exists because the two specs disagree: the MCPB manifest schema rejects inputSchema inside tools, while Smithery's registry requires it — publishing without it fails once per tool, and publishing with tools removed fails with "No values to set". So the script packs a spec-compliant manifest and then patches the tool schemas into the archive, reading them from the running server so they cannot drift.

The bundle carries production node_modules, since the host runs it standalone rather than resolving dependencies itself.

Releasing

Publishing runs on GitHub Actions via npm trusted publishing (OIDC) — no token is stored anywhere and no 2FA prompt is involved.

npm version patch      # bumps package.json and creates the vX.Y.Z tag
git push --follow-tags

The workflow refuses to publish if the tag disagrees with package.json, and runs a stdio smoke test against the built server before publishing.

Related

Full 8-section premium reports, in ten languages, are at somyung.cc — including a free preview.

License

MIT — see LICENSE.