Bibliomantic MCP Server

Instructions

Implementation Reference

• enhanced_bibliomantic_server.py:61-105 (handler)

  Primary enhanced handler and registration for the i_ching_divination MCP tool. Performs divination using EnhancedBiblioManticDiviner and formats response with traditional I Ching elements and ethical disclaimers.
  @mcp.tool() def i_ching_divination(query: Optional[str] = None) -> str: """ Enhanced I Ching divination with traditional three-coin method and changing lines. MAINTAINS EXACT BACKWARD COMPATIBILITY while providing richer content. """ logger.info("Performing enhanced I Ching divination") result = diviner.perform_simple_divination() if result["success"]: # Enhanced formatting while maintaining compatibility response = f"""🎋 **I Ching Divination** **Hexagram {result['hexagram_number']}: {result['hexagram_name']}** {result['interpretation']} **Method:** Traditional three-coin method using cryptographically secure randomness""" # Add enhanced features if available if result.get("enhanced") and result.get("changing_lines"): response += f"\n**Changing Lines:** {', '.join(map(str, result['changing_lines']))}" response += f"\n**Purpose:** Philosophical reflection and contemplation\n\n{ETHICAL_DISCLAIMER}" if query: response += f"\n\n**Your Question:** {query}" if ENHANCED_MODE and hasattr(diviner, 'enhanced_engine') and diviner.enhanced_engine: # Add contextual guidance context = diviner.enhanced_engine.infer_context_from_query(query) contextual_guidance = diviner.enhanced_engine.get_contextual_interpretation( result['hexagram_number'], context ) response += f"\n\n**Contextual Guidance:** {contextual_guidance}" else: response += f"\n\n**Guidance:** Consider how this hexagram's wisdom might offer perspective on your situation." logger.info(f"Generated enhanced hexagram {result['hexagram_number']} - {result['hexagram_name']}") return response else: error_msg = f"Divination failed: {result.get('error', 'Unknown error')}" logger.error(error_msg) return f"{error_msg}\n\n{BRIEF_DISCLAIMER}"
• bibliomantic_fastmcp.py:51-89 (handler)

  Standard handler and registration for the i_ching_divination MCP tool in the main FastMCP server. Delegates to BiblioManticDiviner for core logic.
  @mcp.tool() def i_ching_divination(query: Optional[str] = None) -> str: """ Perform I Ching divination using traditional three-coin method. Generates a random hexagram with interpretation for guidance. Uses cryptographically secure randomness to simulate coin tosses. Args: query: Optional question or context for the divination Returns: Formatted hexagram reading with interpretation """ logger.info("Performing I Ching divination") result = diviner.perform_simple_divination() if result["success"]: response = f"""🎋 **I Ching Divination** **Hexagram {result['hexagram_number']}: {result['hexagram_name']}** {result['interpretation']} *Generated using traditional three-coin method with cryptographically secure randomness.* *This follows the authentic I Ching methodology as described in ancient Chinese divination.*""" if query: response += f"\n\n**Your Question:** {query}" response += f"\n\n**Guidance:** Consider how this hexagram's wisdom applies to your specific situation." logger.info(f"Generated hexagram {result['hexagram_number']} - {result['hexagram_name']}") return response else: error_msg = f"Divination failed: {result.get('error', 'Unknown error')}" logger.error(error_msg) return error_msg
• bibliomantic_fastmcp_ethical.py:57-97 (handler)

  Ethical variant handler and registration for the i_ching_divination MCP tool. Similar to standard but includes prominent ethical disclaimers.
  @mcp.tool() def i_ching_divination(query: Optional[str] = None) -> str: """ Perform I Ching divination using traditional three-coin method. Generates a random hexagram with interpretation for philosophical guidance. Uses cryptographically secure randomness to simulate coin tosses. Args: query: Optional question or context for the divination Returns: Formatted hexagram reading with interpretation and ethical disclaimer """ logger.info("Performing I Ching divination with ethical safeguards") result = diviner.perform_simple_divination() if result["success"]: response = f"""🎋 **I Ching Divination** **Hexagram {result['hexagram_number']}: {result['hexagram_name']}** {result['interpretation']} **Method:** Traditional three-coin method using cryptographically secure randomness **Purpose:** Philosophical reflection and contemplation {ETHICAL_DISCLAIMER}""" if query: response += f"\n\n**Your Question:** {query}" response += f"\n\n**Guidance:** Consider how this hexagram's wisdom might offer perspective on your situation, while remembering this is a tool for reflection, not prediction." logger.info(f"Generated hexagram {result['hexagram_number']} - {result['hexagram_name']} with ethical disclaimer") return response else: error_msg = f"Divination failed: {result.get('error', 'Unknown error')}" logger.error(error_msg) return f"{error_msg}\n\n{BRIEF_DISCLAIMER}"
• divination.py:108-138 (helper)

  Core helper method perform_simple_divination in BiblioManticDiviner class, called by all tool handlers. Generates hexagram using iching.generate_hexagram_by_coins().
  def perform_simple_divination(self) -> dict: """ Perform a standalone divination without query integration. Useful for testing the divination system or providing pure I Ching consultations without Claude integration. Returns: Dictionary containing complete divination information """ try: hexagram_number, hexagram_name, interpretation = self.iching.generate_hexagram_by_coins() return { "success": True, "hexagram_number": hexagram_number, "hexagram_name": hexagram_name, "interpretation": interpretation, "formatted_text": self.iching.format_divination_text( hexagram_number, hexagram_name, interpretation ) } except Exception as e: logger.error(f"Simple divination failed: {str(e)}") return { "success": False, "error": str(e), "fallback_wisdom": "The path forward requires inner contemplation and patient observation." }
• enhanced_divination.py:97-135 (helper)

  Enhanced version of perform_simple_divination in EnhancedBiblioManticDiviner, used in enhanced server. Supports changing lines and richer content.
  def perform_simple_divination(self) -> dict: """Enhanced simple divination with backward compatibility""" try: if self.use_enhanced and self.enhanced_engine: result = self.enhanced_engine.generate_enhanced_divination() hexagram = result['primary_hexagram'] return { "success": True, "hexagram_number": hexagram.number, "hexagram_name": hexagram.english_name, "interpretation": hexagram.general_meaning, "formatted_text": f"I Ching Hexagram {hexagram.number} - {hexagram.english_name}: {hexagram.general_meaning}", "enhanced": True, "changing_lines": result.get('changing_lines', []) } else: # Fallback to basic hexagram_number, hexagram_name, interpretation = self.iching.generate_hexagram_by_coins() return { "success": True, "hexagram_number": hexagram_number, "hexagram_name": hexagram_name, "interpretation": interpretation, "formatted_text": self.iching.format_divination_text( hexagram_number, hexagram_name, interpretation ), "enhanced": False } except Exception as e: logger.error(f"Enhanced simple divination failed: {str(e)}") return { "success": False, "error": str(e), "fallback_wisdom": "The path forward requires inner contemplation and patient observation." }