@typeroll/mcp-server 0.45.40 → 0.45.42

package/dist/tools/forms.js

@@ -60,7 +60,8 @@ export const formTools = [
             fields: z.array(fieldSchema).min(1).optional(),
             steps: z.array(stepSchema).min(1).optional(),
             submit_text: z.string().optional(),
-            success_message: z.string().optional(),
+            success_message: z.string().optional().describe('Shown after the final step. May contain basic HTML (links, emphasis); it is sanitized.'),
+            success_redirect_url: z.string().optional().describe('After the final step, send the visitor to this absolute http(s) URL or root-relative path (for example a booking or thank-you page) instead of showing success_message. Pass an empty string to clear.'),
             target: targetSchema,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -81,7 +82,8 @@ export const formTools = [
                 fields: z.array(fieldSchema).optional(),
                 steps: z.array(stepSchema).optional(),
                 submit_text: z.string().optional(),
-                success_message: z.string().optional(),
+                success_message: z.string().optional().describe('Shown after the final step. May contain basic HTML (links, emphasis); it is sanitized.'),
+                success_redirect_url: z.string().optional().describe('After the final step, send the visitor to this absolute http(s) URL or root-relative path (for example a booking or thank-you page) instead of showing success_message. Pass an empty string to clear.'),
                 target: targetSchema,
             }),
         },

package/dist/tools/page-blocks.js

@@ -3,9 +3,8 @@
 // (override with `version`).
 //
 // The AI agent uses these to author block-mode pages directly. For
