# @saroday/mcp-server

MCP (Model Context Protocol) server for [Saroday](https://saroday.com) — Korean Saju (사주) calculation and myeongni-hak (命理學) glossary lookup.

This MCP server lets Claude Desktop, Cline, Cursor, and any other MCP-compatible AI client perform accurate Korean Saju (Four Pillars of Destiny) calculation by calling the public Saroday API under the hood.

---

## What it does

When connected, the AI client gains access to four tools:

| Tool | Description |
|------|-------------|
| `calculate_saju` | Compute full Saju analysis (8 characters, sipseong, sinsal, hapchung, 12-unseong, yongshin, daeun) from birth date / time / gender. |
| `lookup_glossary` | Look up any of 80+ myeongni-hak terms (도화살, 천을귀인, 식신, 육합, etc.) with full Korean explanation. |
| `get_daily_fortune` | Today's fortune for one of 12 Western zodiac signs or 12 Chinese zodiac signs. Cached server-side, fast response. |
| `discover_saroday_api` | List available Saroday API endpoints and metadata. |

Why this matters: ChatGPT, Claude, and other LLMs frequently miscalculate Saju when asked directly because manse-ryeok (萬歲曆) lookup and 절기 (jeolgi) boundary handling require precise data. This MCP delegates the math to a verified server while letting the AI focus on the interpretation.

---

## Installation

### Option A — npx (no install)

```bash
npx @saroday/mcp-server
```

### Option B — global install

```bash
npm install -g @saroday/mcp-server
saroday-mcp
```

### Option C — clone and run

```bash
git clone https://github.com/saroday/mcp-server.git
cd mcp-server
npm install
node index.js
```

Requires Node.js 18 or newer.

---

## Configure Claude Desktop

Edit your Claude Desktop config file:

- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Add (or merge) the following:

```json
{
  "mcpServers": {
    "saroday": {
      "command": "npx",
      "args": ["-y", "@saroday/mcp-server"]
    }
  }
}
```

Restart Claude Desktop. You should see "saroday" listed in the MCP servers panel (the plug icon in the input area).

### Local development (running from cloned repo)

```json
{
  "mcpServers": {
    "saroday": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/index.js"]
    }
  }
}
```

---

## Configure Cline / Cursor / other MCP clients

Any MCP client that supports stdio transport works. Point it at the `saroday-mcp` binary or `node index.js`. See your client's docs for the exact config format.

---

## Try it out

After connecting, ask Claude things like:

- *"My birthday is March 15, 1992 at 10am. Calculate my Korean Saju."*
- *"What does 도화살 (dohwa-sal) mean in Korean fortune-telling?"*
- *"내 사주 봐줘. 1990년 5월 20일 음력 14시 여성."*
- *"제왕(jeokwang) 12-unseong이 뭐야?"*

Claude will automatically invoke `calculate_saju` or `lookup_glossary` and give you a polished interpretation based on the structured data returned.

---

## Environment variables

| Variable | Default | Purpose |
|----------|---------|---------|
| `SARODAY_API_BASE` | `https://saroday.com` | Override the API base URL (e.g., for self-hosted or staging environments). |

---

## Rate limits

The public Saroday API allows **100 requests per hour per IP** for free use. Heavy users — apps shipping to many end-users, AI agents handling many concurrent users — should request an API key (coming soon) for higher quotas.

Contact: contact@saroday.com

---

## How it works

```
[User in Claude Desktop]
        ↓ types "내 사주 봐줘"
[Claude Desktop]
        ↓ calls calculate_saju via MCP stdio
[saroday-mcp (this package, runs locally)]
        ↓ HTTPS POST /api/v1/saju
[saroday.com server]
        ↓ runs verified manse-ryeok algorithm
[result JSON]
        ↑ flows back through the chain
[Claude] writes a beautiful Korean interpretation
```

This MCP package is a thin adapter — all calculation lives on Saroday's servers, so updates to the algorithm or glossary roll out without you having to upgrade the package.

---

## Differentiators

- **Manse-ryeok accuracy** — handles 절기 (solar terms) boundaries that LLMs routinely get wrong (verified against `@fullstackfamily/manseryeok` library)
- **80+ glossary entries (~400 interpretation fields)** — every sinsal, hapchung, sipseong, 12-unseong term has summary / meaning / positive / negative / practical-tip interpretation written in friendly Korean
- **Korean myeongni-hak tradition** — based on 적천수(滴天髓), 자평진전(子平真詮), 궁통보감(窮通寶鑑) references
- **Three-channel exposure** — same algorithm available as web service (saroday.com), public REST API (saroday.com/api/v1), and MCP server (this package). Pick the channel that fits your integration.

---

## License

MIT

---

## Support

- Web: https://saroday.com
- API docs: https://saroday.com/api/docs
- LLM-friendly index: https://saroday.com/llms.txt
- Email: contact@saroday.com