@francescomalatesta/laravel-forge-mcp 0.2.0 → 0.4.0

package/README.md

@@ -81,6 +81,20 @@ npm run build
 | `forge_get_site` | core | Every detail of a site, including its server |
 | `forge_list_server_events` | core | Operations Forge ran on a server or across the organization |
 | `forge_get_server_event` | core | An event with the output of its script |
+| `forge_create_site` | sites | Create a site (optionally with repository and database) and wait until it is installed |
+| `forge_create_balanced_site` | sites | Create a site on a load balancer |
+| `forge_update_site` | sites | Change PHP version, type, directories, branch, push to deploy, release retention |
+| `forge_update_site_repository` | sites | Switch source control provider, repository or branch |
+| `forge_delete_site` | sites | Delete a site |
+| `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_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_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 |
@@ -98,7 +112,11 @@ npm run build
 | `forge_get_deploy_hook` 🔑 | deployments | The deployment trigger URL |
 | `forge_regenerate_deploy_hook` 🔑 | deployments | Generate a new deployment trigger URL |
 
-🔑 Returns secrets: registered only when `FORGE_ALLOW_SECRETS=true`. Secret fields returned by other tools (e.g. a site's `deployment_url`) are hidden unless secrets are allowed.
+🔑 Reads or replaces secrets: registered only when `FORGE_ALLOW_SECRETS=true`. Secret fields returned by other tools (e.g. a site's `deployment_url`) are hidden unless secrets are allowed.
+
+### Background operations
+
+Forge runs most changes in the background. Tools that start one say so in their description and return a `status`: `completed` or `failed` when they waited for the result, `in_progress` if it was still running at the timeout, `queued` when they returned right away. `check_with` names the tool that shows the current state. By default these tools wait for the outcome (sending progress notifications); pass `wait: false` to return immediately, or tune `timeout_seconds`.
 
 ## Development
 

package/dist/server.js

@@ -66,9 +66,11 @@ function registerTool(server, tool, config, client, sleep) {
         }
     });
 }
+export const ASYNC_NOTE = 'Forge runs this operation in the background: the result `status` says whether it completed, failed, is still in progress or was only queued, and `check_with` names the tool that shows its current state.';
 function describe(tool) {
+    const async = tool.async ? `\n\n${ASYNC_NOTE}` : '';
     const permissions = tool.permissions.length > 0 ? `\n\nRequired Forge permission: ${tool.permissions.join(', ')}.` : '';
-    return `${tool.description}${permissions}`;
+    return `${tool.description}${async}${permissions}`;
 }
 function abortableSleep(ms, signal) {
     return new Promise((resolve, reject) => {

package/dist/tools/deployments/create-deploy-key.js

@@ -1,5 +1,6 @@
 import { flattenSingle } from '../../forge/jsonapi.js';
 import { defineTool } from '../define-tool.js';
+import { operationOutput } from '../shared/async.js';
 import { deployKeyOutput } from './get-deploy-key.js';
 import { SITE_NOT_FOUND_HINT, siteScopeInput, sitePath } from './shared.js';
 export const createDeployKey = defineTool({
@@ -12,14 +13,16 @@ export const createDeployKey = defineTool({
     readOnly: false,
     destructive: false,
     idempotent: true,
+    // Asynchronous in Forge, but the response already carries the key: no wait needed.
+    async: true,
     notFoundHint: SITE_NOT_FOUND_HINT,
     inputSchema: siteScopeInput,
-    outputSchema: deployKeyOutput,
+    outputSchema: { ...operationOutput, ...deployKeyOutput },
     async handler(args, { client, organization, signal }) {
         const response = await client.post(`${sitePath(organization(args.organization), args.server, args.site)}/deploy-key`, { signal });
         const key = response.data ? (flattenSingle(response.data).key ?? null) : null;
         return {
-            structured: { key },
+            structured: { status: key ? 'completed' : 'queued', check_with: 'forge_get_deploy_key', key },
             summary: key
                 ? 'Deploy key ready: add this public key as a deploy key in the repository settings of the Git provider.'
                 : 'Forge accepted the request; read the key with forge_get_deploy_key.',

package/dist/tools/deployments/create-deployment-webhook.js

@@ -1,28 +1,52 @@
 import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
 import { defineTool } from '../define-tool.js';
-import { queued, queuedOutput } from '../shared/async.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
 import { SITE_NOT_FOUND_HINT, siteScopeInput, sitePath } from './shared.js';
+const CHECK_WITH = 'forge_list_deployment_webhooks';
 export const createDeploymentWebhook = defineTool({
     name: 'forge_create_deployment_webhook',
     title: 'Create deployment webhook',
     description: 'Add a URL that Forge notifies (HTTP POST) after every deployment of the site.',
     toolset: 'deployments',
-    operations: ['organizations.servers.sites.webhooks.store'],
-    permissions: ['site:manage-notifications'],
+    operations: ['organizations.servers.sites.webhooks.store', 'organizations.servers.sites.webhooks.index'],
+    permissions: ['site:manage-notifications', 'server:view'],
     readOnly: false,
     destructive: false,
     idempotent: false,
+    async: true,
     notFoundHint: SITE_NOT_FOUND_HINT,
     inputSchema: {
         ...siteScopeInput,
         url: z.string().url().describe('URL to notify after each deployment.'),
+        ...waitInput(60),
     },
-    outputSchema: queuedOutput,
-    async handler(args, { client, organization, signal }) {
-        await client.post(`${sitePath(organization(args.organization), args.server, args.site)}/webhooks`, {
-            body: { url: args.url },
-            signal,
+    outputSchema: {
+        ...operationOutput,
+        webhook_id: z.string().nullable().describe('ID of the new webhook once it exists.'),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const base = `${sitePath(organization(args.organization), args.server, args.site)}/webhooks`;
+        await client.post(base, { body: { url: args.url }, signal });
+        if (!args.wait) {
+            const accepted = queued('add the deployment webhook', CHECK_WITH);
+            return { ...accepted, structured: { ...accepted.structured, webhook_id: null } };
+        }
+        // Forge returns no body: the webhook is ready once it shows up in the list.
+        const result = await waitFor({
+            poll: async () => {
+                const response = await client.get(base, {
+                    query: { sort: ['-created_at'], page: { size: 100 } },
+                    signal,
+                });
+                return flattenCollection(response.data).items.find((item) => item.url === args.url) ?? null;
+            },
+            phase: (webhook) => (webhook ? 'completed' : 'pending'),
+            describe: () => 'Waiting for the webhook to be created',
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
         });
-        return queued('add the deployment webhook', 'forge_list_deployment_webhooks');
+        const done = outcome(result, { action: 'add the deployment webhook', checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+        return { ...done, structured: { ...done.structured, webhook_id: result.value ? String(result.value.id) : null } };
     },
 });

package/dist/tools/deployments/delete-deployment-webhook.js

@@ -1,26 +1,38 @@
 import { defineTool } from '../define-tool.js';
-import { queued, queuedOutput } from '../shared/async.js';
+import { operationOutput, orGone, outcome, queued, waitFor, waitInput } from '../shared/async.js';
 import { idInput } from '../shared/schemas.js';
 import { siteScopeInput, sitePath } from './shared.js';
+const CHECK_WITH = 'forge_list_deployment_webhooks';
 export const deleteDeploymentWebhook = defineTool({
     name: 'forge_delete_deployment_webhook',
     title: 'Delete deployment webhook',
     description: 'Remove a deployment webhook from a site: its URL will no longer be notified after deployments.',
     toolset: 'deployments',
-    operations: ['organizations.servers.sites.webhooks.destroy'],
-    permissions: ['site:manage-notifications'],
+    operations: ['organizations.servers.sites.webhooks.destroy', 'organizations.servers.sites.webhooks.show'],
+    permissions: ['site:manage-notifications', 'server:view'],
     readOnly: false,
     destructive: true,
     idempotent: true,
+    async: true,
     notFoundHint: 'Check the webhook ID with forge_list_deployment_webhooks.',
     inputSchema: {
         ...siteScopeInput,
         webhook: idInput('Webhook ID. Use forge_list_deployment_webhooks to find it.'),
+        ...waitInput(60),
     },
-    outputSchema: queuedOutput,
-    async handler(args, { client, organization, signal }) {
-        const base = sitePath(organization(args.organization), args.server, args.site);
-        await client.delete(`${base}/webhooks/${encodeURIComponent(String(args.webhook))}`, { signal });
-        return queued('delete the deployment webhook', 'forge_list_deployment_webhooks');
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = `${sitePath(organization(args.organization), args.server, args.site)}/webhooks/${encodeURIComponent(String(args.webhook))}`;
+        await client.delete(path, { signal });
+        if (!args.wait)
+            return queued('delete the deployment webhook', CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(() => client.get(path, { signal })),
+            phase: (webhook) => (webhook === null ? 'completed' : 'pending'),
+            describe: () => 'Waiting for the webhook to be removed',
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action: 'delete the deployment webhook', checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
     },
 });

package/dist/tools/deployments/deploy-site.js

@@ -1,8 +1,8 @@
 import { z } from 'zod';
 import { flattenSingle } from '../../forge/jsonapi.js';
 import { defineTool } from '../define-tool.js';
-import { FINAL_STATUSES, deploymentOutput, fetchLog, formatDeployment, logLinesInput, logOutput, SITE_NOT_FOUND_HINT, siteScopeInput, sitePath, } from './shared.js';
-export const POLL_INTERVAL_MS = 5_000;
+import { operationOutput, waitFor, waitInput } from '../shared/async.js';
+import { deploymentOutput, deploymentPhase, fetchLog, formatDeployment, logLinesInput, logOutput, SITE_NOT_FOUND_HINT, siteScopeInput, sitePath, } from './shared.js';
 export const deploySite = defineTool({
     name: 'forge_deploy_site',
     title: 'Deploy site',
@@ -17,20 +17,15 @@ export const deploySite = defineTool({
     readOnly: false,
     destructive: false,
     idempotent: false,
+    async: true,
     notFoundHint: SITE_NOT_FOUND_HINT,
     inputSchema: {
         ...siteScopeInput,
-        wait: z.boolean().default(true).describe('Wait for the deployment to finish before returning.'),
-        timeout_seconds: z
-            .number()
-            .int()
-            .min(10)
-            .max(900)
-            .default(180)
-            .describe('Maximum time to wait when `wait` is true.'),
+        ...waitInput(180),
         log_lines: logLinesInput(50),
     },
     outputSchema: {
+        ...operationOutput,
         deployment: deploymentOutput.nullable(),
         finished: z.boolean().describe('Whether the deployment reached a final status (finished, failed, cancelled).'),
         succeeded: z.boolean(),
@@ -43,37 +38,47 @@ export const deploySite = defineTool({
         if (!created.data?.data) {
             // Accepted without a deployment in the body: nothing to follow by ID.
             return {
-                structured: { deployment: null, finished: false, succeeded: false, ...noLog },
+                structured: { status: 'queued', check_with: 'forge_list_deployments', deployment: null, finished: false, succeeded: false, ...noLog },
                 summary: 'Forge accepted the deployment request. Follow it with forge_list_deployments.',
             };
         }
-        let deployment = formatDeployment(flattenSingle(created.data));
+        const queuedDeployment = formatDeployment(flattenSingle(created.data));
         if (!args.wait) {
             return {
-                structured: { deployment, finished: false, succeeded: false, ...noLog },
-                summary: `Deployment ${deployment.id} was queued. Follow it with forge_get_deployment (deployment ${deployment.id}).`,
+                structured: { status: 'queued', check_with: 'forge_get_deployment', deployment: queuedDeployment, finished: false, succeeded: false, ...noLog },
+                summary: `Deployment ${queuedDeployment.id} was queued. Follow it with forge_get_deployment (deployment ${queuedDeployment.id}).`,
             };
         }
-        const maxPolls = Math.ceil((args.timeout_seconds * 1000) / POLL_INTERVAL_MS);
-        for (let poll = 1; poll <= maxPolls && !FINAL_STATUSES.has(deployment.status ?? ''); poll++) {
-            await progress(poll, maxPolls, `Deployment ${deployment.id} is ${deployment.status ?? 'pending'}`);
-            await sleep(POLL_INTERVAL_MS);
-            const response = await client.get(`${base}/deployments/${encodeURIComponent(deployment.id)}`, { signal });
-            deployment = formatDeployment(flattenSingle(response.data));
-        }
-        const finished = FINAL_STATUSES.has(deployment.status ?? '');
-        const succeeded = deployment.status === 'finished';
+        const result = await waitFor({
+            initial: queuedDeployment,
+            poll: async () => {
+                const response = await client.get(`${base}/deployments/${encodeURIComponent(queuedDeployment.id)}`, { signal });
+                return formatDeployment(flattenSingle(response.data));
+            },
+            phase: (deployment) => deploymentPhase(deployment.status),
+            describe: (deployment) => `Deployment ${deployment.id} is ${deployment.status ?? 'pending'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const deployment = result.value ?? queuedDeployment;
+        const finished = result.status === 'completed' || result.status === 'failed';
         const log = finished ? await fetchLog(client, base, deployment.id, args.log_lines, signal) : noLog;
-        let summary;
-        if (!finished) {
-            summary = `Deployment ${deployment.id} is still ${deployment.status} after ${args.timeout_seconds}s. Check it again with forge_get_deployment.`;
-        }
-        else if (succeeded) {
-            summary = `Deployment ${deployment.id} finished successfully.`;
-        }
-        else {
-            summary = `Deployment ${deployment.id} ended with status "${deployment.status}". The end of the log is included; see forge_get_deployment for more lines.`;
-        }
-        return { structured: { deployment, finished, succeeded, ...log }, summary };
+        const summaries = {
+            completed: `Deployment ${deployment.id} finished successfully.`,
+            failed: `Deployment ${deployment.id} ended with status "${deployment.status}". The end of the log is included; see forge_get_deployment for more lines.`,
+            in_progress: `Deployment ${deployment.id} is still ${deployment.status} after ${args.timeout_seconds}s. Check it again with forge_get_deployment.`,
+            queued: `Deployment ${deployment.id} was queued, but the tool ${result.unfollowed}. Follow it with forge_get_deployment.`,
+        };
+        return {
+            structured: {
+                status: result.status,
+                check_with: 'forge_get_deployment',
+                deployment,
+                finished,
+                succeeded: result.status === 'completed',
+                ...log,
+            },
+            summary: summaries[result.status],
+        };
     },
 });

