@francescomalatesta/laravel-forge-mcp 0.4.0 → 0.6.0

package/README.md

@@ -89,12 +89,34 @@ npm run build
 | `forge_set_site_env_vars` | sites | Set or remove .env variables without exposing the file |
 | `forge_get_site_environment` 🔑 | sites | Read the whole .env file |
 | `forge_update_site_environment` 🔑 | sites | Replace the whole .env file |
-| `forge_get_site_nginx_config` | sites | Read the site's Nginx configuration |
-| `forge_update_site_nginx_config` | sites | Replace the site's Nginx configuration |
+| `forge_get_site_nginx_config` | sites | Read the Nginx configuration of a site or one of its domains |
+| `forge_update_site_nginx_config` | sites | Replace the Nginx configuration of a site or one of its domains |
 | `forge_get_site_log` | sites | End of the application, Nginx access or Nginx error log |
 | `forge_clear_site_log` | sites | Empty a site log |
 | `forge_get_site_healthcheck` | sites | Healthcheck URL used after zero-downtime deployments |
 | `forge_update_site_healthcheck` | sites | Set or remove the healthcheck URL |
+| `forge_list_domains` | sites | Domains of a site with status and www redirection |
+| `forge_get_domain` | sites | A domain with the DNS records to configure |
+| `forge_add_domain` | sites | Add a domain (alias) and wait until it is enabled |
+| `forge_update_domain` | sites | Change www redirection and wildcard subdomains |
+| `forge_run_domain_action` | sites | Enable, disable or mark a domain as primary |
+| `forge_delete_domain` | sites | Remove a domain |
+| `forge_list_certificates` | sites | SSL certificates of a site or of one domain |
+| `forge_get_certificate` | sites | A certificate, or the active one |
+| `forge_create_certificate` | sites | Let's Encrypt, existing, CSR or cloned certificate, waiting until installed |
+| `forge_run_certificate_action` | sites | Activate or deactivate a certificate |
+| `forge_delete_certificate` | sites | Delete a certificate |
+| `forge_run_service_action` | servers | Restart or stop Nginx, MySQL, Postgres, Redis, Supervisor; restart or reload PHP-FPM |
+| `forge_run_server_action` | servers | Reboot or power-cycle a server |
+| `forge_get_server_log` | servers | End of a server log (Nginx, PHP-FPM, MySQL, cron, daemons) |
+| `forge_clear_server_log` | servers | Empty a server log |
+| `forge_update_server` | servers | Rename, change IP addresses, timezone or tags |
+| `forge_get_server_network` | servers | Servers that can reach each other on the private network |
+| `forge_update_server_network` | servers | Set the server network |
+| `forge_list_archived_servers` | servers | Archived servers |
+| `forge_archive_server` | servers | Archive a server (Forge stops managing it) |
+| `forge_unarchive_server` | servers | Restore an archived server |
+| `forge_delete_server` | servers | Delete a server (optionally keeping it at the provider) |
 | `forge_list_deployments` | deployments | Deployments of a site or of every site on a server |
 | `forge_get_deployment` | deployments | A deployment with the end of its log |
 | `forge_get_deployment_status` | deployments | Whether a deployment is running |

package/dist/tools/certificates/create-certificate.js

