HNPX SDK

Instructions

Implementation Reference

• src/hnpx_sdk/tools.py:291-321 (handler)

  The handler function that implements the create_sequence tool. It parses the HNPX document, builds attributes for the new sequence element, uses the _create_element helper to add it under the specified parent, saves the document, and returns the new element's ID.

  def create_sequence(
      file_path: str,
      parent_id: str,
      location: str,
      summary: str,
      time: Optional[str] = None,
      pov: Optional[str] = None,
  ) -> str:
      """Create a new sequence element
  
      Args:
          file_path (str): Path to the HNPX document
          parent_id (str): ID of the parent chapter element
          location (str): Location description
          summary (str): Sequence summary text
          time (Optional[str]): Time indicator (e.g., "night", "next day", "flashback")
          pov (Optional[str]): Point-of-view character identifier
      """
      tree = hnpx.parse_document(file_path)
  
      attributes = {"location": location}
      if time:
          attributes["time"] = time
      if pov:
          attributes["pov"] = pov
  
      new_id = _create_element(tree, parent_id, "sequence", attributes, summary)
  
      hnpx.save_document(tree, file_path)
  
      return f"Created sequence with id {new_id}"

• src/hnpx_sdk/server.py:19-19 (registration)

  Registers the create_sequence function as an MCP tool in the FastMCP application.

  app.tool()(tools.create_sequence)

• src/hnpx_sdk/tools.py:227-264 (helper)

  Shared helper function called by create_sequence (and other create_* functions) to perform hierarchy validation, generate unique ID, create the element with attributes and summary, and return the new ID.

  def _create_element(
      tree: etree.ElementTree,
      parent_id: str,
      element_tag: str,
      attributes: dict,
      summary_text: str,
  ) -> str:
      """Generic element creation helper"""
      parent = hnpx.find_node(tree, parent_id)
      if parent is None:
          raise NodeNotFoundError(parent_id)
  
      # Check hierarchy
      valid_hierarchy = {
          "book": ["chapter"],
          "chapter": ["sequence"],
          "sequence": ["beat"],
          "beat": ["paragraph"],
      }
  
      if (
          parent.tag not in valid_hierarchy
          or element_tag not in valid_hierarchy[parent.tag]
      ):
          raise InvalidHierarchyError(parent.tag, element_tag)
  
      # Generate unique ID
      existing_ids = hnpx.get_all_ids(tree)
      new_id = hnpx.generate_unique_id(existing_ids)
      attributes["id"] = new_id
  
      # Create element
      element = etree.SubElement(parent, element_tag, **attributes)
      summary = etree.SubElement(element, "summary")
      summary.text = summary_text
  
      return new_id