OpenFate Bazi MCP

Servidor MCP de Bazi / Quatro Pilares determinístico com Horário Solar Verdadeiro, ciclos de sorte Da Yun, conversão lunar/solar, interações de ramos e metadados de cálculo OpenFate.

GitHub
157
Experimente este MCPPatrocinado

Documentação

@openfate/bazi-mcp

Inglês | 繁體中文（台灣）

OpenFate Bazi MCP é um servidor Model Context Protocol para cálculo preciso de Bazi / Quatro Pilares dentro de agentes de IA como Claude Desktop, Cursor, Cline e Continue.

Desenvolvido pela OpenFate.ai, uma plataforma de Bazi, Ziwei e astrologia nativa de IA. Você também pode experimentar a Calculadora de Mapa Bazi gratuita, gerar uma Leitura de Bazi com IA, comparar relacionamentos com Compatibilidade Bazi ou ler o guia de Tempo Solar Verdadeiro. Crawlers de IA podem ler o OpenFate llms.txt.

Este MCP encapsula os pacotes de cálculo determinísticos da OpenFate:

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

O objetivo é simples: permitir que o modelo de linguagem chame um mecanismo de cálculo confiável em vez de alucinar cálculos calendáricos.

Por Que Isso Existe

LLMs não devem calcular mapas Bazi manualmente. As partes difíceis são determinísticas:

  • Limites dos 24 termos solares
  • Tempo Solar Verdadeiro
  • Correção de longitude e fuso horário
  • Deslocamentos de horário de verão
  • Regras de mudança de dia na hora Zi
  • Conversão lunar para solar
  • Interações entre ramos

Este servidor fornece ao agente de IA um JSON estável e permite que o modelo se concentre na explicação e interpretação.

Instalação

Execute com npx:

npx -y @openfate/bazi-mcp

Para clientes compatíveis com MCPB e Smithery, crie o bundle local autocontido:

npm run mcpb:pack

O artefato pronto para upload é gravado em release/openfate-bazi-mcp-v<version>.mcpb.

Para publicar esse bundle local no Smithery após smithery auth login:

npm run smithery:publish

Claude Desktop

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

Se o Claude Desktop não encontrar npx no macOS, use o caminho absoluto:

