@typeroll/mcp-server 0.45.43 → 0.45.45

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 or email 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';
@@ -60,8 +63,48 @@ 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')
         return 'admin';
+    if (name === 'diff_version')
+        return 'read';
     if (name.startsWith('list_') ||
         name.startsWith('read_') ||
         name.startsWith('get_') ||
@@ -158,15 +201,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/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/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)}`))),
+    },
+];

package/dist/tools/extensions.js

@@ -66,4 +66,135 @@ export const extensionTools = [
             }
         }),
     },
+    {
+        name: 'install_extension',
+        description: 'Install an Extension release on this site, as the portal\'s install action does. Pass the Extension id and a published release (developer organizations may also install their own draft or review releases on their own sites). granted_scopes must be a subset of the manifest\'s requested permissions — grant only what the user approved. config must satisfy manifest.config_schema; secret values are encrypted and never returned. Does not deploy: trigger_deploy afterwards to publish provisioned components. Admin permission required.',
+        inputSchema: {
+            extension_id: z.string().min(1),
+            version: z.string().min(1).describe('Release version to install.'),
+            granted_scopes: z.array(z.string()).optional().describe('Approved scopes; defaults to none.'),
+            config: z.record(z.unknown()).optional(),
+            developer_org_id: z.string().optional().describe('Organization that publishes the Extension. Defaults to the key\'s own organization.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.post(siteId, 'extensions', args));
+        }),
+    },
+    {
+        name: 'set_extension_installation_status',
+        description: 'Enable or disable an installed Extension on this site. Disabling removes its components from the public snapshot and editor until re-enabled; page instances are kept. Changes apply immediately to previews; deploy to publish. Admin permission required.',
+        inputSchema: {
+            installation_id: z.string().min(1),
+            status: z.enum(['enabled', 'disabled']),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.patch(siteId, `extensions/${encodeURIComponent(args.installation_id)}`, { status: args.status }));
+        }),
+    },
+    {
+        name: 'uninstall_extension',
+        description: 'Uninstall an Extension from this site: revokes the installation and all its server credentials and removes its block definitions. Existing page blocks remain as unavailable placeholders. Not reversible except by installing again (a new installation id). Get explicit user approval. Admin permission required.',
+        inputSchema: { installation_id: z.string().min(1) },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.del(siteId, `extensions/${encodeURIComponent(args.installation_id)}`));
+        }),
+    },
+    {
+        name: 'pair_extension_issuer',
+        description: 'Pair this Typeroll instance\'s token issuer with the Extension provider (manifest auth.pairing_url), the portal\'s "secure connection" action. Contacts the provider. Returns the trusted issuer record. Admin permission required.',
+        inputSchema: { installation_id: z.string().min(1) },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.post(siteId, `extensions/${encodeURIComponent(args.installation_id)}/pair`));
+        }),
+    },
+    {
+        name: 'read_extension_diagnostics',
+        description: 'Read an installation\'s diagnostics: status, health, release resolution, credential metadata (no secrets), the latest audit events and lifecycle event deliveries, and declared URL context inputs. Admin permission required.',
+        inputSchema: { installation_id: z.string().min(1) },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.get(siteId, `extensions/${encodeURIComponent(args.installation_id)}/diagnostics`));
+        }),
+    },
+    {
+        name: 'launch_extension_admin_page',
+        description: 'Issue a single-use, short-lived launch grant for one of the Extension\'s admin pages (manifest admin.pages), as opening the page in the portal does. Returns { launch_url, method, form, expires_at }: a browser tool must POST the `form` fields to launch_url before expires_at. The provider sees the caller as api-key:{prefix}. Treat the code as a credential. For approved native pages prefer call_extension_admin. The page\'s minimum_permission applies.',
+        inputSchema: {
+            installation_id: z.string().min(1),
+            page_id: z.string().min(1).describe('Admin page id from the installation manifest.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            return ok(await client.post(siteId, `extensions/${encodeURIComponent(args.installation_id)}/launch`, { page_id: args.page_id }));
+        }),
+    },
+];
+const ext = (id) => `extensions/${encodeURIComponent(id)}`;
+/** Extension developer tools — the `typeroll extension` CLI's API. They act on
+ *  the key's own organization, not on a site, and need an
+ *  organization-scoped key (a site key gets 403). */
+export const developerExtensionTools = [
+    {
+        name: 'list_developer_extensions', noSite: true,
+        description: 'List Extensions registered by your organization (developer side). Requires an organization API key.',
+        handler: withErrorBoundary(async (_args, { client }) => ok(await client.developer('GET', 'extensions'))),
+    },
+    {
+        name: 'read_developer_extension', noSite: true,
+        description: 'Read one of your organization\'s Extensions with all saved releases and their status (draft, review, published, deprecated, revoked). Requires an organization API key.',
+        inputSchema: { extension_id: z.string().min(1) },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.developer('GET', ext(args.extension_id)))),
+    },
+    {
+        name: 'update_developer_extension', noSite: true,
+        description: 'Update an Extension\'s name, status (active/suspended), distribution (only while every release is a draft), trusted origins or private allow-lists. Requires an organization API key.',
+        inputSchema: {
+            extension_id: z.string().min(1),
+            name: z.string().optional(),
+            status: z.enum(['active', 'suspended']).optional(),
+            distribution: z.enum(['private', 'unlisted', 'public']).optional(),
+            trusted_origins: z.array(z.string()).optional(),
+            allowed_org_ids: z.array(z.string()).optional(),
+            allowed_site_ids: z.array(z.string()).optional(),
+        },
+        handler: withErrorBoundary(async (args, { client }) => {
+            const { extension_id, ...patch } = args;
+            return ok(await client.developer('PATCH', ext(extension_id), patch));
+        }),
+    },
+    {
+        name: 'save_extension_version', noSite: true,
+        description: 'Save (create or replace) a draft release from a full Extension manifest. Published releases are immutable; bump manifest.version instead. Validate locally with `typeroll extension validate` first. Requires an organization API key.',
+        inputSchema: {
+            extension_id: z.string().min(1),
+            manifest: z.record(z.unknown()).describe('Complete manifest; its id must equal extension_id.'),
+        },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.developer('POST', `${ext(args.extension_id)}/versions`, { manifest: args.manifest }))),
+    },
+    {
+        name: 'publish_extension_version', noSite: true,
+        description: 'Publish a saved release after verifying its asset digests. Private releases become installable for allowed organizations and sites; public releases enter review before catalog discovery. Installations follow compatible published releases automatically, so get user approval. Requires an organization API key.',
+        inputSchema: { extension_id: z.string().min(1), version: z.string().min(1) },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.developer('POST', `${ext(args.extension_id)}/versions/${encodeURIComponent(args.version)}/publish`))),
+    },
+    {
+        name: 'set_extension_version_lifecycle', noSite: true,
+        description: 'Deprecate or revoke a release. Revoking stops installations from resolving to it. Requires an organization API key.',
+        inputSchema: {
+            extension_id: z.string().min(1),
+            version: z.string().min(1),
+            status: z.enum(['deprecated', 'revoked']),
+            reason: z.string().optional(),
+        },
+        handler: withErrorBoundary(async (args, { client }) => {
+            const { extension_id, version, ...body } = args;
+            return ok(await client.developer('PATCH', `${ext(extension_id)}/versions/${encodeURIComponent(version)}`, body));
+        }),
+    },
+    {
+        name: 'list_developer_extension_installations', noSite: true,
+        description: 'List operational metadata (status, versions, health; never config) for your Extension\'s installations on one customer site. Requires an organization API key and the customer\'s organization and site ids.',
+        inputSchema: { extension_id: z.string().min(1), owner_org_id: z.string().min(1), site_id: z.string().min(1) },
+        handler: withErrorBoundary(async (args, { client }) => ok(await client.developer('GET', `${ext(args.extension_id)}/installations`, undefined, {
+            owner_org_id: args.owner_org_id, site_id: args.site_id,
+        }))),
+    },
 ];

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 (see get_form_capabilities).'),
+    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 (get_form_capabilities lists the types and their config). Read the form first and send back the actions you keep. Emails send through the provider set with set_email_settings. Requires admin permission, like the portal.';
 export const formTools = [
     {
         name: 'list_forms',
@@ -42,9 +53,14 @@ export const formTools = [
             return ok(res);
         }),
     },
+    {
+        name: 'get_form_capabilities',
+        description: 'List the action types a form can run after a submission (core "email" and "webhook" plus types provided by installed apps) and the prefill sources, each with its config field schema — the same choices as the portal\'s Forms editor. Read this before writing `actions` with create_form/update_form. Admin permission required.',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'form-capabilities'))),
+    },
     {
         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 +78,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 +91,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 +101,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,
             }),
         },
@@ -106,7 +124,7 @@ export const formTools = [
     },
     {
         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.',
+        description: 'List submissions received for a form, newest first, cursor-paginated (cap 200 per page). Admins also see each submission\'s webhook delivery status. Use this to help a customer triage inbound contact / lead submissions; read_form_submission reads one.',
         inputSchema: {
             form_id: z.string(),
             limit: z.number().int().min(1).max(200).optional(),
@@ -118,6 +136,18 @@ export const formTools = [
             return ok(res);
         }),
     },
+    {
+        name: 'read_form_submission',
+        description: 'Read one submission of a form by id (from list_form_submissions): the submitted values, status (partial or complete), step and timestamps. Admins also see its webhook delivery status, as in the portal.',
+        inputSchema: {
+            form_id: z.string(),
+            submission_id: z.string(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `forms/${encodeURIComponent(args.form_id)}/submissions/${encodeURIComponent(args.submission_id)}`);
+            return ok(res);
+        }),
+    },
     {
         name: 'delete_form_submission',
         description: 'Delete a single submission from a form\'s inbox. Use this to remove individual entries (test submissions, spam) without touching the rest — delete_form with delete_submissions is the only way to bulk-delete. Get submission ids from list_form_submissions.',

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/media.js

@@ -18,6 +18,12 @@ export const mediaTools = [
         inputSchema: {},
         handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'media/import'))),
     },
+    {
+        name: 'get_media_upload_status',
+        description: 'Pre-flight for uploads: whether media uploads can go through for this site right now (organization storage connected, or platform storage configured), with the reason and a settings_url when they cannot. Same check as the banner in the portal media library. Requires site read access.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.get(siteId, 'media/upload-status'))),
+    },
     {
         name: 'read_private_media_url',
         description: 'Get a 60-second read URL for a private media original. Use it for authorized image inspection; never store it in page content or generated source. Use the stable media URL or ID in content.',
@@ -229,6 +235,12 @@ export const mediaTools = [
             return ok(res);
         }),
     },
+    {
+        name: 'purge_site_media',
+        description: 'Permanently delete every media object and record of an ARCHIVED site (archive_site first; an active site returns 409). Irreversible — the step before retiring a site for good, same as the portal action. Requires an admin key of the organization that owns the site; shared access is refused. Returns counts; HTTP 207 with `failed` lists objects that could not be removed (their records are kept) — call again to retry exactly those. Confirm with the user before calling.',
+        inputSchema: {},
+        handler: withErrorBoundary(async (_args, { client, siteId }) => ok(await client.post(siteId, 'media/purge'))),
+    },
     {
         name: 'delete_media',
         description: 'Delete a media item\'s metadata. (R2 object cleanup is a separate ops task.)',