@typeroll/mcp-server 0.45.43 → 0.45.44

package/dist/tools/content-types.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ok, withErrorBoundary, versionParam } from './helpers.js';
+import { ok, withErrorBoundary, versionParam, writeAuthority } from './helpers.js';
 const schema = z.array(z.object({ name: z.string(), label: z.string(), type: z.enum(['text', 'textarea', 'richtext', 'image', 'file', 'color', 'select', 'multiselect', 'boolean', 'number', 'url', 'email', 'date', 'datetime', 'list', 'list_simple', 'array', 'object', 'page_ref', 'page_ref_list']) }).passthrough());
 const fields = {
     label_singular: z.string().optional(), label_plural: z.string().optional(), fields: schema.optional(),
@@ -14,7 +14,7 @@ const fields = {
 export const contentTypeTools = [
     { name: 'page_completeness', description: 'Report missing, unverified and stale fields for Pages of one content type, with per-field counts and worst-first Page IDs. Read-only; agent-writable fields only by default.', inputSchema: { content_type: z.string(), limit: z.number().int().min(1).max(200).optional(), stale_after_days: z.number().min(0).optional(), agent_writable_only: z.boolean().optional(), version: versionParam },
         handler: withErrorBoundary(async (args, { client, siteId }) => { const { content_type, ...query } = args; return ok(await client.get(siteId, `content-types/${encodeURIComponent(content_type)}/completeness`, query)); }) },
-    { name: 'change_page_content_type', description: 'Change a saved Page to another content type. Preserves its identity, block body, status and existing URL. Save or discard its working copy first. If supplied, fields replaces the complete custom fields object; omitted fields are kept and must be valid for the new type. Snapshots a revision before changing.', inputSchema: { page_id: z.string(), content_type: z.string(), fields: z.record(z.unknown()).optional(), version: versionParam },
+    { name: 'change_page_content_type', description: 'Change a saved Page to another content type. Preserves its identity, block body, status and existing URL. Save or discard its working copy first. If supplied, fields replaces the complete custom fields object; omitted fields are kept and must be valid for the new type. Snapshots a revision before changing.', inputSchema: { page_id: z.string(), content_type: z.string(), fields: z.record(z.unknown()).optional(), ...writeAuthority, version: versionParam },
         handler: withErrorBoundary(async (args, { client, siteId }) => { const { page_id, version, ...body } = args; return ok(await client.post(siteId, `pages/${encodeURIComponent(page_id)}/content-type`, body, { version })); }) },
     { name: 'list_content_types', description: 'List the field schemas, URL patterns, sorting, allowed templates and default templates for Pages. All content is a Page; use list_pages with content_type to filter.', inputSchema: { version: versionParam },
         handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.get(siteId, 'content-types', { version: args.version }))) },

package/dist/tools/forms.js

@@ -1,4 +1,5 @@
-// Forms — agents can create/update/delete forms, and read submissions.
+// Forms — agents can create/update/delete forms, manage their email
+// notifications and webhooks, and read submissions, like the portal.
 // The customer-facing submit endpoint is HMAC-signed and lives at
 // /api/forms/submit. Agents place forms by reference: core/form in block mode,
 // or <x-form id="…" /> in HTML mode. Preview/build expands either reference
@@ -33,6 +34,16 @@ const targetSchema = z.object({
     context_params: z.array(z.string()).max(8).optional().describe('Explicit URL query keys forwarded to the app hydration endpoint; reserved security keys are rejected.'),
     installation_id: z.string(), path: z.string(), hydrate: z.boolean().optional(), session_param: z.string().optional(),
 }).optional().describe('Admin-only: bind to a declared POST route of an enabled app installation. Read its authenticated guide first.');
+// Actions run after a successful submission: email notifications, signed
+// webhooks and app-provided action types. Same validation as the portal's
+// Forms editor; admin permission required, as in the portal.
+const actionSchema = z.object({
+    id: z.string().optional().describe('Keep an existing action\'s id to update it in place (webhooks keep their stored secret).'),
+    type: z.string().describe('"email", "webhook", or an action type provided by an installed app.'),
+    config: z.record(z.string(), z.unknown()).describe('email: { to, subject, body, cc?, bcc?, reply_to?, include_all?, format?: "html"|"text" } — to/subject/body may use {{field}} placeholders, e.g. to: "{{email}}" for a confirmation to the visitor. ' +
+        'webhook: { url (https), fields: ["name","email"] (only these values are sent), secret (signing secret; send "••••••••" to keep the stored one) }.'),
+});
+const actionsDescription = 'The complete list of actions after a submission (replaces the current list): email notifications, webhooks, app actions. Read the form first and send back the actions you keep. Requires admin permission, like the portal.';
 export const formTools = [
     {
         name: 'list_forms',
@@ -44,7 +55,7 @@ export const formTools = [
     },
     {
         name: 'read_form',
-        description: 'Read one form by id, including fields/steps, submit_text, and success_message. Place it with a `core/form` block using data.form_id on a block-mode page, or `<x-form id="…" />` in HTML mode. Both references are expanded server-side with validation, signed token, initial state, and the shared runtime.',
+        description: 'Read one form by id, including fields/steps, submit_text, success_message and, for admins, its actions (email notifications and webhooks; secrets masked). Place it with a `core/form` block using data.form_id on a block-mode page, or `<x-form id="…" />` in HTML mode. Both references are expanded server-side with validation, signed token, initial state, and the shared runtime.',
         inputSchema: { form_id: z.string() },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.get(siteId, `forms/${encodeURIComponent(args.form_id)}`);
@@ -62,6 +73,7 @@ export const formTools = [
             submit_text: 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.'),
+            actions: z.array(actionSchema).optional().describe(actionsDescription),
             target: targetSchema,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -74,7 +86,7 @@ export const formTools = [
     },
     {
         name: 'update_form',
-        description: 'Patch a form. Provide only what you want to change. Passing `steps` replaces the whole step list; passing `fields` (sugar for simple forms) replaces the whole step list with ONE static step built from them. The existing form_id is immutable.',
+        description: 'Patch a form. Provide only what you want to change. Passing `steps` replaces the whole step list; passing `fields` (sugar for simple forms) replaces the whole step list with ONE static step built from them. Passing `actions` replaces the email notifications and webhooks (admin). The existing form_id is immutable.',
         inputSchema: {
             form_id: z.string(),
             patch: z.object({
@@ -84,6 +96,7 @@ export const formTools = [
                 submit_text: 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.'),
+                actions: z.array(actionSchema).optional().describe(actionsDescription),
                 target: targetSchema,
             }),
         },

package/dist/tools/helpers.js

@@ -53,6 +53,13 @@ export function withErrorBoundary(handler) {
     };
 }
 /** Shared zod fragment for the optional `version` parameter. */
+/**
+ * MCP writes Page field values with the same authority as an editor in the
+ * portal. Only a value the listed business set itself needs a stated reason.
+ */
+export const writeAuthority = {
+    override_reason: z.string().max(500).optional().describe('Why a value the listed business set itself (through its edit link) is being replaced. Required only for those values, as in the portal; the write otherwise returns 409 naming the field.'),
+};
 export const versionParam = z
     .string()
     .optional()

package/dist/tools/page-blocks.js

@@ -1,10 +1,8 @@
-// Page-block mutation tools. Five primitives (get/add/update/move/remove)
-// plus a one-shot HTML→blocks converter. All target the active version
-// (override with `version`).
+// Page-block mutation tools: get/add/update/move/remove and friends. All
+// target the active version (override with `version`).
 //
-// The AI agent uses these to author block-mode pages directly. For
-// HTML-mode pages, `convert_page_to_blocks` returns a preview only.
-// It never writes. A person accepts that preview in the page editor.
+// The AI agent uses these to author block-mode pages directly. Typeroll does
+// not convert HTML into blocks; block pages are built with blocks.
 import { z } from 'zod';
 import { ok, withErrorBoundary, versionParam } from './helpers.js';
 const blockSchema = z.object({
@@ -193,7 +191,7 @@ 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 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.',
+        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. Typeroll does not convert HTML into blocks: after switching to blocks, build the content with blocks.',
         inputSchema: {
             page_id: z.string(),
             to: z.enum(['blocks', 'html']).describe('Target mode.'),
@@ -204,30 +202,4 @@ export const pageBlockTools = [
             return ok(res);
         }),
     },
-    {
-        name: 'convert_page_to_blocks',
-        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(),
-            version: versionParam,
-        },
-        handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks/convert`, { dry_run: true }, v(args.version));
-            return ok(res);
-        }),
-    },
-    {
-        name: 'convert_prose_block',
-        description: 'Turn one text block (core/prose) into separate blocks: headings (a classed label above a heading becomes its eyebrow), paragraphs, lists, images and buttons. Use it when a text block holds headings, classed HTML or media that should be editable and styled with named styles. Call without `accept` to preview (nothing is written); review `converted`, `notes` and `unconverted`, then call again with `accept` set to the preview\'s `fingerprint`. Writes the page draft (working copy) like other block edits. Pages only.',
-        inputSchema: {
-            page_id: z.string(),
-            block_id: z.string(),
-            accept: z.string().optional().describe('The fingerprint from a preview of this same block. Omit to preview.'),
-            version: versionParam,
-        },
-        handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/blocks/convert-prose`, { block_id: args.block_id, ...(args.accept ? { accept: args.accept } : {}) }, v(args.version));
-            return ok(res);
-        }),
-    },
 ];

package/dist/tools/pages.js

@@ -1,7 +1,10 @@
 // Pages tools. Read + write + batch + blocks-view + preview.
 import { z } from 'zod';
-import { ok, withErrorBoundary, versionParam } from './helpers.js';
+import { ok, withErrorBoundary, versionParam, writeAuthority } from './helpers.js';
 const answerSources = z.record(z.object({ source_url: z.string().url().optional(), import_run_id: z.string().max(200).optional() }).strict()).optional().describe('Evidence per schema leaf path. Actor and timestamp are always assigned by the server; unchanged answers are not confirmed.');
+function authorityBody(args) {
+    return args.override_reason ? { override_reason: args.override_reason } : {};
+}
 function v(version) {
     return version ? { version } : undefined;
 }
@@ -108,6 +111,7 @@ export const pageTools = [
             template: z.string().nullable().optional().describe('Allowed Page template ID; null uses the content type default.'),
             image_sizes_default: z.string().optional().describe('Per-page default `sizes` for responsive images (e.g. "(max-width: 640px) 360px, 560px"). Overrides the site setting; a per-<img> `sizes` attr still wins. Set when this page\'s images render narrower than the generic default so the browser stops over-fetching.'),
             custom_css: z.string().optional().describe('Per-page CSS, injected into <head> as a <style> AFTER the site-level custom_css (so it overrides site styling). This is the RIGHT home for page-specific styling — page metadata, not content. Put a page\'s <style> here instead of stuffing it into a core/html block (which is opaque and un-editable in the visual editor). Syntax errors refuse the write; target s-<style> classes or block custom_class rather than [data-block]/.block-* platform markup.'),
+            ...writeAuthority,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -168,11 +172,12 @@ export const pageTools = [
             })
                 .passthrough(),
             answer_sources: answerSources,
+            ...writeAuthority,
             save: z.boolean().optional().describe('Also SAVE (commit) the draft in the same call — use for pre-approved or batch changes. Without it, changes stay in the unsaved draft until commit_working_copy.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.patch(siteId, `pages/${encodeURIComponent(args.page_id)}`, { ...args.patch, ...(args.answer_sources ? { answer_sources: args.answer_sources } : {}), ...(args.save ? { save: true } : {}) }, v(args.version));
+            const res = await client.patch(siteId, `pages/${encodeURIComponent(args.page_id)}`, { ...args.patch, ...(args.answer_sources ? { answer_sources: args.answer_sources } : {}), ...authorityBody(args), ...(args.save ? { save: true } : {}) }, v(args.version));
             return ok(res);
         }),
     },
@@ -183,11 +188,12 @@ export const pageTools = [
             page_id: z.string(),
             page: z.object({ title: z.string().min(1) }).passthrough(),
             answer_sources: answerSources,
+            ...writeAuthority,
             save: z.boolean().optional().describe('Also SAVE (commit) the draft in the same call — use for pre-approved or batch changes. Without it, changes stay in the unsaved draft until commit_working_copy.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.put(siteId, `pages/${encodeURIComponent(args.page_id)}`, { ...args.page, ...(args.answer_sources ? { answer_sources: args.answer_sources } : {}), ...(args.save ? { save: true } : {}) }, v(args.version));
+            const res = await client.put(siteId, `pages/${encodeURIComponent(args.page_id)}`, { ...args.page, ...(args.answer_sources ? { answer_sources: args.answer_sources } : {}), ...authorityBody(args), ...(args.save ? { save: true } : {}) }, v(args.version));
             return ok(res);
         }),
     },
