mcp-luopan

Verwandelt "Luopan" – eine Horoskopberechnung basierend auf der Ziping Zhenquan-Methode – in eine MCP-Tool-Sammlung (Model Context Protocol). Damit kann jeder MCP-Client (Claude Code / Claude Desktop / OpenClaw / Cursor / selbst entwickelte LLM-Agenten) im Dialog Horoskope für Benutzer erstellen, lesen und Folgefragen beantworten.

Der Cloud-Einstiegspunkt ist bereits live: https://luopan.caihangao.com. MCP verweist standardmäßig darauf, ist sofort einsatzbereit und erfordert keinen lokalen Server.

Welches Problem wird gelöst?

LLMs können von sich aus keine Bazi-Berechnungen durchführen. Es ist falsch, das Modell direkt auf Basis von Trainingswissen "Horoskope analysieren" zu lassen – Himmelsstämme, Erdzweige, Monatsregenten, Zehn-Götter-Konstellationen und Strukturanalysen sind rein regelbasierte Berechnungen, die von einer spezialisierten Engine durchgeführt werden müssen.

mcp-luopan kapselt die gesamte Engine (Berechnung → Zehn Götter → Struktur → Glückssäulen → Bericht → Folgefragen) in 3 MCP-Tools. Das LLM erfindet nichts mehr, sondern:

1. Erhält präzise Horoskopdaten (Vier Säulen / Struktur / Glückssäulen / Fünf Elemente / Zehn Götter)

2. Formuliert Sprache basierend auf echten Daten (Die Fähigkeit, Geschichten zu erzählen, liegt beim LLM, die Fakten bei der Engine)

3. Unterstützt kontextbezogene Folgefragen (5 Folgefragen / 2 Stunden TTL, verwaltet durch Backend-Session)

Typische Anwendungsfälle

Szenario A: Analyse für einen Freund in Claude Code / Claude Desktop

Du (Benutzer):

Analysiere bitte einen Jungen, der am 15. März 1991 um 5 Uhr morgens geboren wurde, und schau dir die Struktur und die Karriere für dieses Jahr an.

Claude automatisch:

1. Ruft luopan_analyze(year=1991, month=3, day=15, hour=5, gender=1) auf → erhält session_id und das vollständige Horoskop

2. Übersetzt "Zheng-Guan-Struktur / Tian-Cheng / Trend der Glückssäulen / Partnerprofil" in natürliche Sprache für dich

3. Du fragst nach "Karriere dieses Jahr" → Claude ruft luopan_chat(session_id, "Karriere dieses Jahr") auf → erhält eine Antwort, die spezifisch für dieses eine Horoskop ist

Du musst während des gesamten Prozesses keine Fachbegriffe verstehen oder JSON sehen.

Szenario B: Stapelanalyse

Du möchtest eine "Verteilung der Strukturen von 100 Prominenten" auswerten:

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

Die Engine läuft in der Cloud und belastet nicht deine lokale CPU; das Skript kümmert sich nur um die IO-Orchestrierung.

Szenario C: Einbettung in OpenClaw / Feishu Agent

Registriere luopan in der mcp.json von OpenClaw und autorisiere einen Agenten (z. B. einen Feishu-Bot) für diese 3 Tools. Der Agent kann dann im Feishu-Dialog Horoskope für Benutzer erstellen und Folgefragen beantworten. Die lokale OpenClaw-Instanz läuft bereits nach diesem Muster; die Cloud-Bereitstellung für OpenClaw ist noch TODO.

Szenario D: LLM Eval / Prompt Engineering Experimente

Du möchtest verschiedene Sprachstile von Modellen bei der Horoskopdeutung testen oder ein "Luopan-Persona" für einen Agenten einstellen – das Backend liefert immer dieselben Fakten, die Modellunterschiede zeigen sich vollständig auf der Ebene der natürlichen Sprache.

Quick Start: In 60 Sekunden einsatzbereit

1. Installation

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 .

Oder mit einer normalen venv:

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

Nach der Installation ist mcp-luopan ausführbar (unter .venv/bin/).

2. Rauchtest (Verifizierung ohne MCP-Host)

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

Erwarte die Anzeige von 3 Tools: luopan_analyze / luopan_chat / luopan_session_info.

3. Registrierung bei einem MCP-Host

Claude Code (derzeit am häufigsten)

Bearbeite ~/.claude.json oder die projektbezogene .mcp.json:

{
  "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"
      }
    }
  }
}

Starte Claude Code neu, öffne eine neue Sitzung und sage einfach "Benutze Luopan, um mir ein Horoskop zu erstellen", dann wird das Tool aufgerufen.

OpenClaw (lokal oder Cloud)

Füge es zu ~/.openclaw/mcp.json hinzu:

"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"
  }
}

