swebsy/mcp

Read the current page structure and addressable component target paths. Call this BEFORE editing a named or relative page component that is not the current selection. The default `sections` read lists every top-level section with its target path — enough to pick the one to edit. When copying content between components, use `detail: full` WITH the `targetPath` of the one section you're copying, not a whole-page read. Also call it AFTER applying edits to verify the result.

Replace ALL top-level sections of the CURRENTLY SELECTED page with a generated list of components. This OVERWRITES the page — it does NOT create a new page (use `create_page`) and does NOT append a single section (use `add_section`). Use when the user asks to build/replace/redesign an entire page. Each top-level component should be wrapped in a container.

Add a linked INSTANCE of an existing symbol (see list_symbols) to the CURRENT page. The instance stays in sync with the symbol main and every other instance — the way to reuse one navbar/footer/CTA across pages. Select the target page with select_page first.

Capture a styled screenshot of the current page at a fixed viewport, written under .swebsy-agent/screenshots/. Returns the file path. Scope it with `targetPath` when verifying ONE section — a whole-page PNG downscales so far that component detail is unreadable.

Create a site and open it in Studio. Pass name to set its internal Studio/Home name (default "My Website"). Omit templateId for Swebsy's standard blank site; provide an installed template ID to import that template unchanged. Then poll swebsy_status until editorReady is true and siteId matches before editing.

Delete one managed asset from the open site's asset gallery. By default this refuses assets referenced by any page, shared symbol, style, or site setting; call swebsy_list_assets first. force:true also clears live component references and should be used only when that is explicitly intended.

Delete a symbol. Every instance is DETACHED first and stays on its page as a plain component — nothing disappears from the site. To also remove the copies, delete_section them.

Turn ONE symbol instance on the current page back into a plain component, so it can be edited on its own. The symbol and its other instances stay linked. Use it when one page needs a variant of the shared navbar/footer.

Export the site to .swebsy-agent/exports/. Static files via the site exporter and/or the project JSON (with assets). Returns `outDir`, the exported page paths, and per-kind file counts — verify a build by grepping those HTML files.

DEV-ONLY template authoring: export the open site as a template into the local content catalog. This installs the template (meta, project.json, static preview, thumbnail), harvests every component marked via swebsy_mark_block into the block catalog (light+dark thumbnails included), and rebuilds both catalogs. Requires the local content server (pnpm -F @swebsy/content run dev). Passing an existing `id` replaces that template; omitting `id` re-exports to the template this site was last exported as (or derives an id from `name`). Returns { id, blocksHarvested }.

Load the static Swebsy builder guidance (component system, theme classes, conventions) that the in-app AI Builder is primed with.

List managed assets in the open site with whole-project usage counts. References are checked across every page, shared symbols, styles, and site settings. Use imagesOnly:true and unusedOnly:true before deleting unused gallery images.

List the pre-built block catalog (ids + labels) available to insert_block.

List the project's pages (id, name, fileName, section count, which one is selected). Call this instead of guessing a page name for select_page or link_page.

List saved sites newest-first as metadata only: IDs, internal names, status, timestamps, template ID, page count, and whether each site is open.

List the available deep-guidance skills (animation, page-composition, copywriting, forms, nav) with one-line summaries.

List the project's SYMBOLS (reusable components that stay in sync across every page). Returns each symbol's id, name, component type, instance count, and how many pages use it, plus a `health` report of BROKEN linkage: `orphans` (copies whose main was deleted — editing them changes nothing elsewhere), `unregistered` (instances the main doesn't list back, so edits propagate one way only) and `ghosts`. Repair any of it by calling promote_to_symbol on one affected section. Use before add_symbol_instance to find the symbol id.

Refresh and list installed site templates with names, descriptions, tags, fonts, preview URLs, and thumbnail URLs. Works from Home or Studio.

DEV-ONLY template authoring: mark the component at `targetPath` (from read_page) as a harvestable block, or update/remove its annotation. Marked sections become catalog blocks when the template is exported (see swebsy_export_template). Selection rule: mark the smallest meaningful designed composition, not an atomic content element. Never mark a lone image, video, heading, paragraph, divider, spacer, or a wrapper whose only meaningful child is one of those. A valid block combines at least two complementary content/layout elements (for example image + copy, heading + CTA, or label + stats), or i…

Open a saved site by ID in the paired tab and return its metadata. Idempotent if it is already open. Poll swebsy_status for the expected siteId and editorReady before editing.

Promote an existing component into a reusable SYMBOL so it can be shared, in sync, across pages. Pass its `targetPath` from read_page (e.g. the navbar or the CTA band). Also REPAIRS broken linkage (see list_symbols → health): re-promoting an orphaned copy rebuilds its main and re-links every other copy of it, and re-promoting a symbol registers instances it had lost. Returns the symbol id (for add_symbol_instance) and a `repaired` count; copies whose structure has diverged too far are reported as `detached` — delete_section + add_symbol_instance those instead.

Read the currently selected component (type, classes, attributes, text). Secrets are never surfaced.

Re-apply tool calls reverted by swebsy_undo, oldest-undone last. Cleared by any new edit.

Rename a saved site's internal Studio/Home name. This does not change its SEO or public title settings.

Rename a symbol (the name shown in the Symbols panel).

Select a page in the connected Studio project.

Start a pairing session. Returns a single-use `pairUrl` — give it to the user to click; opening it connects their Studio tab automatically. (Also returns the raw `code`/`port` for manual entry.)

Report bridge status, siteName, selected page, and editorReady, plus a short theme summary (fonts, default color mode, brand colors). After creating or opening a site, wait until editorReady is true and siteId matches the expected site before editing.

Revert your own last editing tool call(s) this session (add/edit/delete/move/duplicate_section, insert_block, update_settings, page tools…), newest first. Does NOT undo symbol or asset tools. Refuses (returns `blocked`) when a page, CSS or settings it would restore has been edited since, so hand edits are never overwritten. Paths may shift — call read_page afterwards.

Upload a local image, font, video, audio or PDF file into the open site and return its `assetId`, `src` and a `usage` snippet. Images go in the asset library for `image` components, video for `video` components (`attributes.src`), audio for `audio`, PDFs as a link `href`; fonts are stored for `update_settings` fonts.custom. This is the ONLY way to get your own imagery (screenshots, logos, textures, mockups) into a site — an `image` with an empty src gets a random stock photo instead. Reads the file from the agent's own filesystem, so pass a path you can see (for example a screenshot you just c…

Rename a page and/or change its URL slug — the Pages panel's rename. Links that pointed at the old `./slug.html` on every page follow the new slug. The home page's `index` slug is locked (its display name can still change).

Update site settings — SEO title/description, site URL, structured data (JSON-LD), per-page SEO overrides, language/direction, theme tokens (light + dark), type scale, animation defaults, Google and uploaded fonts, dark mode toggle, site-wide custom CSS for component-level restyling (globalTheme.customTailwindConfig), favicon, robots.txt/sitemap/service worker/security headers/image optimization (performance), analytics ids, custom head/body code (advanced), the "Made with Swebsy" badge (branding) and the deploy target (deploy). Provide ONLY the fields that change. `general`/`seo` are SITE-WID…

Wrap a run of sibling components in one new element, optionally with a semantic tag — e.g. put everything between the navbar and footer in `<main>`, or a footer symbol in `<footer>`. The wrapped components keep their ids, id-styles and symbol links. ALWAYS use this to add a wrapper; re-sending the components through `edit_section`/`replace_page_content` loses their styles. Paths shift — call `read_page` before the next path-based edit.