OpenFate Bazi MCP 完整教學

1. 專案定位與核心價值

解決什麼問題

大型語言模型（LLM）在面對八字（四柱）排盤計算時，往往會產生曆法運算幻覺。八字排盤並非文字推理題，而是涉及確定性曆法計算的精密工程，包含：

  • 二十四節氣邊界判斷
  • 真太陽時（True Solar Time）校正
  • 經度與時區修正
  • 夏令時間（DST）偏移處理
  • 子時換日規則
  • 農曆轉公曆
  • 地支六沖、六合、三合、三會、刑、破、害等互動

OpenFate Bazi MCP 的核心設計哲學：把確定性計算交給引擎，讓 AI 專注於解讀與說明。

核心價值主張

面向傳統方式OpenFate Bazi MCP
計算準確度LLM 推理，容易出錯確定性引擎，可驗證
真太陽時通常被忽略內建經度+時區校正
地支互動手動查表7 種交互自動偵測
整合成本需自建 API一行 npx 啟動
隱私可能上傳資料完全本機計算

專案基本資訊

  • 專案名稱：@openfate/bazi-mcp
  • 版本：v0.2.3（2026-06-18）
  • 授權：MIT License
  • 主要語言：TypeScript
  • 底層引擎：@openfate/bazi-engine + @openfate/true-solar-time
  • Node.js 需求：>= 20
  • GitHub Stars：49 | Forks：7

2. 安裝與環境設定

前置需求

  • Node.js >= 20（建議使用 nvm 管理版本）
  • 支援 MCP 的 AI 工具（Claude Desktop / Cursor / Cline / Continue）

方式一：npx 直接執行（推薦）

1npx -y @openfate/bazi-mcp

這是最簡單的方式，無需全域安裝，npx 會自動下載並執行 MCP 伺服器。

方式二：Clone 原始碼開發

1git clone https://github.com/openfate-ai/bazi-mcp.git
2cd bazi-mcp
3npm install
4npm run build
5npm run smoke   # 執行煙霧測試

方式三：Docker

1docker build -t openfate-bazi-mcp .
2docker run --rm openfate-bazi-mcp

Dockerfile 使用 multi-stage build（node:20-alpine），最終映像精簡。

MCP Client 設定

Claude Desktop

在 Claude Desktop 設定檔中加入：

1{
2  "mcpServers": {
3    "openfate-bazi": {
4      "command": "npx",
5      "args": ["-y", "@openfate/bazi-mcp"]
6    }
7  }
8}

macOS 若 Claude Desktop 找不到 npx，改用絕對路徑 /opt/homebrew/bin/npx。

Cursor

1{
2  "mcpServers": {
3    "openfate-bazi": {
4      "command": "npx",
5      "args": ["-y", "@openfate/bazi-mcp"]
6    }
7  }
8}

Cline

1{
2  "mcpServers": {
3    "openfate-bazi": {
4      "command": "npx",
5      "args": ["-y", "@openfate/bazi-mcp"],
6      "disabled": false
7    }
8  }
9}

Agent Skill 安裝

將 skills/openfate-bazi/SKILL.md 複製到 Claude Code workspace 的 .claude/skills/openfate-bazi/ 目錄即可。

3. 核心架構解析

系統架構


graph TB
    subgraph "AI Agent Layer"
        CD[Claude Desktop]
        CU[Cursor]
        CL[Cline]
        CT[Continue]
    end

    subgraph "MCP Transport"
        STDIO[stdio Transport]
    end

    subgraph "OpenFate Bazi MCP Server"
        SRV[McpServer v0.2.3]
        T1["calculate_bazi_chart"]
        T2["detect_bazi_interactions"]
        T3["calculate_true_solar_time"]
        T4["reverse_bazi_to_solar_times"]
        T5["get_openfate_bazi_policy"]
        T6["get_openfate_bazi_resources"]
    end

    subgraph "Calculation Engines"
        BE["@openfate/bazi-engine"]
        TST["@openfate/true-solar-time"]
    end

    subgraph "Validation"
        ZOD[Zod Schema]
    end

    CD & CU & CL & CT --> STDIO
    STDIO --> SRV
    SRV --> T1 & T2 & T3 & T4 & T5 & T6
    T1 --> ZOD --> BE
    T1 --> TST
    T2 --> BE
    T3 --> TST
    T4 --> BE

