Bibliomantic MCP Server

Instructions

Implementation Reference

• bibliomantic_fastmcp.py:51-88 (handler)

  Primary handler function for the i_ching_divination tool, decorated with @mcp.tool(). Executes the divination by calling BiblioManticDiviner.perform_simple_divination() and formats the response.
  @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-96 (handler)

  Handler variant with ethical disclaimers. Similar logic to primary handler.
  @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}"
• enhanced_bibliomantic_server.py:61-104 (handler)

  Enhanced handler with additional features like changing lines and contextual guidance, falls back to basic.
  @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}"
• divination.py:108-137 (helper)

  Core helper method in BiblioManticDiviner class that performs the simple divination by calling IChing.generate_hexagram_by_coins() and returns the result dictionary used by all handlers.
  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." }
• iching.py:355-388 (helper)

  Core randomness and hexagram generation logic using cryptographically secure secrets module to simulate three-coin tosses, maps to hexagram from database.
  def generate_hexagram_by_coins(self) -> Tuple[int, str, str]: """ Generate a hexagram using the traditional three-coin method. Simulates throwing three coins six times to generate six lines, building a hexagram from bottom to top as in traditional practice. Returns: Tuple containing (hexagram_number, name, interpretation) """ lines = [] # Generate six lines (bottom to top) for _ in range(6): # Throw three coins: heads = 3, tails = 2 coin_sum = sum(3 if secrets.randbelow(2) else 2 for _ in range(3)) # 6 or 9 are changing lines, but for simplicity we use stable lines # 6 (three tails) = yin line = 0 # 9 (three heads) = yang line = 1 # 7 (two tails, one head) = yang line = 1 # 8 (two heads, one tail) = yin line = 0 if coin_sum in [6, 8]: # Yin line lines.append('0') else: # coin_sum in [7, 9] - Yang line lines.append('1') # Convert binary to hexagram number (1-64) binary_string = ''.join(reversed(lines)) # Traditional order: bottom to top hexagram_number = self._binary_to_hexagram_number(binary_string) hexagram_data = self.hexagrams[hexagram_number] return hexagram_number, hexagram_data["name"], hexagram_data["interpretation"]