create_paragraph

Add paragraph elements to HNPX fiction documents with configurable narrative modes including narration, dialogue, and internal monologue.

Instructions

Create a new paragraph element

Args: file_path (str): Path to the HNPX document parent_id (str): ID of the parent beat element text (str): Paragraph text content mode (str): Narrative mode - one of: "narration" (default), "dialogue", "internal" char (Optional[str]): Character identifier (required when mode="dialogue")

Input Schema

TableJSON Schema

Name	Required	Default
`file_path`	Yes
`parent_id`	Yes
`text`	Yes
`mode`	No	narration
`char`	No

Implementation Reference

src/hnpx_sdk/tools.py:341-382 (handler)

The handler function that implements the create_paragraph tool. It parses the HNPX document, validates the parent is a beat, generates a unique ID, creates a paragraph element with mode and optional char attributes, sets the text content, saves the document, and returns a confirmation message.

def create_paragraph(
    file_path: str,
    parent_id: str,
    text: str,
    mode: str = "narration",
    char: Optional[str] = None,
) -> str:
    """Create a new paragraph element

    Args:
        file_path (str): Path to the HNPX document
        parent_id (str): ID of the parent beat element
        text (str): Paragraph text content
        mode (str): Narrative mode - one of: "narration" (default), "dialogue", "internal"
        char (Optional[str]): Character identifier (required when mode="dialogue")
    """
    tree = hnpx.parse_document(file_path)

    attributes = {"mode": mode}
    if char:
        attributes["char"] = char
    elif mode == "dialogue":
        raise MissingAttributeError("char")

    # Create the paragraph with text content
    parent = hnpx.find_node(tree, parent_id)
    if parent is None:
        raise NodeNotFoundError(parent_id)

    if parent.tag != "beat":
        raise InvalidParentError(parent.tag, "beat")

    existing_ids = hnpx.get_all_ids(tree)
    new_id = hnpx.generate_unique_id(existing_ids)
    attributes["id"] = new_id

    paragraph = etree.SubElement(parent, "paragraph", **attributes)
    paragraph.text = text

    hnpx.save_document(tree, file_path)

    return f"Created paragraph with id {new_id}"

src/hnpx_sdk/server.py:21-21 (registration)
Registers the create_paragraph function as an MCP tool using the fastmcp app.tool() decorator.
```
app.tool()(tools.create_paragraph)
```
src/hnpx_sdk/server.py:2-2 (registration)
Imports the tools module containing the create_paragraph function.
```
from . import tools
```

HNPX SDK