OpenFate Bazi MCP

@openfate/bazi-mcp

English | 繁體中文（台灣）

OpenFate Bazi MCP es un servidor de Model Context Protocol para el cálculo preciso de Bazi / Cuatro Pilares dentro de agentes de IA como Claude Desktop, Cursor, Cline y Continue.

Desarrollado por OpenFate.ai, una plataforma de Bazi, Ziwei y astrología nativa de IA. También puedes probar la Calculadora de Carta Bazi gratuita, generar una Lectura de Bazi con IA, comparar relaciones con Compatibilidad Bazi o leer la guía de Tiempo Solar Verdadero. Los rastreadores de IA pueden leer OpenFate llms.txt.

Este MCP envuelve los paquetes de cálculo deterministas de OpenFate:

• @openfate/bazi-engine
• @openfate/true-solar-time

El propósito es simple: permitir que el modelo de lenguaje llame a un motor de cálculo confiable en lugar de alucinar cálculos calendáricos.

Por Qué Existe Esto

Los LLM no deberían calcular manualmente cartas Bazi. Las partes difíciles son deterministas:

• Límites de los 24 términos solares
• Tiempo Solar Verdadero
• Corrección de longitud y zona horaria
• Desfases de horario de verano
• Reglas de límite de día de la hora Zi
• Conversión lunar a solar
• Interacciones de ramas

Este servidor le da al agente de IA un JSON estable, y luego deja que el modelo se enfoque en la explicación e interpretación.

Instalación

Ejecútalo con npx:

npx -y @openfate/bazi-mcp

Para clientes compatibles con MCPB y Smithery, compila el paquete local autocontenido:

npm run mcpb:pack

El artefacto listo para cargar se escribe en release/openfate-bazi-mcp-v<version>.mcpb.

Para publicar ese paquete local en Smithery después de smithery auth login:

npm run smithery:publish

Claude Desktop

{
  "mcpServers": {
    "openfate-bazi": {
      "command": "npx",
      "args": ["-y", "@openfate/bazi-mcp"]
    }
  }
}

Si Claude Desktop no puede encontrar npx en macOS, usa la ruta absoluta:

{
  "mcpServers": {
    "openfate-bazi": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@openfate/bazi-mcp"]
    }
  }
}

Cursor

{
  "mcpServers": {
    "openfate-bazi": {
      "command": "npx",
      "args": ["-y", "@openfate/bazi-mcp"]
    }
  }
}

Cline

{
  "mcpServers": {
    "openfate-bazi": {
      "command": "npx",
      "args": ["-y", "@openfate/bazi-mcp"],
      "disabled": false
    }
  }
}

Agent Skill

Este repositorio también incluye un Agent Skill portátil:

skills/openfate-bazi/SKILL.md

Úsalo cuando quieras que Claude, Claude Code, Codex, agentes estilo OpenClaw u otras herramientas compatibles con SKILL.md recuerden cómo usar OpenFate Bazi MCP correctamente.

Para uso en el espacio de trabajo de Claude Code, copia la carpeta de la skill a:

.claude/skills/openfate-bazi/

Para Skills personalizadas de Claude, comprime la carpeta openfate-bazi con SKILL.md en la raíz de la carpeta y súbela en la configuración de Skills de Claude.

Herramientas

calculate_bazi_chart

Calcula una carta Bazi determinista.

Entradas:

• year
• month
• day
• hour
• minute
• second
• gender
• calendarType
• isLeapMonth
• longitude
• timezone
• timezoneId
• dstOffset
• enableTrueSolarTime
• dayBoundaryMode

El MCP fija la política de inicio a DAYUN_SECOND_V2; los llamadores no pueden seleccionar silenciosamente una regla diferente. Pasa una hora de nacimiento exacta más timezone o timezoneId para un recibo calculado. Presenta un inicio exacto solo cuando chart.daYun.timing.status sea CALCULATED y su versión sea DAYUN_SECOND_V2. Un recibo UNAVAILABLE identifica la razón y marca los campos escalares heredados retenidos como respaldo. Pasa longitude también para la corrección de Tiempo Solar Verdadero.

detect_bazi_interactions

Detecta ocurrencias de relaciones de Ramas Terrestres en bruto para una carta natal, con ramas anuales y de Da Yun opcionales.

Las entradas son yearBranch, monthBranch, dayBranch, hourBranch opcional, annualBranch opcional y dayunBranch opcional. Omite hourBranch cuando se desconoce la hora de nacimiento; no se reemplaza con una rama asumida. Las llamadas existentes solo anuales siguen siendo compatibles.

Tipos de interacción compatibles:

• choque
• seis-combinación
• semi-trine de rama central (COMBINATION_HALF)
• trine
• direccional
• castigo
• destrucción
• daño

