luopan_analyze

Instructions

Implementation Reference

• src/mcp_luopan/server.py:43-97 (handler)

  The main handler function for the luopan_analyze tool. It validates input parameters (year, month, day, hour, gender), calls the backend HTTP client (LuopanClient.analyze), handles errors, and returns a formatted JSON response containing the session_id, chart data, and next-step instructions.

  @mcp.tool()
  async def luopan_analyze(year: int, month: int, day: int, hour: int, gender: int) -> str:
      """Produce a full destiny-chart reading for a birth moment.
  
      IMPORTANT: Before calling, you MUST confirm with the user:
        - solar calendar date (阳历): year / month / day
        - birth hour 0-23 (时辰)，if unsure warn them the reading will be less precise
        - gender: 1 for 男, 0 for 女
  
      Output contains: session_id (used for follow-ups), sizhu (the chart),
      pattern (格局), report (a three-tier reading), dayun (luck pillars),
      highlights (notable traits), partner (气场画像), female (if gender=0),
      and followup_remaining (starts at 5).
  
      When presenting to the user, translate technical terms (e.g. 十神, 格局名称)
      into plain language like "气场 / 画像 / 此局". The public persona is 罗盘
      (fengshui compass), never expose the words 八字 / 子平.
  
      Sessions expire in 2 hours and allow up to 5 follow-up questions via luopan_chat.
  
      Args:
          year: Birth year, e.g. 1991
          month: Birth month 1-12
          day: Birth day 1-31
          hour: Birth hour 0-23
          gender: 1 = 男, 0 = 女
      """
      if not (1900 <= year <= 2100):
          return _err("bad_input", f"年份 {year} 超出支持范围 1900-2100")
      if not (1 <= month <= 12):
          return _err("bad_input", f"月份 {month} 无效")
      if not (1 <= day <= 31):
          return _err("bad_input", f"日期 {day} 无效")
      if not (0 <= hour <= 23):
          return _err("bad_input", f"时辰 {hour} 无效，应为 0-23")
      if gender not in (0, 1):
          return _err("bad_input", f"性别 {gender} 无效，应为 0 (女) 或 1 (男)")
  
      try:
          data = await _client.analyze(year, month, day, hour, gender)
      except LuopanServiceError as e:
          if e.kind == "service_unreachable":
              return _err("service_unreachable", f"罗盘后端未就绪：{_config.api_base}。请先启动 uvicorn。")
          return _err(e.kind, e.detail)
      except Exception as e:  # noqa: BLE001
          logger.exception("luopan_analyze unexpected error")
          return _err("internal", str(e))
  
      if isinstance(data, dict) and data.get("session_id"):
          data.setdefault("followup_remaining", 5)
      data["_next_step"] = (
          "向用户概述 report.tier1，抛 2-3 个 highlights 作为切入点，"
          "并保存 session_id 至 memory/sessions.json。追问时调 luopan_chat。"
      )
      return _dump(data)

• src/mcp_luopan/server.py:43-43 (registration)

  The @mcp.tool() decorator registers luopan_analyze as a tool with FastMCP on the 'luopan' server instance.

  @mcp.tool()

• src/mcp_luopan/server.py:35-36 (helper)

  Helper function (_err) that formats error responses as JSON strings, used by the handler for validation and service errors.

  def _err(kind: str, hint: str) -> str:
      return json.dumps({"error": kind, "hint": hint}, ensure_ascii=False)

• src/mcp_luopan/server.py:39-40 (helper)

  Helper function (_dump) that formats the final response dict as a pretty-printed JSON string, used by the handler to return results.

  def _dump(payload: dict) -> str:
      return json.dumps(payload, ensure_ascii=False, indent=2)

• src/mcp_luopan/client.py:51-55 (helper)

  The HTTP client method (LuopanClient.analyze) that sends the birth data to the upstream backend's /api/analyze endpoint. Called by the luopan_analyze handler.

  async def analyze(self, year: int, month: int, day: int, hour: int, gender: int) -> dict[str, Any]:
      return await self._post(
          "/api/analyze",
          {"year": year, "month": month, "day": day, "hour": hour, "gender": gender},
      )