bazi-reader-mcp

🇨🇳 中国八字 (Cuatro Pilares del Destino) ・ 🇯🇵 四柱推命 (shichū suimei) ・ 🇰🇷 사주팔자 (Saju Palja)

El motor de cálculo (y servidor MCP) detrás de Shunshi.AI / 顺时, de código abierto.

🇯🇵 Para desarrolladores japoneses: Este es el motor de cálculo + servidor MCP para el "八字 (bāzì)" chino, conocido en Japón como 四柱推命 (shichū suimei). Puede calcular los Cuatro Pilares / Diez Dioses / Grandes Ciclos / equilibrio de los Cinco Elementos a partir de la fecha, hora y lugar de nacimiento. Admite la corrección del tiempo solar verdadero (ecuación del tiempo) y se puede invocar directamente desde agentes de IA (Claude / Cursor / Cline, etc.).

🇰🇷 Para desarrolladores coreanos: Este es el motor de cálculo + servidor MCP para el "八字 (bāzì)" chino, conocido en Corea como 사주팔자 (Saju Palja). Calcula los Cuatro Pilares / Diez Dioses / Grandes Ciclos / equilibrio de los Cinco Elementos a partir de la fecha, hora y lugar de nacimiento. Admite la corrección del tiempo solar verdadero y se puede utilizar directamente desde agentes de IA (Claude / Cursor / Cline, etc.).

Este repositorio es un monorepo con dos paquetes npm publicados:

Ambos paquetes comparten el mismo motor de cálculo que impulsa el backend de producción de Shunshi.AI. Ambos se prueban en paridad en cada lanzamiento.

Por qué existe esto

La mayoría de las bibliotecas Bazi de código abierto existentes (en cualquier lenguaje) tienen al menos uno de estos problemas:

1. Sin corrección de tiempo solar verdadero. Se utiliza la hora del reloj tal cual, lo que da gráficos incorrectos para nacimientos lejos del meridiano estándar de la zona horaria (Xinjiang / Heilongjiang / Costa Oeste de EE. UU. / Hokkaido). Un error de 30 minutos desplaza todo el pilar de la hora.

2. Manejo inconsistente de 子时 (Zi Shi). Algunas bibliotecas colocan el intervalo de 23:00-23:59 en el pilar del día de "ayer", otras en el de "mañana". Si no eliges, tus gráficos no coincidirán con las herramientas de referencia profesionales.

3. Sin línea base de paridad. Calculas un gráfico localmente, lo comparas con un servicio de pago, obtienes números diferentes y no tienes forma de saber quién tiene razón.

4. Solo datos crudos, sin contexto multilingüe. La salida está centrada en el chino, difícil de integrar en asistentes de IA en JP/KR/EN.

shunshi-bazi-core + shunshi-bazi-mcp solucionan los cuatro:

• ✅ Tiempo solar verdadero integrado, activado por defecto (solo pasa city o longitude/latitude).

• ✅ sect=1 por defecto (23:00 = pilar del día de mañana), coincidiendo con 问真八字.

• ✅ Probado en paridad contra el backend de Python de Shunshi.AI (5/5 casos dorados) y calculateRelation() de cantian-tymext (5/5 en el subconjunto de pares 刑冲合会).

• ✅ Descubribilidad multilingüe mediante palabras clave (bazi / 八字 / 四柱推命 / 사주팔자 / saju / shichu-suimei) para que los desarrolladores JP/KR/EN puedan encontrar el paquete.

Inicio rápido

Si estás integrando el cálculo Bazi en tu propia aplicación

npm install shunshi-bazi-core

import { getBaziChart } from 'shunshi-bazi-core';

const chart = getBaziChart({
  year: 1990, month: 3, day: 24, hour: 10, minute: 28,
  gender: 1,           // 0 = 女, 1 = 男
  city: '广州',         // triggers true solar time correction
});

console.log(chart.八字.四柱);          // "庚午 己卯 戊子 丁巳"
console.log(chart.真太阳时?.修正分钟); // -33.85 (minutes of correction applied)

→ Referencia completa de API y salida: packages/bazi-core/README.md

Si quieres que Claude / Cursor / Cline calculen gráficos Bazi

