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