workflowy_list_nodes

Retrieve hierarchical nodes and tasks from WorkFlowy outlines. Specify a parent ID to list children or omit it for root-level items.

Instructions

List WorkFlowy nodes (omit parent_id for root)

Input Schema

TableJSON Schema

Name	Required	Description	Default
`parent_id`	No

Implementation Reference

src/workflowy_mcp/server.py:194-228 (handler)

MCP tool handler function for 'workflowy_list_nodes'. Accepts optional parent_id, creates NodeListRequest, handles rate limiting, calls WorkFlowyClient.list_nodes(), and returns formatted dict with nodes (serialized) and total count.

@mcp.tool(name="workflowy_list_nodes", description="List WorkFlowy nodes (omit parent_id for root)")
async def list_nodes(
    parent_id: str | None = None,
) -> dict:
    """List WorkFlowy nodes.

    Args:
        parent_id: ID of parent node to list children for
                   (omit or pass None to list root nodes - parameter won't be sent to API)

    Returns:
        Dictionary with 'nodes' list and 'total' count
    """
    client = get_client()

    request = NodeListRequest(  # type: ignore[call-arg]
        parentId=parent_id,
    )

    if _rate_limiter:
        await _rate_limiter.acquire()

    try:
        nodes, total = await client.list_nodes(request)
        if _rate_limiter:
            _rate_limiter.on_success()
        return {
            "nodes": [node.model_dump() for node in nodes],
            "total": total,
        }
    except Exception as e:
        if _rate_limiter and hasattr(e, "__class__") and e.__class__.__name__ == "RateLimitError":
            _rate_limiter.on_rate_limit(getattr(e, "retry_after", None))
        raise

src/workflowy_mcp/models/requests.py:52-57 (schema)

Pydantic input schema model NodeListRequest used by the tool handler, defining the optional parentId parameter.

class NodeListRequest(BaseModel):
    """Request parameters for listing nodes."""

    parentId: str | None = Field(None, description="Parent node ID to list children for")

src/workflowy_mcp/client/api_client.py:143-167 (helper)

Supporting method in WorkFlowyClient that executes the HTTP GET request to the WorkFlowy API /nodes endpoint, parses the response into WorkFlowyNode objects, and computes total count.

async def list_nodes(self, request: NodeListRequest) -> tuple[list[WorkFlowyNode], int]:
    """List nodes with optional filtering."""
    try:
        # exclude_none=True ensures parent_id is omitted entirely for root nodes
        # (API requires absence of parameter, not null value)
        params = request.model_dump(exclude_none=True)
        response = await self.client.get("/nodes", params=params)
        response_data: list[Any] | dict[str, Any] = await self._handle_response(response)

        # Assuming API returns an array of nodes directly
        # (Need to verify actual response structure)
        nodes: list[WorkFlowyNode] = []
        if isinstance(response_data, dict):
            if "nodes" in response_data:
                nodes = [WorkFlowyNode(**node_data) for node_data in response_data["nodes"]]
        elif isinstance(response_data, list):
            nodes = [WorkFlowyNode(**node_data) for node_data in response_data]

        total = len(nodes)  # API doesn't provide a total count
        return nodes, total
    except httpx.TimeoutException as err:
        raise TimeoutError("list_nodes") from err
    except httpx.NetworkError as e:
        raise NetworkError(f"Network error: {str(e)}") from e

WorkFlowy MCP Server