## Summary
This improves how coding agents discover, author, verify, and audit
Webstudio projects through the CLI and MCP. The work focuses on making
agents more reliable with less context, while keeping edits semantic and
Builder-editable.
## What changes for users
- Agents can verify dynamic bindings after authoring and receive
actionable diagnostics when expressions, resources, scopes, or component
props do not line up.
- Agents can create complete resource-backed runtime UI through a
semantic operation instead of coordinating fragile low-level edits.
- MCP discovery and command output are compact by default, with
pagination and focused verbose detail when an agent needs more context.
- Asset, style, token, font, page, and component inspection provides
stronger usage context so agents can preserve the existing design
system.
- Rendered audits provide better evidence for responsive behavior,
geometry, contrast, generated-build size, and large-project runs.
- Cross-project MCP workflows can run from a manifest with explicit
mutation approval, isolated failures, resumable progress, and persistent
checkpoints.
- Project-specific agent onboarding is clearer and does not add
telemetry.
- Packaged CLI releases gain stronger smoke verification for install,
MCP startup, authoring, preview, screenshots, and audits.
## Reliability and architecture
- Runtime operation output schemas are generated from the runtime
registry and remain client-compatible.
- Project-build exports are consolidated around architectural boundaries
instead of feature-by-feature convenience entry points.
- HTTP, preview, screenshot, and project-session paths are hardened for
longer autonomous workflows.
- Craft compatibility work is read-only and provenance-aware; it does
not silently opt ordinary projects into Craft behavior.
- A minimal-context evaluation harness exercises key workflows with a
weaker model and stores bounded, privacy-safe evidence.
## Validation
- Rebased on the latest `origin/main`.
- `pnpm lint`
- Repository-wide `oxfmt --check`
- CLI typecheck and full test suite: 773 tests passed.
- Project-build typecheck and full test suite: 1,866 tests passed.
- Protocol typecheck and full test suite: 83 tests passed.
- HTTP client tests: 23 passed.
- CSS data tests: 3,620 passed, 1 skipped.
- Focused Builder tests: 67 passed.
- Package-boundary, generated API, and generated documentation checks
passed.
- Minimal-context agent evaluations passed for authenticated
resource-backed UI and design-system-aware responsive authoring.
## Summary
This improves how agents discover, author, inspect, and verify Webstudio
projects while reducing unnecessary MCP context usage.
## What changed
- Adds an **Agents** section to Project Settings with ready-to-run setup
commands and client configuration for Claude Code, Codex, Cursor, and VS
Code.
- Makes large list and schema responses compact and paginated by
default, with **verbose** available when complete records or diagnostics
are needed.
- Applies consistent compact output to assets, instances, styles, design
tokens, CLI schemas, and project-session metadata.
- Returns actionable expression warnings for props, resources, and
Collection bindings, including unknown variables and risky render-time
mutation resources.
- Improves Collection expression guidance so agents can bind array items
with the correct scoped variables.
- Reports rendered audit outcomes explicitly as complete, partial,
confirmation-required, or failed.
- Expands runtime output schemas so MCP clients can validate responses
reliably.
- Strengthens the packaged CLI smoke workflow with a realistic
seven-page stdio MCP scenario.
## Architecture
- Consolidates `project-build` from 65 file-oriented entrypoints to 11
architecture-owned surfaces.
- Separates the core model, contracts, runtime authoring, transfer,
state, project sessions, MCP, visual tooling, persistence codecs, and
authenticated server services.
- Isolates Node-only JSX evaluation from browser-safe transfer utilities
and authenticated server modules.
- Keeps persistence codecs independent from authenticated database
services, preventing unrelated module initialization.
- Defines shared instance-path types once and reuses them across runtime
modules.
- Preserves Immer initialization through explicit package side-effect
metadata.
- Adds package tests that prevent a return to source-file entrypoints or
generic exposure of Node-only surfaces.
## Validation
- Full repository checks, tests, typechecks, generated-file checks, and
fixtures
- All 163 Builder test files and 2,141 tests
- All 71 project-build test files and 1,794 tests
- Lint and package-boundary validation
- Full packed CLI release smoke test, including install, preview, agent
setup, seven-page stdio MCP workflow, rendered audit, and structured
commands
## What changed
- Return structured validation issues with stable codes, complete field
paths, constraints, and minimal correction examples.
- Preserve validation details through the Builder API, CLI, MCP, local
project sessions, and tRPC errors.
- Explain invalid expressions, JSX fragments, page selectors, component
inputs, asset updates, and project settings in terms an agent can act
on.
- Remove stack frames and credentials from parser details before
exposing them.
- Keep concise human-readable errors while making the complete
structured issues available to agents.
## Why
Agents previously received vague errors without enough information to
repair a request. They could repeat the same invalid call or require
manual intervention.
## User impact
CLI and MCP agents can now identify the exact invalid field, understand
the constraint, see a valid example, and retry with a corrected request.
## Validation
- Focused runtime, MCP, CLI, API, and tRPC validation tests.
- Structured error propagation tests across local and server execution.
- Typechecks and generated contract verification.
## What changed
- Add an `insert-collection` MCP and CLI operation for creating repeated
UI from array or object data.
- Create the Collection, iterable binding, current-item/current-key
parameters, repeated item structure, and descendant bindings atomically.
- Accept literal JSON data or expressions backed by project variables
and resource results.
- Support `collectionItem` and `collectionItemKey` expressions inside
the repeated Webstudio JSX item.
- Return the created Collection, item root, and parameter IDs for
immediate inspection and follow-up edits.
- Document when agents should use Collection for lists, grids, cards,
rows, options, tabs, and other repeated content.
## Why
Building a data-driven list previously required several low-level
operations and manual handling of Collection's internal parameters. A
missed step could leave a partially configured or incorrectly scoped
Collection.
## User impact
Agents can turn resource or variable data into a correctly bound
repeated layout in one operation, then inspect and refine the result
normally.
## Validation
- Real-world local CLI test created and rendered a three-product
Collection from project data.
- Tests cover literal arrays, objects, resource expressions, item/key
bindings, malformed fragments, ID conflicts, server execution, and
project-session behavior.
- 176 focused tests, project-build typecheck, and generated-doc checks
pass after rebasing onto current `main`.
Improves CLI and MCP reliability across project synchronization, asset
editing, imports, audits, and clipboard workflows.
## Changes
- Keeps asset filename and description updates after session refresh.
- Prevents intermittent Immer patch errors during consecutive MCP
mutations.
- Prevents false edit conflicts caused by stale local session state.
- Preserves asset uploads without treating them as redundant metadata
updates.
- Exposes editable asset filenames consistently through MCP.
- Imports project assets correctly when copying projects between
environments.
- Supports refreshing partially available project snapshots.
- Keeps MCP operations working when optional project data is
unavailable.
- Produces clearer compatibility errors when the API and CLI versions
differ.
- Makes rendered audits more resilient when individual screenshots fail.
- Prevents rendered audits from hanging while starting browser captures.
- Handles denied clipboard permissions without uncaught browser errors.
- Improves copy and paste reliability for pages, components, styles, and
animations.
## Verification
- Asset uploader tests and typechecking pass.
- Focused asset workflow E2E passes.
- Complete E2E shard 1 passes.
- Realistic MCP subagent test confirms:
- Asset filename and description persist after refresh.
- Consecutive mutations work without manual refresh.
- No Immer patch error occurs.
- No false conflict occurs.
- Original asset values can be restored successfully.
This PR expands Webstudio MCP and CLI into a more complete agent
authoring interface. Agents can discover project capabilities, edit real
Webstudio content, use data/resources, verify visual output, and report
useful issues when workflows fail.
## MCP User Capabilities
- Create, update, duplicate, reorder, and delete pages.
- Create pages from templates and manage reusable page templates.
- Inspect project pages, instances, props, styles, assets, variables,
resources, and metadata.
- Insert Webstudio components and authored JSX fragments into pages.
- Edit text, props, styles, breakpoints, design tokens, and CSS
variables.
- Update page metadata, SEO fields, redirects, marketplace metadata, and
project settings.
- Create and use static data variables.
- Create and use dynamic resources fetched over HTTP.
- Use REST, GraphQL, and built-in system resources in authored pages.
- Bind data variables and resources to visible page content.
- Create resource-backed pages such as sitemap XML, structured SEO data,
and API-driven content sections.
- Preview current project state without requiring a publish step.
- Capture screenshots for visual verification.
- Verify responsive designs across desktop, tablet, and mobile
breakpoints.
- Use screenshot diff and OCR-style checks to inspect rendered output.
- Reset and refresh local MCP project state when needed.
- Discover available CLI/MCP commands from generated manuals.
- Use clearer examples for resources, data variables, JSX authoring,
previewing, and visual checks.
- Read marketplace product metadata without requiring a full project
snapshot.
- Get safer guidance when using low-level patch tools.
- Get a ready-to-copy Discord report template when MCP/CLI behavior is
confusing or broken.
Oleg Isonen