Se conserva cada ocurrencia de pilar coincidente. Por ejemplo, { yearBranch: '申', monthBranch: '寅', dayBranch: '申', hourBranch: '申' } devuelve tres choques 寅申 distintos, no uno. Las ramas anuales y de Da Yun mantienen roles separados de annual y dayun incluso cuando sus valores de rama coinciden con posiciones natales.

El perfil de semi-trine cubre 申子、子辰、寅午、午戌、亥卯、卯未、巳酉、酉丑: cada par incluye una rama central (子午卯酉). Los pares solo de extremos como 申辰 no son de este tipo de semi-trine. Los semi-trines permanecen en la salida en bruto cuando también está presente el trine completo de tres ramas.

Cada ocurrencia tiene un id estable y arreglos alineados de branches / pillars. targetElement significa afinidad de relación, no energía transformada. El transformationStatus de combinación es NOT_EVALUATED: la presencia solo de ramas no establece transformación ni su fracaso. Otros tipos de relación usan NOT_APPLICABLE. Estos resultados no son pesos puntuados y no cancelan automáticamente choques; el asentamiento y la interpretación pertenecen a una capa de análisis separada.

Para compatibilidad de API, las ocurrencias completas de TRINE y DIRECTIONAL también retienen el resultElement heredado, igual a targetElement y con el mismo significado de solo afinidad. Las seis-combinaciones y semi-trines no emiten resultElement.

calculate_true_solar_time

Calcula el Tiempo Solar Verdadero directamente.

Úsalo cuando un usuario pregunte por qué el pilar de hora de OpenFate difiere de una herramienta de hora de reloj.

reverse_bazi_to_solar_times

Encuentra posibles fechas y horas gregorianas para una cadena de cuatro pilares Bazi.

Ejemplo de entrada:

戊寅 己未 己卯 辛未

Este es un buscador de candidatos. Para precisión final, recalcula el resultado con longitud exacta, zona horaria y Tiempo Solar Verdadero.

get_openfate_bazi_policy

Devuelve la política de cálculo de OpenFate:

• Se prefiere el Tiempo Solar Verdadero cuando hay datos de ubicación disponibles.
• El modo de límite de día predeterminado es ZI_HOUR_23.
• El horario de verano debe pasarse como dstOffset cuando la hora del certificado de nacimiento incluye horario de verano.
• El inicio de Da Yun usa DAYUN_SECOND_V2; las fechas exactas requieren un recibo de sincronización calculado.
• La búsqueda inversa debe tratarse como una búsqueda de candidatos.
• Las interacciones de ramas preservan ocurrencias de pilares en bruto, no resultados ponderados o transformados automáticamente.

get_openfate_bazi_resources

Devuelve enlaces canónicos de OpenFate para cartas, lecturas, compatibilidad, riqueza, tiempo solar verdadero y llms.txt.

Forma de Salida

Las respuestas usan claves en inglés amigables para máquinas:

{
  "data": {
    "chart": {},
    "policy": {}
  },
  "attribution": {
    "brand": "OpenFate.ai",
    "url": "https://openfate.ai",
    "engine": "@openfate/bazi-engine",
    "trueSolarTimeEngine": "@openfate/true-solar-time"
  }
}

La atribución se devuelve como datos de primera clase, no oculta en _meta, para que los clientes MCP y los artefactos generados puedan mostrarla de manera confiable.

Los resultados de la carta incluyen hechos enriquecidos de pilares (Diez Dioses, tallos ocultos, Na Yin, Xun, ramas vacías y etapas de crecimiento), un recibo de sincronización de Da Yun versionado, datos normalizados de calendario solar/lunar y la política de cálculo realmente aplicada.

Desarrollo

npm install
npm run build
npm run smoke

La prueba de humo inicia el servidor stdio compilado y lo maneja a través del cliente real del SDK de MCP.

Para probar cambios de fuente sin compilar dist, ejecuta npm run smoke:source. Esto requiere el checkout de fuente hermano ../bazi-engine con sus dependencias instaladas, así como las dependencias de este paquete. El tests/tsconfig.source.json solo de prueba mapea @openfate/bazi-engine al src/index.ts de ese hermano; el ejecutor de humo pasa esta configuración al servidor iniciado por SDK y verifica la ruta de fuente resuelta antes de probar. No depende de un motor instalado parcheado y sigue siendo reproducible después de npm ci --ignore-scripts en este paquete.

Ambos modos de humo ejercitan el mismo transporte MCP y los mismos fixtures de regresión, incluidos el inicio de Da Yun resuelto a segundos, entradas de sincronización faltantes, ramas repetidas, ocho semi-trines, hora desconocida y roles anuales/Da Yun. El comando ordinario smoke aún prueba la salida MCP compilada contra su dependencia de motor publicada instalada. npx tsc --noEmit -p tests/tsconfig.source.json verifica el contrato de fuente coordinado sin emitir archivos de compilación.

