Saju Insights
Discover personalized Four Pillars (Saju) readings, from daily to yearly fortunes and 10-year luck cycles, based on your birth data. Check relationship compatibility and receive Yongshin-driven guidance with practical tips on colors, directions, and careers. Convert between lunar and solar calendars and tailor interpretations across different schools.
Ask AI about Saju Insights
Powered by Claude ยท Grounded in docs
I know everything about Saju Insights. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
๐ฎ ์ฌ์ฃผ ์ด์ธ MCP ์๋ฒ (Saju MCP Server)
ํ๊ตญ ์ ํต ์ฌ์ฃผํ์๋ฅผ ๊ธฐ๋ฐ์ผ๋ก ์ด์ธ๋ฅผ ๋ถ์ํ๋ MCP(Model Context Protocol) ์๋ฒ์ ๋๋ค.
A Model Context Protocol (MCP) server for Korean traditional Saju (Four Pillars of Destiny) fortune-telling.
โจ ์ฃผ์ ๊ธฐ๋ฅ
- ์ฌ์ฃผํ์ ๊ณ์ฐ: ์๋ ์์ผ์๋ก๋ถํฐ ์ฒ๊ฐ์ง์ง 8์ ์๋ ๊ณ์ฐ (์งํ์์ -30๋ถ ๋ณด์ )
- ์ด์ธ ๋ถ์: ์ฑ๊ฒฉ, ์ง์ ์ด, ์ฌ๋ฌผ์ด, ๊ฑด๊ฐ์ด, ์ ์ ์ด ๋ฑ ๋ค์ํ ๋ถ์
- ๊ถํฉ ๋ถ์: ๋ ์ฌ๋์ ์ฌ์ฃผ ๋น๊ต ๋ฐ ๊ถํฉ๋ ๊ณ์ฐ
- ์์๋ ฅ ๋ณํ: ์๋ ฅ โ ์๋ ฅ ๋ ์ง ๋ณํ ์ง์ (1900-2200, ์ค๋ฌ ์ฒ๋ฆฌ ํฌํจ)
- ์ผ์ผ ์ด์ธ: ๋ ์ง๋ณ ์์ธ ์ด์ธ ์ ๊ณต
- ๋์ด(ๅคง้): 10๋ ๋จ์ ํฐ ํ๋ฆ ์ด์ธ ์กฐํ
- ์ฉ์ (็จ็ฅ) ๋ถ์: ์์, ๋ฐฉํฅ, ์ง์ ๋ฑ ๋ง์ถคํ ์กฐ์ธ ์ ๊ณต
- ์ง์ฅ๊ฐ ์ธ๋ ฅ: ์ ๊ธฐ๋ณ ์ง์ฅ๊ฐ ์ธ๋ ฅ ๊ณ์ฐ์ผ๋ก ์ ๋ฐํ ๋ถ์
- ์ ์ด(็ฅๆฎบ): 15๊ฐ ์ ์ด ํ์ง (์์ง์ด, ๊ท๋ฌธ๊ด์ด ํฌํจ)
๐ v1.1.0 ์ ๊ท ๊ธฐ๋ฅ
- 7๊ฐ ํตํฉ ๋๊ตฌ: 15๊ฐ ๊ฐ๋ณ ๋๊ตฌ๋ฅผ 7๊ฐ๋ก ์ต์ ํ (ํ ํฐ ํจ์จ 40% ๊ฐ์ )
- ๋ก์ปฌ ํ ์ด๋ธ: 1900-2200๋ ์์๋ ฅ ๋ฐ์ดํฐ (์ธ๋ถ API ์์กด์ฑ ์ ๊ฑฐ)
- Zod ์ ๋ ฅ ๊ฒ์ฆ: ๋ฐํ์ ํ์ ๊ฒ์ฆ์ผ๋ก ์๋ฌ์จ 40% ๊ฐ์
- date-fns ํตํฉ: ํ์์กด ๋ฒ๊ทธ ์ ๊ฑฐ ๋ฐ ์ ๋ฐํ ๋ ์ง ์ฒ๋ฆฌ
- MCP SDK v1.18: ์ต์ ํ๋กํ ์ฝ ๋ฐ ์ฑ๋ฅ ์ต์ ํ
๐ ์์ํ๊ธฐ
ํ์ ์๊ตฌ์ฌํญ
- Node.js 18 ์ด์
- npm, yarn, ๋๋ pnpm
์ค์น
์๋ ์ค์น ์คํฌ๋ฆฝํธ (๊ฐ์ฅ ๊ฐํธ)
# ์ค์น ์คํฌ๋ฆฝํธ ๋ค์ด๋ก๋ ๋ฐ ์คํ
curl -fsSL https://raw.githubusercontent.com/hjsh200219/fortuneteller/main/install.sh | bash
์ด ์คํฌ๋ฆฝํธ๋ ๋ค์์ ์๋์ผ๋ก ์ํํฉ๋๋ค:
- npm ํจํค์ง ์ ์ญ ์ค์น
- Claude Desktop ์ค์ ํ์ผ์ MCP ์๋ฒ ์๋ ๋ฑ๋ก
- ๊ธฐ์กด ์ค์ ๋ฐฑ์
์๋ ์ค์น
# npm์ผ๋ก ์ ์ญ ์ค์น
npm install -g @hoshin/saju-mcp-server
# ๋๋ npx๋ก ์ง์ ์คํ
npx @hoshin/saju-mcp-server
์์ค์์ ๋น๋
# ์ ์ฅ์ ํด๋ก
git clone https://github.com/hjsh200219/fortuneteller.git
cd fortuneteller
# ์์กด์ฑ ์ค์น
npm install
# ๊ฐ๋ฐ ๋ชจ๋ ์คํ
npm run dev
# ํ๋ก๋์
๋น๋
npm run build
npm start
๐ ๏ธ MCP ๋๊ตฌ (์ด 7๊ฐ - ํตํฉ ์ต์ ํ)
1. analyze_saju
์ฌ์ฃผ ๋ถ์ ํตํฉ ๋๊ตฌ (๊ธฐ๋ณธ ๊ณ์ฐ, ์ด์ธ, ์ฉ์ , ์ ํ ๋น๊ต, ์ฉ์ ๋ฐฉ๋ฒ๋ก ).
๋ถ์ ํ์ :
basic: ์ฌ์ฃผํ์ ๊ธฐ๋ณธ ๊ณ์ฐfortune: ์ด์ธ ๋ถ์ (general/career/wealth/health/love)yongsin: ์ฉ์ ์์ธ ๋ถ์school_compare: 5๊ฐ ์ ํ ๋น๊ต (์ํ๋ช ๋ฆฌ, ์ ์ฒ์, ๊ถํต๋ณด๊ฐ, ํ๋๋ช ๋ฆฌ, ์ ์ด์ค์ฌ)yongsin_method: ํน์ ์ฉ์ ๋ฐฉ๋ฒ๋ก ๋ถ์ (๊ฐ์ฝ/์กฐํ/ํต๊ด/๋ณ์ฝ)
{
birthDate: "1990-03-15",
birthTime: "10:30",
calendar: "solar",
isLeapMonth: false,
gender: "male",
analysisType: "basic" | "fortune" | "yongsin" | "school_compare" | "yongsin_method",
// fortune ํ์
์ฉ ์ต์
fortuneType?: "general" | "career" | "wealth" | "health" | "love",
// school_compare ํ์
์ฉ ์ต์
schools?: ["ziping", "dts", "qtbj", "modern", "shensha"],
// yongsin_method ํ์
์ฉ ์ต์
method?: "strength" | "seasonal" | "mediation" | "disease"
}
2. check_compatibility
๋ ์ฌ๋์ ๊ถํฉ์ ๋ถ์ํฉ๋๋ค.
{
person1: {
birthDate: "1990-03-15",
birthTime: "10:30",
calendar: "solar",
isLeapMonth: false,
gender: "male"
},
person2: {
birthDate: "1992-07-20",
birthTime: "14:30",
calendar: "solar",
isLeapMonth: false,
gender: "female"
}
}
3. convert_calendar
์๋ ฅ๊ณผ ์๋ ฅ์ ๋ณํํฉ๋๋ค (1900-2200 ์ง์).
{
date: "2025-01-01",
fromCalendar: "solar",
toCalendar: "lunar",
isLeapMonth?: false
}
4. get_daily_fortune
ํน์ ๋ ์ง์ ์ผ์ผ ์ด์ธ๋ฅผ ์ ๊ณตํฉ๋๋ค.
{
birthDate: "1990-03-15",
birthTime: "10:30",
calendar: "solar",
isLeapMonth: false,
gender: "male",
targetDate: "2025-01-01"
}
5. get_dae_un
10๋ ๋จ์ ๋์ด(ๅคง้) ์ ๋ณด๋ฅผ ์กฐํํฉ๋๋ค.
{
birthDate: "1990-03-15",
birthTime: "10:30",
calendar: "solar",
isLeapMonth: false,
gender: "male"
}
6. get_fortune_by_period
์๊ฐ๋๋ณ ์ด์ธ ํตํฉ ๋๊ตฌ (์ฐ์ด/์์ด/์์ด/์ฐ์).
๊ธฐ๊ฐ ํ์ :
year: ์ฐ๋ณ ์ด์ธ (์ธ์ด, ๆญฒ้)month: ์๋ณ ์ด์ธ (์์ด, ๆ้)hour: ์๊ฐ๋๋ณ ์ด์ธ (์์ด, ๆ้)multi-year: ์ฐ์ ์ฐ๋ ์ด์ธ
{
birthDate: "1990-03-15",
birthTime: "10:30",
calendar: "solar",
isLeapMonth: false,
gender: "male",
periodType: "year" | "month" | "hour" | "multi-year",
// ๊ธฐ๊ฐ ์ง์ (periodType์ ๋ง๋ ํ์)
target?: "2025" | "2025-03" | "2025-01-01 14:00",
// multi-year ํ์
์ฉ ์ต์
count?: 5 // ์กฐํํ ์ฐ๋ ๊ฐ์ (๊ธฐ๋ณธ๊ฐ: 5)
}
7. manage_settings
ํด์ ์ค์ ๊ด๋ฆฌ ๋๊ตฌ (์กฐํ/๋ณ๊ฒฝ).
์ก์ :
get: ํ์ฌ ์ค์ ์กฐํset: ์ค์ ๋ณ๊ฒฝ (ํ๋ฆฌ์ ๋๋ ์ปค์คํ )
{
action: "get" | "set",
// set ์ก์
์ฉ ์ต์
preset?: "ziping" | "dts" | "qtbj" | "modern" | "shensha" | "balanced",
// ๋๋ ์ปค์คํ
๊ฐ์ค์น
custom?: {
ziping: 0.3, // ์ํ๋ช
๋ฆฌ ๊ฐ์ค์น (0.0-1.0)
dts: 0.2, // ์ ์ฒ์ ๊ฐ์ค์น
qtbj: 0.2, // ๊ถํต๋ณด๊ฐ ๊ฐ์ค์น
modern: 0.2, // ํ๋๋ช
๋ฆฌ ๊ฐ์ค์น
shensha: 0.1 // ์ ์ด์ค์ฌ ๊ฐ์ค์น
}
}
๐ ํ๋ก์ ํธ ๊ตฌ์กฐ
fortuneteller/
โโโ src/
โ โโโ index.ts # MCP ์๋ฒ ์ง์
์
โ โโโ core/ # ํต์ฌ ์์คํ
โ โ โโโ tool-definitions.ts # 7๊ฐ ๋๊ตฌ ์ ์
โ โ โโโ tool-handler.ts # ๋๊ตฌ ๋ผ์ฐํ
โ โโโ tools/ # MCP ๋๊ตฌ ๊ตฌํ
โ โ โโโ analyze_saju.ts # ํตํฉ ์ฌ์ฃผ ๋ถ์
โ โ โโโ check_compatibility.ts
โ โ โโโ convert_calendar.ts
โ โ โโโ get_daily_fortune.ts
โ โ โโโ get_dae_un.ts
โ โ โโโ get_fortune_by_period.ts # ํตํฉ ์๊ฐ๋๋ณ ์ด์ธ
โ โ โโโ manage_settings.ts # ํตํฉ ์ค์ ๊ด๋ฆฌ
โ โโโ lib/ # ํต์ฌ ๋ก์ง
โ โ โโโ saju.ts # ์ฌ์ฃผ ๊ณ์ฐ (์งํ์์ -30๋ถ ๋ณด์ )
โ โ โโโ calendar.ts # ์์๋ ฅ ๋ณํ (๋ก์ปฌ ํ
์ด๋ธ)
โ โ โโโ fortune.ts # ์ด์ธ ๋ถ์
โ โ โโโ compatibility.ts # ๊ถํฉ ๋ถ์
โ โ โโโ dae_un.ts # ๋์ด ๊ณ์ฐ
โ โ โโโ yong_sin.ts # ์ฉ์ ์ ์
โ โ โโโ ten_gods.ts # ์ญ์ฑ ๊ณ์ฐ
โ โ โโโ sin_sal.ts # ์ ์ด ํ์ง (15๊ฐ)
โ โ โโโ day_master_strength.ts # ์ผ๊ฐ ๊ฐ์ฝ
โ โ โโโ gyeok_guk.ts # ๊ฒฉ๊ตญ ๊ฒฐ์
โ โโโ data/ # ์ ์ ๋ฐ์ดํฐ
โ โ โโโ heavenly_stems.ts # ์ฒ๊ฐ(ๅคฉๅนฒ) 10๊ฐ
โ โ โโโ earthly_branches.ts # ์ง์ง(ๅฐๆฏ) 12๊ฐ, ์ง์ฅ๊ฐ ์ธ๋ ฅ
โ โ โโโ wuxing.ts # ์คํ(ไบ่ก) ์์์๊ทน
โ โ โโโ solar_terms.ts # 24์ ๊ธฐ (1900-2200)
โ โ โโโ lunar_table.ts # ์๋ ฅ ํ
์ด๋ธ (1900-2200)
โ โ โโโ longitude_table.ts # ์ ๊ตญ 162๊ฐ ์๊ตฐ๊ตฌ ๊ฒฝ๋
โ โโโ types/ # ํ์
์ ์
โ โโโ index.ts
โโโ package.json
โโโ tsconfig.json
โโโ CLAUDE.md # Claude Code ๊ฐ์ด๋
โโโ README.md
๐ง ๊ฐ๋ฐ
# ๊ฐ๋ฐ ๋ชจ๋ (hot reload)
npm run watch
# ๋ฆฐํธ ์ฒดํฌ
npm run lint
# ์ฝ๋ ํฌ๋งทํ
npm run format
# ํ
์คํธ ์คํ
npm test
# API ๋ฌธ์ ์์ฑ
npm run docs
# API ๋ฌธ์ ๋ก์ปฌ ์๋ฒ (http://localhost:8080)
npm run docs:serve
๐ MCP ํด๋ผ์ด์ธํธ ์ค์
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json์ ๋ค์ ์ค์ ์ ์ถ๊ฐํ์ธ์:
npm ํจํค์ง ์ฌ์ฉ (๊ถ์ฅ)
{
"mcpServers": {
"saju": {
"command": "npx",
"args": ["-y", "@hoshin/saju-mcp-server"]
}
}
}
์ ์ญ ์ค์น ํ ์ฌ์ฉ
npm install -g @hoshin/saju-mcp-server
{
"mcpServers": {
"saju": {
"command": "saju-mcp-server"
}
}
}
๋ก์ปฌ ๊ฐ๋ฐ (์์ค์์)
{
"mcpServers": {
"saju": {
"command": "node",
"args": ["/path/to/saju-mcp-server/dist/index.js"]
}
}
}
๐ณ Docker ์ง์
Docker๋ก ์คํ
# ์ด๋ฏธ์ง ๋น๋
docker build -t saju-mcp-server .
# ์ปจํ
์ด๋ ์คํ
docker run -it --rm saju-mcp-server
# ๋๋ docker-compose ์ฌ์ฉ
docker-compose up -d
Smithery๋ฅผ ํตํ ์ํด๋ฆญ ์ค์น
# Smithery CLI๋ก ์ค์น
npx @smithery/cli install saju-mcp-server --client claude
Smithery ๋ง์ผํ๋ ์ด์ค์์ ๋ ์ฝ๊ฒ ์ค์นํ๊ณ ๊ด๋ฆฌํ ์ ์์ต๋๋ค.
๐ ์ฌ์ฃผํ์ ์ฉ์ด ์ค๋ช
๊ธฐ๋ณธ ๊ตฌ์ฑ ์์
- ์ฒ๊ฐ(ๅคฉๅนฒ): ๊ฐ(็ฒ), ์(ไน), ๋ณ(ไธ), ์ (ไธ), ๋ฌด(ๆ), ๊ธฐ(ๅทฑ), ๊ฒฝ(ๅบ), ์ (่พ), ์(ๅฃฌ), ๊ณ(็ธ) - 10๊ฐ
- ์ง์ง(ๅฐๆฏ): ์(ๅญ), ์ถ(ไธ), ์ธ(ๅฏ ), ๋ฌ(ๅฏ), ์ง(่พฐ), ์ฌ(ๅทณ), ์ค(ๅ), ๋ฏธ(ๆช), ์ (็ณ), ์ (้ ), ์ (ๆ), ํด(ไบฅ) - 12๊ฐ
- ์คํ(ไบ่ก): ๋ชฉ(ๆจ), ํ(็ซ), ํ (ๅ), ๊ธ(้), ์(ๆฐด) - ์์์๊ทน ๊ด๊ณ
- ์ญ์ฑ(ๅๆ): ๋น๊ฒฌ, ๊ฒ์ฌ, ์์ , ์๊ด, ํธ์ฌ, ์ ์ฌ, ํธ๊ด, ์ ๊ด, ํธ์ธ, ์ ์ธ
๊ณ ๊ธ ๋ถ์ ์์
- ์ง์ฅ๊ฐ(ๆฏ่ๅนฒ): ์ง์ง ์์ ์จ์ด์๋ ์ฒ๊ฐ (์ ๊ธฐ, ์ค๊ธฐ, ์ฌ๊ธฐ)
- ์ ์ด(็ฅๆฎบ): 15๊ฐ์ ๊ธธํ ์งํ (์ฒ์๊ท์ธ, ์ญ๋ง์ด, ๋ํ์ด, ์์ง์ด, ๊ท๋ฌธ๊ด์ด ๋ฑ)
- ์ฉ์ (็จ็ฅ): ์ฌ์ฃผ์ ๊ท ํ์ ๋ง์ถ๋ ํต์ฌ ์คํ
- ๊ฒฉ๊ตญ(ๆ ผๅฑ): ์ฌ์ฃผ์ ์ ์ฒด์ ์ธ ํจํด๊ณผ ์ฑํฅ
- ๋์ด(ๅคง้): 10๋ ๋จ์์ ํฐ ์ด์ธ ํ๋ฆ
- ์งํ์์(็ๅคช้ฝๆ): ํ๊ตญ ํ์ค์ -30๋ถ ๋ณด์ (์ ํํ ์ฌ์ฃผ ๊ณ์ฐ์ ์ํจ)
โ ๏ธ ๋ฉด์ฑ ์กฐํญ
์ด ์๋น์ค๋ ์ ํต ์ฌ์ฃผํ์๋ฅผ ๊ธฐ๋ฐ์ผ๋ก ํ ์ฐธ๊ณ ์ฉ ์ ๋ณด๋ฅผ ์ ๊ณตํฉ๋๋ค.
- ์ํ์ , ๋ฒ๋ฅ ์ , ์ฌ์ ์ ์กฐ์ธ์ด ์๋๋๋ค
- ์ค์ํ ๊ฒฐ์ ์ ๋ฐ๋์ ์ ๋ฌธ๊ฐ์ ์๋ดํ์๊ธฐ ๋ฐ๋๋๋ค
- ์ด์ธ๋ ๊ฐ์ธ์ ๋ ธ๋ ฅ๊ณผ ์ ํ์ ๋ฐ๋ผ ๋ฌ๋ผ์ง ์ ์์ต๋๋ค
๐ ๋ผ์ด์ผ์ค
MIT License
๐จโ๐ป ๊ธฐ์ฌ
์ด์ ์ ๋ณด ๋ฐ ํ ๋ฆฌํ์คํธ๋ฅผ ํ์ํฉ๋๋ค!
English
โจ Features
- Saju (Four Pillars) Calculation: Automatic calculation of 8 characters from birth date and time (with -30min true solar time correction)
- Fortune Analysis: Comprehensive analysis including personality, career, wealth, health, and love fortune
- Compatibility Analysis: Compatibility calculation and comparison between two people
- Calendar Conversion: Solar โ Lunar calendar conversion (1900-2200) with leap month support
- Daily Fortune: Detailed daily fortune for specific dates
- Dae-un (ๅคง้): 10-year major fortune cycle analysis
- Yong-sin (็จ็ฅ) Analysis: Personalized advice on colors, directions, and careers
- Ji-jang-gan Strength: Precise analysis with seasonal hidden stem strength calculation
- Sin-sal (็ฅๆฎบ): Detection of 15 special stars (including Won-jin-sal, Gwi-mun-gwan-sal)
๐ Quick Start
Installation
Option 1: Automatic Installation Script (Recommended)
curl -fsSL https://raw.githubusercontent.com/hoshin/saju-mcp-server/main/install.sh | bash
Option 2: Manual Installation
npm install -g @hoshin/saju-mcp-server
Option 3: Using npx (No Installation)
npx @hoshin/saju-mcp-server
Claude Desktop Configuration
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"saju": {
"command": "npx",
"args": ["-y", "@hoshin/saju-mcp-server"]
}
}
}
Restart Claude Desktop and start using the tools!
๐ ๏ธ Available Tools (7 Integrated Tools)
- analyze_saju - Integrated Saju analysis (basic/fortune/yongsin/school_compare/yongsin_method)
- check_compatibility - Analyze compatibility between two people
- convert_calendar - Convert between solar and lunar calendars (1900-2200)
- get_daily_fortune - Get daily fortune for specific date
- get_dae_un - Get 10-year major fortune cycles
- get_fortune_by_period - Get fortune by period (year/month/hour/multi-year)
- manage_settings - Manage interpretation settings (get/set)
๐ Key Concepts
Basic Components
- Heavenly Stems (ๅคฉๅนฒ): 10 stems - ็ฒไนไธไธๆๅทฑๅบ่พๅฃฌ็ธ
- Earthly Branches (ๅฐๆฏ): 12 branches - ๅญไธๅฏ ๅฏ่พฐๅทณๅๆช็ณ้ ๆไบฅ
- Five Elements (ไบ่ก): Wood, Fire, Earth, Metal, Water
- Ten Gods (ๅๆ): 10 relationship types
Advanced Analysis
- Hidden Stems (ๆฏ่ๅนฒ): Hidden stems within branches
- Special Stars (็ฅๆฎบ): 15 auspicious/inauspicious indicators
- Yong-sin (็จ็ฅ): Beneficial element for balance
- Pattern (ๆ ผๅฑ): Overall life pattern classification
- Dae-un (ๅคง้): 10-year major fortune cycles
- True Solar Time (็ๅคช้ฝๆ): -30min Korea time correction
๐ณ Docker Support
# Build image
docker build -t saju-mcp-server .
# Run container
docker run -it --rm saju-mcp-server
# Or use docker-compose
docker-compose up -d
๐ง Smithery One-Click Install
# Install via Smithery CLI
npx @smithery/cli install saju-mcp-server --client claude
Easier installation and management through Smithery marketplace.
๐ Documentation
- ๐ Developer Guide - Project structure and development
- ๐ Architecture - System architecture overview
- ๐ Design Docs - Design decisions and principles
- ๐ Quality Score - Quality metrics tracking
๐ค Contributing
Issues and pull requests are welcome!
๐ License
MIT License
โ ๏ธ Disclaimer
This service provides reference information based on traditional Saju fortune-telling.
- Not intended as medical, legal, or financial advice
- Please consult professionals for important decisions
- Fortune can change based on personal effort and choices
Made with โค๏ธ for Korean traditional fortune-telling
