@typeroll/mcp-server 0.45.44 → 0.45.46

package/dist/client.js

@@ -44,7 +44,7 @@ export class TyperollClient {
         }
         return url.toString();
     }
-    /** Top-level URL (no siteId prefix) — used by GET /v1/sites only. */
+    /** Top-level URL (no siteId prefix) — /v1/sites, /v1/organization/*, /v1/publishing/*. */
     rootUrl(path, query) {
         const cleanPath = path.replace(/^\/+/, '');
         const url = new URL(`${this.baseUrl}/api/v1/${cleanPath}`);
@@ -110,4 +110,18 @@ export class TyperollClient {
     rootPut(path, body) {
         return this.request('PUT', this.rootUrl(path), body);
     }
+    // ── Extension developer API ────────────────────────────────────────────
+    /** `/api/developer/{path}` — the Extension developer API used by the
+     *  `typeroll extension` CLI. Requires an organization-scoped key. */
+    developer(method, path, body, query) {
+        const url = new URL(`${this.baseUrl}/api/developer/${path.replace(/^\/+/, '')}`);
+        for (const [k, v] of Object.entries(query ?? {})) {
+            if (v !== undefined && v !== null)
+                url.searchParams.set(k, String(v));
+        }
+        return this.request(method, url.toString(), body);
+    }
+    rootDelete(path, body) {
+        return this.request('DELETE', this.rootUrl(path), body);
+    }
 }

package/dist/compact-tools.js

@@ -22,7 +22,7 @@ export function compactTools(catalog) {
         }),
         ...['read', 'write', 'admin'].map(effect => ({
             name: `call_${effect}_tool`, effect,
-            description: effect === 'read' ? 'Call a discovered read-only tool with its exact arguments. Does not accept write/admin tools.' : `Call a discovered ${effect} tool. May ${effect === 'admin' ? 'change app configuration or activate releases' : 'save, delete, publish or otherwise change state'}. Inspect describe_tool first and follow the user’s authorization.`,
+            description: effect === 'read' ? 'Call a discovered read-only tool with its exact arguments. Does not accept write/admin tools.' : `Call a discovered ${effect} tool. May ${effect === 'admin' ? 'change app, email or block type configuration, send a test email or activate releases' : 'save, delete, publish or otherwise change state'}. Inspect describe_tool first and follow the user’s authorization.`,
             schema: { name: z.string().max(100), arguments: z.record(z.unknown()).default({}) },
             invoke: async (args) => {
                 const tool = byName.get(String(args.name));

package/dist/server.js

@@ -20,6 +20,7 @@ import { styleTools } from './tools/styles.js';
 import { reusableBlockTools } from './tools/reusable-blocks.js';
 import { migrationTools } from './tools/migration.js';
 import { formTools } from './tools/forms.js';
+import { emailTools } from './tools/email.js';
 import { searchTools } from './tools/search.js';
 import { bulkTools } from './tools/bulk.js';
 import { versionTools } from './tools/versions.js';
@@ -32,8 +33,10 @@ import { settingsTools } from './tools/settings.js';
 import { siteTools } from './tools/sites.js';
 import { domainTools } from './tools/domain.js';
 import { appTools } from './tools/apps.js';
-import { extensionTools } from './tools/extensions.js';
+import { extensionTools, developerExtensionTools } from './tools/extensions.js';
 import { skillTools } from './tools/skills.js';
+import { accessTools } from './tools/access.js';
+import { workflowTools } from './tools/workflows.js';
 import { fail } from './tools/helpers.js';
 import { VERSION } from './version.js';
 import { compactTools, COMPACT_INSTRUCTIONS } from './compact-tools.js';
@@ -47,7 +50,7 @@ const PERM_RANK = { read: 0, write: 1, admin: 2 };
  * gate then checks `effect <= sitePermission`.
  *
  * Naming convention is followed by the tool modules: read paths are
- * `list_*` / `read_*` / `get_*` / `preview_*` / `search_*` / `check_*`; everything else
+ * `list_*` / `read_*` / `get_*` / `preview_*` / `search_*` / `check_*` / `find_*`; everything else
  * mutates.
  */
 function effectFor(name) {
@@ -60,8 +63,57 @@ function effectFor(name) {
         || name === 'list_extension_installations'
         || name === 'read_extension_installation'
         || name === 'update_extension_installation_config'
-        || name === 'activate_extension_release')
+        || name === 'activate_extension_release'
+        // Same role as the portal: Settings, lifecycle and media purge are
+        // admin actions (the v1 routes enforce it as well).
+        || name === 'update_site_settings'
+        || name === 'archive_site'
+        || name === 'restore_site'
+        || name === 'purge_site_media'
+        || name === 'install_extension'
+        || name === 'set_extension_installation_status'
+        || name === 'uninstall_extension'
+        || name === 'pair_extension_issuer'
+        || name === 'read_extension_diagnostics'
+        // Branch lifecycle on main is site administration in the portal too.
+        || name === 'create_branch'
+        || name === 'merge_branch'
+        || name === 'delete_branch'
+        || name === 'reset_version'
+        // Developer-organization administration (org admin in the portal).
+        || name === 'update_developer_extension'
+        || name === 'save_extension_version'
+        || name === 'publish_extension_version'
+        || name === 'set_extension_version_lifecycle'
+        // Access and credential management: API keys, sharing, membership invites
+        // and organization publishing connections need admin, as in the portal.
+        || name === 'revoke_api_key'
+        || name === 'list_site_shares'
+        || name === 'share_site'
+        || name === 'update_site_share'
+        || name === 'revoke_site_share'
+        || name === 'revoke_organization_api_key'
+        || name === 'create_organization_invite'
+        || name === 'disconnect_organization_publishing_provider'
+        || name === 'connect_organization_cloudflare'
+        || name === 'prepare_organization_media_storage'
+        || name === 'save_organization_media_access'
+        || name === 'set_email_settings'
+        || name === 'delete_email_settings'
+        || name === 'send_test_email'
+        || name === 'set_incoming_email_forwarding'
+        // Block type authoring is site administration (the portal and the v1
+        // routes require admin); placing and editing blocks on pages stays write.
+        || name === 'create_block_type'
+        || name === 'update_block_type'
+        || name === 'delete_block_type'
+        || name === 'import_block_types')
         return 'admin';
+    // Compute an answer and write nothing, like the preview_* tools.
+    if (name === 'validate_block_type' || name.startsWith('find_'))
+        return 'read';
+    if (name === 'diff_version')
+        return 'read';
     if (name.startsWith('list_') ||
         name.startsWith('read_') ||
         name.startsWith('get_') ||
@@ -158,15 +210,19 @@ export function buildServer(options) {
         ...reusableBlockTools,
         ...migrationTools,
         ...formTools,
+        ...emailTools,
         ...settingsTools,
         ...appTools,
         ...extensionTools,
+        ...developerExtensionTools,
         ...searchTools,
         ...bulkTools,
         ...versionTools,
         ...deployTools,
         ...previewTools,
         ...domainTools,
+        ...workflowTools,
+        ...accessTools,
     ];
     // SDK's registerTool has deeply-nested generics we can't unify across a
     // heterogeneous tool list at compile time — same shrug as stdio's index.ts.

package/dist/tools/access.js

@@ -0,0 +1,75 @@
+// Access tools — API keys, cross-organization site sharing and organization
+// invites. Each wraps the authenticated public API with the same permission
+// checks as the portal: a key never mints a key or a grant that reaches
+// further than it does.
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+const keyId = z.string().regex(/^[a-f0-9]{12}$/).describe('Key id (the 12-hex prefix) from list_api_keys / list_organization_api_keys.');
+export const accessTools = [
+    {
+        name: 'list_api_keys',
+        description: 'List this Site\'s site-scoped API keys: id (prefix), name, created_at/created_by, last_used_at/last_used_ip and revoked_at. Never returns secrets or hashes. Any key that reaches the Site may list, as in Site settings → API keys.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'api-keys'))),
+    },
+    {
+        name: 'revoke_api_key',
+        description: 'Revoke one of this Site\'s API keys (admin permission on the Site). It stops authenticating immediately and stays listed as revoked for audit. Revoking the key this connection uses ends the connection. Organization keys are revoked with revoke_organization_api_key.',
+        inputSchema: { key_id: keyId },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.del(siteId, `api-keys/${encodeURIComponent(args.key_id)}`))),
+    },
+    {
+        name: 'list_site_shares',
+        description: 'List the organizations this Site is shared with, including revoked shares for audit: id, shared_with_org_id, permission (read | write | admin), label, created_at, revoked_at. Admin permission on the Site, as in the portal.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'shares'))),
+    },
+    {
+        name: 'share_site',
+        description: 'Share this Site with another Organization, identified by org_id or org_slug (admin permission on the Site). permission is read, write (default) or admin; a share never exceeds admin, which the caller already holds. One active share per Organization: change it with update_site_share. Confirm the recipient with the user first — it gives every member of that Organization access.',
+        inputSchema: {
+            org_id: z.string().optional().describe('Recipient Organization id.'),
+            org_slug: z.string().optional().describe('Recipient Organization slug, if the id is not known.'),
+            permission: z.enum(['read', 'write', 'admin']).optional(),
+            label: z.string().max(200).optional().describe('Optional note shown in the sharing list.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.post(siteId, 'shares', args))),
+    },
+    {
+        name: 'update_site_share',
+        description: 'Change the permission (read | write | admin) and/or label of an active share of this Site (admin permission on the Site). Takes effect on the recipient\'s next request.',
+        inputSchema: {
+            share_id: z.string().describe('Share id from list_site_shares.'),
+            permission: z.enum(['read', 'write', 'admin']).optional(),
+            label: z.string().max(200).optional(),
+        },
+        handler: withErrorBoundary(async ({ share_id, ...patch }, { client, siteId }) => ok(await client.patch(siteId, `shares/${encodeURIComponent(share_id)}`, patch))),
+    },
+    {
+        name: 'revoke_site_share',
+        description: 'Revoke a share of this Site (admin permission on the Site). The recipient Organization and its keys lose access immediately; the record stays listed as revoked.',
+        inputSchema: { share_id: z.string().describe('Share id from list_site_shares.') },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.del(siteId, `shares/${encodeURIComponent(args.share_id)}`))),
+    },
+    {
+        name: 'list_organization_api_keys',
+        noSite: true,
+        description: 'List the Organization\'s organization-scoped API keys (metadata only, never secrets). Requires an organization API key; site-scoped keys get 403. Site-scoped keys are listed per Site with list_api_keys.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client }) => ok(await client.rootGet('organization/api-keys'))),
+    },
+    {
+        name: 'revoke_organization_api_key',
+        noSite: true,
+        description: 'Revoke an organization-scoped API key. Requires an organization API key. It stops authenticating immediately; revoking the key this connection uses ends the connection.',
+        inputSchema: { key_id: keyId },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootDelete(`organization/api-keys/${encodeURIComponent(args.key_id)}`))),
+    },
+    {
+        name: 'create_organization_invite',
+        noSite: true,
+        description: 'Create a signed invite link to the Organization (organization API key required). The invited person opens invite_url, signs in and joins as an editor; the link works until expires_at (ttl_days 1–30, default 7) and cannot be revoked early. Send it only to the person the user named.',
+        inputSchema: { ttl_days: z.number().int().min(1).max(30).optional() },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPost('organization/invites', args))),
+    },
+];