Compatibilidad del motor

La versión 0.3 requiere la versión 2 de @openfate/bazi-engine. Sus contratos de DAYUN_SECOND_V2, ocurrencia en bruto y dayunBranch se verifican tanto en el modo de humo de paquete compilado como en el de fuente coordinada. La dependencia publicada sigue siendo la fuente de verdad de la versión; este paquete no usa una dependencia local de file:.

Privacidad

Este paquete no se comunica con el exterior. Los cálculos se ejecutan localmente en el subproceso MCP.

Enlaces de OpenFate

• OpenFate.ai
• Calculadora de Carta Bazi Gratuita
• Lectura de Bazi con IA
• Compatibilidad Bazi
• Guía de Tiempo Solar Verdadero
• OpenFate llms.txt

Licencia

MIT

---

繁體中文（台灣）

OpenFate Bazi MCP 是一個給 AI Agent 使用的 Model Context Protocol 伺服器，讓 Claude Desktop、Cursor、Cline、Continue 等工具可以直接呼叫準確的八字／四柱排盤引擎。

本專案由 OpenFate.ai 提供。OpenFate 是結合八字、紫微斗數與占星的 AI 命理平台。你也可以使用免費的 八字排盤工具、產生完整的 AI 八字解讀、查看 八字合盤，或閱讀 真太陽時說明。AI crawler 也可以讀取 OpenFate llms.txt。

這個 MCP 包裝了 OpenFate 的確定性計算套件：

• @openfate/bazi-engine
• @openfate/true-solar-time

目標很直接：不要讓大型語言模型自己亂算干支、節氣、真太陽時，而是把排盤交給可驗證的計算引擎。

為什麼需要這個 MCP

八字排盤不是文字推理題，而是確定性的曆法與時間計算。容易出錯的部分包括：

• 二十四節氣邊界
• 真太陽時
• 經度與時區校正
• 夏令時間偏移
• 子時換日規則
• 農曆轉公曆
• 地支刑沖合害等互動

這個伺服器會回傳穩定 JSON，讓 AI 專心做說明、整理與解讀。

安裝

直接用 npx 執行：

npx -y @openfate/bazi-mcp

如果 MCP client 支援 MCPB，或需要發布到 Smithery，可以建立完整的本機安裝 bundle：

npm run mcpb:pack

可上傳的檔案會輸出到 release/openfate-bazi-mcp-v<version>.mcpb。

完成 smithery auth login 後，可發布這個本機 bundle 到 Smithery：

npm run smithery:publish

Claude Desktop 設定

{
  "mcpServers": {
    "openfate-bazi": {
      "command": "npx",
      "args": ["-y", "@openfate/bazi-mcp"]
    }
  }
}

如果 macOS 上 Claude Desktop 找不到 npx，可以改用絕對路徑：

{
  "mcpServers": {
    "openfate-bazi": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@openfate/bazi-mcp"]
    }
  }
}

Cursor 設定

{
  "mcpServers": {
    "openfate-bazi": {
      "command": "npx",
      "args": ["-y", "@openfate/bazi-mcp"]
    }
  }
}

Cline 設定

{
  "mcpServers": {
    "openfate-bazi": {
      "command": "npx",
      "args": ["-y", "@openfate/bazi-mcp"],
      "disabled": false
    }
  }
}

Agent Skill

這個 repository 也包含一個可攜式 Agent Skill：

skills/openfate-bazi/SKILL.md

當你希望 Claude、Claude Code、Codex、OpenClaw-style agent，或其他支援 SKILL.md 的工具記住如何正確使用 OpenFate Bazi MCP 時，可以使用這個 Skill。

如果要在 Claude Code workspace 使用，請把整個 skill folder 複製到：

.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
• second
• gender
• calendarType
• isLeapMonth
• longitude
• timezone
• timezoneId
• dstOffset
• enableTrueSolarTime
• dayBoundaryMode

MCP 固定使用 DAYUN_SECOND_V2，呼叫端不能暗中切換起運規則。精確出生時間還要搭配 timezone 或 timezoneId，並且只有 chart.daYun.timing.status 為 CALCULATED、版本為 DAYUN_SECOND_V2 時才能呈現精確起運時間。UNAVAILABLE 會說明原因，原有起運欄位只作 明確標記的舊版 fallback。若要校正真太陽時，還應提供 longitude。

detect_bazi_interactions

偵測本命盤及選填流年、大運地支的原始關係。

輸入欄位為 yearBranch、monthBranch、dayBranch，以及選填的 hourBranch、annualBranch、dayunBranch。出生時辰未知時省略 hourBranch，不會補入假設時柱。原有只傳流年的呼叫方式仍可使用。

支援類型：