package/dist/tools/deployments/reset-deployment-state.js

@@ -1,21 +1,44 @@
+import { flattenSingle } from '../../forge/jsonapi.js';
 import { defineTool } from '../define-tool.js';
-import { queued, queuedOutput } from '../shared/async.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
 import { SITE_NOT_FOUND_HINT, siteScopeInput, sitePath } from './shared.js';
+const CHECK_WITH = 'forge_get_deployment_status';
 export const resetDeploymentState = defineTool({
     name: 'forge_reset_deployment_state',
     title: 'Reset deployment state',
     description: 'Clear the "deploying" state of a site when a deployment is stuck (e.g. the server was rebooted mid-deploy) so new deployments can run. It does not stop a running process or roll back code.',
     toolset: 'deployments',
-    operations: ['organizations.servers.sites.deployments.status.destroy'],
-    permissions: ['site:manage-deploys'],
+    operations: [
+        'organizations.servers.sites.deployments.status.destroy',
+        'organizations.servers.sites.deployments.status.show',
+    ],
+    permissions: ['site:manage-deploys', 'server:view'],
     readOnly: false,
     destructive: false,
     idempotent: true,
+    async: true,
     notFoundHint: SITE_NOT_FOUND_HINT,
-    inputSchema: siteScopeInput,
-    outputSchema: queuedOutput,
-    async handler(args, { client, organization, signal }) {
-        await client.delete(`${sitePath(organization(args.organization), args.server, args.site)}/deployments/status`, { signal });
-        return queued('reset the deployment state', 'forge_get_deployment_status');
+    inputSchema: {
+        ...siteScopeInput,
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const base = `${sitePath(organization(args.organization), args.server, args.site)}/deployments/status`;
+        await client.delete(base, { signal });
+        if (!args.wait)
+            return queued('reset the deployment state', CHECK_WITH);
+        const result = await waitFor({
+            poll: async () => {
+                const response = await client.get(base, { signal });
+                return flattenSingle(response.data).status ?? null;
+            },
+            // The reset is done when the site no longer reports a deployment in progress.
+            phase: (status) => (status === null ? 'completed' : 'pending'),
+            describe: (status) => `Deployment state is still ${status}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action: 'reset the deployment state', checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
     },
 });

package/dist/tools/deployments/set-push-to-deploy.js

@@ -1,7 +1,10 @@
 import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { apiPath } from '../../forge/path.js';
 import { defineTool } from '../define-tool.js';
-import { queued, queuedOutput } from '../shared/async.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
 import { SITE_NOT_FOUND_HINT, siteScopeInput, sitePath } from './shared.js';
+const CHECK_WITH = 'forge_get_site';
 export const setPushToDeploy = defineTool({
     name: 'forge_set_push_to_deploy',
     title: 'Enable or disable push to deploy',
@@ -10,25 +13,42 @@ export const setPushToDeploy = defineTool({
     operations: [
         'organizations.servers.sites.deployments.push-to-deploy.store',
         'organizations.servers.sites.deployments.push-to-deploy.destroy',
+        'organizations.sites.show',
     ],
-    permissions: ['site:manage-deploys'],
+    permissions: ['site:manage-deploys', 'server:view'],
     readOnly: false,
     destructive: false,
     idempotent: true,
+    async: true,
     notFoundHint: SITE_NOT_FOUND_HINT,
     inputSchema: {
         ...siteScopeInput,
         enabled: z.boolean().describe('true to enable push to deploy, false to disable it.'),
+        ...waitInput(60),
     },
-    outputSchema: queuedOutput,
-    async handler(args, { client, organization, signal }) {
-        const path = `${sitePath(organization(args.organization), args.server, args.site)}/deployments/push-to-deploy`;
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const org = organization(args.organization);
+        const path = `${sitePath(org, args.server, args.site)}/deployments/push-to-deploy`;
         if (args.enabled) {
             await client.post(path, { signal });
         }
         else {
             await client.delete(path, { signal });
         }
-        return queued(`${args.enabled ? 'enable' : 'disable'} push to deploy`, 'forge_get_site', '(field `quick_deploy`)');
+        const action = `${args.enabled ? 'enable' : 'disable'} push to deploy`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH, '(field `quick_deploy`)');
+        const result = await waitFor({
+            poll: async () => {
+                const response = await client.get(apiPath `/orgs/${org}/sites/${args.site}`, { signal });
+                return flattenSingle(response.data).quick_deploy ?? null;
+            },
+            phase: (quickDeploy) => (quickDeploy === args.enabled ? 'completed' : 'pending'),
+            describe: () => `Waiting for push to deploy to be ${args.enabled ? 'enabled' : 'disabled'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
     },
 });

package/dist/tools/deployments/shared.js

@@ -1,21 +1,14 @@
 import { z } from 'zod';
 import { ForgeApiError } from '../../forge/errors.js';
 import { flattenSingle } from '../../forge/jsonapi.js';
-import { apiPath } from '../../forge/path.js';
+import { phaseOf } from '../shared/async.js';
 import { relatedField, relatedId } from '../shared/relationships.js';
-import { organizationInput, serverInput, siteInput, tail } from '../shared/schemas.js';
-/** Arguments identifying a site: deployment endpoints are nested under the server. */
-export const siteScopeInput = {
-    organization: organizationInput,
-    server: serverInput,
-    site: siteInput,
-};
-export function sitePath(org, server, site) {
-    return apiPath `/orgs/${org}/servers/${server}/sites/${site}`;
+import { tail } from '../shared/schemas.js';
+export { SITE_NOT_FOUND_HINT, siteScopeInput, sitePath } from '../shared/site-scope.js';
+/** Deployments complete when finished and fail when failed, failed in the build or cancelled. */
+export function deploymentPhase(status) {
+    return phaseOf(status, { completed: ['finished'], failed: ['failed', 'failed-build', 'cancelled'] });
 }
-export const SITE_NOT_FOUND_HINT = 'Check the server and site IDs with forge_list_sites (each site lists its `server_id`).';
-/** Deployment statuses after which nothing changes anymore. */
-export const FINAL_STATUSES = new Set(['finished', 'failed', 'failed-build', 'cancelled']);
 export const deploymentOutput = z.looseObject({
     id: z.string().describe('Deployment ID.'),
     status: z.string().nullable().describe('queued, pending, deploying, finished, failed, failed-build, cancelled.'),

package/dist/tools/registry.js

@@ -19,8 +19,22 @@ import { listServerEvents } from './events/list-server-events.js';
 import { listOrganizations } from './organizations/list-organizations.js';
 import { getServer } from './servers/get-server.js';
 import { listServers } from './servers/list-servers.js';
+import { clearSiteLog } from './sites/clear-site-log.js';
+import { createBalancedSite } from './sites/create-balanced-site.js';
+import { createSite } from './sites/create-site.js';
+import { deleteSite } from './sites/delete-site.js';
+import { getSiteEnvironment } from './sites/get-site-environment.js';
+import { getSiteHealthcheck } from './sites/get-site-healthcheck.js';
+import { getSiteLog } from './sites/get-site-log.js';
+import { getSiteNginxConfig } from './sites/get-site-nginx-config.js';
 import { getSite } from './sites/get-site.js';
 import { listSites } from './sites/list-sites.js';
+import { setSiteEnvVars } from './sites/set-site-env-vars.js';
+import { updateSite } from './sites/update-site.js';
+import { updateSiteEnvironment } from './sites/update-site-environment.js';
+import { updateSiteHealthcheck } from './sites/update-site-healthcheck.js';
+import { updateSiteNginxConfig } from './sites/update-site-nginx-config.js';
+import { updateSiteRepository } from './sites/update-site-repository.js';
 /** Every tool shipped by the server. Add new tools here. */
 export const ALL_TOOLS = [
     // core
@@ -31,6 +45,21 @@ export const ALL_TOOLS = [
     getSite,
     listServerEvents,
     getServerEvent,
+    // sites
+    createSite,
+    createBalancedSite,
+    updateSite,
+    updateSiteRepository,
+    deleteSite,
+    setSiteEnvVars,
+    getSiteEnvironment,
+    updateSiteEnvironment,
+    getSiteNginxConfig,
+    updateSiteNginxConfig,
+    getSiteLog,
+    clearSiteLog,
+    getSiteHealthcheck,
+    updateSiteHealthcheck,
     // deployments
     listDeployments,
     getDeployment,

package/dist/tools/shared/async.js

@@ -1,16 +1,108 @@
-import { z } from 'zod';
 /**
- * Forge processes many write operations asynchronously (HTTP 202): the request
- * is accepted and the work continues in the background. Tools must say so and
- * point to the tool that shows the outcome.
+ * Asynchronous operations.
+ *
+ * Forge runs most write operations in the background (`x-processingMode: async`
+ * in the spec, HTTP 202): the request is accepted and the work continues on the
+ * server. Every tool covering such an operation follows the same contract,
+ * documented in CLAUDE.md ("Asynchronous operations"):
+ *
+ * - it declares `async: true` (checked against the spec by tests);
+ * - its output includes `operationOutput`: `status` + `check_with`;
+ * - when the outcome can be observed through the API and the response does not
+ *   already carry it, it accepts `waitInput()` and follows the operation with
+ *   `waitFor()`, reading the resource until it leaves its transitional state
+ *   (or disappears, for deletions: `orGone()`).
  */
-export const queuedOutput = {
-    status: z.literal('queued').describe('Forge accepted the request; the work continues in the background.'),
-    check_with: z.string().describe('Tool to call to follow the outcome.'),
+import { z } from 'zod';
+import { ForgeApiError, ForgeConnectionError } from '../../forge/errors.js';
+export const POLL_INTERVAL_MS = 5_000;
+export const OPERATION_STATUSES = ['queued', 'in_progress', 'completed', 'failed'];
+/** Output fields shared by every asynchronous tool. */
+export const operationOutput = {
+    status: z
+        .enum(OPERATION_STATUSES)
+        .describe('Outcome of the background operation. queued: accepted but not followed (wait=false or the state could not be read); in_progress: still running when the wait timed out; completed / failed: final result.'),
+    check_with: z.string().describe('Tool that shows the current state of the operation.'),
 };
+/** `wait` / `timeout_seconds` inputs for tools that can follow their operation. */
+export function waitInput(defaultTimeoutSeconds) {
+    return {
+        wait: z.boolean().default(true).describe('Wait until Forge finishes the operation before returning.'),
+        timeout_seconds: z
+            .number()
+            .int()
+            .min(10)
+            .max(900)
+            .default(defaultTimeoutSeconds)
+            .describe('Maximum time to wait when `wait` is true.'),
+    };
+}
+/**
+ * Classifies a resource status. `failed` values fail. With `completed`, only
+ * those values complete and anything else is pending; otherwise `pending`
+ * values are pending and anything else (including unknown values) completes.
+ */
+export function phaseOf(status, lists) {
+    const value = typeof status === 'string' ? status : '';
+    if (lists.failed?.includes(value))
+        return 'failed';
+    if (lists.completed)
+        return lists.completed.includes(value) ? 'completed' : 'pending';
+    return lists.pending?.includes(value) ? 'pending' : 'completed';
+}
+/**
+ * Polls every POLL_INTERVAL_MS until the phase is final or the timeout expires,
+ * sending MCP progress notifications. Read errors stop the wait without failing
+ * the tool: the write already succeeded, so the result is "queued" with a reason.
+ */
+export async function waitFor(options) {
+    const { poll, phase, describe, timeoutSeconds, context } = options;
+    const maxPolls = Math.ceil((timeoutSeconds * 1000) / POLL_INTERVAL_MS);
+    let value = options.initial;
+    try {
+        if (value === undefined)
+            value = await poll();
+        for (let attempt = 1; attempt <= maxPolls && phase(value) === 'pending'; attempt++) {
+            await context.progress(attempt, maxPolls, describe(value));
+            await context.sleep(POLL_INTERVAL_MS);
+            value = await poll();
+        }
+    }
+    catch (error) {
+        if (error instanceof ForgeApiError || error instanceof ForgeConnectionError) {
+            return { status: 'queued', value, unfollowed: `could not follow the operation (${error.message})` };
+        }
+        throw error;
+    }
+    const final = phase(value);
+    return { status: final === 'pending' ? 'in_progress' : final, value };
+}
+/** Reads a resource, resolving to null once it no longer exists (404): use it to wait for deletions. */
+export async function orGone(read) {
+    try {
+        return await read();
+    }
+    catch (error) {
+        if (error instanceof ForgeApiError && error.status === 404)
+            return null;
+        throw error;
+    }
+}
+/** Result for an operation that was accepted and not followed. */
 export function queued(action, checkWith, hint) {
     return {
         structured: { status: 'queued', check_with: checkWith },
         summary: `Forge accepted the request to ${action}; it runs in the background. Check the outcome with ${checkWith}${hint ? ` ${hint}` : ''}.`,
     };
 }
+/** Structured status and summary for the result of `waitFor()` (or a skipped wait). */
+export function outcome(result, { action, checkWith, timeoutSeconds, detail }) {
+    const extra = detail ? ` ${detail}` : '';
+    const summaries = {
+        completed: `Forge completed the request to ${action}.${extra}`,
+        failed: `Forge could not ${action}.${extra} Check ${checkWith} for details.`,
+        in_progress: `Forge is still working on the request to ${action} after ${timeoutSeconds}s. Check the outcome later with ${checkWith}.${extra}`,
+        queued: `Forge accepted the request to ${action}; it runs in the background${result.unfollowed ? `, but the tool ${result.unfollowed}` : ''}. Check the outcome with ${checkWith}.${extra}`,
+    };
+    return { structured: { status: result.status, check_with: checkWith }, summary: summaries[result.status] };
+}

package/dist/tools/shared/site-scope.js

@@ -0,0 +1,12 @@
+import { apiPath } from '../../forge/path.js';
+import { organizationInput, serverInput, siteInput } from './schemas.js';
+/** Arguments identifying a site: site endpoints are nested under the server. */
+export const siteScopeInput = {
+    organization: organizationInput,
+    server: serverInput,
+    site: siteInput,
+};
+export function sitePath(org, server, site) {
+    return apiPath `/orgs/${org}/servers/${server}/sites/${site}`;
+}
+export const SITE_NOT_FOUND_HINT = 'Check the server and site IDs with forge_list_sites (each site lists its `server_id`).';