-// HTML-mode pages, `convert_page_to_blocks` is the bridge — call with
-// `dry_run: true` first to preview, then `dry_run: false, switch_mode:
-// true` to commit.
+// HTML-mode pages, `convert_page_to_blocks` returns a preview only.
+// It never writes. A person accepts that preview in the page editor.
 import { z } from 'zod';
 import { ok, withErrorBoundary, versionParam } from './helpers.js';
 const blockSchema = z.object({
@@ -194,32 +193,26 @@ export const pageBlockTools = [
     },
     {
         name: 'set_page_mode',
-        description: 'Safely switch a page\'s content_mode between "blocks" and "html". Always snapshots a revision before the flip so the previous state is restorable. HTML → blocks with `convert: true` also runs the heuristic converter so the page starts with a populated tree. Blocks → HTML drops the block tree (the revision retains it). Prefer this over `update_page patch={content_mode}` because that bypasses snapshotting.',
+        description: 'Safely switch a page\'s content_mode between "blocks" and "html". Always snapshots a revision before the flip so the previous state is restorable. HTML → blocks does not convert or rewrite the body. Blocks → HTML drops the block tree (the revision retains it). Prefer this over `update_page patch={content_mode}` because that bypasses snapshotting. Automatic HTML-to-blocks conversion is preview-only; a person accepts it in the page editor.',
         inputSchema: {
             page_id: z.string(),
             to: z.enum(['blocks', 'html']).describe('Target mode.'),
-            convert: z.boolean().optional().describe('When going to blocks: run the htmlToBlocks heuristic on html_content. Ignored for blocks → html.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/mode`, { to: args.to, convert: args.convert ?? false }, v(args.version));
+            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/mode`, { to: args.to }, v(args.version));
             return ok(res);
         }),
     },
     {
         name: 'convert_page_to_blocks',
-        description: 'Heuristically convert a page\'s html_content into a block tree. By default runs as dry_run and returns the proposed blocks without writing. Pass dry_run: false to apply, and switch_mode: true to flip content_mode to "blocks" so the renderer uses the new tree. For a safer one-call switch with revision snapshot, use `set_page_mode` with `convert: true` instead.',
+        description: 'Preview a heuristic conversion of a page\'s html_content into a block tree. Always returns the proposal, including unconverted text, classes and markup, and does not write. A person accepts the preview in the page editor. This tool cannot change content_mode or replace the body.',
         inputSchema: {
             page_id: z.string(),
-            dry_run: z.boolean().optional().describe('Default true. When true, returns the proposed tree without writing.'),
-            switch_mode: z.boolean().optional().describe('When applying (dry_run=false), flip content_mode to "blocks". Default false.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks/convert`, {
-                dry_run: args.dry_run ?? true,
-                switch_mode: args.switch_mode ?? false,
-            }, v(args.version));
+            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks/convert`, { dry_run: true }, v(args.version));
             return ok(res);
         }),
     },

package/dist/tools/partials.js

@@ -56,15 +56,14 @@ export const partialTools = [
     },
     {
         name: 'set_partial_mode',
-        description: 'Switch a header, footer, or free partial between HTML and native blocks through the revision-safe mode endpoint. To author a native partial deterministically: update_partial with blocks + save:true, then set_partial_mode to="blocks", then read_partial and verify the returned mode/tree. Set convert:true only for heuristic HTML-to-block conversion.',
+        description: 'Switch a header, footer, or free partial between HTML and native blocks through the revision-safe mode endpoint. To author a native partial deterministically: update_partial with blocks + save:true, then set_partial_mode to="blocks", then read_partial and verify the returned mode/tree. This does not convert HTML into blocks.',
         inputSchema: {
             partial_id: z.string(),
             to: z.enum(['blocks', 'html']),
-            convert: z.boolean().optional(),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.post(siteId, `partials/${encodeURIComponent(args.partial_id)}/mode`, { to: args.to, convert: args.convert ?? false }, v(args.version));
+            const res = await client.post(siteId, `partials/${encodeURIComponent(args.partial_id)}/mode`, { to: args.to }, v(args.version));
             return ok(res);
         }),
     },

package/dist/tools/search.js

@@ -6,7 +6,7 @@ function v(version) {
 export const searchTools = [
     {
         name: 'search_pages',
-        description: 'Search page bodies by literal substring or regex. Returns up to 500 matches each with an excerpt around the first hit. Use this to scope a redesign or a bulk replacement before running it. ' +
+        description: 'Search saved page content by literal substring or regex: block data in block-mode pages, html_content in HTML-mode pages, and content-type text fields (the same text bulk_replace_text edits). Returns up to 500 matches, each with the matching field (blocks, html_content or fields.<name>) and an excerpt around the first hit. Use this to scope a redesign or a bulk replacement before running it. ' +
             'Pass either "contains" (case-insensitive literal) or "regex" (JS regex source without slashes) — not both. ' +
             'Example: search_pages({"contains": "kontakta oss"}) finds every page mentioning that phrase. ' +
             'Example: search_pages({"regex": "\\\\d{3}-\\\\d{3}"}) finds pages with phone-number patterns.',

package/dist/tools/settings.js

@@ -53,7 +53,7 @@ export const settingsTools = [
             // Scriptable surfaces. Trusted because the caller has an API key.
             scripts_head: z.string().optional().describe('Raw HTML injected into <head> on every page. Use for analytics, fonts, third-party CSS links.'),
             scripts_body_end: z.string().optional().describe('Raw HTML injected just before </body> on every page. Use for chat widgets, deferred analytics.'),
-            custom_css: z.string().optional().describe('Global CSS shipped in <style> at the end of <head>. Lets you define site-wide design tokens (CSS variables, @media queries, :hover states) without inlining on every element.'),
+            custom_css: z.string().optional().describe('Global CSS in a <style> in <head>, after block CSS and before the page\'s own custom CSS and the template base stylesheet (reset + global). Base rules for :root tokens (spacing, radius, container widths), body font and line-height load after it, so override those with a more specific selector (for example html:root or body.page) rather than a bare :root/body rule. Preview uses the same order. Lets you define site-wide design tokens (CSS variables, @media queries, :hover states) without inlining on every element.'),
             colors: z.record(z.string()).optional(),
             fonts: z.record(z.unknown()).optional(),
             contact: z

package/dist/tools/versions.js

@@ -12,7 +12,7 @@ export const versionTools = [
     },
     {
         name: 'create_branch',
-        description: "Create a copy-on-write branch from main (or the version passed in `base`) — the RECOMMENDED first step for any larger or experimental change (redesigns, multi-page edits, trying a new design direction). Work lands on the branch, never on the live main version, until you merge_branch it. New branches default to robots_blocked:true (a half-finished design can't be indexed) and get their own deploy URL ({branch}.{project}.pages.dev) for stakeholder review. Pass the returned id as ?version= on every subsequent read/write. When in doubt, branch — it's cheap and keeps the live site safe. The tr-redesign-branch skill (read_skill) walks the full flow.",
+        description: "Create a copy-on-write branch from main (or the version passed in `base`) — the RECOMMENDED first step for any larger or experimental change (redesigns, multi-page edits, trying a new design direction). Work lands on the branch, never on the live main version, until you merge_branch it. New branches default to robots_blocked:true (a half-finished design can't be indexed) and get their own stable deploy address for stakeholder review: after the branch's first trigger_deploy, read it from deploy_url in list_versions or read_version (the publishing setup decides the host: under a Hosting Group it is a v-… host under that group's site address base, otherwise the address the host reported; never construct it yourself). Pass the returned id as ?version= on every subsequent read/write. When in doubt, branch — it's cheap and keeps the live site safe. The tr-redesign-branch skill (read_skill) walks the full flow.",
         inputSchema: {
             name: z.string().min(1),
             base: z.string().optional().describe('Source version id; defaults to main.'),

package/dist/tools/working-copy.js

@@ -8,6 +8,7 @@
 //   commit_working_copy                    →  SAVE (same op as the editor's
 //                                              Save button)
 //   discard_working_copy                   →  throw the draft away
+//   list/read/restore_page_revision        →  saved-state history (undo)
 //
 // The portal editor shows any agent-written draft as "Unsaved changes", so
 // the human can also Save or Discard it from the UI.
@@ -72,4 +73,47 @@ export const workingCopyTools = [
             return ok(res);
         }),
     },
+    {
+        name: 'list_page_revisions',
+        description: "Saved-state history of a page on this version, newest first. Every save snapshots the page as it was BEFORE the save, so each entry is a state you can go back to. Returns { revisions: [{ id, created_at, created_by, note, title, content_mode, date_updated }], total }. Use read_page_revision for the full document and restore_page_revision to undo.",
+        inputSchema: {
+            page_id: z.string(),
+            limit: z.number().int().min(1).max(100).optional().describe('Newest N entries (default 50).'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const query = { ...(v(args.version) ?? {}) };
+            if (args.limit)
+                query.limit = String(args.limit);
+            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}/revisions`, query);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_page_revision',
+        description: 'Read one page revision with the full saved document (title, blocks or html_content, SEO fields, fields, …) — compare it with read_page before restoring.',
+        inputSchema: {
+            page_id: z.string(),
+            revision_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `pages/${encodeURIComponent(args.page_id)}/revisions/${encodeURIComponent(args.revision_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'restore_page_revision',
+        description: "Restore a page revision's content into the page's DRAFT (replacing the current draft, like replace_page). Pass save:true to save it at once; the save snapshots the current page first, so the restore is itself undoable. Publication status and schedule are kept. A revision from the other content mode is refused (409) — switch mode first. Returns { restored_revision, saved, has_unsaved_changes, staged_fields, … }.",
+        inputSchema: {
+            page_id: z.string(),
+            revision_id: z.string(),
+            save: z.boolean().optional().describe('Save immediately (default false: leave it as an unsaved draft to preview).'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/revisions/${encodeURIComponent(args.revision_id)}/restore`, { save: args.save === true }, v(args.version));
+            return ok(res);
+        }),
+    },
 ];

