MCP 3: create the document

[deanleigh]

Third increment of #129. Turns the dry run into a real import. This is the one that writes, so it carries the risk.

The tool

Same call as #131 with dryRun: false:

updoc-import { workflowAlias, sourceFile, documentName, parentId }
  → { documentId, extracted{}, warnings[] }

Save, not publish. Publishing stays with the session flow and human review — decision 4 on #106.

No blueprintId parameter: a workflow folder already belongs to exactly one blueprint.

How it writes

Through delegation — the handler calls the chained developer server (@umbraco-cms/mcp-dev) rather than reimplementing Management API calls. The AI never sees the chained tools.

An import is naturally a composite: scaffold, apply the mapping, create. One tool invocation, no LLM round-trips in between.

The rule that must not be broken

update-document and raw PUT /document/{id} do full replacement. Every top-level field omitted is set to null. Three incidents behind this: 115 group tours (July 2026), TTM5086 (June), Sights media loss (April). The classic symptom is template going null and the page 404ing while the data looks perfect in the backoffice.

Delegating does not exempt anything. A composite tool calling the destructive endpoint is exactly as destructive as calling it directly.

Use update-document-properties and update-block-property. See memory/reference_mcp_surgical_edits.md.

Depends on #41

This is the increment that needs the apply logic — the part that fills a page from a mapping, currently living twice in up-doc-action.ts and up-doc-collection-action.element.ts, both browser-bound.

import-facts.ts proved the shared-module pattern works and is imported by both bridge files, but it is one small function. The rest is the real work, and it is the most likely thing here to run long.

Done when

• Imports a real tour end to end and returns the document key
• The created page matches one made through the dialog, field for field
• Nothing is published
• A failure mid-import leaves no half-made page, or says clearly that it did
• No call anywhere in the path uses the full-replacement endpoint

Open

Partial failure: delete the half-made document, or leave it flagged? Worth deciding before building rather than after the first one happens.

Part of #129. Follows #131. Depends on #41.