• 沖
• 六合
• 含旺支的半合（COMBINATION_HALF）
• 三合
• 三會
• 刑
• 破
• 害

同一地支出現在不同柱位時，每個關係都會保留。例如申、寅、申、申會回傳三組不同柱位的寅申沖。流年與大運分別使用 annual、dayun 角色，即使地支相同，也不會與本命柱位合併。

半合口徑涵蓋申子、子辰、寅午、午戌、亥卯、卯未、巳酉、酉丑八組，每組都含子午卯酉其中一個旺支。申辰等兩端支不屬於此半合類型。三合齊全時，原始資料仍保留其中的半合關係。

每個關係包含穩定的 id，以及逐項對應的 branches、pillars。targetElement 只表示關係指向的五行，不代表已經合化。合類的 transformationStatus 為 NOT_EVALUATED，表示尚未評估合化，並非已成化或已判定不能化；其他關係使用 NOT_APPLICABLE。這些資料不是可直接累加的評分，也不會自動解沖；成立程度與解讀須由獨立分析層處理。

為相容既有 API，完整 TRINE、DIRECTIONAL 關係仍保留舊欄位 resultElement，值與 targetElement 相同，也僅表示五行指向。六合與半合不回傳 resultElement。

calculate_true_solar_time

直接計算真太陽時。

當使用者問「為什麼 OpenFate 算出的時柱跟一般排盤網站不同」時，可以用這個工具說明差異。

reverse_bazi_to_solar_times

用四柱八字反查可能的公曆時間。

範例輸入：

戊寅 己未 己卯 辛未

這是候選時間搜尋工具。最後仍應該用準確出生地經度、時區與真太陽時重新排盤。

get_openfate_bazi_policy

回傳 OpenFate 的計算口徑：

• 有出生地資料時，優先使用真太陽時。
• 預設換日規則是 ZI_HOUR_23。
• 如果出生證明時間包含夏令時間，應傳入 dstOffset。
• 大運起運固定採用 DAYUN_SECOND_V2；只有計算成功的 timing receipt 才是精確起運時間。
• 八字反查只能當候選搜尋，不能取代精準排盤。
• 地支互動保留原始柱位關係，不代表加權分數或自動合化結果。

get_openfate_bazi_resources

回傳 OpenFate 的官方連結，包括排盤、解讀、合盤、財富、真太陽時與 llms.txt。

回傳格式

回傳資料使用穩定、適合機器讀取的英文 key：

{
  "data": {
    "chart": {},
    "policy": {}
  },
  "attribution": {
    "brand": "OpenFate.ai",
    "url": "https://openfate.ai",
    "engine": "@openfate/bazi-engine",
    "trueSolarTimeEngine": "@openfate/true-solar-time"
  }
}

署名資訊會以一般資料欄位回傳，而不是藏在 _meta，方便 MCP client 或 AI 產生的圖表正確顯示來源。

排盤結果同時包含十神、藏干、納音、旬空、十二長生等柱位資料、版本化大運起運 receipt、標準化陽曆／農曆日期，以及實際採用的計算口徑。

開發

npm install
npm run build
npm run smoke

smoke 測試會啟動編譯後的 stdio server，並透過真正的 MCP SDK client 呼叫工具。

不編譯 dist 時可執行 npm run smoke:source 驗證原始碼。須具備相鄰的 ../bazi-engine 原始碼工作目錄，且引擎與本套件都已安裝依賴。測試專用的 tests/tsconfig.source.json 將 @openfate/bazi-engine 指向該引擎的 src/index.ts；測試執行器會把設定傳給 MCP SDK 啟動的伺服器，並先驗證實際解析的原始碼路徑。這個模式不依賴修改過的已安裝引擎，在本套件重新執行 npm ci --ignore-scripts 後仍可重現。

兩種 smoke 模式使用相同 MCP 傳輸與回歸案例，涵蓋秒級起運、缺少起運輸入、重複地支、八組半合、未知時辰，以及流年／大運角色。一般 smoke 仍驗證編譯後 MCP 與已安裝的 npm 公開引擎。npx tsc --noEmit -p tests/tsconfig.source.json 可檢查協調中的原始碼契約，不產生編譯檔案。

引擎相容性

0.3 版需要 @openfate/bazi-engine 2.x。DAYUN_SECOND_V2、完整柱位關係與 dayunBranch 契約皆由已編譯套件及協調原始碼兩種 smoke 模式驗證。正式發布的 npm 依賴仍是版本來源；本套件不使用本機 file: 依賴。

隱私

這個套件不會回傳資料到 OpenFate 伺服器。所有計算都在本機 MCP subprocess 內完成。

OpenFate 連結

• OpenFate.ai
• 免費八字排盤工具
• AI 八字解讀
• 八字合盤
• 真太陽時說明
• OpenFate llms.txt

授權

MIT