fatenava-mcp 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/LICENSE +21 -0
  2. package/README.ja.md +115 -0
  3. package/README.ko.md +115 -0
  4. package/README.md +115 -0
  5. package/README.zh-Hans.md +115 -0
  6. package/README.zh-Hant.md +115 -0
  7. package/dist/index.js +139 -0
  8. package/package.json +58 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 FateNava
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.ja.md ADDED
@@ -0,0 +1,115 @@
1
+ # fatenava-mcp
2
+
3
+ [English](./README.md) | [繁體中文](./README.zh-Hant.md) | [简体中文](./README.zh-Hans.md) | **日本語** | [한국어](./README.ko.md)
4
+
5
+ **MCP 対応の AI エージェントから、四柱推命・紫微斗数・西洋占星術の出生図を直接作成。**
6
+
7
+ 1 つのツール、3 つの決定論的エンジン、セットアップ不要:アカウント不要・API キー不要・データは一切保存されません。
8
+ [FateNava](https://fatenava.com/ja/) の無料チャート API を利用しています。
9
+
10
+ ## できること
11
+
12
+ 出生情報(日付・時刻・場所・性別)を渡すと、最大 3 体系の構造化チャートデータが返ります:
13
+
14
+ | 体系 | 内容 |
15
+ |---|---|
16
+ | **四柱推命**(八字) | 四柱の干支、日主、五行の分布——出生地の経度に基づく**真太陽時**補正つき |
17
+ | **紫微斗数** | 十二宮と主星、命宮、四化 |
18
+ | **西洋占星術 出生図** | トロピカル方式・Placidus ハウス:上昇点(ASC)、惑星のサイン/ハウス配置、エレメントとモダリティ |
19
+
20
+ チャートの数値は **AI 生成ではなく決定論的な計算**です——同じ出生情報からは常に同じチャートが得られます。解釈はあなたの AI エージェント(または [FateNava の無料鑑定ツール](https://fatenava.com/ja/))にお任せください。
21
+
22
+ ## クイックスタート
23
+
24
+ ### Claude Code
25
+
26
+ ```bash
27
+ claude mcp add fatenava -- npx -y fatenava-mcp
28
+ ```
29
+
30
+ ### Codex CLI
31
+
32
+ ```toml
33
+ # ~/.codex/config.toml
34
+ [mcp_servers.fatenava]
35
+ command = "npx"
36
+ args = ["-y", "fatenava-mcp"]
37
+ ```
38
+
39
+ ### Cursor / 汎用 MCP クライアント
40
+
41
+ ```json
42
+ {
43
+ "mcpServers": {
44
+ "fatenava": {
45
+ "command": "npx",
46
+ "args": ["-y", "fatenava-mcp"]
47
+ }
48
+ }
49
+ }
50
+ ```
51
+
52
+ ## ツール:`cast_chart`
53
+
54
+ 出生情報の指定方法は 2 通り(どちらか一方):
55
+
56
+ **1. 1 行テキスト**(最も簡単。API が日付・時刻・場所・性別を解析し、都市名から座標とタイムゾーンを解決します):
57
+
58
+ ```json
59
+ { "text": "1995-08-10 12:00 東京 女" }
60
+ ```
61
+
62
+ 都市名は日本語・英語・中国語・韓国語に対応。
63
+
64
+ **2. 構造化フィールド**:
65
+
66
+ ```json
67
+ {
68
+ "year": 1995, "month": 8, "day": 10, "hour": 12, "minute": 0,
69
+ "gender": "female",
70
+ "longitude": 139.69, "latitude": 35.69, "timeZoneId": "Asia/Tokyo"
71
+ }
72
+ ```
73
+
74
+ オプション:
75
+
76
+ - `systems`:`["bazi", "ziwei", "astro"]` ——必要な体系だけ取得してレスポンスを小さく(デフォルトは全部)。
77
+ - `birthTimeKnown: false` ——出生時刻が不明な場合。四柱推命は年月日の三柱を返し、時刻に依存する部分は捏造せず正直に省略します。
78
+
79
+ ### レスポンス構造
80
+
81
+ ```jsonc
82
+ {
83
+ "birth": { "date": "1995-08-10", "time": "12:00", "gender": "female", "place": "…" },
84
+ "timeKnown": true,
85
+ "charts": {
86
+ "bazi": { "ok": true, "view": { "dayMaster": {…}, "fourPillars": […], … } },
87
+ "ziwei": { "ok": true, "view": { "palaces": […], … } },
88
+ "astro": { "ok": true, "view": { "ascendant": {…}, "bodies": […], … } }
89
+ }
90
+ }
91
+ ```
92
+
93
+ フィールド名は英語、干支・宮・星などの伝統用語は漢字表記で返ります。
94
+
95
+ ## ポリシー
96
+
97
+ - **無料・匿名。** ログイン不要、データは保存されません。
98
+ - **決定論的。** チャートはテスト済みエンジンが計算し、AI は解釈のみを担当。
99
+ - **限界に正直。** 出生時刻が不明な場合は推測せず正直に省略します。チャートが描くのは傾向とテーマであり、**決められた運命ではありません**。医療・法律・投資のアドバイスは行いません。
100
+ - 入門記事:[四柱推命(八字)とは?](https://fatenava.com/ja/articles/what-is-bazi/) · [出生図とは?](https://fatenava.com/ja/articles/what-is-a-natal-chart/) · [紫微斗数入門](https://fatenava.com/ja/articles/what-is-ziwei/)
101
+ - 詳細鑑定・相性診断(四柱推命の相性/シナストリー)・AI への追加質問:**[fatenava.com](https://fatenava.com/ja/)**
102
+
103
+ ## 開発
104
+
105
+ ```bash
106
+ npm install
107
+ npm run build
108
+ node dist/index.js # stdio で MCP を提供
109
+ ```
110
+
111
+ 環境変数 `FATENAVA_API_BASE` で API のオリジンを上書きできます(テスト用)。
112
+
113
+ ## ライセンス
114
+
115
+ [MIT](./LICENSE)
package/README.ko.md ADDED
@@ -0,0 +1,115 @@
1
+ # fatenava-mcp
2
+
3
+ [English](./README.md) | [繁體中文](./README.zh-Hant.md) | [简体中文](./README.zh-Hans.md) | [日本語](./README.ja.md) | **한국어**
4
+
5
+ **MCP를 지원하는 어떤 AI 에이전트에서든 사주(팔자)·자미두수·서양 점성술 출생 차트를 바로 뽑아 보세요.**
6
+
7
+ 하나의 도구, 세 가지 결정론적 엔진, 설정 제로: 계정 불필요, API 키 불필요, 어떤 데이터도 저장하지 않습니다.
8
+ [FateNava](https://fatenava.com/ko/)의 무료 차트 API로 구동됩니다.
9
+
10
+ ## 기능
11
+
12
+ 출생 정보(날짜·시각·장소·성별)를 입력하면 최대 세 체계의 구조화된 차트 데이터를 반환합니다:
13
+
14
+ | 체계 | 내용 |
15
+ |---|---|
16
+ | **사주(팔자)** | 사주 간지, 일간, 오행 분포——출생지 경도 기반 **진태양시** 보정 |
17
+ | **자미두수** | 십이궁과 주성, 명궁, 사화 |
18
+ | **서양 점성술 출생 차트** | 트로피컬 방식·Placidus 하우스: 상승점(ASC), 행성의 별자리/하우스 배치, 원소와 모달리티 |
19
+
20
+ 차트 수치는 **AI 생성이 아닌 결정론적 계산**입니다——같은 출생 정보는 언제나 같은 차트를 냅니다. 해석은 당신의 AI 에이전트(또는 [FateNava의 무료 풀이 도구](https://fatenava.com/ko/))에 맡기세요.
21
+
22
+ ## 빠른 시작
23
+
24
+ ### Claude Code
25
+
26
+ ```bash
27
+ claude mcp add fatenava -- npx -y fatenava-mcp
28
+ ```
29
+
30
+ ### Codex CLI
31
+
32
+ ```toml
33
+ # ~/.codex/config.toml
34
+ [mcp_servers.fatenava]
35
+ command = "npx"
36
+ args = ["-y", "fatenava-mcp"]
37
+ ```
38
+
39
+ ### Cursor / 일반 MCP 클라이언트
40
+
41
+ ```json
42
+ {
43
+ "mcpServers": {
44
+ "fatenava": {
45
+ "command": "npx",
46
+ "args": ["-y", "fatenava-mcp"]
47
+ }
48
+ }
49
+ }
50
+ ```
51
+
52
+ ## 도구: `cast_chart`
53
+
54
+ 출생 정보는 두 가지 방식 중 하나로 지정합니다:
55
+
56
+ **1. 한 줄 텍스트**(가장 간단. API가 날짜·시각·장소·성별을 해석하고 도시명을 좌표+시간대로 변환):
57
+
58
+ ```json
59
+ { "text": "1995-08-10 12:00 서울 여" }
60
+ ```
61
+
62
+ 도시명은 한국어·영어·중국어·일본어를 지원합니다.
63
+
64
+ **2. 구조화 필드**:
65
+
66
+ ```json
67
+ {
68
+ "year": 1995, "month": 8, "day": 10, "hour": 12, "minute": 0,
69
+ "gender": "female",
70
+ "longitude": 126.98, "latitude": 37.57, "timeZoneId": "Asia/Seoul"
71
+ }
72
+ ```
73
+
74
+ 선택 파라미터:
75
+
76
+ - `systems`: `["bazi", "ziwei", "astro"]` —— 필요한 체계만 받아 응답을 줄입니다(기본값: 전부).
77
+ - `birthTimeKnown: false` —— 정확한 태어난 시각을 모를 때. 사주는 연·월·일 세 기둥을 반환하고, 시각에 의존하는 부분은 지어내지 않고 정직하게 생략합니다.
78
+
79
+ ### 응답 구조
80
+
81
+ ```jsonc
82
+ {
83
+ "birth": { "date": "1995-08-10", "time": "12:00", "gender": "female", "place": "…" },
84
+ "timeKnown": true,
85
+ "charts": {
86
+ "bazi": { "ok": true, "view": { "dayMaster": {…}, "fourPillars": […], … } },
87
+ "ziwei": { "ok": true, "view": { "palaces": […], … } },
88
+ "astro": { "ok": true, "view": { "ascendant": {…}, "bodies": […], … } }
89
+ }
90
+ }
91
+ ```
92
+
93
+ 필드명은 영어이며, 간지·궁·별 등 전통 용어는 한자 원문으로 반환됩니다.
94
+
95
+ ## 원칙
96
+
97
+ - **무료·익명.** 로그인 불필요, 아무것도 저장하지 않습니다.
98
+ - **결정론적.** 차트는 검증된 엔진이 계산하고 AI는 해석만 담당합니다.
99
+ - **한계에 정직.** 태어난 시각을 모르면 추측하는 대신 정직하게 생략합니다. 차트가 그리는 것은 경향과 과제이지 **정해진 운명이 아닙니다**. 의료·법률·투자 조언은 하지 않습니다.
100
+ - 개념 입문: [사주(팔자)란?](https://fatenava.com/ko/articles/what-is-bazi/) · [출생 차트란?](https://fatenava.com/ko/articles/what-is-a-natal-chart/) · [자미두수 입문](https://fatenava.com/ko/articles/what-is-ziwei/)
101
+ - 심층 리포트·궁합(사주 궁합/시너스트리)·AI 추가 질문: **[fatenava.com](https://fatenava.com/ko/)**
102
+
103
+ ## 개발
104
+
105
+ ```bash
106
+ npm install
107
+ npm run build
108
+ node dist/index.js # stdio로 MCP 제공
109
+ ```
110
+
111
+ 환경 변수 `FATENAVA_API_BASE`로 API 오리진을 바꿀 수 있습니다(테스트용).
112
+
113
+ ## 라이선스
114
+
115
+ [MIT](./LICENSE)
package/README.md ADDED
@@ -0,0 +1,115 @@
1
+ # fatenava-mcp
2
+
3
+ **English** | [繁體中文](./README.zh-Hant.md) | [简体中文](./README.zh-Hans.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md)
4
+
5
+ **Cast BaZi, Zi Wei Dou Shu, and Western astrology natal charts from any MCP-capable AI agent.**
6
+
7
+ One tool, three deterministic engines, zero setup: no account, no API key, nothing stored.
8
+ Powered by the free chart API of [FateNava](https://fatenava.com).
9
+
10
+ ## What it does
11
+
12
+ Give it a birth (date, time, place, gender) and it returns structured chart data from up to three systems:
13
+
14
+ | System | What you get |
15
+ |---|---|
16
+ | **BaZi 八字** (Four Pillars of Destiny) | Four pillars (stems & branches), Day Master, Five-Elements distribution — computed with **True Solar Time** correction from the birthplace longitude |
17
+ | **Zi Wei Dou Shu 紫微斗數** (Purple Star Astrology) | Twelve palaces with major stars, Life Palace, transformations |
18
+ | **Western natal chart** | Tropical zodiac, Placidus houses: Ascendant, planets by sign/house, elements & modalities |
19
+
20
+ The numbers are **computed, not AI-generated** — the same birth always produces the same charts. Interpretation is left to your AI agent (or to [FateNava's free reading tools](https://fatenava.com)).
21
+
22
+ ## Quick start
23
+
24
+ ### Claude Code
25
+
26
+ ```bash
27
+ claude mcp add fatenava -- npx -y fatenava-mcp
28
+ ```
29
+
30
+ ### Codex CLI
31
+
32
+ ```toml
33
+ # ~/.codex/config.toml
34
+ [mcp_servers.fatenava]
35
+ command = "npx"
36
+ args = ["-y", "fatenava-mcp"]
37
+ ```
38
+
39
+ ### Cursor / generic MCP client
40
+
41
+ ```json
42
+ {
43
+ "mcpServers": {
44
+ "fatenava": {
45
+ "command": "npx",
46
+ "args": ["-y", "fatenava-mcp"]
47
+ }
48
+ }
49
+ }
50
+ ```
51
+
52
+ ## Tool: `cast_chart`
53
+
54
+ Two ways to describe the birth — pick one:
55
+
56
+ **1. One-line text** (easiest; the API parses date, time, place and gender, and resolves the city to coordinates + timezone):
57
+
58
+ ```json
59
+ { "text": "1995-08-10 12:00 Taipei female" }
60
+ ```
61
+
62
+ City names in English, Chinese, Japanese, or Korean are accepted.
63
+
64
+ **2. Structured fields**:
65
+
66
+ ```json
67
+ {
68
+ "year": 1995, "month": 8, "day": 10, "hour": 12, "minute": 0,
69
+ "gender": "female",
70
+ "longitude": 121.5, "latitude": 25.04, "timeZoneId": "Asia/Taipei"
71
+ }
72
+ ```
73
+
74
+ Optional:
75
+
76
+ - `systems`: `["bazi", "ziwei", "astro"]` — pick a subset to keep the response small (default: all three).
77
+ - `birthTimeKnown: false` — when the exact hour is unknown. BaZi still returns three pillars; hour-dependent parts are omitted honestly instead of being guessed.
78
+
79
+ ### Response shape
80
+
81
+ ```jsonc
82
+ {
83
+ "birth": { "date": "1995-08-10", "time": "12:00", "gender": "female", "place": "…" },
84
+ "timeKnown": true,
85
+ "charts": {
86
+ "bazi": { "ok": true, "view": { "dayMaster": {…}, "fourPillars": […], … } },
87
+ "ziwei": { "ok": true, "view": { "palaces": […], … } },
88
+ "astro": { "ok": true, "view": { "ascendant": {…}, "bodies": […], … } }
89
+ }
90
+ }
91
+ ```
92
+
93
+ Field names are English; traditional terms (heavenly stems, earthly branches, palace and star names) come in their native Chinese characters — ask your agent to translate them for the user.
94
+
95
+ ## Notes & principles
96
+
97
+ - **Free & anonymous.** The underlying endpoint requires no login and stores nothing.
98
+ - **Deterministic.** Charts are calculated by tested engines; the AI layer only interprets.
99
+ - **Honest about limits.** Unknown birth time degrades gracefully instead of inventing an hour. Charts describe tendencies and themes — not fixed fate. Not medical, legal, or financial advice.
100
+ - Learn the concepts: [What is BaZi?](https://fatenava.com/en/articles/what-is-bazi/) · [What is a natal chart?](https://fatenava.com/en/articles/what-is-a-natal-chart/) · [What is Zi Wei Dou Shu?](https://fatenava.com/en/articles/what-is-ziwei/)
101
+ - Full readings, compatibility (synastry / 合婚) and AI Q&A: **[fatenava.com](https://fatenava.com)**
102
+
103
+ ## Development
104
+
105
+ ```bash
106
+ npm install
107
+ npm run build
108
+ node dist/index.js # speaks MCP over stdio
109
+ ```
110
+
111
+ `FATENAVA_API_BASE` env var overrides the API origin (for testing).
112
+
113
+ ## License
114
+
115
+ [MIT](./LICENSE)
package/README.zh-Hans.md ADDED
@@ -0,0 +1,115 @@
1
+ # fatenava-mcp
2
+
3
+ [English](./README.md) | [繁體中文](./README.zh-Hant.md) | **简体中文** | [日本語](./README.ja.md) | [한국어](./README.ko.md)
4
+
5
+ **让任何支持 MCP 的 AI Agent 直接排出八字、紫微斗数与西洋占星本命盘。**
6
+
7
+ 一个工具、三套确定性排盘引擎、零门槛:无需账号、无需 API key、不存储任何数据。
8
+ 由 [FateNava](https://fatenava.com/zh-hans/) 的免费排盘 API 驱动。
9
+
10
+ ## 功能
11
+
12
+ 输入一份出生资料(日期、时间、地点、性别),最多返回三套命盘的结构化数据:
13
+
14
+ | 体系 | 内容 |
15
+ |---|---|
16
+ | **八字**(四柱命理) | 四柱干支、日主、五行分布——按出生地经度做**真太阳时**校正 |
17
+ | **紫微斗数** | 十二宫与主星、命宫、四化 |
18
+ | **西洋占星本命盘** | 回归黄道、Placidus 分宫:上升点、行星落座落宫、元素与模式分布 |
19
+
20
+ 盘面数据为**确定性计算,非 AI 生成**——同一份出生资料永远得到同一张盘。解读交给你的 AI Agent(或 [FateNava 的免费解读工具](https://fatenava.com/zh-hans/))。
21
+
22
+ ## 快速开始
23
+
24
+ ### Claude Code
25
+
26
+ ```bash
27
+ claude mcp add fatenava -- npx -y fatenava-mcp
28
+ ```
29
+
30
+ ### Codex CLI
31
+
32
+ ```toml
33
+ # ~/.codex/config.toml
34
+ [mcp_servers.fatenava]
35
+ command = "npx"
36
+ args = ["-y", "fatenava-mcp"]
37
+ ```
38
+
39
+ ### Cursor / 通用 MCP 客户端
40
+
41
+ ```json
42
+ {
43
+ "mcpServers": {
44
+ "fatenava": {
45
+ "command": "npx",
46
+ "args": ["-y", "fatenava-mcp"]
47
+ }
48
+ }
49
+ }
50
+ ```
51
+
52
+ ## 工具:`cast_chart`
53
+
54
+ 出生资料两种写法,二选一:
55
+
56
+ **1. 单行文本**(最简单;API 自动解析日期、时间、地点与性别,并将城市解析为经纬度+时区):
57
+
58
+ ```json
59
+ { "text": "1995-08-10 12:00 台北 女" }
60
+ ```
61
+
62
+ 城市名支持中文、英文、日文、韩文。
63
+
64
+ **2. 结构化字段**:
65
+
66
+ ```json
67
+ {
68
+ "year": 1995, "month": 8, "day": 10, "hour": 12, "minute": 0,
69
+ "gender": "female",
70
+ "longitude": 121.5, "latitude": 25.04, "timeZoneId": "Asia/Taipei"
71
+ }
72
+ ```
73
+
74
+ 可选参数:
75
+
76
+ - `systems`:`["bazi", "ziwei", "astro"]`——只取需要的体系,缩小响应体积(默认全部)。
77
+ - `birthTimeKnown: false`——不确定出生时辰时使用。八字仍返回年月日三柱;依赖时辰的部分诚实从缺,不臆造。
78
+
79
+ ### 响应结构
80
+
81
+ ```jsonc
82
+ {
83
+ "birth": { "date": "1995-08-10", "time": "12:00", "gender": "female", "place": "…" },
84
+ "timeKnown": true,
85
+ "charts": {
86
+ "bazi": { "ok": true, "view": { "dayMaster": {…}, "fourPillars": […], … } },
87
+ "ziwei": { "ok": true, "view": { "palaces": […], … } },
88
+ "astro": { "ok": true, "view": { "ascendant": {…}, "bodies": […], … } }
89
+ }
90
+ }
91
+ ```
92
+
93
+ 字段名为英文;干支、宫位、星曜等传统术语以汉字原文呈现。
94
+
95
+ ## 原则
96
+
97
+ - **免费且匿名。** 底层端点无需登录、不存储任何数据。
98
+ - **确定性。** 盘面由经过测试的引擎计算,AI 只负责解读。
99
+ - **诚实面对边界。** 时辰不明时优雅降级而非臆造;命盘描述的是倾向与课题,**不是写定的命运**;不提供医疗、法律或投资建议。
100
+ - 概念入门:[八字(四柱)是什么?](https://fatenava.com/zh-hans/articles/what-is-bazi/) · [本命盘是什么?](https://fatenava.com/zh-hans/articles/what-is-a-natal-chart/) · [紫微斗数入门](https://fatenava.com/zh-hans/articles/what-is-ziwei/)
101
+ - 深度报告、双人合盘(八字合婚/占星合盘)与 AI 追问:**[fatenava.com](https://fatenava.com/zh-hans/)**
102
+
103
+ ## 开发
104
+
105
+ ```bash
106
+ npm install
107
+ npm run build
108
+ node dist/index.js # 通过 stdio 提供 MCP 服务
109
+ ```
110
+
111
+ 环境变量 `FATENAVA_API_BASE` 可覆写 API 来源(测试用)。
112
+
113
+ ## 许可
114
+
115
+ [MIT](./LICENSE)
package/README.zh-Hant.md ADDED
@@ -0,0 +1,115 @@
1
+ # fatenava-mcp
2
+
3
+ [English](./README.md) | **繁體中文** | [简体中文](./README.zh-Hans.md) | [日本語](./README.ja.md) | [한국어](./README.ko.md)
4
+
5
+ **讓任何支援 MCP 的 AI Agent 直接排出八字、紫微斗數與西洋占星本命盤。**
6
+
7
+ 一個工具、三套確定性排盤引擎、零門檻：無需帳號、無需 API key、不儲存任何資料。
8
+ 由 [FateNava](https://fatenava.com/zh-hant/) 的免費排盤 API 驅動。
9
+
10
+ ## 功能
11
+
12
+ 輸入一份出生資料（日期、時間、地點、性別），最多回傳三套命盤的結構化資料：
13
+
14
+ | 體系 | 內容 |
15
+ |---|---|
16
+ | **八字**（四柱命理） | 四柱干支、日主、五行分布——依出生地經度做**真太陽時**校正 |
17
+ | **紫微斗數** | 十二宮與主星、命宮、四化 |
18
+ | **西洋占星本命盤** | 回歸黃道、Placidus 分宮：上升點、行星落座落宮、元素與模式分布 |
19
+
20
+ 盤面數據為**確定性計算，非 AI 生成**——同一份出生資料永遠得到同一張盤。解讀交給你的 AI Agent（或 [FateNava 的免費解讀工具](https://fatenava.com/zh-hant/)）。
21
+
22
+ ## 快速開始
23
+
24
+ ### Claude Code
25
+
26
+ ```bash
27
+ claude mcp add fatenava -- npx -y fatenava-mcp
28
+ ```
29
+
30
+ ### Codex CLI
31
+
32
+ ```toml
33
+ # ~/.codex/config.toml
34
+ [mcp_servers.fatenava]
35
+ command = "npx"
36
+ args = ["-y", "fatenava-mcp"]
37
+ ```
38
+
39
+ ### Cursor / 通用 MCP 客戶端
40
+
41
+ ```json
42
+ {
43
+ "mcpServers": {
44
+ "fatenava": {
45
+ "command": "npx",
46
+ "args": ["-y", "fatenava-mcp"]
47
+ }
48
+ }
49
+ }
50
+ ```
51
+
52
+ ## 工具：`cast_chart`
53
+
54
+ 出生資料兩種寫法，二選一：
55
+
56
+ **1. 單行文字**（最簡單；API 自動解析日期、時間、地點與性別，並將城市解析為經緯度＋時區）：
57
+
58
+ ```json
59
+ { "text": "1995-08-10 12:00 台北 女" }
60
+ ```
61
+
62
+ 城市名支援中文、英文、日文、韓文。
63
+
64
+ **2. 結構化欄位**：
65
+
66
+ ```json
67
+ {
68
+ "year": 1995, "month": 8, "day": 10, "hour": 12, "minute": 0,
69
+ "gender": "female",
70
+ "longitude": 121.5, "latitude": 25.04, "timeZoneId": "Asia/Taipei"
71
+ }
72
+ ```
73
+
74
+ 可選參數：
75
+
76
+ - `systems`：`["bazi", "ziwei", "astro"]` ——只取需要的體系，縮小回應體積（預設全部）。
77
+ - `birthTimeKnown: false` ——不確定出生時辰時使用。八字仍回傳年月日三柱；依賴時辰的部分誠實從缺，不臆造。
78
+
79
+ ### 回應結構
80
+
81
+ ```jsonc
82
+ {
83
+ "birth": { "date": "1995-08-10", "time": "12:00", "gender": "female", "place": "…" },
84
+ "timeKnown": true,
85
+ "charts": {
86
+ "bazi": { "ok": true, "view": { "dayMaster": {…}, "fourPillars": […], … } },
87
+ "ziwei": { "ok": true, "view": { "palaces": […], … } },
88
+ "astro": { "ok": true, "view": { "ascendant": {…}, "bodies": […], … } }
89
+ }
90
+ }
91
+ ```
92
+
93
+ 欄位名為英文；干支、宮位、星曜等傳統術語以漢字原文呈現。
94
+
95
+ ## 原則
96
+
97
+ - **免費且匿名。** 底層端點無需登入、不儲存任何資料。
98
+ - **確定性。** 盤面由經過測試的引擎計算，AI 只負責解讀。
99
+ - **誠實面對邊界。** 時辰不明時優雅降級而非臆造；命盤描述的是傾向與課題，**不是寫定的命運**；不提供醫療、法律或投資建議。
100
+ - 概念入門：[八字（四柱）是什麼？](https://fatenava.com/zh-hant/articles/what-is-bazi/) · [本命盤是什麼？](https://fatenava.com/zh-hant/articles/what-is-a-natal-chart/) · [紫微斗數入門](https://fatenava.com/zh-hant/articles/what-is-ziwei/)
101
+ - 深度報告、雙人合盤（八字合婚／占星合盤）與 AI 追問：**[fatenava.com](https://fatenava.com/zh-hant/)**
102
+
103
+ ## 開發
104
+
105
+ ```bash
106
+ npm install
107
+ npm run build
108
+ node dist/index.js # 透過 stdio 提供 MCP 服務
109
+ ```
110
+
111
+ 環境變數 `FATENAVA_API_BASE` 可覆寫 API 來源（測試用）。
112
+
113
+ ## 授權
114
+
115
+ [MIT](./LICENSE)
package/dist/index.js ADDED
@@ -0,0 +1,139 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * fatenava-mcp — MCP server for casting destiny charts via the free FateNava API.
4
+ *
5
+ * Three deterministic engines behind one tool:
6
+ * - BaZi (Four Pillars of Destiny, 八字) with True Solar Time correction
7
+ * - Zi Wei Dou Shu (Purple Star Astrology, 紫微斗數)
8
+ * - Western astrology natal chart (tropical zodiac, Placidus houses)
9
+ *
10
+ * The API is free and anonymous: no account, no API key, nothing is stored.
11
+ * Charts are computed deterministically from birth data — the numbers are not
12
+ * AI-generated. Interpretation is left to the calling model.
13
+ */
14
+ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
15
+ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
16
+ import { z } from 'zod';
17
+ const API_BASE = process.env.FATENAVA_API_BASE ?? 'https://fatenava.com';
18
+ const COMPUTE_URL = `${API_BASE}/api/chart/compute`;
19
+ const VERSION = '0.1.0';
20
+ const SYSTEMS = ['bazi', 'ziwei', 'astro'];
21
+ // ── input schema ────────────────────────────────────────────────────────────
22
+ // Two ways to specify a birth (exactly one is required):
23
+ // 1. `text` — one free-form line, e.g. "1995-08-10 12:00 Taipei female".
24
+ // The API parses the date, time, place (geocoding + timezone)
25
+ // and gender from it.
26
+ // 2. structured fields — explicit date/time/gender plus coordinates.
27
+ const inputShape = {
28
+ text: z
29
+ .string()
30
+ .min(4)
31
+ .max(200)
32
+ .optional()
33
+ .describe('One-line birth description: date, time (or omit if unknown), birthplace, gender. ' +
34
+ 'Example: "1995-08-10 12:00 Taipei female". City names in English, Chinese, Japanese or Korean are accepted. ' +
35
+ 'Use EITHER this field OR the structured fields below.'),
36
+ year: z.number().int().min(1).max(9999).optional().describe('Birth year (structured input)'),
37
+ month: z.number().int().min(1).max(12).optional(),
38
+ day: z.number().int().min(1).max(31).optional(),
39
+ hour: z.number().int().min(0).max(23).optional().describe('Birth hour 0-23; pass with birthTimeKnown=false if unknown'),
40
+ minute: z.number().int().min(0).max(59).optional(),
41
+ birthTimeKnown: z
42
+ .boolean()
43
+ .optional()
44
+ .describe('Set false when the exact birth time is unknown — BaZi still returns three pillars; hour-dependent parts are omitted honestly'),
45
+ gender: z.enum(['male', 'female']).optional().describe('Required with structured input'),
46
+ longitude: z.number().min(-180).max(180).optional().describe('Birthplace longitude (structured input); used for True Solar Time correction'),
47
+ latitude: z.number().min(-90).max(90).optional(),
48
+ timeZoneId: z.string().optional().describe('IANA timezone of the birthplace, e.g. "Asia/Taipei" (structured input)'),
49
+ systems: z
50
+ .array(z.enum(SYSTEMS))
51
+ .optional()
52
+ .describe('Which chart systems to return: "bazi", "ziwei", "astro". Default: all three.'),
53
+ };
54
+ function errorResult(message) {
55
+ return { content: [{ type: 'text', text: message }], isError: true };
56
+ }
57
+ async function callCompute(body) {
58
+ const res = await fetch(COMPUTE_URL, {
59
+ method: 'POST',
60
+ headers: {
61
+ 'content-type': 'application/json',
62
+ 'user-agent': `fatenava-mcp/${VERSION}`,
63
+ },
64
+ body: JSON.stringify(body),
65
+ });
66
+ const data = (await res.json().catch(() => ({})));
67
+ return { status: res.status, data };
68
+ }
69
+ // ── server ──────────────────────────────────────────────────────────────────
70
+ const server = new McpServer({ name: 'fatenava-mcp', version: VERSION });
71
+ server.registerTool('cast_chart', {
72
+ title: 'Cast destiny charts (BaZi / Zi Wei / Western astrology)',
73
+ description: 'Cast up to three deterministic destiny charts from one birth: BaZi (Four Pillars, with True Solar Time correction), ' +
74
+ 'Zi Wei Dou Shu (Purple Star Astrology), and a Western natal chart (tropical zodiac, Placidus houses). ' +
75
+ 'Free and anonymous — no account, nothing stored. ' +
76
+ 'Input is either a one-line `text` birth description, or structured fields (year/month/day/hour/minute + gender + longitude/latitude + timeZoneId). ' +
77
+ 'Returns structured JSON per system: field names in English; traditional terms (stems & branches, palace and star names) in their native Chinese characters — translate them for the user as needed. ' +
78
+ 'The chart data is computed, not AI-generated; interpretation is up to you. Full reading tools at https://fatenava.com',
79
+ inputSchema: inputShape,
80
+ }, async (args) => {
81
+ // Build the API request: text path or structured path.
82
+ let body;
83
+ if (args.text) {
84
+ body = { text: args.text };
85
+ }
86
+ else {
87
+ const required = ['year', 'month', 'day', 'gender', 'longitude', 'latitude'];
88
+ const missing = required.filter((k) => args[k] === undefined);
89
+ if (missing.length > 0) {
90
+ return errorResult(`Missing required structured fields: ${missing.join(', ')}. ` +
91
+ 'Either pass a one-line `text` birth description, or provide year/month/day (+hour/minute), gender, longitude, latitude and ideally timeZoneId.');
92
+ }
93
+ body = {
94
+ year: args.year,
95
+ month: args.month,
96
+ day: args.day,
97
+ hour: args.hour ?? 12,
98
+ minute: args.minute ?? 0,
99
+ birthTimeKnown: args.birthTimeKnown ?? (args.hour !== undefined),
100
+ gender: args.gender,
101
+ longitude: args.longitude,
102
+ latitude: args.latitude,
103
+ ...(args.timeZoneId ? { timeZoneId: args.timeZoneId } : {}),
104
+ };
105
+ }
106
+ let status;
107
+ let data;
108
+ try {
109
+ ({ status, data } = await callCompute(body));
110
+ }
111
+ catch (err) {
112
+ return errorResult(`Network error calling FateNava API: ${err instanceof Error ? err.message : String(err)}`);
113
+ }
114
+ if (status === 422) {
115
+ return errorResult(`The API could not understand the birth input (HTTP 422): ${JSON.stringify(data)}. ` +
116
+ 'Check the date/time format and that the birthplace is a recognizable city.');
117
+ }
118
+ if (status !== 200) {
119
+ return errorResult(`FateNava API returned HTTP ${status}: ${JSON.stringify(data).slice(0, 300)}`);
120
+ }
121
+ // Trim to requested systems; pass through slot errors honestly.
122
+ const wanted = args.systems && args.systems.length > 0 ? args.systems : SYSTEMS;
123
+ const charts = {};
124
+ for (const s of wanted)
125
+ charts[s] = data[s] ?? { ok: false, reason: 'missing from API response' };
126
+ const result = {
127
+ birth: data.birth,
128
+ timeKnown: data.timeKnown,
129
+ charts,
130
+ _source: {
131
+ provider: 'FateNava',
132
+ url: 'https://fatenava.com',
133
+ note: 'Deterministic chart computation (not AI-generated). Free full readings and AI interpretation at the website.',
134
+ },
135
+ };
136
+ return { content: [{ type: 'text', text: JSON.stringify(result) }] };
137
+ });
138
+ const transport = new StdioServerTransport();
139
+ await server.connect(transport);
package/package.json ADDED
@@ -0,0 +1,58 @@
1
+ {
2
+ "name": "fatenava-mcp",
3
+ "version": "0.1.0",
4
+ "description": "MCP server for casting BaZi (Four Pillars), Zi Wei Dou Shu, and Western astrology natal charts — deterministic, free, no account required. Powered by FateNava.",
5
+ "type": "module",
6
+ "bin": {
7
+ "fatenava-mcp": "dist/index.js"
8
+ },
9
+ "main": "dist/index.js",
10
+ "files": [
11
+ "dist",
12
+ "README*.md",
13
+ "LICENSE"
14
+ ],
15
+ "scripts": {
16
+ "build": "tsc && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\"",
17
+ "start": "node dist/index.js",
18
+ "prepublishOnly": "npm run build"
19
+ },
20
+ "engines": {
21
+ "node": ">=18"
22
+ },
23
+ "publishConfig": {
24
+ "registry": "https://registry.npmjs.org/"
25
+ },
26
+ "keywords": [
27
+ "mcp",
28
+ "model-context-protocol",
29
+ "bazi",
30
+ "four-pillars",
31
+ "ziwei",
32
+ "zi-wei-dou-shu",
33
+ "astrology",
34
+ "natal-chart",
35
+ "horoscope",
36
+ "fortune-telling",
37
+ "chinese-astrology",
38
+ "fatenava"
39
+ ],
40
+ "author": "FateNava (https://fatenava.com)",
41
+ "license": "MIT",
42
+ "repository": {
43
+ "type": "git",
44
+ "url": "git+https://github.com/fatenava/fatenava-mcp.git"
45
+ },
46
+ "homepage": "https://fatenava.com",
47
+ "bugs": {
48
+ "url": "https://github.com/fatenava/fatenava-mcp/issues"
49
+ },
50
+ "dependencies": {
51
+ "@modelcontextprotocol/sdk": "^1.12.0",
52
+ "zod": "^3.24.0"
53
+ },
54
+ "devDependencies": {
55
+ "typescript": "^5.6.0",
56
+ "@types/node": "^22.0.0"
57
+ }
58
+ }