mcp-luopan

Convierte "Luopan" —el cálculo de cartas astrales basado en el método de格局 (geju) de Ziping Zhenquan— en un conjunto de herramientas MCP (Model Context Protocol), permitiendo que cualquier cliente MCP (Claude Code / Claude Desktop / OpenClaw / Cursor / Agente LLM propio) pueda calcular cartas, leerlas y responder preguntas de seguimiento en la conversación.

La entrada en la nube ya está disponible: https://luopan.caihangao.com. MCP apunta a ella por defecto, lista para usar, sin necesidad de iniciar servicios localmente.

¿Qué problema resuelve?

Los LLM por sí mismos no saben calcular Bazi. Hacer que el modelo "analice una carta" basándose directamente en su conocimiento de entrenamiento es incorrecto: los tallos y ramas, los meses, los diez dioses y la determinación de patrones son cálculos basados en reglas que deben ser realizados por un motor especializado.

mcp-luopan encapsula todo el motor (cálculo de carta → diez dioses → patrones → grandes ciclos → informe → preguntas de seguimiento) en 3 herramientas MCP, para que el LLM no invente, sino que:

1. Obtenga datos precisos de la carta (cuatro pilares / patrones / grandes ciclos / cinco elementos / diez dioses)

2. Organice el lenguaje basándose en datos reales (la capacidad de contar historias se deja al LLM, los hechos al motor)

3. Admita preguntas de seguimiento con contexto (5 preguntas / TTL de 2 horas, gestionado por la sesión del backend)

Escenarios de uso típicos

Escenario A: Analizar una carta para un amigo en Claude Code / Claude Desktop

Tú (usuario):

Ayúdame a analizar a un chico nacido el 15 de marzo de 1991 a las 5 de la mañana, mira su patrón y su carrera este año.

Claude automáticamente:

1. Llama a luopan_analyze(year=1991, month=3, day=15, hour=5, gender=1) → obtiene el session_id y la carta completa

2. Traduce para ti en lenguaje natural el "Patrón de Oficial Directo / Destino Celestial / Tendencia de los Grandes Ciclos / Perfil de pareja"

3. Tú preguntas "¿carrera este año?" → Claude llama a luopan_chat(session_id, "carrera este año") → obtiene la respuesta específica para esta carta

En todo el proceso no necesitas entender terminología ni ver JSON.

Escenario B: Análisis por lotes

Quieres ejecutar una "distribución de patrones de 100 celebridades":

# 伪代码：让一个 Agent 循环调用
for person in people:
    chart = call_tool("luopan_analyze", **person.birth_info)
    record(person.name, chart["pattern"]["final_pattern"])

El motor está en la nube, no ocupa CPU de tu máquina; el script solo se encarga de la orquestación de E/S.

Escenario C: Integración en OpenClaw / Agente de Feishu

Registra luopan en el mcp.json de OpenClaw, autoriza estas 3 herramientas a un agente (por ejemplo, un bot de Feishu), y el agente podrá calcular cartas y responder preguntas en la conversación de Feishu. Actualmente, OpenClaw local ya ha funcionado bajo este modelo; el despliegue de OpenClaw en la nube está en TODO.

Escenario D: Evaluación de LLM / Experimentos de ingeniería de prompts

Quieres probar el estilo de lenguaje de diferentes modelos al interpretar cartas, o ajustar la "personalidad de Luopan" para un agente: el backend siempre devuelve los mismos datos factuales, y las diferencias del modelo quedan totalmente expuestas en el nivel del lenguaje natural.

Inicio rápido: 60 segundos para empezar

1. Instalar

git clone <this-repo> /Users/Neil/Projects/mcp-servers/mcp-luopan
cd /Users/Neil/Projects/mcp-servers/mcp-luopan
uv venv && uv pip install -e .

O usa un venv normal:

python3 -m venv .venv && source .venv/bin/activate
pip install -e .

Una vez instalado, tendrás el ejecutable mcp-luopan (en .venv/bin/).

2. Prueba de humo (verificación sin entrar al host MCP)

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | .venv/bin/mcp-luopan

Se espera ver 3 herramientas: luopan_analyze / luopan_chat / luopan_session_info.

3. Registrar en un host MCP

Claude Code (el más común actualmente)

Edita ~/.claude.json o el .mcp.json a nivel de proyecto:

{
  "mcpServers": {
    "luopan": {
      "command": "/Users/Neil/Projects/mcp-servers/mcp-luopan/.venv/bin/mcp-luopan",
      "env": {
        "LUOPAN_API_BASE": "https://luopan.caihangao.com",
        "LUOPAN_TIMEOUT_SECONDS": "60"
      }
    }
  }
}

Reinicia Claude Code, luego abre una nueva sesión y di directamente "usa Luopan para mirarme una carta", y llamará a la herramienta.

OpenClaw (local o en la nube)

Añádelo a ~/.openclaw/mcp.json:

"luopan": {
  "command": "/Users/Neil/Projects/mcp-servers/mcp-luopan/.venv/bin/mcp-luopan",
  "env": {
    "LUOPAN_API_BASE": "https://luopan.caihangao.com",
    "LUOPAN_TIMEOUT_SECONDS": "60"
  }
}

Para que un agente lo use, tools.allow del agente no necesita listar explícitamente luopan_*: OpenClaw permite por defecto que todos los agentes vean todos los servidores en mcp.json.

Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json, la estructura es la misma.