Damit ein Agent es nutzen kann, muss tools.allow nicht explizit luopan_* auflisten – OpenClaw erlaubt standardmäßig allen Agenten den Zugriff auf alle Server in der mcp.json.

Claude Desktop

Bearbeite ~/Library/Application Support/Claude/claude_desktop_config.json, die Struktur ist identisch.

Semantik der drei Tools

Alle Tools geben JSON-Strings zurück. Bei Fehlern wird {"error": "...", "hint": "..."} zurückgegeben, ohne Exceptions an das LLM zu werfen.

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

Vollständige Horoskopanalyse – ein Aufruf liefert alle Informationen. Vor dem Aufruf muss: das Geburtsdatum (gregorianisch), die Geburtsstunde (0-23) und das Geschlecht (1=männlich / 0=weiblich) mit dem Benutzer bestätigt werden.

Zurückgegebene Felder (Auszug):

luopan_chat(session_id, question)

Folgefragen zu einem bestehenden Horoskop. Muss innerhalb von 2 Stunden und maximal 5 Mal erfolgen.

Antwort (standardisiert):

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

Wenn followup_remaining == 0 oder session_expired zurückgegeben wird, muss zwingend luopan_analyze für ein neues Horoskop aufgerufen werden.

luopan_session_info(session_id)

Optimistische Abfrage des Session-Status – kein Backend-Aufruf. Das Backend hat keine separate Session-Status-Schnittstelle; die verbindliche Prüfung erfolgt über Fehlermeldungen von luopan_chat. Dieses Tool dient als Hilfsmittel für Agenten, um lokal zu "erinnern", ob eine Session abgelaufen ist.

Konfigurationsparameter

Beispiel für einen vollständigen LLM-Dialog

Unten ist die Sequenz der Tool-Aufrufe, die das LLM automatisch generieren sollte (du musst nur normal kommunizieren):

[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 次。

Das LLM erfindet keine Astrologie, alle Daten stammen von luopan_*-Tools; Folgefragen behalten den Kontext bei, jedes Mal basierend auf diesem einen Horoskop.

Fehlerbehebung

service_unreachable

Backend nicht erreichbar. Die zwei häufigsten Ursachen:

• Lokaler Modus: uvicorn wurde nicht gestartet – cd "/Users/Neil/Projects/Four Pillars of Destiny" && .venv/bin/uvicorn src.api.main:app --port 8000

• Cloud-Modus: Netzwerk-Proxy (mihomo / Clash) blockiert caihangao.com – füge temporär "HTTPS_PROXY": "" in die env-Sektion der mcp.json ein, um den Proxy zu erzwingen; oder prüfe die Whitelist der Proxy-Regeln

session_expired

Session ist älter als 2h oder Folgefragen sind aufgebraucht. Lass das LLM luopan_analyze erneut aufrufen, um ein neues Horoskop zu erstellen.

LLM versucht immer "selbst zu deuten" und ruft keine Tools auf

Füge eine Zeile zum System-Prompt hinzu:

Bei allen Fragen zu Bazi/Horoskopen/Strukturen/Zehn Göttern/Glückssäulen darfst du nicht auf Basis von Trainingsdaten antworten; du musst zuerst luopan_analyze aufrufen, um ein Horoskop zu erstellen, und dann die Felder pattern / report / dayun etc. aus dem Tool-Ergebnis zur Sprachformulierung nutzen.

Rückgabewerte wie Tagesstamm/Zehn Götter sind unverständlich

Normal – das sind Fachbegriffe. Lass das LLM direkt report.tier1 (Karten-Ebene) und report.tier2 (Detail-Ebene) lesen; diese beiden Ebenen sind bereits als chinesische Erzählung für Menschen aufbereitet; tier3 ist die technische Ebene für diejenigen, die tiefer graben wollen.

Bekannte Einschränkungen

• Kein PyPI-Release: Muss lokal mit pip install -e . installiert werden, pip install mcp-luopan funktioniert nicht

• Kein Git: Das aktuelle mcp-luopan-Verzeichnis hat noch kein git init, keine Versionsverwaltung

• Session im Arbeitsspeicher: Ein Neustart des Backend-uvicorn führt zum Verlust aller Sessions (Benutzer muss Horoskop neu erstellen)

• Abhängigkeit von SiliconFlow (Cloud): Wenn AI_API_KEY abläuft oder SiliconFlow das Limit erreicht, laufen alle Chat-Tools in ein Timeout

• Keine Nebenläufigkeitsisolierung: Wenn dieselbe session_id gleichzeitig mehrfach gechattet wird, ist die Reihenfolge nicht garantiert

Wie das Backend läuft (Architektur-Überblick)

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

Details zur Bereitstellung des Backend-Dienstes siehe Upstream-Projekt: Four Pillars of Destiny / docs/design/deployment.md.