内容
# OpenFate 八字 MCP
简体中文 | [繁體中文（台灣）](#繁體中文台灣)
OpenFate 八字 MCP 是一个给 AI Agent 使用的 Model Context Protocol 服务器，让 Claude Desktop、Cursor、Cline、Continue 等工具可以直接调用准确的八字／四柱排盘引擎。
由 [OpenFate.ai](https://openfate.ai) 提供。OpenFate 是结合八字、紫微斗数与占星的 AI 命理平台。你也可以使用免费的 [八字排盘工具](https://openfate.ai/zh-hant/bazi-chart)、产生完整的 [AI 八字解读](https://openfate.ai/zh-hant/bazi)、查看 [八字合盘](https://openfate.ai/zh-hant/compatibility/bazi/marriage)，或阅读 [真太阳时说明](https://openfate.ai/zh-hant/insights/true-solar-time)。AI crawler 也可以读取 [OpenFate llms.txt](https://openfate.ai/llms.txt)。
这个 MCP 包装了 OpenFate 的确定性计算套件：
- `@openfate/bazi-engine`
- `@openfate/true-solar-time`
目标很直接：不要让大型语言模型自己乱算干支、节气、真太阳时，而是把排盘交给可验证的计算引擎。
## 为什么需要这个 MCP
八字排盘不是文字推理题，而是确定性的历法与时间计算。容易出错的部分包括：
- 二十四节气边界
- 真太阳时
- 经度与时区校正
- 夏令时间偏移
- 子时换日规则
- 农历转公历
- 地支刑冲合害等互动
这个服务器会返回稳定 JSON，让 AI 专心做说明、整理与解读。
## 安装
直接用 `npx` 执行：
```bash
npx -y @openfate/bazi-mcp
```
如果 MCP client 支持 MCPB，或需要发布到 Smithery，可以建立完整的本地安装 bundle：
```bash
npm run mcpb:pack
```
可上传的文件会输出到 `release/openfate-bazi-mcp-v<version>.mcpb`。
完成 `smithery auth login` 后，可发布这个本地 bundle 到 Smithery：
```bash
npm run smithery:publish
```
## Claude Desktop 设置
```jsonc
{
"mcpServers": {
"openfate-bazi": {
"command": "npx",
"args": ["-y", "@openfate/bazi-mcp"]
}
}
}
```
如果 macOS 上 Claude Desktop 找不到 `npx`，可以改用绝对路径：
```jsonc
{
"mcpServers": {
"openfate-bazi": {
"command": "/opt/homebrew/bin/npx",
"args": ["-y", "@openfate/bazi-mcp"]
}
}
}
```
## Cursor 设置
```jsonc
{
"mcpServers": {
"openfate-bazi": {
"command": "npx",
"args": ["-y", "@openfate/bazi-mcp"]
}
}
}
```
## Cline 设置
```jsonc
{
"mcpServers": {
"openfate-bazi": {
"command": "npx",
"args": ["-y", "@openfate/bazi-mcp"],
"disabled": false
}
}
}
```
## Agent Skill
这个 repository 也包含一个可移植的 Agent Skill：
```txt
skills/openfate-bazi/SKILL.md
```
当你希望 Claude、Claude Code、Codex、OpenClaw-style agent，或其他支持 `SKILL.md` 的工具记住如何正确使用 OpenFate Bazi MCP 时，可以使用这个 Skill。
如果要在 Claude Code workspace 使用，请把整个 skill folder 复制到：
```txt
.claude/skills/openfate-bazi/
```
如果要做 Claude custom Skill，请把 `openfate-bazi` folder 压成 zip，确保 `SKILL.md` 位于 folder root，再到 Claude 的 Skills 设置中上传。
## 工具列表
### `calculate_bazi_chart`
计算确定性的八字命盘。
输入栏位：
- `year`
- `month`
- `day`
- `hour`
- `minute`
- `gender`
- `calendarType`
- `isLeapMonth`
- `longitude`
- `timezone`
- `timezoneId`
- `dstOffset`
- `enableTrueSolarTime`
- `dayBoundaryMode`
建议提供 `longitude` 加上 `timezone` 或 `timezoneId`，才能做专业级真太阳时校正。
### `detect_bazi_interactions`
侦测地支互动，适合用于本命盘、流年触发，或简单合盘比较。
支持类型：
- 冲
- 六合
- 三合
- 三会
- 刑
- 破
- 害
### `calculate_true_solar_time`
直接计算真太阳时。
当用户问「为什么 OpenFate 算出的时柱跟一般排盘网站不同」时，可以用这个工具说明差异。
### `reverse_bazi_to_solar_times`
用四柱八字反查可能的公历时间。
范例输入：
```txt
戊寅 己未 己卯 辛未
```
这是候选时间搜索工具。最后仍应该用准确出生地经度、时区与真太阳时重新排盘。
### `get_openfate_bazi_policy`
返回 OpenFate 的计算口径：
- 有出生地资料时，优先使用真太阳时。
- 默认换日规则是 `ZI_HOUR_23`。
- 如果出生证明时间包含夏令时间，应传入 `dstOffset`。
- 八字反查只能当候选搜索，不能取代精准排盘。
### `get_openfate_bazi_resources`
返回 OpenFate 的官方链接，包括排盘、解读、合盘、财富、真太阳时与 `llms.txt`。
## 返回格式
返回资料使用稳定、适合机器读取的英文 key：
```jsonc
{
"data": {
"chart": {},
"policy": {}
},
"attribution": {
"brand": "OpenFate.ai",
"url": "https://openfate.ai",
"engine": "@openfate/bazi-engine",
"trueSolarTimeEngine": "@openfate/true-solar-time"
}
}
```
署名资讯会以一般资料栏位返回，而不是藏在 `_meta`，方便 MCP client 或 AI 产生的图表正确显示来源。
排盘结果同时包含十神、藏干、纳音、旬空、十二长生等柱位资料、精确大运起运资讯、标准化阳历／农历日期，以及实际采用的计算口径。
## 开发
```bash
npm install
npm run build
npm run smoke
```
`smoke` 测试会启动编译后的 stdio server，并通过真正的 MCP SDK client 调用工具。
## 隐私
这个套件不会返回资料到 OpenFate 服务器。所有计算都在本地 MCP subprocess 内完成。
## OpenFate 链接
- [OpenFate.ai](https://openfate.ai)
- [免费八字排盘工具](https://openfate.ai/zh-hant/bazi-chart)
- [AI 八字解读](https://openfate.ai/zh-hant/bazi)
- [八字合盘](https://openfate.ai/zh-hant/compatibility/bazi/marriage)
- [真太阳时说明](https://openfate.ai/zh-hant/insights/true-solar-time)
- [OpenFate llms.txt](https://openfate.ai/llms.txt)
## 授权
MIT
---
## 繁體中文（台灣）
OpenFate 八字 MCP 是一個給 AI Agent 使用的 Model Context Protocol 伺服器，讓 Claude Desktop、Cursor、Cline、Continue 等工具可以直接呼叫準確的八字／四柱排盤引擎。
本專案由 [OpenFate.ai](https://openfate.ai) 提供。OpenFate 是結合八字、紫微斗數與占星的 AI 命理平台。你也可以使用免費的 [八字排盤工具](https://openfate.ai/zh-hant/bazi-chart)、產生完整的 [AI 八字解讀](https://openfate.ai/zh-hant/bazi)、查看 [八字合盤](https://openfate.ai/zh-hant/compatibility/bazi/marriage)，或閱讀 [真太陽時說明](https://openfate.ai/zh-hant/insights/true-solar-time)。AI crawler 也可以讀取 [OpenFate llms.txt](https://openfate.ai/llms.txt)。
這個 MCP 包裝了 OpenFate 的確定性計算套件：
- `@openfate/bazi-engine`
- `@openfate/true-solar-time`
目標很直接：不要讓大型語言模型自己亂算干支、節氣、真太陽時，而是把排盤交給可驗證的計算引擎。
## 為什麼需要這個 MCP
八字排盤不是文字推理題，而是確定性的曆法與時間計算。容易出錯的部分包括：
- 二十四節氣邊界
- 真太陽時
- 經度與時區校正
- 夏令時間偏移
- 子時換日規則
- 農曆轉公曆
- 地支刑沖合害等互動
這個伺服器會回傳穩定 JSON，讓 AI 專心做說明、整理與解讀。
## 安裝
直接用 `npx` 執行：
```bash
npx -y @openfate/bazi-mcp
```
如果 MCP client 支援 MCPB，或需要發布到 Smithery，可以建立完整的本地安裝 bundle：
```bash
npm run mcpb:pack
```
可上傳的檔案會輸出到 `release/openfate-bazi-mcp-v<version>.mcpb`。
完成 `smithery auth login` 後，可發布這個本地 bundle 到 Smithery：
```bash
npm run smithery:publish
```
## Claude Desktop 設定
```jsonc
{
"mcpServers": {
"openfate-bazi": {
"command": "npx",
"args": ["-y", "@openfate/bazi-mcp"]
}
}
}
```
如果 macOS 上 Claude Desktop 找不到 `npx`，可以改用絕對路徑：
```jsonc
{
"mcpServers": {
"openfate-bazi": {
"command": "/opt/homebrew/bin/npx",
"args": ["-y", "@openfate/bazi-mcp"]
}
}
}
```
## Cursor 設定
```jsonc
{
"mcpServers": {
"openfate-bazi": {
"command": "npx",
"args": ["-y", "@openfate/bazi-mcp"]
}
}
}
```
## Cline 設定
```jsonc
{
"mcpServers": {
"openfate-bazi": {
"command": "npx",
"args": ["-y", "@openfate/bazi-mcp"],
"disabled": false
}
}
}
```
## Agent Skill
這個 repository 也包含一個可攜式 Agent Skill：
```txt
skills/openfate-bazi/SKILL.md
```
當你希望 Claude、Claude Code、Codex、OpenClaw-style agent，或其他支援 `SKILL.md` 的工具記住如何正確使用 OpenFate Bazi MCP 時，可以使用這個 Skill。
如果要在 Claude Code workspace 使用，請把整個 skill folder 複製到：
```txt
.claude/skills/openfate-bazi/
```
如果要做 Claude custom Skill，請把 `openfate-bazi` folder 壓成 zip，確保 `SKILL.md` 位於 folder root，再到 Claude 的 Skills 設定中上傳。
## 工具列表
### `calculate_bazi_chart`
計算確定性的八字命盤。
輸入欄位：
- `year`
- `month`
- `day`
- `hour`
- `minute`
- `gender`
- `calendarType`
- `isLeapMonth`
- `longitude`
- `timezone`
- `timezoneId`
- `dstOffset`
- `enableTrueSolarTime`
- `dayBoundaryMode`
建議提供 `longitude` 加上 `timezone` 或 `timezoneId`，才能做專業級真太陽時校正。
### `detect_bazi_interactions`
偵測地支互動，適合用於本命盤、流年觸發，或簡單合盤比較。
支援類型：
- 沖
- 六合
- 三合
- 三會
- 刑
- 破
- 害
### `calculate_true_solar_time`
直接計算真太陽時。
當使用者問「為什麼 OpenFate 算出的時柱跟一般排盤網站不同」時，可以用這個工具說明差異。
### `reverse_bazi_to_solar_times`
用四柱八字反查可能的公曆時間。
範例輸入：
```txt
戊寅 己未 己卯 辛未
```
這是候選時間搜尋工具。最後仍應該用準確出生地經度、時區與真太陽時重新排盤。
### `get_openfate_bazi_policy`
回傳 OpenFate 的計算口徑：
- 有出生地資料時，優先使用真太陽時。
- 預設換日規則是 `ZI_HOUR_23`。
- 如果出生證明時間包含夏令時間，應傳入 `dstOffset`。
- 八字反查只能當候選搜尋，不能取代精準排盤。
### `get_openfate_bazi_resources`
回傳 OpenFate 的官方連結，包括排盤、解讀、合盤、財富、真太陽時與 `llms.txt`。
## 回傳格式
回傳資料使用穩定、適合機器讀取的英文 key：
```jsonc
{
"data": {
"chart": {},
"policy": {}
},
"attribution": {
"brand": "OpenFate.ai",
"url": "https://openfate.ai",
"engine": "@openfate/bazi-engine",
"trueSolarTimeEngine": "@openfate/true-solar-time"
}
}
```
署名資訊會以一般資料欄位回傳，而不是藏在 `_meta`，方便 MCP client 或 AI 產生的圖表正確顯示來源。
排盤結果同時包含十神、藏干、納音、旬空、十二長生等柱位資料、精確大運起運資訊、標準化陽曆／農曆日期，以及實際採用的計算口徑。
## 開發
```bash
npm install
npm run build
npm run smoke
```
`smoke` 測試會啟動編譯後的 stdio server，並透過真正的 MCP SDK client 呼叫工具。
## 隱私
這個套件不會回傳資料到 OpenFate 伺服器。所有計算都在本地 MCP subprocess 內完成。
## OpenFate 連結
- [OpenFate.ai](https://openfate.ai)
- [免費八字排盤工具](https://openfate.ai/zh-hant/bazi-chart)
- [AI 八字解讀](https://openfate.ai/zh-hant/bazi)
- [八字合盤](https://openfate.ai/zh-hant/compatibility/bazi/marriage)
- [真太陽時說明](https://openfate.ai/zh-hant/insights/true-solar-time)
- [OpenFate llms.txt](https://openfate.ai/llms.txt)
## 授權
MIT