程式碼結構

 1bazi-mcp/
 2├── src/
 3│   ├── stdio.ts          # 進入點：建立 StdioServerTransport 並連接 MCP server
 4│   └── mcp.ts            # 核心：createServer() 註冊 6 個 MCP tools
 5├── tests/
 6│   └── smoke-stdio.ts    # 煙霧測試：透過真實 MCP SDK client 驗證
 7├── skills/
 8│   └── openfate-bazi/
 9│       └── SKILL.md      # Agent Skill 描述檔
10├── scripts/
11│   ├── pack-mcpb.mjs     # MCPB 打包腳本
12│   └── publish-smithery.mjs  # Smithery 發佈腳本
13├── mcpb/
14│   ├── manifest.json     # MCPB manifest
15│   └── assets/icon.png   # MCP 圖示
16├── .github/workflows/
17│   ├── ci.yml            # CI pipeline
18│   ├── npm-publish.yml   # npm 自動發佈
19│   ├── github-release.yml # GitHub release 自動化
20│   └── mcp-registry.yml  # MCP Registry 元資料更新
21├── server.json           # MCP server 描述
22├── glama.json            # Glama registry 元資料
23├── Dockerfile            # Docker multi-stage build
24├── package.json          # v0.2.3, @openfate/bazi-mcp
25└── tsconfig.json

關鍵設計決策

  1. 純 stdio transport：不支援 HTTP/SSE，所有通訊走 stdin/stdout，符合 MCP 標準且安全
  2. Zod schema 驗證：所有輸入經過嚴格型別檢查，避免無效資料進入引擎
  3. 確定性計算分離：MCP server 只負責 I/O 與格式化，計算全部委託給 @openfate/bazi-engine
  4. Attribution 作為一級資料：回傳的 attribution 不藏在 _meta，確保 AI 能正確顯示來源

4. 主要功能詳解

4.1 calculate_bazi_chart — 八字排盤

這是最核心的 tool，計算完整的八字命盤。

輸入參數：

參數型別必填說明
yearnumber是出生年（1800-2100）
monthnumber是出生月（1-12）
daynumber是出生日（1-31）
hournumber否出生時（0-23），未知可省略
minutenumber否出生分（0-59），預設 0
gender“male” / “female”是性別，用於大運方向
longitudenumber否出生地經度（-180 到 180），啟用真太陽時
timezonenumber否UTC 偏移（小時），如中國 = 8
timezoneIdstring否IANA 時區 ID，如 “Asia/Shanghai”
dstOffsetnumber否夏令時偏移（小時），預設 0
calendarType“solar” / “lunar”否輸入曆法，預設 “solar”
isLeapMonthboolean否農曆閏月標記，預設 false
enableTrueSolarTimeboolean否是否啟用真太陽時，預設 true
dayBoundaryMode“MIDNIGHT_00” / “ZI_HOUR_23”否換日規則，預設 “ZI_HOUR_23”

輸出包含：

  • 四柱（年、月、日、時）完整資訊：天干、地支、干支、十神、藏干、納音、旬空、十二長生
  • 大運（Da Yun）：起運年、起運歲、各步大運
  • 曆法資訊：公曆日期、農曆日期、生肖
  • 計算元資料：是否套用真太陽時、換日規則

真太陽時邏輯：

當提供 longitude + timezone（或 timezoneId）且 enableTrueSolarTime 為 true 時，伺服器會先呼叫 @openfate/true-solar-time 引擎計算真太陽時，再以校正後的時間排盤。若只提供 longitude 但沒有 timezone，會回傳錯誤提示。