@@ -201,6 +207,7 @@ export const pageTools = [
                 patch: z.record(z.unknown()),
                 save: z.boolean().optional(),
                 answer_sources: answerSources,
+                ...writeAuthority,
             }))
                 .min(1)
                 .max(200),

package/dist/tools/working-copy.js

@@ -13,7 +13,7 @@
 // The portal editor shows any agent-written draft as "Unsaved changes", so
 // the human can also Save or Discard it from the UI.
 import { z } from 'zod';
-import { ok, withErrorBoundary, versionParam } from './helpers.js';
+import { ok, withErrorBoundary, versionParam, writeAuthority } from './helpers.js';
 function v(version) {
     return version ? { version } : undefined;
 }
@@ -42,10 +42,11 @@ export const workingCopyTools = [
         description: 'SAVE a doc\'s unsaved draft: promote it onto the saved doc through the canonical write path (revision snapshot, SEO transform, redirect hygiene) and delete the draft. Identical to the Save button in the portal editor. Returns { committed, seo_warnings, auto_redirects, retired_redirects }. Never changes publish status. Deploys only ship saved content, so commit before trigger_deploy. Equivalent shortcut: save:true on the write tools.',
         inputSchema: {
             target: wcTargetSchema,
+            ...writeAuthority,
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.post(siteId, wcPath(args.target), {}, v(args.version));
+            const res = await client.post(siteId, wcPath(args.target), { ...(args.override_reason ? { override_reason: args.override_reason } : {}) }, v(args.version));
             return ok(res);
         }),
     },