package/dist/version.js

@@ -8,4 +8,4 @@
 //
 // Keep it in lockstep with package.json: tests/version.test.ts asserts
 // VERSION === package.json.version, so a bump that forgets this line fails CI.
-export const VERSION = '0.45.40';
+export const VERSION = '0.45.42';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.45.40",
+  "version": "0.45.42",
   "description": "Typeroll CMS MCP server – connect AI agents to the REST API to manage content and publish static websites.",
   "license": "MIT",
   "repository": {

package/skills/tr-forms.md

@@ -35,6 +35,11 @@ shell or paste a token into page HTML.
 }
 ```
 
+`success_message` may contain basic sanitized HTML, such as a link to the next
+step. To send the visitor somewhere after the final step instead, set
+`success_redirect_url` to a root-relative path (`/tack/`) or an `http(s)` URL,
+for example a booking page. Other schemes are rejected; `""` clears it.
+
 Field names must match `[a-z][a-z0-9_-]*`. Labels may be localized. Supported
 simple types include `text`, `email`, `tel`, `url`, `number`, `textarea`,
 `select`, `radio`, `checkbox`, `hidden`, and `gdpr_consent`.

package/skills/tr-migrate-wp.md

@@ -1,6 +1,6 @@
 ---
 name: tr-migrate-wp
-description: Use when the user asks to migrate a WordPress site to Typeroll, mentions wp-json, or names a WP source URL. Walks the WP REST API, preserves content and shared references in editable blocks, transfers media, sets redirects, leaves everything as drafts for human review.
+description: Use when the user asks to migrate a WordPress site to Typeroll, mentions wp-json, or names a WP source URL. Walks the WP REST API, preserves cleaned HTML and shared references, transfers media, sets redirects, and leaves everything as drafts for human review. Do not apply automatic HTML-to-blocks conversion.
 ---
 
 # Migrate from WordPress to Typeroll
@@ -140,6 +140,8 @@ c. Migrate referenced images with `upload_media_from_url`. The customer's
    media reference only after verification. Stop and report a failed required
    transfer; do not silently hotlink the WordPress source.
 
+The managed importer stores cleaned HTML and does not run HTML-to-blocks conversion. Do not call `convert_page_to_blocks` or `set_page_mode` to rewrite that HTML. A person previews and accepts a conversion in the page editor.
+
 d. Preserve exact text, headings, anchors, links, media and semantic structure with native blocks first. Read the
    available block types and map headings, prose, images, buttons and layout
    into their typed fields. Use HTML mode only for source-specific markup that

package/skills/tr-new-site.md

@@ -335,8 +335,10 @@ For migrated legacy pages or a hand-crafted one-off, `content_mode:
 - HTML-mode bodies are container-constrained; full-bleed requires the
   negative-margin escape (`margin-left: calc(50% - 50vw); width: 100vw`)
   — never combine with `overflow-x: clip` on a wrapper.
