MCP server

Read this token’s site, compact page summaries, urls, resources and baseRevisions. urls are the absolute addresses to hand the person, on this server: admin (the site in the admin), editor (add ?pageId=<id> to open a page), draftPreview (the draft as the editor sees it, for a signed-in person; put a page path before the ?) and publicSite (the live site, null when it has no address), in the default locale, and locales, the draftPreview and publicSite homes of every site locale by its code (such as /en-us/?site=…); never build these links yourself. resources lists every resource of the site as a full URI, libretto://site/<siteId>/<path> with this site's id, ready for read_resources. baseRevisions holds every document revision keyed exactly as an apply_ops batch's baseRevisions (history, pages, designSystem, tree:<pageId>, ...), ready to pass through unchanged.

No arguments: call it with {}.

Lazily discover operations by name or by a word of their description. Each comes in one line by default: its name, its first sentence, its permission, how it changes the site, the confirmation it needs and whether dry_run_ops can run it; cursor pages through them (nextCursor). Name operations in names (or pass schemas: true) for their input schema, one worked example input and the documents they read and write, and outputSchemas: true for their output schema. Use the schemas and examples to build apply_ops batches. Only the operations this token may run are listed (its role, its workspace owner's grant and its design-system levels count); one listed may still refuse a particular input, such as a token in an area you only view: access.read answers your levels.

Read a bounded set of Libretto resource URIs from this site (at most 16 per call), each the full libretto://site/<siteId>/<path> with this site's id (libretto://site/<siteId>/pages, never libretto://site/pages). The paths are context, pages, catalog, design-system (the design system's index; ?tokens=<group>,<group> for token values), presets, motion (scene recipes and diagnosis codes), tickets (your reported problems), regions (header and footer trees), versions (published versions), pending-changes (what the next publish ships), tree/<pageId> (a page's outline, one node with ?node=<id>&depth=<n>, the whole tree with ?full=true), outline/<pageId> (the outline, as tree/<pageId>), motion/<pageId> (a page's scenes and findings), component/<key> (the cells of a design-system component such as button, ?variant=&state=&own=true to filter), catalog/<type> (one node type, such as catalog/ds.button), preset/<presetId> (one preset's tree, ?kind=<kind>) and versions/<versionId> (a version's pages); site_context.resources lists the ones this site has. A path may end with a query, such as component/button?variant=primary&state=hover&own=true, design-system?tokens=color.palette,type or tree/<pageId>?node=<nodeId>&depth=1: each resource that takes one runs the registry read it names, with the same parameters. tree/<pageId> answers the page's outline by default (one line per node: id, kind and type, name, variant, theme and the start of its text; styles=font-size,padding-top adds those declarations to each line, depth=2 stops at that depth, cursor and limit page the lines), ?node=<nodeId>&depth=1 one node with its props and styles, ?full=true the whole document. design-system answers its index; with tokens, components, css or embeds it answers only those parts unless index=true. One answer holds at most 40,000 characters of resources: the ones past it come back in deferred with their size, to read in another call. No network URLs are fetched.

Apply one confirmed, revision-checked operation batch to this token’s site; returns inverses, findings and structured conflicts. A batch with a motion.* operation also reports the scene problems of each touched page as motion.<code> findings; run motion.diagnose { pageId } to read them on their own, and prefer motion.applyRecipe (recipes and knobs from motion.listRecipes or the motion resource) to hand-written scenes. The answer is a receipt: revisions, the undo call, each result in short (a tree commit as the ids of the nodes it changed, a design-system write as the names of the overrides it changed and at most 5 warnings) and the findings counted by severity and rule with the first 20; pass answer: "full" for every result and finding in full, the inverse ops included. A design-system write answers its change, not the whole draft: the overrides it adds, changes or removes (changes), every error, the warnings about what it changed and the count of every warning by reason; read the stylesheet with render_preview and the rest with designSystem.read. designSystem.lint and designSystem.diff answer a summary unless their input has full: true. The arguments are the batch itself, at the top level (not wrapped in a batch or file key): format: "libretto.batch", v: 1, requestId (a fresh UUID; resending the same batch with it replays the stored answer), baseRevisions (copy site_context.baseRevisions; every document an operation writes must be named) and operations (1 to 100 { name, input, ref? }), with optional dryRun, confirmed (["destructive"], ["publish"]) and answer ("receipt" or "full"). discover_operations gives each operation's input schema and a worked example input.

Validate a complete operation batch with transaction rollback; publication and provider effects are refused. A dry run reports each touched page's scene problems as motion.<code> findings (the reasons of motion.diagnose: target-missing, target-ambiguous, stateful-target, overlap, empty-range, hidden-at-rest, never-matches). The answer is a receipt: revisions, the undo call, each result in short (a tree commit as the ids of the nodes it changed, a design-system write as the names of the overrides it changed and at most 5 warnings) and the findings counted by severity and rule with the first 20; pass answer: "full" for every result and finding in full, the inverse ops included. A design-system write answers its change, not the whole draft: the overrides it adds, changes or removes (changes), every error, the warnings about what it changed and the count of every warning by reason; read the stylesheet with render_preview and the rest with designSystem.read. designSystem.lint and designSystem.diff answer a summary unless their input has full: true. The arguments are the batch itself, at the top level (not wrapped in a batch or file key): format: "libretto.batch", v: 1, requestId (a fresh UUID; resending the same batch with it replays the stored answer), baseRevisions (copy site_context.baseRevisions; every document an operation writes must be named) and operations (1 to 100 { name, input, ref? }), with optional dryRun, confirmed (["destructive"], ["publish"]) and answer ("receipt" or "full"). discover_operations gives each operation's input schema and a worked example input.

Lease the next bounded step of an assistant job and get what it needs: the brief, the summaries of the steps already reported, the steps left (counting this one; 1 means this step must end with done: true) and the job deadline. A step is yours for 5 minutes (leaseUntil). Calling again while the lease is live answers the same stepId, so a lost answer is safe to ask for again; after the lease lapses the step expires and the next call leases a new stepId. A queued job starts on the first call. A job that is cancelled, failed, waiting for review or applied answers job_not_running: stop working on it.

Report the result of a leased step: a summary, the operation calls this step adds to the job's proposal (the operations array of an apply_ops batch, without the batch fields; the server dry-runs the proposal so far plus these calls under your session, and refuses them with job_fragment_invalid and the dry-run issues, the step staying leased so you can fix and report it again), and done. done: false means call job_next_step for the next step; done: true ends the work and the job waits for the operator's review. Nothing is applied to the site: the operator applies the proposal. Reporting the same report again answers the first answer; a different report for an already reported step is job_step_report_conflict (409). A step whose lease lapsed answers job_step_expired.

See a page of this site: its draft by default, or with target "live" what the public site serves now (the active published version as a visitor gets it, named in the answer's liveVersion), to confirm a publish or a rollback; a page that version lacks is page_not_live, a site never published site_not_live. mode "document" (default) answers a summary of its render: outlines of the rendered page and of its header and footer (regions; one line per node, text cut short), the node and scene counts and the sizes of the parts left out; with jobId, also the design-system declarations the proposal changes. find: "<words>" adds the nodes of the page, header and footer whose text holds those words, with their whole text: use it to check a text rather than reading the document. include names the parts to add, each large: "render" (the splash.render/1 document, about 110,000 characters on a large page), "regions" (the header and footer documents), "scenes", "designSystemCss" (the compiled stylesheet, about 240,000); mode "screenshot" a JPEG for one device (desktop 1440 px, tablet 820 px or mobile 390 px wide), with every image loaded: the whole page by default, the first screen with area "viewport", or the box of one node with crop { nodeId } (an id from the outline or the regions resource: a header or footer node, an instance by its own id; node_not_drawn when the node is absent or has no size at that width). The answer's text gives width, height, regionHeight and truncated: a region over 24 million pixels (about 16,600 px tall on desktop, 29,200 on tablet, 61,500 on mobile) comes back as its top part with truncated true; crop a lower node to see the rest. locale shows the page in another of the site's locales (site_context lists them; absent: the default locale), theme under one of its design-system themes (absent: the theme the site's rules pick) and colorScheme as a light or dark browser (screenshot only); an unknown locale or theme is refused (locale_unsupported, theme_unknown). With jobId (document mode, draft target only) the job's proposal runs as a dry run and the page is rendered as the proposal would leave it; the draft is not changed. Bounded by 30000 ms: past it the answer is the error code render_timeout.

Compare a full-page screenshot of a draft page with a reference image: one of this site's media library (referenceMediaId) or an image at a public https URL (referenceUrl: fetched once, not stored, no redirects, an image content type, at most 20 MB; a refused URL answers reference_url_refused). Name exactly one. The page is captured like render_preview's screenshot, with the same device, locale, theme, colorScheme, area and crop (compare one section with crop { nodeId }); truncated tells whether the capture was cut. The reference is resized to the capture's width and compared with the visual review's metric: ratio (share of differing pixels, a pixel differs when a channel differs by more than the channel tolerance), heightMismatch (capture minus reference height, in pixels) and the verdict words ("identical" at or below the identical ratio, else "differs (ratio 0.123)"). Bounded by 30000 ms.

Report a problem to the platform owner when Libretto stops you or the person you work for: a bug, a missing capability, a refusal that looks wrong (category "refusal"), a docs gap (category "docs"), or anything else. Give a one-line title and a Markdown body (what you were doing, for whom, what blocked you); add steps, expected and actual (paste the error code and message), the requestId of the failing batch and the pageId when you have them. severity "blocking" means the person cannot go on. It is ticket.create in one call, without a batch: it changes nothing on the site. The answer is the ticket; read your tickets and the owner's close notes later at the tickets resource. At most 20 tickets an hour per person (ticket_rate_limited); a pageId that is not a page of this site is ticket_page_unknown.