nexus_weave_enchanted_async

Start an asynchronous job to weave WorkFlowy data back into your outline structure, returning a job ID for tracking progress and managing the process.

Instructions

Start an async NEXUS ENCHANTED WEAVE job (WEAVE T2 back into Workflowy ETHER) and return a job_id for status polling and cancellation.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`nexus_tag`	Yes
`dry_run`	No

Implementation Reference

src/workflowy_mcp/server.py:1610-1655 (handler)

MCP tool handler: Launches detached weave_worker.py process for asynchronous enchanted terrain weaving into Workflowy. Includes validation to prevent misuse with JSON paths.

    name="nexus_weave_enchanted_async",
    description=(
        "Start an async NEXUS ENCHANTED WEAVE job (WEAVE T2 back into Workflowy ETHER) "
        "and return a job_id for status polling and cancellation."
    ),
)
async def nexus_weave_enchanted_async(
    nexus_tag: str,
    dry_run: bool = False,
) -> dict:
    """Start ENCHANTED TERRAIN weave as a detached background process.

    Launches weave_worker.py as a separate process that survives MCP restart.
    Progress tracked via .weave.pid and .weave_journal.json files.
    
    Use mcp_job_status() to monitor progress (scans directory for active PIDs).

    NOTE: nexus_tag must be a NEXUS TAG (e.g. "my-arc-tag"), **not** a JSON file path.
    If you have a JSON file that describes nodes you want to create, use
    workflowy_etch or workflowy_etch_async instead.
    """
    client = get_client()

    # Detect misuse: nexus_tag looks like a JSON file path
    lowered = (nexus_tag or "").lower()
    if lowered.endswith(".json") or "/" in nexus_tag or "\\" in nexus_tag:
        return {
            "success": False,
            "error": (
                "nexus_weave_enchanted_async expects a NEXUS TAG (e.g. 'my-arc-tag'), not a JSON file path.\n\n"
                "If you have a JSON file representing nodes to create, use ETCH instead:\n\n"
                "  workflowy_etch(\n"
                "    parent_id='...',\n"
                "    nodes_file='E:...\\your_nodes.json'\n"
                "  )\n\n"
                "or the async variant:\n\n"
                "  workflowy_etch_async(\n"
                "    parent_id='...',\n"
                "    nodes_file='E:...\\your_nodes.json'\n"
                "  ).\n"
            ),
        }

    # Use detached launcher (survives MCP restart)
    return client.nexus_weave_enchanted_detached(nexus_tag=nexus_tag, dry_run=dry_run)

src/workflowy_mcp/client/api_client_nexus.py:1325-1328 (helper)

Client method called by handler: Launches the detached weave process using subprocess.Popen on weave_worker.py

def nexus_weave_enchanted_detached(self, nexus_tag: str, dry_run: bool = False) -> dict[str, Any]:
    """Launch ENCHANTED WEAVE as detached process."""
    return self._launch_detached_weave(mode='enchanted', nexus_tag=nexus_tag, dry_run=dry_run)

src/workflowy_mcp/weave_worker.py:161-162 (helper)
The detached worker script entry point which calls the synchronous nexus_weave_enchanted (bulk_import_from_file) to perform the actual weaving.
```
log_worker(f"Calling nexus_weave_enchanted for tag={nexus_tag}...")
result = await client.nexus_weave_enchanted(nexus_tag=nexus_tag, dry_run=dry_run)
```

src/workflowy_mcp/server.py:1610-1655 (registration)

MCP tool registration via @mcp.tool decorator defining the tool name, description, and parameters.

    name="nexus_weave_enchanted_async",
    description=(
        "Start an async NEXUS ENCHANTED WEAVE job (WEAVE T2 back into Workflowy ETHER) "
        "and return a job_id for status polling and cancellation."
    ),
)
async def nexus_weave_enchanted_async(
    nexus_tag: str,
    dry_run: bool = False,
) -> dict:
    """Start ENCHANTED TERRAIN weave as a detached background process.

    Launches weave_worker.py as a separate process that survives MCP restart.
    Progress tracked via .weave.pid and .weave_journal.json files.
    
    Use mcp_job_status() to monitor progress (scans directory for active PIDs).

    NOTE: nexus_tag must be a NEXUS TAG (e.g. "my-arc-tag"), **not** a JSON file path.
    If you have a JSON file that describes nodes you want to create, use
    workflowy_etch or workflowy_etch_async instead.
    """
    client = get_client()

    # Detect misuse: nexus_tag looks like a JSON file path
    lowered = (nexus_tag or "").lower()
    if lowered.endswith(".json") or "/" in nexus_tag or "\\" in nexus_tag:
        return {
            "success": False,
            "error": (
                "nexus_weave_enchanted_async expects a NEXUS TAG (e.g. 'my-arc-tag'), not a JSON file path.\n\n"
                "If you have a JSON file representing nodes to create, use ETCH instead:\n\n"
                "  workflowy_etch(\n"
                "    parent_id='...',\n"
                "    nodes_file='E:...\\your_nodes.json'\n"
                "  )\n\n"
                "or the async variant:\n\n"
                "  workflowy_etch_async(\n"
                "    parent_id='...',\n"
                "    nodes_file='E:...\\your_nodes.json'\n"
                "  ).\n"
            ),
        }

    # Use detached launcher (survives MCP restart)
    return client.nexus_weave_enchanted_detached(nexus_tag=nexus_tag, dry_run=dry_run)

WorkFlowy MCP Server