-- `set_page_mode` flips a page between modes;
-  `convert_page_to_blocks` does a heuristic HTML→blocks conversion.
+- `set_page_mode` flips a page between modes and does not convert HTML.
+  `convert_page_to_blocks` previews a heuristic conversion, including
+  what it could not convert, and does not write. A person accepts that
+  preview in the page editor.
 
 ## Pitfalls
 

package/skills/tr-redesign-branch.md

@@ -230,11 +230,15 @@ link for your own verification:
   yourself) see a change.
 - **When they want the COMPILED static site** (a permanent bookmark, a
   stakeholder link to the built output, or a final pre-merge check): deploy
-  the branch once (`trigger_deploy version="<branch>"`) and share the stable
-  alias `https://<branch>.<project>.pages.dev` (the `<project>` is the part
-  after the hash in the returned `deploy_url`). Branch deploys are
-  `robots_blocked`, so it won't be indexed. The immutable per-deploy
-  `<hash>.pages.dev` is for your own one-off checks (a new hash each deploy).
+  the branch once (`trigger_deploy version="<branch>"`) and share its stable
+  address: `deploy_url` from `list_versions` / `read_version` once the deploy
+  has succeeded. The publishing setup decides the host: under a Hosting Group
+  it is a `v-…` host under that group's site address base (which need not be
+  the site's own domain); otherwise it is the address the host reported. Never
+  construct it yourself, and do not guess a `<branch>.<project>.pages.dev`
+  alias. Branch deploys are `robots_blocked`, so the
+  address won't be indexed. A per-deploy `<hash>.pages.dev` URL in the job
+  details is for your own one-off checks (a new hash each deploy).
 
 Default: review/iterate on the reused DB-live preview; deploy only for the
 compiled output or merge. Wait for an explicit "looks good, ship it."