mcp-luopan

把"罗盘"——基于子平真诠格局法的命盘推算——做成一个 MCP（Model Context Protocol）工具集，让任何 MCP 客户端（Claude Code / Claude Desktop / OpenClaw / Cursor / 自研 LLM Agent）都能在对话里给用户起盘、读盘、追问。

云端入口已上线：https://luopan.caihangao.com。MCP 默认就指向它，开箱即用，不需要本机起服务。

---

它解决什么问题

LLM 自己不会算八字。让模型直接基于训练知识"分析命盘"是错的——干支、月令、十神、格局判定全是规则计算，必须由专门的引擎做。

mcp-luopan 把整套引擎（排盘 → 十神 → 格局 → 大运 → 报告 → 多轮追问）封装成 3 个 MCP 工具，LLM 不再瞎编，而是：

1. 拿到准确的命盘数据（四柱 / 格局 / 大运 / 五行 / 十神）
2. 依据真实数据组织语言（讲故事的能力交给 LLM，事实交给引擎）
3. 支持有上下文的追问（5 次追问 / 2 小时 TTL，由后端 session 管理）

---

典型使用场景

场景 A：在 Claude Code / Claude Desktop 里给朋友测一个

你（用户）：

帮我分析一下 1991 年 3 月 15 日早上 5 点出生的男生，看看格局和今年事业。

Claude 自动：

1. 调 luopan_analyze(year=1991, month=3, day=15, hour=5, gender=1) → 拿到 session_id 和完整命盘
2. 用自然语言把"正官格 / 天成 / 大运走势 / 配偶画像"翻译给你
3. 你追问"今年事业"→ Claude 调 luopan_chat(session_id, "今年事业") → 拿到针对这一个盘的回答

整个过程你不需要懂术语、不需要看到 JSON。

场景 B：批量分析

你想跑一份"100 个名人的格局分布"：

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

引擎在云端，不占你本机 CPU；脚本只管 IO 编排。

场景 C：嵌入到 OpenClaw / 飞书 Agent

把 luopan 注册到 OpenClaw 的 mcp.json，给某个 agent（比如飞书 bot）授权这 3 个工具，agent 就能在飞书对话里给用户测命盘 + 追问。当前本机 OpenClaw 已经按这个模式跑过；云端 OpenClaw 部署还在 TODO。

场景 D：LLM Eval / 提示工程实验

想测试不同模型解读命盘的语言风格、想给某个 agent 调"罗盘人设"——后端永远返回同一份事实数据，模型差异完全暴露在自然语言层。

---

Quick start：60 秒上手

1. 装

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 .

或用普通 venv：

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

装好后会有 mcp-luopan 可执行（在 .venv/bin/ 里）。

2. 烟雾测试（不进 MCP host 直接验证）

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

预期看到 3 个工具：luopan_analyze / luopan_chat / luopan_session_info。

3. 注册到一个 MCP host

Claude Code（当前最常见）

编辑 ~/.claude.json 或项目级 .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"
      }
    }
  }
}

重启 Claude Code，然后开一个新会话直接说"用罗盘帮我看个盘"，它就会调工具。

OpenClaw（本机或云端）

加到 ~/.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"
  }
}

要让某个 agent 用它，agent 的 tools.allow 不需要显式列 luopan_*——OpenClaw 默认让所有 agent 看到 mcp.json 里所有 server。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，结构同上。

---

三个工具的语义

所有工具都返回 JSON 字符串。出错时返回 {"error": "...", "hint": "..."}，不抛异常给 LLM。

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

完整命盘分析——一次调用产出全部信息。调用前必须：和用户确认阳历日期、出生小时（0-23）、性别（1=男 / 0=女）。

返回字段（节选）：

字段	内容
session_id	12 位短 ID，用于后续 luopan_chat
sizhu	四柱（年/月/日/时柱的天干地支）
pattern	格局判定（如"正官格 / 天成 / followup_remaining=5"）
report	三层解读（卡片 tier1 / 详读 tier2 / 技术 tier3）
dayun	大运时间轴 + 5 级吉凶
highlights	命盘亮点（13 条规则，rarity 1-3）
partner	互补搭档画像（38 子格局 × 3 状态映射）
female	女命专属（夫星/子星/夫妻宫，仅 gender=0 时）
wuxing / shishen	五行统计 / 十神关系
followup_remaining	还能追问几次（默认 5）

luopan_chat(session_id, question)

针对某一个已有命盘追问。必须在 2 小时内、5 次以内。

返回（已规范化）：

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

followup_remaining == 0 或返回 session_expired 时，必须重新 luopan_analyze 起新盘。

luopan_session_info(session_id)

乐观查 session 状态——不打后端。后端没有独立的 session 状态接口，权威判定要靠 luopan_chat 的报错。这个工具是为 agent 在本地维护"记得 session 是否过期"的辅助。

---

配置参数

环境变量	默认值	说明
LUOPAN_API_BASE	http://127.0.0.1:8000	后端地址。云端推荐 https://luopan.caihangao.com；本机调试用 http://127.0.0.1:8000 起 uvicorn
LUOPAN_TIMEOUT_SECONDS	60	HTTP 超时。AI 分析偶尔 30s+，留够余量
LUOPAN_HTTP_RETRIES	1	短暂网络抖动重试次数

---

一段完整 LLM 对话示例

下面是 LLM 应该自动产生的工具调用序列（你只需要正常对话）：

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

LLM 不会自己编命理，全部数据来自 luopan_* 工具；追问保持上下文，每次都是基于这一个盘。

---

故障排查

service_unreachable

后端不可达。最常见两种：

• 本机模式未起 uvicorn——cd "/Users/Neil/Projects/Four Pillars of Destiny" && .venv/bin/uvicorn src.api.main:app --port 8000
• 云端模式网络代理（mihomo / Clash）拦截了 caihangao.com——临时在 mcp.json 的 env 里加 "HTTPS_PROXY": "" 强制关代理；或检查代理规则白名单

session_expired

session 过 2h 或追问用完。让 LLM 重新调 luopan_analyze 起一个新盘。

LLM 总是想"自己解读"，不调工具

System prompt 里加一行：

任何关于八字/命盘/格局/十神/大运的问题，你都不能凭训练数据回答；必须先调 luopan_analyze 起盘，再用工具返回的 pattern / report / dayun 等字段组织语言。

返回里出现日柱/十神看不懂

正常——这些是术语。让 LLM 直接读 report.tier1（卡片层）和 report.tier2（详读层），那两层已经是给人看的中文叙述；tier3 是技术层留给愿意往下看的人。

---

已知限制

• 未发布 PyPI：必须本地 pip install -e .，不能 pip install mcp-luopan
• 未 git 化：当前 mcp-luopan 目录还没 git init，没有版本管理
• session 存内存：后端 uvicorn 重启会丢所有 session（用户得重起盘）
• 依赖云端 SiliconFlow：AI_API_KEY 失效或 SiliconFlow 限流时所有 chat 工具会卡 timeout
• 不做并发隔离：同一个 session_id 同时被多次 chat 时不保证顺序

---

后端是怎么跑的（架构速览）

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

后端服务部署细节见上游项目：Four Pillars of Destiny / docs/design/deployment.md。