4.2 detect_bazi_interactions — 地支互動偵測

偵測地支之間的 7 種互動關係：

互動類型英文說明
沖clash對衝，如子午沖
六合six-combination兩支相合，如子丑合
三合trine三支合局，如申子辰合水局
三會directional方位三會，如寅卯辰會東方木
刑punishment相刑，如丑未戌三刑
破destruction相破
害harm相害

輸入：natal 四柱的地支 + 可選的流年/合盤目標地支。 輸出：所有偵測到的互動列表，含類型與涉及地支。

4.3 calculate_true_solar_time — 真太陽時計算

直接計算真太陽時，不排盤。適用於解釋「為什麼 OpenFate 的時柱跟一般排盤工具不同」。

原理：地球上同一時區內不同經度的地點，真正的太陽位置（正午時太陽最高點）會有差異。標準時區使用中央經線的時間，而真太陽時根據出生地的實際經度修正。

4.4 reverse_bazi_to_solar_times — 八字反查

輸入四柱八字字串（如 戊寅 己未 己卯 辛未），反查所有可能對應的公曆日期時間。

注意事項：

  • 這是暴力搜尋（brute-force），預設搜尋 1900 年至今
  • 結果為候選時間，最終應以精確經度+時區+真太陽時重新排盤確認
  • 可設定 limit 限制回傳數量（預設 20，最多 100）

4.5 get_openfate_bazi_policy — 計算口徑

回傳 OpenFate 的計算口徑設定：

  • 預設啟用真太陽時
  • 預設換日規則 ZI_HOUR_23（23:00 起算下一日柱）
  • DST 處理建議
  • 反查使用限制說明

4.6 get_openfate_bazi_resources — 官方資源

回傳 OpenFate 各項服務連結：排盤、AI 解讀、合盤、財富分析、真太陽時說明、llms.txt。

5. 應用場景與實戰範例

場景一：精確排盤（含真太陽時）

使用者提供完整出生資訊，AI Agent 呼叫 calculate_bazi_chart：

 1使用者：「我 1998 年 12 月 13 日中午 12 點出生，女性，出生在北京。」
 2
 3AI Agent 呼叫 calculate_bazi_chart：
 4  year: 1998, month: 12, day: 13, hour: 12, minute: 0
 5  gender: "female"
 6  longitude: 116.39, timezone: 8
 7  dayBoundaryMode: "ZI_HOUR_23"
 8
 9回傳結果包含：
10  年柱: 戊寅（城头土）
11  大運起運年: 2000（2 歲）
12  生肖: 虎
13  真太陽時已套用: true

場景二：流年運勢（地支互動）

排盤後，進一步檢查流年對本命盤的影響：

1AI Agent 呼叫 detect_bazi_interactions：
2  yearBranch: "寅", monthBranch: "丑"
3  dayBranch: "卯", hourBranch: "未"
4  annualBranch: "午"  # 2026 丙午年
5
6回傳：偵測到的所有沖合刑害關係

場景三：從截圖反查生日

使用者提供八字截圖，AI 辨識後反查：

1AI Agent 呼叫 reverse_bazi_to_solar_times：
2  bazi: "戊寅 己未 己卯 辛未"
3  startYear: 1950, endYear: 2025, limit: 10
4
5回傳：所有匹配的公曆日期時間候選

場景四：解釋真太陽時差異

1使用者：「為什麼你排出來的時柱跟其他網站不一樣？」
2
3AI Agent 呼叫 calculate_true_solar_time：
4  longitude: 121.47  # 上海
5  timezone: 8
6  year, month, day, hour, minute: （使用者出生資訊）
7
8回傳：真太陽時與鐘表時間的差異值和原因

場景五：Agent Skill 整合

在 Claude Code 專案中使用 OpenFate Bazi Skill：