@@ -0,0 +1,116 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { ToolInputError } from '../errors.js';
+import { operationOutput, outcome, waitFor, waitInput } from '../shared/async.js';
+import { DOMAIN_NOT_FOUND_HINT, domainPath, domainScopeInput } from '../domains/shared.js';
+import { certificateOutput, certificatePhase, formatCertificate, readCertificate } from './shared.js';
+const CHECK_WITH = 'forge_get_certificate';
+export const createCertificate = defineTool({
+    name: 'forge_create_certificate',
+    title: 'Create certificate',
+    description: [
+        'Secure a domain with an SSL certificate. Types:',
+        '"letsencrypt" (free, issued and renewed automatically; the domain DNS must already point to the server, or use dns-01 verification);',
+        '"existing" (install your own `certificate` chain and `private_key`);',
+        '"csr" (generate a signing request to send to a certificate authority);',
+        '"clone" (copy certificate `clone_certificate_id` from another domain).',
+        'Waits until the certificate is issued and installed unless `wait` is false.',
+    ].join(' '),
+    toolset: 'sites',
+    operations: ['organizations.servers.sites.domains.certificates.store', 'organizations.servers.sites.domains.certificates.show'],
+    permissions: ['site:manage-ssl', 'site:meta'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    async: true,
+    notFoundHint: DOMAIN_NOT_FOUND_HINT,
+    inputSchema: {
+        ...domainScopeInput,
+        type: z.enum(['letsencrypt', 'existing', 'csr', 'clone']).default('letsencrypt'),
+        enable: z.boolean().optional().describe('Activate the certificate once installed (existing and clone only; Let\'s Encrypt activates automatically).'),
+        verification_method: z.enum(['http-01', 'dns-01']).optional().describe('Let\'s Encrypt: domain verification method.'),
+        key_type: z.enum(['ecdsa', 'rsa']).optional().describe('Let\'s Encrypt: key type.'),
+        preferred_chain: z.enum(['ISRG Root X1']).optional().describe('Let\'s Encrypt: preferred chain.'),
+        certificate: z.string().min(1).optional().describe('Existing: the certificate chain (PEM).'),
+        private_key: z.string().min(1).optional().describe('Existing: the private key (PEM).'),
+        csr_domain: z.string().min(1).optional().describe('CSR: domain to generate the request for.'),
+        csr_sans: z.string().min(1).optional().describe('CSR: additional domains, comma-separated.'),
+        csr_country: z.string().min(1).optional(),
+        csr_state: z.string().min(1).optional(),
+        csr_city: z.string().min(1).optional(),
+        csr_organization: z.string().min(1).optional(),
+        csr_department: z.string().min(1).optional(),
+        clone_certificate_id: z.number().int().optional().describe('Clone: ID of the certificate to copy.'),
+        ...waitInput(180),
+    },
+    outputSchema: {
+        ...operationOutput,
+        certificate: certificateOutput.nullable(),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const body = buildBody(args);
+        const base = `${domainPath(organization(args.organization), args.server, args.site, args.domain)}/certificates`;
+        const response = await client.post(base, { body, signal });
+        const initial = response.data?.data ? flattenSingle(response.data) : undefined;
+        const action = `create the ${args.type} certificate`;
+        if (!initial || !args.wait) {
+            return {
+                structured: { status: 'queued', check_with: initial ? CHECK_WITH : 'forge_list_certificates', certificate: initial ? formatCertificate(initial) : null },
+                summary: `Forge accepted the request to ${action}. Follow it with ${initial ? `${CHECK_WITH} (certificate ${initial.id})` : 'forge_list_certificates'}.`,
+            };
+        }
+        const result = await waitFor({
+            initial,
+            poll: () => readCertificate(client, `${base}/${encodeURIComponent(initial.id)}`, signal),
+            phase: certificatePhase,
+            describe: (certificate) => `Certificate ${certificate.id}: request ${certificate.request_status}, ${certificate.status}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const done = outcome(result, {
+            action,
+            checkWith: CHECK_WITH,
+            timeoutSeconds: args.timeout_seconds,
+            detail: result.status === 'failed' && args.type === 'letsencrypt'
+                ? "Let's Encrypt usually fails when the domain DNS does not point to the server: check it with forge_get_domain, and the error with forge_list_server_events."
+                : undefined,
+        });
+        return { structured: { ...done.structured, certificate: formatCertificate(result.value ?? initial) }, summary: done.summary };
+    },
+});
+/** Maps the flat tool arguments to the nested request body of the chosen certificate type. */
+function buildBody(args) {
+    const pickDefined = (entries) => Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined));
+    switch (args.type) {
+        case 'letsencrypt':
+            return {
+                type: 'letsencrypt',
+                letsencrypt: pickDefined({ verification_method: args.verification_method, key_type: args.key_type, preferred_chain: args.preferred_chain }),
+            };
+        case 'existing':
+            if (!args.certificate || !args.private_key) {
+                throw new ToolInputError('An "existing" certificate needs both `certificate` and `private_key`.');
+            }
+            return pickDefined({ type: 'existing', enable: args.enable, existing: { certificate: args.certificate, key: args.private_key } });
+        case 'csr':
+            if (!args.csr_domain)
+                throw new ToolInputError('A "csr" certificate needs `csr_domain`.');
+            return {
+                type: 'csr',
+                csr: pickDefined({
+                    domain: args.csr_domain,
+                    sans: args.csr_sans,
+                    country: args.csr_country,
+                    state: args.csr_state,
+                    city: args.csr_city,
+                    organization: args.csr_organization,
+                    department: args.csr_department,
+                }),
+            };
+        case 'clone':
+            if (args.clone_certificate_id === undefined)
+                throw new ToolInputError('A "clone" certificate needs `clone_certificate_id`.');
+            return pickDefined({ type: 'clone', enable: args.enable, clone: { certificate_id: args.clone_certificate_id } });
+    }
+}

package/dist/tools/certificates/delete-certificate.js

@@ -0,0 +1,42 @@
+import { defineTool } from '../define-tool.js';
+import { operationOutput, orGone, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { domainPath, domainScopeInput } from '../domains/shared.js';
+import { CERTIFICATE_NOT_FOUND_HINT, certificateInput, readCertificate } from './shared.js';
+const CHECK_WITH = 'forge_list_certificates';
+export const deleteCertificate = defineTool({
+    name: 'forge_delete_certificate',
+    title: 'Delete certificate',
+    description: 'Delete a certificate from a domain. If it is the active one, the domain is no longer served over HTTPS.',
+    toolset: 'sites',
+    operations: [
+        'organizations.servers.sites.domains.certificates.destroy',
+        'organizations.servers.sites.domains.certificates.show',
+    ],
+    permissions: ['site:manage-ssl', 'site:meta'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: CERTIFICATE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...domainScopeInput,
+        certificate: certificateInput,
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = `${domainPath(organization(args.organization), args.server, args.site, args.domain)}/certificates/${encodeURIComponent(String(args.certificate))}`;
+        await client.delete(path, { signal });
+        const action = `delete certificate ${args.certificate}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(() => readCertificate(client, path, signal)),
+            phase: (certificate) => (certificate === null ? 'completed' : 'pending'),
+            describe: (certificate) => `Certificate is ${certificate?.status ?? 'deleting'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/certificates/get-certificate.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { ForgeApiError } from '../../forge/errors.js';
+import { defineTool } from '../define-tool.js';
+import { DOMAIN_NOT_FOUND_HINT, domainPath, domainScopeInput } from '../domains/shared.js';
+import { certificateInput, certificateOutput, formatCertificate, readCertificate } from './shared.js';
+export const getCertificate = defineTool({
+    name: 'forge_get_certificate',
+    title: 'Get certificate',
+    description: 'Get a certificate of a domain, or the active one (the certificate currently served) when `certificate` is omitted.',
+    toolset: 'sites',
+    operations: [
+        'organizations.servers.sites.domains.certificates.show',
+        'organizations.servers.sites.domains.certificates.active',
+    ],
+    permissions: ['site:meta'],
+    readOnly: true,
+    notFoundHint: DOMAIN_NOT_FOUND_HINT,
+    inputSchema: {
+        ...domainScopeInput,
+        certificate: certificateInput.optional().describe('Certificate ID; omit to get the active certificate.'),
+    },
+    outputSchema: {
+        certificate: certificateOutput.nullable().describe('The certificate, or null when the domain has no active certificate.'),
+    },
+    async handler(args, { client, organization, signal }) {
+        const base = `${domainPath(organization(args.organization), args.server, args.site, args.domain)}/certificates`;
+        if (args.certificate !== undefined) {
+            const certificate = formatCertificate(await readCertificate(client, `${base}/${encodeURIComponent(String(args.certificate))}`, signal));
+            return { structured: { certificate }, summary: `Certificate ${certificate.id} (${certificate.type}) is ${certificate.status}.` };
+        }
+        try {
+            const certificate = formatCertificate(await readCertificate(client, `${base}/active`, signal));
+            return { structured: { certificate }, summary: `The active certificate is ${certificate.id} (${certificate.type}), ${certificate.status}.` };
+        }
+        catch (error) {
+            if (error instanceof ForgeApiError && error.status === 404) {
+                return {
+                    structured: { certificate: null },
+                    summary: 'The domain has no active certificate (or the domain does not exist). Secure it with forge_create_certificate.',
+                };
+            }
+            throw error;
+        }
+    },
+});

package/dist/tools/certificates/list-certificates.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput, sitePath } from '../shared/site-scope.js';
+import { domainInput } from '../domains/shared.js';
+import { certificateOutput, formatCertificate } from './shared.js';
+export const listCertificates = defineTool({
+    name: 'forge_list_certificates',
+    title: 'List certificates',
+    description: 'List the SSL certificates of a site across all its domains, or of one domain with `domain`. Shows type, status and which certificate is active.',
+    toolset: 'sites',
+    operations: ['organizations.servers.sites.certificates.index', 'organizations.servers.sites.domains.certificates.index'],
+    permissions: ['site:meta'],
+    readOnly: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        domain: domainInput.optional().describe('Only list the certificates of this domain.'),
+    },
+    outputSchema: {
+        certificates: z.array(certificateOutput),
+    },
+    async handler(args, { client, organization, signal }) {
+        const base = sitePath(organization(args.organization), args.server, args.site);
+        const path = args.domain === undefined ? `${base}/certificates` : `${base}/domains/${encodeURIComponent(String(args.domain))}/certificates`;
+        const response = await client.get(path, { signal });
+        const certificates = flattenCollection(response.data).items.map(formatCertificate);
+        const active = certificates.filter((certificate) => certificate.active).length;
+        return {
+            structured: { certificates },
+            summary: certificates.length === 0
+                ? 'No certificates found: secure the domain with forge_create_certificate.'
+                : `Found ${certificates.length} certificate(s), ${active} active.`,
+        };
+    },
+});

package/dist/tools/certificates/run-certificate-action.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { domainPath, domainScopeInput } from '../domains/shared.js';
+import { CERTIFICATE_NOT_FOUND_HINT, certificateInput, certificatePhase, readCertificate } from './shared.js';
+const CHECK_WITH = 'forge_get_certificate';
+export const runCertificateAction = defineTool({
+    name: 'forge_run_certificate_action',
+    title: 'Activate or deactivate a certificate',
+    description: 'Activate ("enable") a certificate so the domain serves it, or deactivate it ("disable").',
+    toolset: 'sites',
+    operations: [
+        'organizations.servers.sites.domains.certificates.actions.store',
+        'organizations.servers.sites.domains.certificates.show',
+    ],
+    permissions: ['site:meta'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    async: true,
+    notFoundHint: CERTIFICATE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...domainScopeInput,
+        certificate: certificateInput,
+        action: z.enum(['enable', 'disable']),
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = `${domainPath(organization(args.organization), args.server, args.site, args.domain)}/certificates/${encodeURIComponent(String(args.certificate))}`;
+        await client.post(`${path}/actions`, { body: { action: args.action }, signal });
+        const action = `${args.action} certificate ${args.certificate}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const wanted = args.action === 'enable';
+        const result = await waitFor({
+            poll: () => readCertificate(client, path, signal),
+            phase: (certificate) => (certificate.active === wanted ? certificatePhase(certificate) : 'pending'),
+            describe: (certificate) => `Certificate ${certificate.id} is ${certificate.status}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/certificates/shared.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { phaseOf } from '../shared/async.js';
+import { idInput, pick } from '../shared/schemas.js';
+export const certificateInput = idInput('Certificate ID. Use forge_list_certificates to find it.');
+export const CERTIFICATE_NOT_FOUND_HINT = 'Check the domain ID with forge_list_domains and the certificate ID with forge_list_certificates.';
+const CERTIFICATE_FIELDS = [
+    'id',
+    'type',
+    'status',
+    'request_status',
+    'active',
+    'verification_method',
+    'key_type',
+    'preferred_chain',
+    'created_at',
+    'updated_at',
+];
+export const certificateOutput = z.looseObject({
+    id: z.string().describe('Certificate ID.'),
+    type: z.string().nullable().describe('letsencrypt, csr or existing.'),
+    status: z.string().nullable().describe('installing, installed, failed, renewing, ...'),
+    request_status: z.string().nullable().describe('verifying, creating or created.'),
+    active: z.boolean().nullable().describe('Whether the certificate is the one served for the domain.'),
+    verification_method: z.string().nullable(),
+    key_type: z.string().nullable(),
+    preferred_chain: z.string().nullable(),
+    created_at: z.string().nullable(),
+    updated_at: z.string().nullable(),
+});
+export function formatCertificate(flat) {
+    return pick(flat, CERTIFICATE_FIELDS);
+}
+export async function readCertificate(client, path, signal) {
+    const response = await client.get(path, { signal });
+    return flattenSingle(response.data);
+}
+const FAILED = ['failed', 'failed-unknown', 'failed-runner'];
+const TRANSITIONAL = ['installing', 'removing', 'restarting', 'stopping', 'starting', 'syncing', 'updating', 'disabling', 'enabling', 'restoring', 'deleting', 'renewing'];
+/** A certificate is settled once requested (`request_status: created`) and no longer transitional. */
+export function certificatePhase(certificate) {
+    if (FAILED.includes(String(certificate.status)))
+        return 'failed';
+    if (certificate.request_status !== 'created')
+        return 'pending';
+    return phaseOf(certificate.status, { pending: TRANSITIONAL, failed: FAILED });
+}

package/dist/tools/domains/add-domain.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, waitFor, waitInput } from '../shared/async.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput, sitePath } from '../shared/site-scope.js';
+import { WWW_REDIRECT_TYPES, domainOutput, domainPhase, formatDomain, readDomain } from './shared.js';
+const CHECK_WITH = 'forge_get_domain';
+export const addDomain = defineTool({
+    name: 'forge_add_domain',
+    title: 'Add domain',
+    description: 'Add a domain (alias) to a site. Waits until Forge enables it unless `wait` is false; if it stays pending, the DNS records are probably missing: check them with forge_get_domain. Secure it afterwards with forge_create_certificate.',
+    toolset: 'sites',
+    operations: ['organizations.servers.sites.domains.store', 'organizations.servers.sites.domains.show'],
+    permissions: ['site:meta'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    async: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        name: z.string().min(1).describe('Domain name, e.g. "www.example.com".'),
+        www_redirect_type: z.enum(WWW_REDIRECT_TYPES).default('none').describe('Redirect www to non-www ("from-www"), the opposite ("to-www") or neither.'),
+        allow_wildcard_subdomains: z.boolean().default(false),
+        ...waitInput(120),
+    },
+    outputSchema: {
+        ...operationOutput,
+        domain: domainOutput.nullable(),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const base = `${sitePath(organization(args.organization), args.server, args.site)}/domains`;
+        const response = await client.post(base, {
+            body: { name: args.name, www_redirect_type: args.www_redirect_type, allow_wildcard_subdomains: args.allow_wildcard_subdomains },
+            signal,
+        });
+        const initial = response.data?.data ? flattenSingle(response.data) : undefined;
+        const action = `add the domain ${args.name}`;
+        if (!initial || !args.wait) {
+            return {
+                structured: { status: 'queued', check_with: initial ? CHECK_WITH : 'forge_list_domains', domain: initial ? formatDomain(initial) : null },
+                summary: `Forge accepted the request to ${action}. Follow it with ${initial ? `${CHECK_WITH} (domain ${initial.id})` : 'forge_list_domains'}.`,
+            };
+        }
+        const result = await waitFor({
+            initial,
+            poll: () => readDomain(client, `${base}/${encodeURIComponent(initial.id)}`, signal),
+            phase: (domain) => domainPhase(domain.status),
+            describe: (domain) => `Domain ${domain.name} is ${domain.status}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const done = outcome(result, {
+            action,
+            checkWith: CHECK_WITH,
+            timeoutSeconds: args.timeout_seconds,
+            detail: result.status === 'in_progress' ? 'Check the DNS records with forge_get_domain.' : undefined,
+        });
+        return { structured: { ...done.structured, domain: formatDomain(result.value ?? initial) }, summary: done.summary };
+    },
+});

package/dist/tools/domains/delete-domain.js

@@ -0,0 +1,37 @@
+import { defineTool } from '../define-tool.js';
+import { operationOutput, orGone, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { DOMAIN_NOT_FOUND_HINT, domainPath, domainScopeInput, readDomain } from './shared.js';
+const CHECK_WITH = 'forge_list_domains';
+export const deleteDomain = defineTool({
+    name: 'forge_delete_domain',
+    title: 'Delete domain',
+    description: 'Remove a domain (alias) from a site, together with its certificates. The site stops answering on that domain.',
+    toolset: 'sites',
+    operations: ['organizations.servers.sites.domains.destroy', 'organizations.servers.sites.domains.show'],
+    permissions: ['site:meta'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: DOMAIN_NOT_FOUND_HINT,
+    inputSchema: {
+        ...domainScopeInput,
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = domainPath(organization(args.organization), args.server, args.site, args.domain);
+        await client.delete(path, { signal });
+        const action = `delete domain ${args.domain}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(() => readDomain(client, path, signal)),
+            phase: (domain) => (domain === null ? 'completed' : 'pending'),
+            describe: (domain) => `Domain is ${domain?.status ?? 'removing'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/domains/get-domain.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { pick } from '../shared/schemas.js';
+import { DOMAIN_NOT_FOUND_HINT, domainOutput, domainPath, domainScopeInput, formatDomain, readDomain } from './shared.js';
+const dnsRecord = z.looseObject({
+    type: z.string().nullable().describe('A, CNAME or TXT.'),
+    name: z.string().nullable(),
+    value: z.string().nullable(),
+    ttl: z.number().int().nullable(),
+});
+export const getDomain = defineTool({
+    name: 'forge_get_domain',
+    title: 'Get domain',
+    description: 'Get a domain of a site with the DNS records that must exist at the DNS provider for it to work (and for Let\'s Encrypt to issue certificates). Use it when a domain stays "pending" or "connecting".',
+    toolset: 'sites',
+    operations: ['organizations.servers.sites.domains.show', 'organizations.servers.sites.domains.configurations'],
+    permissions: ['site:meta'],
+    readOnly: true,
+    notFoundHint: DOMAIN_NOT_FOUND_HINT,
+    inputSchema: {
+        ...domainScopeInput,
+        include_dns: z.boolean().default(true).describe('Also return the DNS records to configure.'),
+    },
+    outputSchema: {
+        domain: domainOutput,
+        dns_records: z.array(dnsRecord).nullable().describe('DNS records to configure, or null when not requested.'),
+    },
+    async handler(args, { client, organization, signal }) {
+        const path = domainPath(organization(args.organization), args.server, args.site, args.domain);
+        const [domain, dns] = await Promise.all([
+            readDomain(client, path, signal),
+            args.include_dns ? client.get(`${path}/configurations`, { signal }) : Promise.resolve(undefined),
+        ]);
+        const records = dns
+            ? flattenCollection(dns.data).items.map((record) => pick(record, ['type', 'name', 'value', 'ttl']))
+            : null;
+        const formatted = formatDomain(domain);
+        return {
+            structured: { domain: formatted, dns_records: records },
+            summary: `Domain ${formatted.name} is ${formatted.status}.${records && records.length > 0 ? ` It needs ${records.length} DNS record(s) at the DNS provider.` : ''}`,
+        };
+    },
+});

package/dist/tools/domains/list-domains.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { paginationInput, paginationOutput, paginationSummary } from '../shared/schemas.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput, sitePath } from '../shared/site-scope.js';
+import { domainOutput, formatDomain } from './shared.js';
+const STATUSES = ['pending', 'connecting', 'enabled', 'removing', 'securing', 'updating', 'disabling', 'disabled', 'enabling'];
+export const listDomains = defineTool({
+    name: 'forge_list_domains',
+    title: 'List domains',
+    description: 'List the domains of a site (the primary domain and its aliases) with their status and www redirection. Use forge_get_domain for the DNS records to configure.',
+    toolset: 'sites',
+    operations: ['organizations.servers.sites.domains.index'],
+    permissions: ['site:meta'],
+    readOnly: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        status: z.enum(STATUSES).optional().describe('Filter by status.'),
+        type: z.enum(['primary', 'alias']).optional().describe('Filter by type.'),
+        sort: z.array(z.enum(['name', '-name', 'created_at', '-created_at'])).min(1).optional(),
+        ...paginationInput,
+    },
+    outputSchema: {
+        domains: z.array(domainOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const response = await client.get(`${sitePath(organization(args.organization), args.server, args.site)}/domains`, {
+            query: {
+                filter: { status: args.status, type: args.type },
+                sort: args.sort,
+                page: { size: args.page_size, cursor: args.cursor },
+            },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const domains = page.items.map(formatDomain);
+        return {
+            structured: { domains, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: domains.length === 0
+                ? 'No domains found for the site.'
+                : `Found ${domains.length} domain(s): ${domains.map((d) => `${d.name} (${d.status})`).join(', ')}.${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

package/dist/tools/domains/run-domain-action.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { DOMAIN_NOT_FOUND_HINT, domainPath, domainScopeInput, readDomain } from './shared.js';
+const CHECK_WITH = 'forge_get_domain';
+/** What the domain looks like once each action is done. */
+const DONE = {
+    enable: (domain) => domain.status === 'enabled',
+    disable: (domain) => domain.status === 'disabled',
+    'mark-as-primary': (domain) => domain.type === 'primary',
+};
+export const runDomainAction = defineTool({
+    name: 'forge_run_domain_action',
+    title: 'Enable, disable or make a domain primary',
+    description: 'Run an action on a domain: "enable" or "disable" it, or "mark-as-primary" to make it the main domain of the site (the previous primary becomes an alias).',
+    toolset: 'sites',
+    operations: ['organizations.servers.sites.domains.actions.store', 'organizations.servers.sites.domains.show'],
+    permissions: ['site:meta'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    async: true,
+    notFoundHint: DOMAIN_NOT_FOUND_HINT,
+    inputSchema: {
+        ...domainScopeInput,
+        action: z.enum(['enable', 'disable', 'mark-as-primary']),
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = domainPath(organization(args.organization), args.server, args.site, args.domain);
+        await client.post(`${path}/actions`, { body: { action: args.action }, signal });
+        const action = `${args.action.replace(/-/g, ' ')} domain ${args.domain}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => readDomain(client, path, signal),
+            phase: (domain) => (DONE[args.action](domain) ? 'completed' : 'pending'),
+            describe: (domain) => `Domain ${domain.name} is ${domain.status}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/domains/shared.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { phaseOf } from '../shared/async.js';
+import { idInput, pick } from '../shared/schemas.js';
+import { siteScopeInput, sitePath } from '../shared/site-scope.js';
+export const domainInput = idInput('Domain ID. Use forge_list_domains to find it.');
+/** Arguments identifying a domain of a site. */
+export const domainScopeInput = {
+    ...siteScopeInput,
+    domain: domainInput,
+};
+export function domainPath(org, server, site, domain) {
+    return `${sitePath(org, server, site)}/domains/${encodeURIComponent(String(domain))}`;
+}
+export const DOMAIN_NOT_FOUND_HINT = 'Check the domain ID with forge_list_domains.';
+export const WWW_REDIRECT_TYPES = ['from-www', 'to-www', 'none'];
+const DOMAIN_FIELDS = ['id', 'name', 'type', 'status', 'www_redirect_type', 'allow_wildcard_subdomains', 'created_at'];
+export const domainOutput = z.looseObject({
+    id: z.string().describe('Domain ID, used as the `domain` argument.'),
+    name: z.string().nullable(),
+    type: z.string().nullable().describe('primary or alias.'),
+    status: z.string().nullable().describe('pending, connecting, enabled, securing, disabled, ...'),
+    www_redirect_type: z.string().nullable(),
+    allow_wildcard_subdomains: z.boolean().nullable(),
+    created_at: z.string().nullable(),
+});
+export function formatDomain(flat) {
+    return pick(flat, DOMAIN_FIELDS);
+}
+export async function readDomain(client, path, signal) {
+    const response = await client.get(path, { signal });
+    return flattenSingle(response.data);
+}
+/** Domains have no failed status: anything not transitional is settled. */
+export function domainPhase(status) {
+    return phaseOf(status, { pending: ['pending', 'connecting', 'removing', 'securing', 'updating', 'disabling', 'enabling'] });
+}