package/dist/tools/block-types.js

@@ -1,16 +1,18 @@
-// Block-type tools. Surface is wired in now so the future block editor
-// drops in without breaking integrations.
+// Block-type tools: discovery, authoring (validate, preview, create, update,
+// delete), usage, starters and .tcblocks packages. Every write goes through
+// the portal's one block type write path (shared validator, version chain,
+// rename migration), and authoring needs admin permission on the Site.
 import { z } from 'zod';
 import { ok, withErrorBoundary, versionParam } from './helpers.js';
 function v(version) {
     return version ? { version } : undefined;
 }
-// The per-block markup. These three fields dominate the payload size (a few
-// dozen blocks of template HTML + scoped CSS can exceed an agent's token
-// budget and get truncated), and an agent enumerating the library rarely
-// needs them — read_block_type fetches them for one block on demand. So
-// list_block_types omits them by default and returns a lightweight summary.
-const HEAVY_BLOCK_TYPE_FIELDS = ['template', 'styles', 'script'];
+// The per-block markup. These fields dominate the payload size (a few dozen
+// blocks of template HTML + scoped CSS can exceed an agent's token budget and
+// get truncated), and an agent enumerating the library rarely needs them —
+// read_block_type fetches them for one block on demand. So list_block_types
+// omits them by default and returns a lightweight summary.
+const HEAVY_BLOCK_TYPE_FIELDS = ['template', 'styles', 'styles_compiled', 'script', 'composition'];
 /** Strip the heavy markup fields from each block type in a `block-types`
  *  response, preserving the field `schema` and all light metadata. Defensive:
  *  if the shape isn't the expected `{ block_types: [...] }`, pass it through. */