Semántica de las tres herramientas

Todas las herramientas devuelven cadenas JSON. En caso de error, devuelven {"error": "...", "hint": "..."}, sin lanzar excepciones al LLM.

luopan_analyze(year, month, day, hour, gender)

Análisis completo de la carta: una llamada produce toda la información. Antes de llamar, debes: confirmar con el usuario la fecha solar, la hora de nacimiento (0-23) y el género (1=hombre / 0=mujer).

Campos de retorno (extracto):

luopan_chat(session_id, question)

Pregunta de seguimiento sobre una carta existente. Debe realizarse dentro de las 2 horas y con un máximo de 5 preguntas.

Retorno (normalizado):

{
  "answer": "AI 的回答文本",
  "followup_remaining": 4,
  "followup_count": 1,
  "max_followups": 5,
  "session_id": "..."
}

Cuando followup_remaining == 0 o devuelve session_expired, se debe llamar de nuevo a luopan_analyze para iniciar una nueva carta.

luopan_session_info(session_id)

Consulta optimista del estado de la sesión: no contacta al backend. El backend no tiene una interfaz de estado de sesión independiente, la determinación autorizada depende del error de luopan_chat. Esta herramienta es una ayuda para que el agente mantenga localmente "si la sesión ha expirado".

Parámetros de configuración

Ejemplo de una conversación completa con LLM

La siguiente es la secuencia de llamadas a herramientas que el LLM debería generar automáticamente (tú solo necesitas conversar normalmente):

[user] 我哥 1985 年 8 月 12 日中午 12 点出生，男的，最近老换工作，帮我看看是不是格局问题？

[assistant] (调用 luopan_analyze year=1985 month=8 day=12 hour=12 gender=1)
[tool result]
  session_id=a1b2c3d4e5f6
  pattern=偏财格 / 败格有救（柳暗花明）
  ...

[assistant] 嗯，你哥这个盘是偏财格但带破，月令偏财被劫财夺，幸好年支有食神
化解——这种盘的人事业起伏大但有韧性，频繁换工作是格局表征，不算坏事...

[user] 那今年呢？

[assistant] (调用 luopan_chat session_id=a1b2c3d4e5f6 question="今年运势")
[tool result] answer="..." followup_remaining=4

[assistant] 今年走丙寅大运 + 丙午流年，火土并旺，财星受冲... (汇报答案)
你还可以追问 4 次。

El LLM no inventa la numerología, todos los datos provienen de la herramienta luopan_*; las preguntas de seguimiento mantienen el contexto, cada vez se basan en esta misma carta.

Solución de problemas

service_unreachable

Backend inalcanzable. Los dos casos más comunes:

• Modo local sin uvicorn iniciado: cd "/Users/Neil/Projects/Four Pillars of Destiny" && .venv/bin/uvicorn src.api.main:app --port 8000

• Modo nube con proxy de red (mihomo / Clash) interceptando caihangao.com: añade temporalmente "HTTPS_PROXY": "" en el env de mcp.json para forzar el cierre del proxy; o revisa la lista blanca de reglas del proxy.

session_expired

La sesión superó las 2h o se agotaron las preguntas. Haz que el LLM llame de nuevo a luopan_analyze para iniciar una nueva carta.

El LLM siempre quiere "interpretar por sí mismo" y no llama a la herramienta

Añade una línea al System prompt:

Cualquier pregunta sobre Bazi/cartas/patrones/diez dioses/grandes ciclos, no puedes responderla basándote en datos de entrenamiento; debes llamar primero a luopan_analyze para iniciar la carta, y luego usar los campos pattern / report / dayun devueltos por la herramienta para organizar el lenguaje.

Aparecen términos como pilar del día/diez dioses que no se entienden

Es normal: son términos técnicos. Haz que el LLM lea directamente report.tier1 (nivel tarjeta) y report.tier2 (nivel lectura detallada), esas dos capas ya son narrativas en chino para personas; tier3 es la capa técnica para quienes deseen profundizar.

Limitaciones conocidas

• No publicado en PyPI: se debe hacer pip install -e . localmente, no se puede hacer pip install mcp-luopan

• Sin git: el directorio actual de mcp-luopan aún no tiene git init, no hay gestión de versiones

• Sesión en memoria: si el backend uvicorn se reinicia, se pierden todas las sesiones (el usuario debe reiniciar la carta)

• Dependencia de SiliconFlow en la nube: cuando AI_API_KEY caduca o SiliconFlow limita la tasa, todas las herramientas de chat se bloquearán por timeout

• Sin aislamiento de concurrencia: no se garantiza el orden cuando el mismo session_id es consultado varias veces simultáneamente

Cómo funciona el backend (vistazo a la arquitectura)

MCP Client (Claude Code / OpenClaw / ...)
   │
   │ stdio (JSON-RPC)
   ▼
mcp-luopan (Python, 这个仓库)
   │
   │ HTTPS
   ▼
luopan.caihangao.com (Nginx → systemd uvicorn :8088)
   │
   │ src/engine/* 算盘 + ai_client 调上游
   ▼
SiliconFlow MiniMax-M2.5

Para detalles sobre el despliegue del servicio backend, consulta el proyecto original: Four Pillars of Destiny / docs/design/deployment.md.