Añade esto a tu configuración de MCP (ej. claude_desktop_config.json):

{
  "mcpServers": {
    "shunshi-bazi": {
      "command": "npx",
      "args": ["-y", "shunshi-bazi-mcp"]
    }
  }
}

Luego reinicia el cliente y pregúntale a tu agente de IA en lenguaje natural:

"Ayúdame a calcular el Bazi de un chico nacido en Guangzhou el 24 de marzo de 1990 a las 10:28 a.m."

→ Documentación completa de herramientas MCP, configuraciones de clientes alternativos, solución de problemas: packages/bazi-mcp/README.md

Estructura del repositorio

bazi-reader-mcp/
├── package.json                 # npm workspace root (private)
├── tsconfig.base.json           # shared TypeScript config
├── LICENSE                      # MIT
├── README.md                    # you are here
└── packages/
    ├── bazi-core/               # → publishes as "shunshi-bazi-core"
    │   ├── src/
    │   │   ├── index.ts
    │   │   └── lib/{bazi,relations,shensha,solarTime,cityCache}.ts
    │   ├── tests/{parity,relations-vs-cantian,smoke}.ts
    │   ├── package.json
    │   └── README.md
    └── bazi-mcp/                # → publishes as "shunshi-bazi-mcp"
        ├── src/{mcp,stdio}.ts
        ├── tests/smoke-stdio.ts
        ├── package.json
        └── README.md

Desarrollo

# install deps for both packages
npm install

# build both packages
npm run build

# run bazi-core tests (parity + relations-vs-cantian)
npm test

# run the MCP server locally via tsx (no build required)
npm run dev:mcp

# stdio smoke test for the MCP (spawns the built dist/stdio.js)
cd packages/bazi-mcp && npm run smoke

Cobertura de pruebas

• packages/bazi-core/tests/parity.test.ts — 5 casos dorados etiquetados manualmente a partir de capturas de pantalla de 问真八字, verificados contra el backend de Python de Shunshi.AI en 四柱 / 十神 / 空亡 / 纳音 / 藏干.

• packages/bazi-core/tests/relations-vs-cantian.test.ts — Coincidencia 5/5 frente a calculateRelation() de cantian-tymext en 刑冲合会 (subconjunto de pares: 合 / 冲 / 刑 / 害 / 破 / 克).

• packages/bazi-mcp/tests/smoke-stdio.ts — Handshake stdio de extremo a extremo + tools/list + tools/call, afirma la salida real de 四柱 y el bloque de atribución de 数据来源. Utiliza el cliente SDK de MCP real, por lo que ejercita exactamente la misma ruta de código que Claude Desktop.

Proyectos relacionados

• tyme4ts por 6tail — las primitivas de calendario lunar/solar en TypeScript sobre las que se construye esta biblioteca.

• cantian-ai/bazi-mcp — MCP de Bazi de código abierto pionero. Usamos su cantian-tymext como dependencia de desarrollo para pruebas de paridad de relaciones. Los dos MCP son complementarios, no competitivos; establecimos valores predeterminados diferentes (sect=1, tiempo solar verdadero activado por defecto) basados en lo que coincide con la práctica profesional en el mundo de habla china.

Acerca de Shunshi.AI

🌐 Sitio web: https://shunshi.ai 🐦 X / Twitter: @shunshiai2026 🚀 Product Hunt: Shunshi.AI

Shunshi.AI (顺时) es una plataforma de lectura de Bazi impulsada por IA que admite inglés, 中文, 日本語 y 한국어. Gratis para probar, no se requiere tarjeta de crédito.

Abrimos el código del motor de cálculo detrás de nuestro backend de producción para que:

• Cualquier desarrollador pueda calcular gráficos Bazi con la misma precisión que nuestro producto de pago.

• Los casos extremos de 真太阳时 / 子时 se resuelvan de una vez por todas, en lugar de que cada proyecto los haga mal de una manera ligeramente diferente.

• Los desarrolladores JP/KR/EN finalmente tengan una biblioteca de TypeScript que hable su terminología (四柱推命 / 사주팔자).

Licencia

MIT © 2026 Shunshi.AI