@@ -25,18 +27,47 @@ function summariseBlockTypes(res) {
         if (!bt || typeof bt !== 'object')
             return bt;
         const copy = { ...bt };
+        if (Array.isArray(copy.composition) && copy.composition.length)
+            copy.composed = true;
         for (const field of HEAVY_BLOCK_TYPE_FIELDS)
             delete copy[field];
         return copy;
     });
     return { ...envelope, block_types: slim };
 }
+const AUTHORING_GUIDE = 'Two kinds of site block type. COMPOSED (preferred): `composition` is a tree of existing blocks ({ id, type, data, children? } — core/heading, core/text, core/prose, core/image, core/icon, core/button, core/container, core/grid, core/repeater …) and `schema` declares the props people edit when they place the block. Inner blocks read props through exact bindings as the WHOLE value: a heading\'s text "{{props.title}}"; a core/repeater with items "{{props.items}}" (an array prop) renders its children once per item, where "{{item.title}}" reads the item and "{{item.link.href}}" a link sub-value. Everything the inner blocks do (named styles, responsive settings, images, safe links, render versions) carries over. ' +
+    'TEMPLATE (advanced, when existing blocks cannot express the markup): `template` is HTML with {{field}} (escaped), {{{field}}} (raw: richtext fields and derived …_svg / …_html only), {{#field}}…{{/field}} (shown when set), {{^field}}…{{/field}} (shown when empty), {{#each items}}…{{/each}} (per array item; names resolve against the item first; {{@index}}, {{@number}}, {{@first}}, {{@last}}), {{#link field class="…"}}…{{/link}} (wraps the body in a safe <a href rel target> when the link resolves), plus {{children}} / {{slot:NAME}} for containers. ' +
+    'Fields: text, textarea, richtext, image, icon (derived {name}_svg), select (options), boolean, number, url, link ({ page_id?, url?, new_tab? } — prefer page_id for a page on the Site, it survives slug changes; resolves to .href, .target, .rel), array (a repeating group: fields, item_label, min_items, max_items; nests 3 levels), object, style … each with name, type, label and optional help, required, default. ' +
+    '`styles` is scoped to the block when written: every selector applies inside [data-block="<name>"], :scope is the block element itself, body/html/:root are refused; use the site\'s var(--color-*) and spacing tokens. The response returns `styles_compiled`, the CSS that ships. ' +
+    'Unknown properties are errors. Every problem has a JSON-pointer `path` (and a `line` for markup/CSS); a 400 lists them all in `problems`, warnings come back in `warnings`. Call validate_block_type / preview_block_type first, and list_block_type_starters for complete examples. Needs ADMIN permission on the Site; editors (write) place block types on pages and edit their fields.';
+const definitionShape = {
+    label: z.string().optional().describe('Display label in the block picker.'),
+    description: z.string().optional().describe('When to use this block type; shown to editors and agents (≤ 500 chars).'),
+    icon: z.string().optional().describe('Lucide icon name shown in the block picker.'),
+    category: z.enum(['layout', 'content', 'media', 'custom']).optional(),
+    container: z.union([
+        z.literal(true), z.literal(false),
+        z.enum(['slots', 'repeater', 'conditional']),
+    ]).optional().describe('Template types only. true renders {{children}}, slots fixed named slots, repeater loops over items, conditional show-if. A composed type is never a container; put a container block inside its composition.'),
+    slot_count: z.number().optional().describe('Required when container="slots". 1-8.'),
+    slot_labels: z.array(z.string()).optional(),
+    item_compatible: z.boolean().optional().describe('Mark true if this block is designed to render as a repeater item (no outer padding).'),
+    expand_to: z.object({
+        target: z.string(),
+        defaults: z.record(z.unknown()),
+    }).optional().describe('Alias mechanism — render as another block type with these defaults merged under authored data.'),
+    schema: z.array(z.unknown()).optional().describe('FieldDefinition[]: { name, type, label, help?, required?, default?, options? (select), fields? (array/object), item_label?, min_items?, max_items? }. Replaces the whole schema on update.'),
+    composition: z.array(z.unknown()).optional().describe('Block[] a composed type is built from. Bind data to props with "{{props.name}}" and, inside a core/repeater over an array prop, to items with "{{item.name}}" — always as the whole value.'),
+    template: z.string().optional().describe('Markup of a template type (instead of composition); see the section syntax above.'),
+    styles: z.string().optional().describe('CSS scoped to the block. Write selectors for the block\'s own markup; :scope is the block element.'),
+    script: z.string().optional().describe("Client-side JS shipped with the block (runs on the published site's own origin). Accepted under your API key's authority — the write is audit-logged. Prefer a composed type without script."),
+};
 export const blockTypeTools = [
     {
         name: 'export_block_types',
-        description: 'Pack custom block types into a .tcblocks zip (base64). When `ids` is omitted, every user-created block type is bundled. Useful for moving blocks between sites or backing them up — the returned zip is a portable package the import tool reads back.',
+        description: 'Pack site block types into a .tcblocks zip (base64). When `ids` is omitted, every block type the Site has (made in the portal, by an agent, or imported) is bundled. The package keeps every property — composition, template, styles and CSS scope, script, field help and list settings — so it moves between any Sites, in any Organization or Typeroll instance. import_block_types reads it back.',
         inputSchema: {
-            ids: z.array(z.string()).optional().describe('Specific block-type ids to include. Omit to export every user-created block.'),
+            ids: z.array(z.string()).optional().describe('Specific block-type ids to include. Omit to export every site block type.'),
             name: z.string().optional().describe('Package name (default: {site}-blocks).'),
             version: z.string().optional().describe('Package version written into the manifest (default: 1.0.0). This is the package semver, not a Site version — use version_branch for that.'),
             version_branch: versionParam,
@@ -60,26 +91,29 @@ export const blockTypeTools = [
     },
     {
         name: 'import_block_types',
-        description: 'Install block types from a .tcblocks package. Provide the zip as base64. Re-importing the same package overwrites existing blocks with the same id (package_name/block_name). Each imported BlockType may include arbitrary CSS and JS — the caller is responsible for trusting the source. Returns counts of created vs updated docs.',
+        description: 'Install block types from a .tcblocks package (zip as base64). Needs ADMIN permission on the Site. Each definition is checked by the same validator as create_block_type; a definition with errors is reported as failed and not written. On a name conflict `on_conflict` decides: skip (default) keeps the Site\'s type, rename imports it under a free name (references inside the package follow), replace overwrites it. Returns `results` per type (created, renamed, replaced, skipped, failed with problems) and counts. Imported types may carry CSS and JS — only import packages you trust.',
         inputSchema: {
             zip_base64: z.string().describe('Base64-encoded .tcblocks zip.'),
+            on_conflict: z.enum(['skip', 'rename', 'replace']).optional().describe('What to do when the Site already has a block type with the same name. Default skip.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const v = args.version ? { version: args.version } : undefined;
-            const res = await client.post(siteId, 'blocks/import', { zip_base64: args.zip_base64 }, v);
+            const res = await client.post(siteId, 'blocks/import', {
+                zip_base64: args.zip_base64,
+                ...(args.on_conflict ? { on_conflict: args.on_conflict } : {}),
+            }, v(args.version));
             return ok(res);
         }),
     },
     {
         name: 'list_block_types',
-        description: 'Discover every block type usable on this site. Returns ALL of them in one list: core blocks (id like "core/section", always available), custom blocks (origin: "user", created in the portal), and third-party blocks (origin: "third_party", imported from .tcblocks packages). Call this FIRST when starting block-mode work — never hardcode block ids; the available set is per-site. By default this is a LIGHTWEIGHT SUMMARY: each entry has id, label, category, icon, container/slot info, origin, and the full field schema (name/type/label/required/options/default) — everything you need to pick a block and call add_block — but NOT the render-time markup. The per-block template HTML, scoped styles, and script are omitted so the list stays within token budget no matter how large the library grows; fetch them for a single block with read_block_type, or pass full:true to inline them for every block (can be very large).',
+        description: 'Discover every block type usable on this site. Returns ALL of them in one list: core blocks (id like "core/section", always available), site block types (origin "user" from the portal, "ai" from an agent) and third-party blocks (origin "third_party", imported from .tcblocks packages). Call this FIRST when starting block-mode work — never hardcode block ids; the available set is per-site. By default this is a LIGHTWEIGHT SUMMARY: id, label, description, category, icon, container/slot info, origin, `composed: true` for composed types, and the full field schema — everything you need to pick a block and call add_block — but NOT the template, composition, styles or script. Fetch those for one block with read_block_type, or pass full:true to inline them for every block (can be very large).',
         inputSchema: {
-            include_core: z.boolean().optional().describe('Default true. Set false to get only custom + third-party (rarely needed).'),
+            include_core: z.boolean().optional().describe('Default true. Set false to get only the site\'s own and third-party types.'),
             full: z
                 .boolean()
                 .optional()
-                .describe("Default false. When true, include each block type's template HTML, styles CSS, and script inline — the full doc. Large; prefer read_block_type for one block's markup."),
+                .describe("Default false. When true, include each block type's template, composition, styles and script inline — the full doc. Large; prefer read_block_type for one block."),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -94,7 +128,7 @@ export const blockTypeTools = [
     },
     {
         name: 'read_block_type',
-        description: "Full schema for one block type. Returns the BlockType doc with template, styles, optional script, and the field-definitions array. Use this when list_block_types' summary isn't enough — e.g. before add_block on a custom block whose data fields you haven't seen.",
+        description: "Full definition of one block type: the field schema, and its composition (composed types) or template (template types), styles with `styles_compiled` (the scoped CSS that ships), and optional script. Use this when list_block_types' summary isn't enough — before add_block on an unfamiliar block, or before update_block_type.",
         inputSchema: {
             type_id: z.string(),
             version: versionParam,
@@ -106,7 +140,7 @@ export const blockTypeTools = [
     },
     {
         name: 'find_pages_using_block_type',
-        description: 'Pages whose block tree contains this block type. Empty for HTML-mode sites (the default today); fills in once block-mode pages exist.',
+        description: 'Everything that uses a block type, on every surface: `pages` (saved block pages and drafts — `sources` says which), `templates` (page templates), `partials` (header, footer, global blocks), `block_templates`, and `block_types` (other site block types built from it). Repeaters that render the type as their item_block count, and a use through another block type names it in `via`. `total` sums the lists; delete_block_type is refused while it is above zero. Call it before changing or removing fields of a type in use.',
         inputSchema: {
             type_id: z.string(),
             version: versionParam,
@@ -116,36 +150,62 @@ export const blockTypeTools = [
             return ok(res);
         }),
     },
+    {
+        name: 'list_block_type_starters',
+        description: 'Built-in starting points for a new block type: complete composed definitions (icon list, feature cards, numbered steps) with fields, composition and scoped CSS. Adapt one (rename it, change fields) and pass it to create_block_type — it is the quickest way to a valid composed type.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, 'block-types/starters');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'validate_block_type',
+        description: `Check a block type definition without saving it, with the exact validator create_block_type and update_block_type use. Pass the whole definition, or with type_id a patch to that stored type (renames are checked too). Returns { ok, problems, merged }: every error and warning with a JSON-pointer path (e.g. /schema/0/fields/2/name, /composition/0/children/1/data/text) and a line for markup and CSS, and the definition as it would be stored. Writes nothing. ${AUTHORING_GUIDE}`,
+        inputSchema: {
+            definition: z.record(z.unknown()).describe('The block type definition (as for create_block_type), or a patch when type_id is set.'),
+            type_id: z.string().optional().describe('Validate `definition` as a patch to this stored block type.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const query = {};
+            if (args.type_id)
+                query.type_id = args.type_id;
+            if (args.version)
+                query.version = args.version;
+            const res = await client.post(siteId, 'block-types/validate', args.definition, query);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'preview_block_type',
+        description: 'Render a block type definition that need not be saved, through the same preview renderer as the portal (the Site\'s render version, theme CSS, named styles, custom CSS, the other site block types, and the sanitizer). Without `data` the block shows sample values derived from its fields. Returns { ok, html, css, document, data, problems }: `html` is the block\'s markup as a page carries it, `css` the scoped block CSS that ships, `document` a standalone HTML page. A definition with errors is not rendered (ok:false, problems listed). Block scripts never run in a preview. Writes nothing.',
+        inputSchema: {
+            definition: z.record(z.unknown()).optional().describe('The block type definition, or a patch when type_id is set. Omit with type_id to preview the stored type.'),
+            type_id: z.string().optional().describe('Preview `definition` as a patch to this stored block type.'),
+            data: z.record(z.unknown()).optional().describe('Field values for the previewed block. Omit for sample data.'),
+            render_version: z.number().int().optional().describe('Render with this platform render version instead of the Site\'s own.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'block-types/preview', { ...body, definition: body.definition ?? {} }, v(version));
+            return ok(res);
+        }),
+    },
     // ─── BlockType authoring — CREATE / UPDATE / DELETE ──────────────────
-    // `script` runs with full DOM access in every visitor's browser. Through
-    // an API key it is ACCEPTED under the key holder's authority (same trust
-    // level as scripts_head) — the write is audit-logged and the response
-    // carries a notice naming the stored JS. Only the in-portal chat AI
-    // remains gated on Site.ai_scripts_enabled. Origin is stamped 'ai' so
-    // audit + UI distinguish agent-authored types.
+    // Admin permission on the Site, as in the portal. `script` runs with full
+    // DOM access in every visitor's browser. Through an API key it is ACCEPTED
+    // under the key holder's authority (same trust level as scripts_head) and
+    // the write is audit-logged. Only the in-portal chat never writes it.
+    // Origin is stamped 'ai' so audit + UI distinguish agent-authored types.
     {
         name: 'create_block_type',
-        description: "Create a new custom block type usable on this site. Origin is stamped 'ai' automatically. The block ships immediately to every page editor + the renderer's registry. Custom JS via `script` is accepted under your API key's authority (audit-logged; the response carries a notice) — review before deploy. This is the supported way to ship per-page JS: `<script>` written into page or block MARKUP is stripped by the renderer's sanitizer no matter which credential wrote it, so package the behaviour as a block type instead. Site-wide tags belong in settings.scripts_head / scripts_body_end. Returns the created BlockType. Responsive fields: mark a schema field `responsive: true` and expose it as style=\"--{field}:{{field}}\" on the outermost element so it can vary per breakpoint. If the value is directly usable CSS, read var(--{field}); if it's a token that maps to CSS (e.g. layout 'icon-left' → flex-direction:row) add a `responsive_css` map on the field ({ 'icon-left': '--dir: row;' }), otherwise per-breakpoint overrides won't take effect.",
+        description: `Create a block type for this Site when no core block (or block template) fits a recurring shape. Origin is stamped 'ai'; id = name. The type is available to every page editor immediately and reaches the live site with the next deploy. ${AUTHORING_GUIDE} Returns { block_type, warnings }; 409 when the name exists. A block type is the supported way to ship per-block JS (\`script\`): <script> written into page or block markup is always stripped by the sanitizer. Site-wide tags belong in settings.scripts_head / scripts_body_end.`,
         inputSchema: {
-            name: z.string().describe('Machine name (lowercase kebab/underscore, 1-64 chars). Becomes the id.'),
-            label: z.string().optional().describe('Display label (defaults to name).'),
-            icon: z.string().optional().describe('Lucide icon name shown in the block picker.'),
-            category: z.enum(['layout', 'content', 'media', 'custom']).optional(),
-            container: z.union([
-                z.literal(true), z.literal(false),
-                z.enum(['slots', 'repeater', 'conditional']),
-            ]).optional().describe('Container kind. Use slots for fixed named slots, repeater for looping over items, conditional for show-if blocks.'),
-            slot_count: z.number().optional().describe('Required when container="slots". 1-8.'),
-            slot_labels: z.array(z.string()).optional(),
-            item_compatible: z.boolean().optional().describe('Mark true if this block is designed to render as a repeater item (no outer padding, kernel layout).'),
-            expand_to: z.object({
-                target: z.string(),
-                defaults: z.record(z.unknown()),
-            }).optional().describe('Alias mechanism — render as another block type with these defaults merged under authored data.'),
-            schema: z.array(z.unknown()).optional().describe('FieldDefinition[]. Each field has name, type, label, optional required/default/options/responsive.'),
-            template: z.string().optional().describe('HTML with {{field}}, {{{field}}}, {{=tag}}, {{children}}, {{slot:NAME}} substitutions.'),
-            styles: z.string().optional().describe('Block-scoped CSS. Selectors should start with [data-block="<name>"].'),
-            script: z.string().optional().describe("Client-side JS shipped with the block (runs on the published site). Accepted under your API key's authority — the write is audit-logged and the response carries a notice naming the stored JS. It runs on the published site's own origin, which shares nothing with the Typeroll portal."),
+            name: z.string().describe('Machine name (lowercase letters, digits, "-" and "_", 1-64 chars). Becomes the id.'),
+            ...definitionShape,
+            label: z.string().describe('Display label in the block picker.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -160,24 +220,12 @@ export const blockTypeTools = [
     },
     {
         name: 'update_block_type',
-        description: "Update fields of an existing custom block type. Core blocks (id starts with 'core/') are read-only — they're managed in platform code. Schema/template/styles replace wholesale (no deep merge); other fields shallow-merge. The `script` field follows the same policy as create_block_type — accepted under your key's authority, audit-logged, notice in the response.",
+        description: "Change a site block type (core/* types are read-only). Needs ADMIN permission. schema, composition, template and styles replace wholesale when sent; other properties merge. Changing a type in use: to RENAME a field, send the new schema with `renames` ({ \"title\": \"heading\", \"items.label\": \"text\" } — dotted paths of the OLD names, new name of the field) and the data moves in every block that uses the type (saved pages and drafts, page templates, header/footer/global blocks, block templates, other block types, repeater items), after a revision of each changed page; a composed type's own {{props.…}}/{{item.…}} bindings follow unless you send a composition. Removing or retyping a field that holds data answers 409 with the affected uses until you resend with confirm_data_loss: true (ask the user first). Returns { block_type, warnings, impact: { usages, renamed, removed, retyped } }. The same validation as create_block_type applies.",
         inputSchema: {
-            type_id: z.string().describe('Block type id (custom or third_party). Cannot be a core/* block.'),
-            label: z.string().optional(),
-            icon: z.string().optional(),
-            category: z.enum(['layout', 'content', 'media', 'custom']).optional(),
-            container: z.union([
-                z.literal(true), z.literal(false),
-                z.enum(['slots', 'repeater', 'conditional']),
-            ]).optional(),
-            slot_count: z.number().optional(),
-            slot_labels: z.array(z.string()).optional(),
-            item_compatible: z.boolean().optional(),
-            expand_to: z.object({ target: z.string(), defaults: z.record(z.unknown()) }).optional(),
-            schema: z.array(z.unknown()).optional(),
-            template: z.string().optional(),
-            styles: z.string().optional(),
-            script: z.string().optional().describe("Accepted under your API key's authority; audit-logged, and the response carries a notice naming the stored JS."),
+            type_id: z.string().describe('Block type id (a site type). Cannot be a core/* block.'),
+            ...definitionShape,
+            renames: z.record(z.string()).optional().describe('Old field path → new field name, e.g. { "title": "heading", "items.label": "text" }. Send together with the new schema.'),
+            confirm_data_loss: z.boolean().optional().describe('Drop the data of removed or retyped fields that hold data. Only after the user agreed; the 409 lists what would be lost.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -188,7 +236,7 @@ export const blockTypeTools = [
     },
     {
         name: 'delete_block_type',
-        description: "Remove a custom block type. Core blocks (core/*) cannot be deleted. **Warning**: pages currently using this block type will render '<!-- unknown block type -->' comments instead. Call find_pages_using_block_type FIRST to see the blast radius; the AI should prompt the user before deleting if usage > 0.",
+        description: "Remove a site block type. Needs ADMIN permission; core blocks (core/*) cannot be deleted. Refused with 409 while anything uses the type — pages and drafts, page templates, header, footer, global blocks, block templates, other block types or repeaters — and the refusal lists the uses (as find_pages_using_block_type does). Remove those uses first and confirm with the user.",
         inputSchema: {
             type_id: z.string(),
             version: versionParam,

package/dist/tools/domain.js

@@ -28,6 +28,39 @@ export const domainTools = [
         inputSchema: { revision: z.string() },
         handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.post(siteId, 'publishing/managed-migration', args))),
     },
+    {
+        name: 'read_organization_publishing_connections', noSite: true,
+        description: 'Read the Organization\'s GitHub and Cloudflare publishing connections: status, revision (needed to change or disconnect), account identity, media_ready, media migration, and connect_urls. Requires an organization API key; never returns credentials. GitHub sign-in/App installation and Cloudflare OAuth need a person in a browser: give the user the matching connect_urls link (an organization owner or admin completes it), then read again.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client }) => ok(await client.rootGet('publishing/connections'))),
+    },
+    {
+        name: 'disconnect_organization_publishing_provider', noSite: true,
+        description: 'Disconnect the Organization\'s GitHub or Cloudflare publishing connection at the revision from read_organization_publishing_connections. Erases stored credentials; does not delete repositories, buckets, media, DNS or published sites, but publishing through that provider stops until reconnected. Requires an organization API key and the user\'s explicit go-ahead.',
+        inputSchema: { provider: z.enum(['github', 'cloudflare']), revision: z.string(), hosting_group_id: z.string().optional().describe('Omit for the organization (Default) connection.') },
+        handler: withErrorBoundary(async ({ provider, ...body }, { client }) => ok(await client.rootDelete(`publishing/connections/${provider}`, body))),
+    },
+    {
+        name: 'connect_organization_cloudflare', noSite: true,
+        description: 'Connect the Organization\'s default Cloudflare account without a browser, using a customer Cloudflare API token plus R2 access keys for an existing private bucket. Verifies the account, Pages access and the bucket before saving; credentials are encrypted and never returned. Requires an organization API key and the current revision. Reconnecting must keep the same account and bucket. For additional Hosting Groups use connect_hosting_group.',
+        inputSchema: {
+            revision: z.string(), account_id: z.string().regex(/^[a-f0-9]{32}$/), bucket: z.string(),
+            api_token: z.string(), access_key_id: z.string(), secret_access_key: z.string(),
+        },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPost('publishing/connections/cloudflare', { ...args, action: 'connect' }))),
+    },
+    {
+        name: 'prepare_organization_media_storage', noSite: true,
+        description: 'Create or reuse the Organization\'s private and public R2 media buckets in the connected Cloudflare account and configure upload CORS and lifecycle rules. Run after Cloudflare is connected and before save_organization_media_access. Requires an organization API key and the current Cloudflare revision. Idempotent.',
+        inputSchema: { revision: z.string() },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPost('publishing/connections/cloudflare', { ...args, action: 'prepare_media' }))),
+    },
+    {
+        name: 'save_organization_media_access', noSite: true,
+        description: 'Save and verify the Cloudflare R2 Access Key ID and Secret Access Key for the prepared media buckets (not the Cloudflare API token). Marks media storage ready, which imports require, and queues media migration. Requires an organization API key and the current Cloudflare revision. Keys are encrypted and never returned.',
+        inputSchema: { revision: z.string(), access_key_id: z.string(), secret_access_key: z.string() },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.rootPost('publishing/connections/cloudflare', { ...args, action: 'save_media' }))),
+    },
     {
         name: 'check_organization_github_permissions', noSite: true,
         description: 'Check live GitHub build permissions without disconnecting or reconnecting. Requires an organization API key. Distinguishes an update the organization owner can approve from permissions Typeroll has not requested yet. Returns the existing installation approval URL only when actionable; does not enable a build engine.',

package/dist/tools/email.js

@@ -0,0 +1,69 @@
+// Site email — the same settings as the portal's Settings → Email & notifications, with the
+// same admin permission: the outgoing connector that form notifications send
+// through (with a test send), and incoming email forwarding for host-approved
+// addresses. Secrets are write-only: reads return { set: true } instead.
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+export const emailTools = [
+    {
+        name: 'get_email_settings',
+        description: "Read the site's outgoing email connector (the provider form notifications send through): type, from, reply_to and config with secrets masked as { set: true }, plus every available provider with its field schema and whether the server can store secrets (crypto_configured). email is null when nothing is connected. Admin permission required.",
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'integrations/email'))),
+    },
+    {
+        name: 'set_email_settings',
+        description: "Connect or change the site's outgoing email provider, like Settings → Email & notifications in the portal. Read get_email_settings first for the provider field schema. Examples: postmark config { server_token, message_stream? }; smtp config { host, port?, secure?, user?, password? }. Secrets are encrypted server-side and never returned; omit a secret (or send the masked value) to keep the stored one. Then call send_test_email. Admin permission required.",
+        inputSchema: {
+            type: z.string().min(1).describe('Provider type from get_email_settings providers, e.g. "postmark" or "smtp".'),
+            from: z.string().min(1).describe('Sender, e.g. "Acme <hello@acme.com>". Must be a sender the provider accepts.'),
+            reply_to: z.string().optional().describe('Optional default Reply-To address.'),
+            config: z.record(z.unknown()).optional().describe('Provider fields keyed by the field schema.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.put(siteId, 'integrations/email', {
+            type: args.type,
+            from: args.from,
+            ...(args.reply_to !== undefined ? { reply_to: args.reply_to } : {}),
+            config: args.config ?? {},
+        }))),
+    },
+    {
+        name: 'delete_email_settings',
+        description: "Disconnect the site's outgoing email provider and delete its stored credentials. Form email notifications stop being sent until a provider is connected again; submissions are still stored. Admin permission required.",
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.del(siteId, 'integrations/email'))),
+    },
+    {
+        name: 'send_test_email',
+        description: 'Send a test email through the stored email connector to check it works, like "Send test" in the portal. Save the connector with set_email_settings first. Admin permission required.',
+        inputSchema: {
+            to: z.string().min(3).describe('Recipient address for the test message.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.post(siteId, 'integrations/email/test', { to: args.to }))),
+    },
+    {
+        name: 'get_incoming_email_settings',
+        description: "Read the site's incoming email forwarding: host-approved routes (alias → forwarding target), each route's current revision, whether forwarding is enabled and the last message receipt with delivery status. Routes are created by the hosting administrator; an empty list means none is approved yet. Admin permission required.",
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'delivery/inbound'))),
+    },
+    {
+        name: 'set_incoming_email_forwarding',
+        description: 'Enable or disable forwarding for one host-approved incoming email route, like Settings → Email & notifications in the portal. Pass the route_id and the current revision from get_incoming_email_settings; a changed route (409) must be read again and reviewed first. This cannot create aliases or change targets. Enable, verify with a real test message, and only then change the site\'s Reply-To. Admin permission required.',
+        inputSchema: {
+            route_id: z.string().min(1),
+            revision: z.string().min(1).describe('The revision returned by get_incoming_email_settings for this route.'),
+            enabled: z.boolean(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.put(siteId, 'delivery/inbound', {
+            route_id: args.route_id,
+            revision: args.revision,
+            enabled: args.enabled,
+        }))),
+    },
+    {
+        name: 'read_incoming_email_receipt',
+        description: 'Read one incoming email receipt (status such as forwarded, held or blocked, its reason and the forwarded delivery status) by the receipt_id shown in get_incoming_email_settings. Contains no subject, sender or body. Admin permission required.',
+        inputSchema: {
+            receipt_id: z.string().regex(/^[a-f0-9]{64}$/),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => ok(await client.get(siteId, `delivery/inbound/${encodeURIComponent(args.receipt_id)}`))),
+    },
+];