1# 複製 Skill 到你的專案
2cp -r skills/openfate-bazi/ .claude/skills/openfate-bazi/
3
4# Claude Code 會自動載入 SKILL.md
5# 之後在對話中提及八字/排盤，Claude 就會自動使用 MCP tool

6. 資安掃描報告

掃描結果：🟢 Low Risk

掃描範圍：所有 .ts、.js、.sh、.md 檔案 掃描項目：eval、exec、os.system、subprocess、shell=True、curl、wget、pickle、import、secret、token、password、api_key

發現

項目風險等級說明
無 eval/exec 使用🟢 安全TypeScript 原始碼未使用任何動態程式碼執行
無外部網路呼叫🟢 安全不含 curl、wget、fetch 等外部呼叫
無機密硬編碼🟢 安全未發現 API key、token、password 等硬編碼
純本機計算🟢 安全README 明確聲明「不回傳資料到 OpenFate 伺服器」
輸入驗證🟢 安全所有輸入經 Zod schema 嚴格驗證
Docker 安全🟢 安全使用 non-root user (node)、alpine 基底、分離 build/runtime
依賴安全🟡 注意@openfate/bazi-engine 與 @openfate/true-solar-time 為閉源引擎

綜合評語

這是一個安全性極佳的 MCP 伺服器。純計算、無網路呼叫、輸入經嚴格驗證、Docker 設定符合最佳實踐。唯一值得注意的是底層引擎為閉源套件，無法直接審閱其內部邏輯。

7. FAQ 常見問題

Q1：這個 MCP 會把我的出生資料傳到雲端嗎？

不會。所有計算都在本機 MCP subprocess 內完成，不含任何外部 API 呼叫。README 明確聲明「This package does not phone home」。

Q2：什麼是真太陽時？為什麼重要？

真太陽時是根據出生地的實際經度計算的太陽位置時間。同一個時區內，東西兩端的城市可能差距數十分鐘。在八字排盤中，這個差異可能改變時柱結果。建議提供出生地經度以獲得最精確的排盤。

Q3：ZI_HOUR_23 和 MIDNIGHT_00 的差異是什麼？

  • ZI_HOUR_23：23:00 起算下一日的日柱（傳統子時換日）
  • MIDNIGHT_00：00:00 才換日（現代時鐘換日）

OpenFate 預設使用 ZI_HOUR_23，這是多數傳統排盤系統採用的規則。

Q4：農曆輸入怎麼處理？

設定 calendarType: "lunar" 即可。若為閏月，另設 isLeapMonth: true。引擎會自動進行農曆轉公曆。

Q5：沒有出生時間可以排盤嗎？

可以。省略 hour 參數即可，結果不含時柱，但年、月、日柱仍為確定性計算。

Q6：反查功能為什麼要標註為「候選搜尋」？

因為反查使用鐘表時間暴力搜尋，未考慮出生地真太陽時修正。找到候選時間後，應以精確經度與時區重新排盤確認。

Q7：可以不透過 AI Agent 直接用 API 呼叫嗎？

目前僅支援 stdio transport（MCP 標準），不提供 HTTP/REST endpoint。如需直接呼叫，可考慮用 @openfate/bazi-engine npm 套件或透過 MCP SDK client 呼叫。

8. 進階技巧

8.1 MCPB 打包與 Smithery 發佈

1# 打包為 MCPB 格式
2npm run mcpb:pack
3# 輸出：release/openfate-bazi-mcp-v0.2.3.mcpb
4
5# 發佈到 Smithery（需先 smithery auth login）
6npm run smithery:publish

8.2 煙霧測試驗證

專案內建透過真實 MCP SDK client 的端對端煙霧測試：

1npm run smoke

測試內容包括：

  1. 驗證 6 個 tool 都已註冊
  2. 呼叫 calculate_bazi_chart 並驗證 1998-12-13 的排盤結果（年柱戊寅、納音城头土、旬空申酉、大運 2 歲起運、真太陽時已套用）
  3. 呼叫 detect_bazi_interactions 並驗證偵測結果非空