{
  "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 repositório também inclui um Agent Skill portátil:

skills/openfate-bazi/SKILL.md

Use-o quando quiser que Claude, Claude Code, Codex, agentes estilo OpenClaw ou outras ferramentas compatíveis com SKILL.md lembrem como usar o OpenFate Bazi MCP corretamente.

Para uso no workspace do Claude Code, copie a pasta do skill para:

.claude/skills/openfate-bazi/

Para Skills personalizados do Claude, compacte a pasta openfate-bazi com SKILL.md na raiz da pasta e envie nas configurações de Skills do Claude.

Ferramentas

calculate_bazi_chart

Calcula um mapa Bazi determinístico.

Entradas:

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

O MCP fixa a política de início em DAYUN_SECOND_V2; os chamadores não podem selecionar silenciosamente uma regra diferente. Informe um horário de nascimento exato mais timezone ou timezoneId para um recibo calculado. Apresente um início exato somente quando chart.daYun.timing.status for CALCULATED e sua versão for DAYUN_SECOND_V2. Um recibo UNAVAILABLE identifica o motivo e marca os campos escalares legados retidos como fallback. Informe longitude também para correção de Tempo Solar Verdadeiro.

detect_bazi_interactions

Detecta ocorrências brutas de relações entre Ramos Terrestres para um mapa natal, com ramos anuais e de Da Yun opcionais.

As entradas são yearBranch, monthBranch, dayBranch, hourBranch opcional, annualBranch opcional e dayunBranch opcional. Omita hourBranch quando a hora de nascimento for desconhecida; ela não é substituída por um ramo assumido. Chamadas existentes apenas com ano continuam suportadas.

Tipos de interação suportados:

  • clash
  • six-combination
  • half-trine de ramo central (COMBINATION_HALF)
  • trine
  • directional
  • punishment
  • destruction
  • harm

Toda ocorrência de pilar correspondente é preservada. Por exemplo, { yearBranch: '申', monthBranch: '寅', dayBranch: '申', hourBranch: '申' } retorna três clashes 寅申 distintos, não um. Ramos anuais e de Da Yun mantêm papéis separados de annual e dayun mesmo quando seus valores de ramo correspondem a posições natais.

O perfil de half-trine cobre 申子、子辰、寅午、午戌、亥卯、卯未、巳酉、酉丑: cada par inclui um ramo central (子午卯酉). Pares apenas de extremidades, como 申辰, não são deste tipo de half-trine. Half-trines permanecem na saída bruta quando o trine completo de três ramos também está presente.

Cada ocorrência tem um id estável e arrays branches / pillars alinhados. targetElement significa afinidade de relacionamento, não energia transformada. O transformationStatus da combinação é NOT_EVALUATED: a presença apenas do ramo não estabelece transformação nem sua falha. Outros tipos de relacionamento usam NOT_APPLICABLE. Esses resultados não são pesos pontuados e não cancelam clashes automaticamente; liquidação e interpretação pertencem a uma camada de análise separada.

Para compatibilidade de API, ocorrências completas de TRINE e DIRECTIONAL também retêm o resultElement legado, igual a targetElement e com o mesmo significado de apenas afinidade. Six-combinations e half-trines não emitem resultElement.

calculate_true_solar_time

Calcula o Tempo Solar Verdadeiro diretamente.

Use isto quando um usuário perguntar por que o pilar da hora da OpenFate difere de uma ferramenta baseada em horário de relógio.

reverse_bazi_to_solar_times

Encontra possíveis datas e horários gregorianos para uma string de Bazi de quatro pilares.

Exemplo de entrada:

戊寅 己未 己卯 辛未

Este é um localizador de candidatos. Para precisão final, recalcule o resultado com longitude exata, fuso horário e Tempo Solar Verdadeiro.

get_openfate_bazi_policy

Retorna a política de cálculo da OpenFate:

  • Tempo Solar Verdadeiro é preferido quando dados de localização estão disponíveis.
  • O modo padrão de mudança de dia é ZI_HOUR_23.
  • Horário de verão deve ser informado como dstOffset quando o horário da certidão de nascimento incluir horário de verão.
  • O início do Da Yun usa DAYUN_SECOND_V2; datas exatas exigem um recibo de timing calculado.
  • A busca reversa deve ser tratada como uma pesquisa de candidatos.
  • Interações entre ramos preservam ocorrências brutas de pilares, não resultados ponderados ou automaticamente transformados.

get_openfate_bazi_resources

Retorna links canônicos da OpenFate para mapas, leituras, compatibilidade, riqueza, tempo solar verdadeiro e llms.txt.

Formato de Saída

As respostas usam chaves em inglês amigáveis para máquinas:

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

A atribuição é retornada como dado de primeira classe, não oculta em _meta, para que clientes MCP e artefatos gerados possam exibi-la de forma confiável.

Os resultados do mapa incluem fatos enriquecidos dos pilares (Dez Deuses, hastes ocultas, Na Yin, Xun, ramos vazios e estágios de crescimento), um recibo de timing de Da Yun versionado, dados normalizados de calendário solar/lunar e a política de cálculo realmente aplicada.

Desenvolvimento

npm install
npm run build
npm run smoke

O teste de fumaça inicia o servidor stdio compilado e o conduz pelo cliente real do SDK MCP.

Para testar mudanças no código-fonte sem compilar dist, execute npm run smoke:source. Isso requer o checkout do código-fonte irmão ../bazi-engine com suas dependências instaladas, bem como as dependências deste pacote. O tests/tsconfig.source.json somente de teste mapeia @openfate/bazi-engine para o src/index.ts do irmão; o executor de fumaça passa essa configuração ao servidor iniciado pelo SDK e verifica o caminho do código-fonte resolvido antes de testar. Ele não depende de um mecanismo instalado com patch e permanece reproduzível após npm ci --ignore-scripts neste pacote.

Ambos os modos de fumaça exercitam o mesmo transporte MCP e fixtures de regressão, incluindo início de Da Yun resolvido em segundos, entradas de timing ausentes, ramos repetidos, oito half-trines, hora desconhecida e papéis anual/Da Yun. O comando comum smoke ainda testa a saída MCP compilada contra sua dependência de mecanismo publicada instalada. npx tsc --noEmit -p tests/tsconfig.source.json verifica o contrato de código-fonte coordenado sem emitir arquivos de build.

Compatibilidade do mecanismo

A versão 0.3 requer @openfate/bazi-engine versão 2. Seus contratos de DAYUN_SECOND_V2, ocorrência bruta e dayunBranch são verificados nos modos de fumaça de pacote compilado e código-fonte coordenado. A dependência publicada permanece como a fonte de verdade da versão; este pacote não usa uma dependência local file:.

Privacidade

Este pacote não faz phone home. Os cálculos são executados localmente no subprocesso MCP.

Links da OpenFate

Licença

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 O teste iniciará o servidor stdio compilado e chamará as ferramentas por meio de um cliente real do SDK MCP.

Sem compilar dist, é possível executar npm run smoke:source para validar o código-fonte. É necessário ter um diretório de trabalho adjacente com o código-fonte de ../bazi-engine, e tanto o mecanismo quanto este pacote devem ter as dependências instaladas. O tests/tsconfig.source.json específico para testes aponta o @openfate/bazi-engine para o src/index.ts desse mecanismo; o executor de testes passará a configuração para o servidor iniciado pelo SDK MCP e verificará primeiro o caminho real do código-fonte resolvido. Esse modo não depende de um mecanismo instalado modificado e pode ser reproduzido após a reexecução do npm ci --ignore-scripts neste pacote.

Ambos os modos de smoke test usam o mesmo transporte MCP e casos de regressão, cobrindo inicialização em segundos, falta de entrada de inicialização, ramo terrestre duplicado, oito combinações de meia harmonia, hora desconhecida e papéis de ano corrente / pilar da sorte. O smoke geral ainda valida o MCP compilado e o mecanismo público npm instalado. O npx tsc --noEmit -p tests/tsconfig.source.json pode verificar os contratos de código-fonte em coordenação, sem gerar arquivos compilados.

Compatibilidade do mecanismo

A versão 0.3 requer @openfate/bazi-engine 2.x. DAYUN_SECOND_V2, relações completas de pilares e o contrato de dayunBranch são validados por ambos os modos de smoke test: pacote compilado e código-fonte em coordenação. A dependência npm publicada oficialmente continua sendo a fonte da versão; este pacote não usa dependências locais de file:.

Privacidade

Este pacote não envia dados de volta ao servidor OpenFate. Todos os cálculos são realizados localmente no subprocesso MCP.

Links do OpenFate

Licença

MIT