mcp-luopan

Превращает «Лопань» — расчет карты судьбы на основе метода «Чжэнь Цюань» (Ziping Zhenquan) — в набор инструментов MCP (Model Context Protocol), чтобы любой MCP-клиент (Claude Code / Claude Desktop / OpenClaw / Cursor / собственный LLM-агент) мог составлять карты, читать их и отвечать на вопросы пользователей в ходе диалога.

Облачный вход уже запущен: https://luopan.caihangao.com. MCP по умолчанию указывает на него, работает «из коробки», не нужно запускать сервер локально.

Какие проблемы это решает

LLM сами по себе не умеют рассчитывать Бацзы. Позволять модели «анализировать карту» на основе тренировочных данных — ошибка: небесные стволы, земные ветви, месячные указатели, десять божеств и определение структуры — это правила, которые должны выполняться специализированным движком.

mcp-luopan упаковывает весь движок (расчет → десять божеств → структура → удача → отчет → уточняющие вопросы) в 3 инструмента MCP. LLM больше не выдумывает, а:

1. Получает точные данные карты (четыре столпа / структура / удача / пять элементов / десять божеств).

2. Формулирует ответ на основе реальных данных (способность рассказывать истории остается за LLM, факты — за движком).

3. Поддерживает контекстные уточняющие вопросы (5 уточняющих вопросов / TTL 2 часа, управляется сессией на бэкенде).

Типичные сценарии использования

Сценарий А: Анализ для друга в Claude Code / Claude Desktop

Вы (пользователь):

Помоги мне проанализировать мужчину, родившегося 15 марта 1991 года в 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.

Сценарий Б: Пакетный анализ

Вы хотите запустить «распределение структур 100 знаменитостей»:

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

Движок находится в облаке и не нагружает ваш локальный процессор; скрипт занимается только IO-оркестрацией.

Сценарий В: Встраивание в OpenClaw / Feishu Agent

Зарегистрируйте luopan в mcp.json для OpenClaw, предоставьте агенту (например, боту Feishu) доступ к этим 3 инструментам, и агент сможет рассчитывать карты и отвечать на вопросы в диалоге Feishu. Текущий локальный OpenClaw уже работает по этой модели; развертывание облачного OpenClaw — в планах (TODO).

Сценарий Г: LLM Eval / Эксперименты с промпт-инжинирингом

Хотите протестировать языковой стиль разных моделей при интерпретации карт или настроить «личность Лопаня» для агента — бэкенд всегда возвращает одни и те же фактические данные, различия моделей полностью проявляются на уровне естественного языка.

Быстрый старт: 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-хоста)

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

Ожидается увидеть 3 инструмента: luopan_analyze / luopan_chat / luopan_session_info.

3. Регистрация в MCP-хосте

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

Чтобы агент мог использовать его, в tools.allow агента не нужно явно перечислять luopan_* — OpenClaw по умолчанию позволяет всем агентам видеть все серверы из mcp.json.

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=женщина).

Поля ответа (выборочно):

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)

Оптимистичная проверка состояния сессии — не обращается к бэкенду. У бэкенда нет отдельного интерфейса состояния сессии, авторитетное решение принимается на основе ошибки luopan_chat. Этот инструмент предназначен для помощи агенту в локальном отслеживании того, «истекла ли сессия».

Параметры конфигурации

Пример полного диалога с 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 — временно добавьте "HTTPS_PROXY": "" в env в mcp.json, чтобы принудительно отключить прокси; или проверьте белый список правил прокси.

session_expired

Сессия истекла через 2 часа или закончились уточняющие вопросы. Попросите LLM заново вызвать luopan_analyze для создания новой карты.

LLM постоянно пытается «интерпретировать самостоятельно» и не вызывает инструменты

Добавьте в системный промпт строку:

Любые вопросы о Бацзы/карте судьбы/структуре/десяти божествах/удаче нельзя отвечать на основе тренировочных данных; необходимо сначала вызвать luopan_analyze для создания карты, а затем использовать поля pattern / report / dayun и другие, возвращаемые инструментом, для формулировки ответа.

В ответе встречаются непонятные термины (столп дня/десять божеств)

Это нормально — это терминология. Попросите LLM читать напрямую report.tier1 (уровень карточки) и report.tier2 (уровень подробного разбора), эти два уровня уже являются описанием на понятном языке; tier3 — это технический уровень для тех, кто хочет углубиться.

Известные ограничения

• Не опубликован в PyPI: необходимо локально pip install -e ., нельзя pip install mcp-luopan.

• Не инициализирован git: текущая директория mcp-luopan еще не имеет git init, нет управления версиями.

• Сессия в памяти: при перезапуске бэкенда uvicorn все сессии теряются (пользователю придется создавать карту заново).

• Зависимость от облачного SiliconFlow: при недействительном AI_API_KEY или ограничении скорости SiliconFlow все инструменты чата будут зависать по тайм-ауту.

• Нет изоляции параллелизма: при одновременном использовании одного и того же session_id в нескольких чатах порядок не гарантируется.

Как работает бэкенд (краткий обзор архитектуры)

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.