mcp-luopan

'나침반(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, 백엔드 세션 관리)

주요 사용 시나리오

시나리오 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 / 페이슈(Feishu) Agent에 임베딩

luopan을 OpenClaw의 mcp.json에 등록하고, 특정 에이전트(예: 페이슈 봇)에게 이 3가지 도구에 대한 권한을 부여하면, 에이전트가 페이슈 대화창에서 사용자에게 명반을 봐주고 추가 질문을 받을 수 있습니다. 현재 로컬 OpenClaw는 이 모드로 실행된 바 있으며, 클라우드 OpenClaw 배포는 TODO 상태입니다.

시나리오 D: LLM Eval / 프롬프트 엔지니어링 실험

모델별 명반 해석 언어 스타일을 테스트하거나, 특정 에이전트의 '나침반 페르소나'를 조정하고 싶을 때—백엔드는 항상 동일한 사실 데이터를 반환하므로, 모델 간의 차이가 자연어 계층에서 완전히 드러납니다.

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 .

설치 후 .venv/bin/ 내에 mcp-luopan 실행 파일이 생성됩니다.

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을 차단함—mcp.json의 env에 "HTTPS_PROXY": ""를 추가하여 프록시를 강제 종료하거나, 프록시 규칙 화이트리스트를 확인하십시오.

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 속도 제한 시 모든 chat 도구가 타임아웃됩니다.

• 동시성 격리 미지원: 동일한 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.