webcake-landing-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

An MCP (Model Context Protocol) stdio server that teaches an AI agent how to build a complete Webcake landing-page source JSON from a requirement, validate it, and persist it to a Webcake backend. The server is knowledge + validation + persistence — it does not render pages. The AI agent assembles the full { page, popup, settings, options, cartConfigs } object; create_page saves it and then AUTO-PUBLISHES (build host + publish_html) so the preview renders; the EDIT tools (update_page/add_section/patch_page) save source-only (re-publish via publish_page to refresh the rendered build).

Published to npm as webcake-landing-mcp; runs via node dist/index.js or npx -y webcake-landing-mcp.

Commands

npm run build      # tsc -> dist/ AND copies src/**/*.json -> dist/ (scripts/copy-assets.mjs; both steps matter)
npm run smoke      # offline self-test of factory + validator; MUST print "ALL GOOD". Run after every change.
npm run dev        # tsc --watch
npm start          # node dist/index.js (start the stdio server)
node dist/index.js serve --port 8787   # remote Streamable-HTTP server (Claude custom connector); or PORT env
npm run release    # interactive local publish (scripts/release.js): build+smoke gate, npm version, OTP publish, gh release
npm run release:dry   # dry-run the release flow without publishing

There is no unit-test runner or linter — npm run smoke is the test gate. It exercises the pure logic (factory skeletons, validator, and every LIBRARY example) without an MCP transport. prepublishOnly runs build && smoke, so a broken smoke test blocks publishing.

Build rules (must follow when editing src/)

1. Each element is ONE descriptor. An element's docs + container/field flags + defaultName + factory seed + example all live in a single object in src/domains/landing/elements/<category>.ts. CONTAINER_TYPES/FIELD_TYPES/the catalog/createElement all DERIVE from these — adding or editing a type is a one-file change. Only src/domains/landing/page-schema.json's elementType enum must be updated alongside; smoke re-checks it against the descriptor keys, so schema drift fails the gate.
2. Gate every change: npm run build && npm run smoke — must end with ALL GOOD. Editing the schema requires a rebuild (dist/domains/landing/page-schema.json is runtime data copied by the build).
3. New tools go in a src/tools/*.ts group via server.tool(...), return through the text() helper (src/mcp/response.ts), and register the name in src/domains/landing/instructions.ts + docs/tools.md(+.vi) + the README at-a-glance table + the webcake-landing skill. New HTTP goes in src/persistence/webcake-client.ts.
4. Mutating tools default to dry_run=true and return a JWT-redacted request preview; only the network when dry_run===false.
5. stdout is the MCP channel — log with console.error only. ESM/Node16 — relative imports end in .js. Secrets come from WEBCAKE_JWT env only; the repo is public.