@typeroll/mcp-server 0.7.4

package/dist/index.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// Typeroll MCP server — stdio entry point.
+//
+// Reads two env vars at startup:
+//   TYPEROLL_API_URL  — base URL of the portal (e.g. https://app.typeroll.com)
+//   TYPEROLL_API_KEY  — a typeroll_live_... bearer token from /app/sites/{id}/settings/api-keys
+//
+// Optionally:
+//   TYPEROLL_SITE_ID  — pre-set the site id. If omitted we discover it by
+//                   calling GET /v1/sites at startup (the v1 keys are
+//                   per-site so that endpoint always returns exactly one).
+//
+// Each tool wraps a single REST endpoint. The MCP server itself does no
+// business logic — that all lives in the portal. This keeps the package
+// boring to maintain and lets the customer's self-hosted portal serve the
+// same MCP without needing two implementations to stay in sync.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { TyperollClient } from './client.js';
+import { pageTools } from './tools/pages.js';
+import { partialTools } from './tools/partials.js';
+import { collectionTools } from './tools/collections.js';
+import { mediaTools } from './tools/media.js';
+import { redirectTools } from './tools/redirects.js';
+import { formTools } from './tools/forms.js';
+import { searchTools } from './tools/search.js';
+import { bulkTools } from './tools/bulk.js';
+import { versionTools } from './tools/versions.js';
+import { deployTools } from './tools/deploy.js';
+import { previewTools } from './tools/preview.js';
+import { blockTypeTools } from './tools/block-types.js';
+import { pageBlockTools } from './tools/page-blocks.js';
+import { settingsTools } from './tools/settings.js';
+import { siteTools } from './tools/sites.js';
+const VERSION = '0.1.0';
+async function resolveSiteId(client) {
+    const fromEnv = process.env.TYPEROLL_SITE_ID?.trim();
+    if (fromEnv)
+        return fromEnv;
+    // Per-site keys → exactly one site. We fetch it so the agent doesn't
+    // have to know its own site id ahead of time.
+    const res = await client.rootGet('sites');
+    if (!res.sites || res.sites.length === 0) {
+        throw new Error('No sites returned for this API key. Check the key is valid.');
+    }
+    if (res.sites.length > 1) {
+        throw new Error(`This key authorises ${res.sites.length} sites; set TYPEROLL_SITE_ID to pick one.`);
+    }
+    return res.sites[0].id;
+}
+function bail(message) {
+    console.error(`typeroll-mcp: ${message}`);
+    process.exit(1);
+}
+async function main() {
+    const apiUrl = process.env.TYPEROLL_API_URL?.trim();
+    const apiKey = process.env.TYPEROLL_API_KEY?.trim();
+    if (!apiUrl)
+        bail('TYPEROLL_API_URL is not set. Point it at your Typeroll portal (e.g. https://app.typeroll.com).');
+    if (!apiKey)
+        bail('TYPEROLL_API_KEY is not set. Create a key in /app/sites/{siteId}/settings/api-keys and copy it once.');
+    if (!apiKey.startsWith('typeroll_live_')) {
+        bail('TYPEROLL_API_KEY does not look like a Typeroll key (expected typeroll_live_... prefix).');
+    }
+    const client = new TyperollClient({ baseUrl: apiUrl, apiKey });
+    let siteId;
+    try {
+        siteId = await resolveSiteId(client);
+    }
+    catch (e) {
+        bail(`Failed to discover site: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const deps = { client, siteId };
+    const server = new McpServer({ name: 'typeroll', version: VERSION }, { capabilities: { tools: {} } });
+    const allTools = [
+        ...siteTools,
+        ...pageTools,
+        ...partialTools,
+        ...blockTypeTools,
+        ...pageBlockTools,
+        ...collectionTools,
+        ...mediaTools,
+        ...redirectTools,
+        ...formTools,
+        ...settingsTools,
+        ...searchTools,
+        ...bulkTools,
+        ...versionTools,
+        ...deployTools,
+        ...previewTools,
+    ];
+    // The SDK's registerTool signature has very deep generic constraints
+    // (ZodRawShape × AnySchema × annotations) that TypeScript can't unify
+    // when we iterate heterogeneous tools at runtime. We cast the bag once
+    // here and rely on our own ToolDef contract for type safety.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const register = server.registerTool.bind(server);
+    for (const tool of allTools) {
+        register(tool.name, {
+            description: tool.description,
+            ...(tool.inputSchema ? { inputSchema: tool.inputSchema } : {}),
+        }, 
+        // The SDK's callback gets the args object (when inputSchema is set) or
+        // no args (when it isn't). Both are valid for our handler signature.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        async (args) => tool.handler(args ?? {}, deps));
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error('typeroll-mcp fatal:', err);
+    process.exit(1);
+});

package/dist/tools/block-types.js

@@ -0,0 +1,86 @@
+// Block-type tools. Surface is wired in now so the future block editor
+// drops in without breaking integrations.
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+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.',
+        inputSchema: {
+            ids: z.array(z.string()).optional().describe('Specific block-type ids to include. Omit to export every user-created block.'),
+            name: z.string().optional().describe('Package name (default: {site}-blocks).'),
+            version: z.string().optional().describe('Package version (default: 1.0.0).'),
+            version_branch: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const query = {};
+            if (args.ids?.length)
+                query.ids = args.ids.join(',');
+            if (args.name)
+                query.name = args.name;
+            if (args.version)
+                query.version = args.version;
+            if (args.version_branch)
+                query.version = args.version_branch;
+            const res = await client.get(siteId, 'blocks/export', query);
+            return ok(res);
+        }),
+    },
+    {
+        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.',
+        inputSchema: {
+            zip_base64: z.string().describe('Base64-encoded .tcblocks zip.'),
+            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);
+            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). Each entry includes id, label, category, container/slot info, origin, and the full schema (fields with name/type/label/required/options/default). Call this FIRST when starting block-mode work — never hardcode block ids; the available set is per-site.',
+        inputSchema: {
+            include_core: z.boolean().optional().describe('Default true. Set false to get only custom + third-party (rarely needed).'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const query = {};
+            if (args.version)
+                query.version = args.version;
+            if (args.include_core === false)
+                query.include_core = 'false';
+            const res = await client.get(siteId, 'block-types', query);
+            return ok(res);
+        }),
+    },
+    {
+        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.",
+        inputSchema: {
+            type_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `block-types/${encodeURIComponent(args.type_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        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.',
+        inputSchema: {
+            type_id: z.string(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `block-types/${encodeURIComponent(args.type_id)}/usage`, v(args.version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/bulk.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const bulkTools = [
+    {
+        name: 'bulk_replace_text',
+        description: 'Replace a literal substring or regex across pages in one call. ALWAYS run with dry_run=true first and show the sample_diffs to the user before running the real call. Writes go through the normal pipeline (SEO transforms + revision snapshots). Response shape: { dry_run, updated, total_matches, pages_with_matches, sample_diffs_shown, additional_pages_with_matches, sample_diffs[], skipped (deprecated) }.',
+        inputSchema: {
+            pattern: z.string().min(1).describe('Literal substring (default) or JS regex source if regex=true.'),
+            replacement: z.string(),
+            regex: z.boolean().optional().describe('Treat pattern as a regex source. Always case-insensitive + global.'),
+            page_ids: z.array(z.string()).optional().describe('Restrict to these page ids. Omit to apply to every matching page.'),
+            dry_run: z.boolean().optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'bulk-replace', body, v(version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/collections.js

@@ -0,0 +1,197 @@
+// Collections + items (blog, team, events, products, custom).
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const collectionTools = [
+    {
+        name: 'create_collection',
+        description: 'Create a new content collection with a field schema and (optionally) per-item URLs. Pass `route_template` (e.g. "/restaurants/{slug}") to give each published item its own URL — omit to default to "/{name}/{slug}", set to "" to disable per-item URLs entirely.',
+        inputSchema: {
+            name: z.string().regex(/^[a-z][a-z0-9_-]{0,62}$/),
+            label_singular: z.string().min(1),
+            label_plural: z.string().min(1),
+            icon: z.string().optional(),
+            fields: z
+                .array(z.object({
+                name: z.string(),
+                label: z.string(),
+                type: z.string(),
+                required: z.boolean().optional(),
+                default: z.unknown().optional(),
+                options: z.array(z.string()).optional(),
+            }).passthrough())
+                .min(1),
+            slug_field: z.string().optional(),
+            sort_field: z.string().optional(),
+            sort_dir: z.enum(['asc', 'desc']).optional(),
+            route_template: z.string().optional(),
+            item_template_html: z.string().optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'collections', body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_collection_schema',
+        description: 'PATCH a collection\'s schema or routing. Pass only the fields you want to change. Renaming a field would orphan existing item data — adding new fields is safe, removing fields is silently allowed but item docs keep the dropped data.',
+        inputSchema: {
+            name: z.string(),
+            patch: z
+                .object({
+                label_singular: z.string().optional(),
+                label_plural: z.string().optional(),
+                icon: z.string().optional(),
+                fields: z.array(z.record(z.unknown())).optional(),
+                slug_field: z.string().optional(),
+                sort_field: z.string().optional(),
+                sort_dir: z.enum(['asc', 'desc']).optional(),
+                route_template: z.string().optional(),
+                item_template_html: z.string().optional(),
+            })
+                .passthrough(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.patch(siteId, `collections/${encodeURIComponent(args.name)}`, args.patch, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'delete_collection',
+        description: 'Delete a collection AND every item in it. Destructive; requires `confirm: true`. Get-the-user-to-confirm workflow recommended.',
+        inputSchema: {
+            name: z.string(),
+            confirm: z.literal(true).describe('Must be true to actually delete.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `collections/${encodeURIComponent(args.name)}`, { confirm: 'true', ...v(args.version) });
+            return ok(res);
+        }),
+    },
+    {
+        name: 'list_collections',
+        description: 'List content collections on the site (name, label, icon, field schemas).',
+        inputSchema: { version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, 'collections', v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_collection',
+        description: 'Fetch one collection\'s schema (label, fields, icon).',
+        inputSchema: { name: z.string(), version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `collections/${encodeURIComponent(args.name)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'list_collection_items',
+        description: 'List items in a collection with status filter + cursor pagination (cap 200 per page). Defaults to summary mode (richtext/textarea fields replaced with a byte-count hint) so a 200-item directory listing stays compact; pass include_richtext: true if you actually need full bodies.',
+        inputSchema: {
+            collection: z.string(),
+            status: z.enum(['draft', 'published', 'all']).optional(),
+            limit: z.number().int().min(1).max(200).optional(),
+            cursor: z.string().optional(),
+            include_richtext: z.boolean().optional().describe('Include full richtext/textarea field values inline. Default false.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { collection, version, include_richtext, ...query } = args;
+            const res = await client.get(siteId, `collections/${encodeURIComponent(collection)}/items`, { ...query, ...(include_richtext ? {} : { summary: 'true' }), ...v(version) });
+            return ok(res);
+        }),
+    },
+    {
+        name: 'batch_read_collection_items',
+        description: 'Read up to 200 collection items in one call. Returns per-id found/not-found.',
+        inputSchema: {
+            collection: z.string(),
+            item_ids: z.array(z.string()).min(1).max(200),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `collections/${encodeURIComponent(args.collection)}/items/batch-read`, { item_ids: args.item_ids }, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_collection_item',
+        description: 'Fetch a single item with all fields.',
+        inputSchema: { collection: z.string(), item_id: z.string(), version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `collections/${encodeURIComponent(args.collection)}/items/${encodeURIComponent(args.item_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'create_collection_item',
+        description: 'Create an item. Fields outside the collection schema are silently dropped — call list_collections first if you\'re unsure what fields exist.',
+        inputSchema: {
+            collection: z.string(),
+            fields: z.record(z.unknown()),
+            status: z.enum(['draft', 'published']).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { collection, version, ...body } = args;
+            const res = await client.post(siteId, `collections/${encodeURIComponent(collection)}/items`, body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_collection_item',
+        description: 'Update a collection item. Fields outside the schema are dropped.',
+        inputSchema: {
+            collection: z.string(),
+            item_id: z.string(),
+            fields: z.record(z.unknown()).optional(),
+            status: z.enum(['draft', 'published']).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { collection, item_id, version, ...body } = args;
+            const res = await client.patch(siteId, `collections/${encodeURIComponent(collection)}/items/${encodeURIComponent(item_id)}`, body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'regenerate_collection_listing',
+        description: 'Refresh a hand-managed listing of collection items on a page. The agent inserts a marker pair `<!-- typeroll:listing:{collection} -->` ... `<!-- /typeroll:listing:{collection} -->` into a page body once; from then on this tool fills the section between the markers with the current published items, sorted by the collection\'s sort_field. Pass `item_template` to customize per-item HTML — {{field}} substitutes HTML-escaped, {{{field}}} raw, {{url}} resolves through the collection\'s route_template. Defaults to a basic <ul> of links.',
+        inputSchema: {
+            collection: z.string(),
+            page_id: z.string(),
+            item_template: z.string().optional()
+                .describe('Per-item HTML template. Default: <li><a href="{{url}}">{{title}}</a></li>'),
+            wrap_open: z.string().optional().describe('Override the opening wrap element. Default: <ul class="tr-listing">'),
+            wrap_close: z.string().optional().describe('Override the closing wrap element. Default: </ul>'),
+            empty_html: z.string().optional().describe('Rendered when no items exist.'),
+            sort_field: z.string().optional().describe('Override the collection\'s default sort_field.'),
+            sort_dir: z.enum(['asc', 'desc']).optional(),
+            status_filter: z.enum(['published', 'all']).optional().describe('Default: published.'),
+            limit: z.number().int().min(1).max(500).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { collection, version, ...body } = args;
+            const res = await client.post(siteId, `collections/${encodeURIComponent(collection)}/regenerate-listing`, body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'delete_collection_item',
+        description: 'Delete a collection item.',
+        inputSchema: { collection: z.string(), item_id: z.string(), version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `collections/${encodeURIComponent(args.collection)}/items/${encodeURIComponent(args.item_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/deploy.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const deployTools = [
+    {
+        name: 'trigger_deploy',
+        description: "Enqueue a deploy of the currently active version. Returns a job_id immediately; poll get_deploy_status until the status leaves queued/running. With `dry_run: true`, the deploy runs through every step EXCEPT the hosting-adapter upload — useful for validating a structural change (new collection routes, schema bump, mode switch) without risking the live site. A dry_run job that succeeds proves the build is clean; one that fails returns the same astro stack-trace in get_deploy_status.error as a real deploy would.",
+        inputSchema: {
+            environment: z.enum(['production', 'staging']).optional(),
+            dry_run: z.boolean().optional().describe('Run the build but skip the CDN upload. The job ends in succeeded/failed the same way a real deploy does.'),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'deploy', body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'list_deploys',
+        description: 'Recent deploy jobs, newest first (capped at 50).',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, 'deploys');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'get_deploy_status',
+        description: "Status of a single deploy job. Returns { job, queued_for_seconds, queue_timeout_seconds }. job.status is one of queued | running | succeeded | failed. Polling cadence: ~5s for queued/running. A job stuck in 'queued' for longer than queue_timeout_seconds (default 300s) auto-flips to failed with phase='queue_timeout' — so a single poll past that timestamp returns the terminal state and you can stop polling.",
+        inputSchema: { job_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `deploys/${encodeURIComponent(args.job_id)}`);
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/forms.js

@@ -0,0 +1,98 @@
+// Forms — agents can create/update/delete forms, and read submissions.
+// The customer-facing submit endpoint is HMAC-signed and lives at
+// /api/forms/submit; the in-portal chat's `get_form_embed` tool produces
+// the snippet customers paste into their pages. This file is the
+// management surface.
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+const fieldSchema = z.object({
+    name: z.string().regex(/^[a-z][a-z0-9_-]{0,62}$/),
+    type: z.enum([
+        'text', 'email', 'tel', 'url', 'number', 'textarea',
+        'select', 'checkbox', 'radio', 'hidden', 'gdpr_consent',
+    ]),
+    label: z.string(),
+    required: z.boolean().optional(),
+    placeholder: z.string().optional(),
+    options: z.array(z.string()).optional().describe('Required for type "select" and "radio".'),
+    default: z.unknown().optional(),
+});
+export const formTools = [
+    {
+        name: 'list_forms',
+        description: 'List every form defined on the site with its full field schema.',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, 'forms');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_form',
+        description: 'Read one form by id, including fields, submit_text, and success_message.',
+        inputSchema: { form_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `forms/${encodeURIComponent(args.form_id)}`);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'create_form',
+        description: 'Create a form. Each field has { name, type, label, required?, placeholder?, options? }. Allowed types: text, email, tel, url, number, textarea, select, checkbox, radio, hidden, gdpr_consent. The form can then be embedded on any page — use get_form_embed (in-portal chat) or render the form yourself by reading the schema.',
+        inputSchema: {
+            id: z.string().regex(/^[a-z][a-z0-9_-]{0,62}$/),
+            name: z.string().min(1),
+            fields: z.array(fieldSchema).min(1),
+            submit_text: z.string().optional(),
+            success_message: z.string().optional(),
+            actions: z.array(z.object({ type: z.string(), config: z.record(z.unknown()) })).optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'forms', args);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_form',
+        description: 'Patch a form. Provide only the fields you want to change. Passing `fields` replaces the entire field list (so reorder + rename + drop happens in one call). The existing form_id is immutable.',
+        inputSchema: {
+            form_id: z.string(),
+            patch: z.object({
+                name: z.string().optional(),
+                fields: z.array(fieldSchema).optional(),
+                submit_text: z.string().optional(),
+                success_message: z.string().optional(),
+                actions: z.array(z.object({ type: z.string(), config: z.record(z.unknown()) })).optional(),
+            }),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.patch(siteId, `forms/${encodeURIComponent(args.form_id)}`, args.patch);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'delete_form',
+        description: 'Delete a form. Existing submissions are preserved by default — pass delete_submissions: true to also drop them.',
+        inputSchema: {
+            form_id: z.string(),
+            delete_submissions: z.boolean().optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `forms/${encodeURIComponent(args.form_id)}`, args.delete_submissions ? { delete_submissions: 'true' } : undefined);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'list_form_submissions',
+        description: 'List submissions received for a form, newest first, cursor-paginated (cap 200 per page). Use this to help a customer triage inbound contact / lead submissions.',
+        inputSchema: {
+            form_id: z.string(),
+            limit: z.number().int().min(1).max(200).optional(),
+            cursor: z.string().optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { form_id, ...query } = args;
+            const res = await client.get(siteId, `forms/${encodeURIComponent(form_id)}/submissions`, query);
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/helpers.js

@@ -0,0 +1,59 @@
+// Shared helpers for tool handlers.
+import { z } from 'zod';
+import { ApiError } from '../client.js';
+/** Format an arbitrary result as MCP tool output. Pretty-print JSON because
+ *  Claude renders code blocks well and we want the model to see structured
+ *  shapes, not blobby unfolded strings. */
+export function ok(data) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: typeof data === 'string' ? data : JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+/** Turn an API error into a structured tool error. Preserves the status
+ *  code so the agent can decide between "retry" and "give up". */
+export function fail(err) {
+    if (err instanceof ApiError) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: err.message,
+                        status: err.status,
+                        body: err.body,
+                    }, null, 2),
+                },
+            ],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            { type: 'text', text: `Unexpected error: ${err instanceof Error ? err.message : String(err)}` },
+        ],
+        isError: true,
+    };
+}
+/** Convenience to wrap a handler so all API errors become structured tool
+ *  errors instead of throwing — Claude Code displays the result more
+ *  usefully when isError is set. */
+export function withErrorBoundary(handler) {
+    return async (args, deps) => {
+        try {
+            return await handler(args, deps);
+        }
+        catch (err) {
+            return fail(err);
+        }
+    };
+}
+/** Shared zod fragment for the optional `version` parameter. */
+export const versionParam = z
+    .string()
+    .optional()
+    .describe('Branch id to target. Omit for main.');