MCP site_import: browser-executed Super Import — needs a store-access decision

[spcxai2025]

The goal

Let an MCP connector run the Super Import pipeline — the same thing the Site Import modal does — so a site can be handed to Instatic programmatically instead of a human dragging a ZIP.

I have this working locally and would happily open a PR, but it lands on an architectural decision that is yours to make rather than mine. Details below; the question is at the bottom.

(Context: I opened #539 earlier today, a small site-import fix. Same area, unrelated change.)

What turned out to need no decision

Two things I expected to have to ask about are already settled by precedent in the repo, so I followed it rather than inventing anything:

• Transport. uploadMediaTool already accepts bytes inline as base64 (with a byte-budget→character-budget guard). I matched that exactly. Its https sourceUrl variant isn't offered here, because this tool runs in the browser and a cross-origin fetch would be CORS-blocked for most hosts — a host-downloaded URL would need server-side staging first, which seems like a follow-up rather than a prerequisite.
• Capability. data.import already exists and is what POST /admin/api/cms/import/archive requires, so site_import requires data.import + site.structure.edit (it creates pages and style rules, not just data). No new capability.

Browser execution is clearly correct here: the pipeline commits through createSiteImportAdapter into the live editor store and parseHtml needs a real DOMParser, which is precisely what runtime/types.ts documents execution: 'browser' for.

One thing your gates caught that I'd have missed: SITE_MUTATION_TOOLS. A whole-site import is the largest write there is, and the comment on that set describes the exact failure — "the tool would still report the ids it meant to create, so the caller saw success and an empty document."

The blocker

The architecture gate rejects a cycle:

src/admin/pages/site/store/store.ts
  → src/admin/pages/site/agent/index.ts
  → src/admin/pages/site/agent/agentSliceConfig.site.ts
  → src/admin/pages/site/agent/executor.ts
  → src/admin/modals/SiteImport/shared/createSiteImportAdapter.ts   (→ store.ts)

createSiteImportAdapter.ts:20 and importPlanning.ts:27 both import { useEditorStore } from '@site/store/store', and the agent executor is reachable from that store — so any executor import of them closes the loop.

A call-time dynamic import does not help: madge --circular follows dynamic imports too.

Options, and what I'd suggest

The executor already avoids this for its own store access, via the storeRef.ts registration indirection (setAgentStoreApi / getAgentStoreApi).

1. Apply that same indirection to createSiteImportAdapter / importPlanning — have them reach the store through a registered API instead of importing it. No duplication, uses your existing pattern, and the modal keeps working unchanged. It does mean touching two existing modal modules' store access, which is why I stopped rather than just doing it.
2. A separate registry slot (setSiteImportRunner) populated from an always-mounted admin entry point. No change to existing modules, but adds indirection for one tool and raises a "what if unregistered" case.
3. Reimplement the adapter inside the agent against getAgentStoreApi. No cycle, but duplicates ~240 lines of adapter surface — which reads like exactly the kind of thing CONTRIBUTING's "update the source of truth and all callers" is telling me not to do.

I'd suggest (1), but it's your call on where import machinery should live.

Question

Would you accept (1) — moving createSiteImportAdapter / importPlanning onto the storeRef indirection — as part of adding this tool? If you'd rather have (2), or would rather this feature not exist at all, equally useful to know before I spend more on it.

Happy to open the PR either way; the rest is done (schema, tool registration, browser executor, 15 tests, docs in agent.md + site-import.md, bun run build and bun run lint clean, and the only failing tests are this cycle plus three bookkeeping gates — SSOT schema map, tool count, module size budget).