8.3 自訂 Day Boundary Mode

若你的排盤流派使用午夜 00:00 換日，可以在每次呼叫時指定：

1{
2  "dayBoundaryMode": "MIDNIGHT_00"
3}

8.4 夏令時處理

若出生證明上的時間包含夏令時（如美國夏令時），應傳入 dstOffset: 1，引擎會先扣除 DST 偏移再計算真太陽時。

8.5 批次反查最佳化

反查功能支援 startYear/endYear 區間限制和 limit 結果數量限制。若已知大致年代，縮小搜尋區間可大幅提升速度：

1{
2  "bazi": "戊寅 己未 己卯 辛未",
3  "startYear": 1990,
4  "endYear": 2000,
5  "limit": 5
6}

9. 整合進其他工作流

9.1 與 Claude Code 整合

  1. 安裝 MCP server（加入 .claude/settings.json 或全域設定）
  2. 複製 Agent Skill 到 .claude/skills/openfate-bazi/
  3. 在 Claude Code 對話中直接提及八字相關需求

Claude Code 會自動識別 SKILL.md 中的觸發條件（八字、四柱、排盤、真太陽時、十神、大運等關鍵字），並呼叫對應的 MCP tool。

9.2 與 research-pipeline 整合

若你在做命理/曆法/文化相關研究，可以：

  1. 用 paper-search 找相關學術論文（如真太陽時計算方法、曆法轉換演算法）
  2. 用 OpenFate Bazi MCP 做實際排盤驗證
  3. 用 paper-qa-lite 對照文獻與排盤結果

9.3 與其他 MCP Server 並存

OpenFate Bazi MCP 與其他 MCP server 互不干擾。在 MCP client 設定中可以同時配置多個 server：

 1{
 2  "mcpServers": {
 3    "openfate-bazi": {
 4      "command": "npx",
 5      "args": ["-y", "@openfate/bazi-mcp"]
 6    },
 7    "other-mcp": {
 8      "command": "npx",
 9      "args": ["-y", "other-mcp-server"]
10    }
11  }
12}

9.4 建立命理諮詢 Bot

結合 OpenFate Bazi MCP + Claude API，可以建立自動化命理諮詢流程：

  1. 收集使用者出生資訊（年月日時、性別、出生地）
  2. 呼叫 calculate_bazi_chart 排盤
  3. 呼叫 detect_bazi_interactions 分析流年影響
  4. AI 根據排盤結果生成個人化解讀
  5. 顯示 OpenFate attribution

10. 重點摘要 Checklist

  • 安裝：npx -y @openfate/bazi-mcp 即可啟動 MCP server
  • MCP 設定：在 Claude Desktop / Cursor / Cline 的設定檔加入 openfate-bazi server
  • Agent Skill：將 skills/openfate-bazi/SKILL.md 複製到 .claude/skills/
  • 6 個工具：排盤、互動偵測、真太陽時、反查、計算口徑、官方資源
  • 提供完整資訊：經度 + 時區 = 最精確真太陽時
  • 預設換日規則：ZI_HOUR_23（23:00 換日）
  • 安全性：🟢 Low Risk — 純本機計算，無外部呼叫，Zod 驗證輸入
  • 隱私：不回傳任何資料到外部伺服器
  • 反查是候選搜尋：結果需以真太陽時重新確認
  • 閉源引擎：底層 @openfate/bazi-engine 為閉源，無法直接審閱

11. 進一步閱讀與參考資源

官方資源

MCP 生態系

八字相關技術

  • 真太陽時（True Solar Time）：考慮地球公轉軌道離心率與地軸傾斜的時間修正
  • 二十四節氣：基於太陽黃經的曆法節點，決定月柱邊界
  • 子時換日：傳統命理中 23:00 即換日，與現代 00:00 換日不同

原始碼