@@ -109,10 +110,11 @@ export const workingCopyTools = [
             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).'),
+            ...writeAuthority,
             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));
+            const res = await client.post(siteId, `pages/${encodeURIComponent(args.page_id)}/revisions/${encodeURIComponent(args.revision_id)}/restore`, { save: args.save === true, ...(args.override_reason ? { override_reason: args.override_reason } : {}) }, 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.43';
+export const VERSION = '0.45.44';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.45.43",
+  "version": "0.45.44",
   "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-content-write.md

@@ -45,9 +45,9 @@ setting one-off values; ask first when it changes the site's look.
 A small label above a heading is the heading block's `eyebrow`, and a line
 below it is its `subtitle` (render version 2), each with its own style field.
 Never write them as separate text blocks with classed HTML. In text blocks,
-style whole paragraphs with site text styles (`<p class="s-lead">`); a text
-block that needs other classes, images or headings with parts is better split
-with `convert_prose_block`.
+style whole paragraphs with site text styles (`<p class="s-lead">`). Content
+that needs headings with parts, images or buttons belongs in their own blocks,
+not in a text block's HTML.
 
 `list_block_templates` and `list_partials` too. Start a common section from a
 block template (`insert_block_template`, then edit the copy). Use a global

package/skills/tr-forms.md

@@ -6,8 +6,8 @@ description: Use when the user wants to add a contact form, newsletter signup, b
 # Add a form to a Typeroll site
 
 Typeroll forms are server-backed. The platform renders the form shell, accepts
-signed submissions, validates declared fields, stores submissions, and can run
-admin-configured email or webhook actions.
+signed submissions, validates declared fields, stores submissions, and runs
+email and webhook actions configured in the portal or through MCP/API.
 
 ## Choose the placement
 
@@ -97,9 +97,23 @@ actions in the form editor:
   `X-Typeroll-Signature`, sends an idempotency key, retries transient failures,
   and stores delivery status.
 
-Actions are deliberately excluded from MCP/API-key writes and reads because
-they can exfiltrate submitted data. Direct the user to the portal form editor
-to configure them.
+Agents manage the same actions with `read_form` (actions with secrets masked)
+and `update_form patch={ actions: [...] }`, with admin permission as in the
+portal. `actions` replaces the whole list: read the form, change what you need
+and send the list back. Examples:
+
+```
+update_form form_id=contact patch={ actions: [
+  { type: "email", config: { to: "hello@example.com", subject: "New lead: {{name}}",
+    body: "<p>{{message}}</p>", include_all: true, reply_to: "{{email}}" } },
+  { type: "email", config: { to: "{{email}}", subject: "Thanks, {{name}}",
+    body: "<p>We will get back to you within a day.</p>" } }
+] }
+```
+
+A webhook needs `url` (https), an explicit `fields` allowlist and a signing
+`secret`; send the masked value back to keep a stored secret. `list_form_submissions`
+reads what visitors sent.
 
 ## Verify
 
@@ -143,7 +157,7 @@ Booking request:
 
 - Do not hand-write a form, token, honeypot, or submit script.
 - Do not put a raw `<script>` in page HTML; the sanitizer removes it.
-- Do not expose action configuration through agent surfaces.
+- Do not drop existing actions by accident: `actions` replaces the list.
 - Do not send every submitted field to a webhook by default; choose the
   smallest allowlist the external register needs.
 - `submit_token` is stable until the platform rotates its form-signing secret;

package/skills/tr-import-url.md

@@ -61,8 +61,8 @@ small label directly above a heading is an eyebrow style, not a heading of its
 own: put it in the heading block's `eyebrow` field (and a line under the
 heading in `subtitle`). Never carry classed raw HTML into text blocks to keep a
 look: the editor cannot edit it, and the next render version may not keep it.
-A text block that already holds such markup can be split with
-`convert_prose_block` (preview, then `accept`).
+Build such sections with heading, text, image and button blocks; Typeroll does
+not convert HTML into blocks.
 
 ### 2. Measure the source and protect existing target work
 

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 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.
+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. Typeroll does not convert HTML into blocks.
 ---
 
 # Migrate from WordPress to Typeroll
@@ -145,7 +145,7 @@ 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.
+The managed importer stores cleaned HTML. Typeroll does not convert HTML into blocks, and `set_page_mode` never rewrites HTML. Pages move to blocks only when someone rebuilds them with blocks.
 
 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

package/skills/tr-new-site.md

@@ -359,9 +359,8 @@ For migrated legacy pages or a hand-crafted one-off, `content_mode:
   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 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.
+  Typeroll has no HTML-to-blocks conversion: to move a page to blocks,
+  build its content with blocks.
 
 ## Pitfalls