AI-driven import: let AI sessions run Create from Source (endpoint / UpDoc MCP server)

[deanleigh]

Future work / nice to have. No build committed yet. This issue captures the design so it is not lost.

Full design record: planning/AI_DRIVEN_IMPORT_ROUTES.md (30 July 2026).

The problem

Importing a tour is the only step an AI session cannot do.

Everything after import already runs over the Umbraco MCP server: content fixes, publish, all of it. Everything before it is a human driving the Create from Source dialog. The Tailored Travel migration has ~135 tours left, each starting with the same manual sequence.

Goal: "make TTM5175" becomes a single instruction to an AI session. One page at a time, human review between each. Batch imports are explicitly not wanted.

The key architectural fact

The workflow is a recipe, not a machine. The engine that executes it is split:

• Extract and transform: server-side C# (already done)
• Fill in the page and create the document: TypeScript in the browser dialog, duplicated across the two bridge files (Extract duplicated apply logic from the two bridge files #41)

There is no server-side "run the workflow" command. Any automation route must either drive the browser or relocate the page-filling half.

Routes considered

Route	What	Effort	Notes
0	Playwright "keep the document" variant of smoke-test-pdf.spec.ts	~1 day	Interim migration aid. No regrets. Works now.
A	C# import endpoint (POST /updoc/.../import) + thin MCP tool	~1 month	Port TS apply logic to C#. Proper long-term home. Plain HTTP API for any consumer.
B	UpDoc MCP server orchestrates via existing APIs, reusing apply logic extracted into a shared TS module	~1-2 weeks	Same pattern as the Umbraco MCP server. Fixes #41 as a side effect. No plain API.
C	Session-only skill making the same HTTP calls	days	Private stepping stone, not a product.
D	Mapping endpoint + generic Umbraco MCP writes	ruled out	No blueprint scaffold over MCP; block-grid writes via generic tools are unsafe.

Routes are compatible: B first, A later if demand for a plain API appears. The MCP tool would swap its internals for one endpoint call, invisibly.

Decisions made

1. Umbraco-only, forever. No multi-CMS ambitions.
2. Mirror the Umbraco MCP server's conventions exactly: TypeScript, npm/npx distribution, API user client credentials in env vars. First implementation step is reading its source.
3. Same repo, own folder for the MCP server (e.g. src/UpDoc.Mcp/), versioned with the endpoint contract.
4. Save, not publish. Import returns the document key; publish stays with the session flow and human review.
5. No blueprintId parameter: a workflow folder already belongs to exactly one blueprint.
6. Dialog switchover to any new endpoint is out of scope for a first build (that is the eventual endgame of Route A only).
7. Client-facing use (Claude Desktop + Umbraco MCP + UpDoc MCP against the live site) is real but "later, deliberately": needs packaged guardrails, a tightly scoped API user, and a human eye in the loop.

Current recommendation

• Now: nothing built. The planning doc is the deliverable.
• When migration pressure bites: Route 0.
• When ready to invest: Route B.
• Route A: only if demand for a plain HTTP API materialises.

The playing field is moving (Umbraco now has editor and developer MCP servers). The core idea is durable because no one else's MCP server will ever run UpDoc workflows; only packaging conventions might need to follow the ecosystem. Re-check the ecosystem state before building.

Open questions

• What should import return beyond the document key (warnings, unmapped fields, unmatched sections)?
• Partial-failure behaviour: delete the half-made document or leave it flagged?
• Does the shared apply module (Extract duplicated apply logic from the two bridge files #41 extraction) run cleanly in Node, or do browser-only dependencies run deeper than the initial scan suggested?
• Confirm the client-credentials API user flow against UpDoc's backoffice-secured controller routes.

Related: #41 (duplicated apply logic), #42 / #43 (TypeScript markdown converter bugs, relevant to Route A's Markdig divergence).

[deanleigh]

Update, 3 August 2026

The design above still holds. Three things have changed since it was written, all of which shorten the distance to Route B.

Imports now produce a more complete page

#124 shipped in 17.5.3.5: the source PDF attaches itself to the created document via a media picker mapping. That was previously a manual step after every single import.

This matters to the automation question because the argument for a route is partly "how much hand-finishing remains per page". One less step, ~135 times.

One piece of the #41 extraction is already done

Route B depends on pulling the apply logic out of the two bridge files into a shared module. #124 did this for its own slice: src/UpDoc/wwwroot/App_Plugins/UpDoc/src/import-facts.ts is imported by both up-doc-action.ts and up-doc-collection-action.element.ts.

It is a small piece, but it establishes the pattern and proves the shared-module approach works in the browser context. The rest of the apply logic can follow the same shape.

Route 0 is closer than "about a day"

The planning doc costed Route 0 as adding a keep-the-document switch to smoke-test-pdf.spec.ts. Since then:

• smoke-test-mirror.spec.ts was added, which already drives the full create flow against the Tailored Travel mirror and asserts the result
• TARGET=mirror switches the E2E target, credentials included

So Route 0 is now closer to "add a flag that skips the afterEach cleanup" than a day of work. Whether that is worth doing depends on whether the migration starts before Route B does.

Open question worth answering before choosing

The doc asks what import should return beyond the document key. Worth revisiting with fresh eyes: now that a page comes out more complete, the useful return may be a list of what was not filled, so the session knows what to fix rather than having to inspect everything.

[deanleigh]

Field notes from the Tailored Travel migration

From driving Create from Source with Playwright across ~40 tailored tour imports. This is the first input from actually doing the work at volume, and it sharpens the design in three ways.

Thirteen mechanical steps

Navigate, Create from Source, pick document type, pick blueprint, type a name, open the media picker, enter a folder, search, upload, verify auto-selection, Choose, wait for extraction, Create. No judgement in any of them.

sourceFile accepting a file path — as create-media already does with sourceType: "filePath" — removes the entire media-picker sequence on its own.

Every failure was the browser, not UpDoc

Stale JS asset hashes 404ing in a cold browser profile. Cookie injection. A generated file holding live session cookies needing deletion after every run. A browser window left open blocking the next run.

None of that is import logic. It exists only to drive a UI.

This is the strongest argument yet for Route B over Route 0: Route 0 keeps every one of those failure modes permanently, because it is browser automation by definition. It remains the right interim move if migration starts before a server exists, but it is a stopgap whose costs do not decrease with use.

dryRun changes the shape of the design

The design above treats import as a single act. It should be two:

updoc-list-workflows
  → [{ alias, name, documentTypeAlias, sourceType }]

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

dryRun returns the extraction without creating anything. Extraction is the one step that genuinely needs a human or AI eye, and today the only way to see it is to click through a wizard you are about to submit anyway. Making review a call in its own right is better than what was designed here.

(Note blueprintId is not needed as a parameter — a workflow folder already belongs to exactly one blueprint. Decision 5 above.)

warnings[] answers the open question

The comment above asked what import should return beyond the document key, and guessed "what was not filled". The field notes confirm it with a real failure: Organiser Name silently fell back to the blueprint placeholder while every other organiser field extracted fine.

Silent fallback is the dangerous case. The page looks complete and is not. A warnings[] entry for every field that took a blueprint default would have caught it immediately.

What stays outside the server

Extraction still needs judging, and the server should not try to be clever about it. Two examples from a single tour:

• The price caveat ("Price based on twin share…") extracts correctly but lands at the end of the Extras body when it belongs in the summary slot
• The Organiser Name fallback above

Return what was extracted; let the caller decide. Members, public access, redirects and image selection are deliberately human calls — no API wanted.

Also worth having

• Idempotency on re-importing the same source, or at minimum a clear error rather than a duplicate