@francescomalatesta/laravel-forge-mcp 0.1.0 → 0.3.0

package/README.md

@@ -70,31 +70,39 @@ npm run build
 | `FORGE_TIMEOUT_MS` | `30000` | Per-request timeout. |
 | `FORGE_MAX_RETRIES` | `2` | Retries for rate limits (429) and transient errors. |
 
-### Toolsets
-
-| Toolset | Contents |
-|---|---|
-| `core` | Organizations, servers and other entry points |
-| `sites` | Sites, domains, certificates, Nginx, site configuration |
-| `deployments` | Deployments, scripts, logs, push-to-deploy |
-| `servers` | PHP, services, network, events, server logs |
-| `databases` | Database schemas, users, backups |
-| `jobs` | Scheduled jobs, background processes |
-| `security` | Firewall, security and redirect rules, SSH keys |
-| `integrations` | Horizon, Octane, Reverb, Pulse, Inertia, scheduler, maintenance |
-| `monitoring` | Monitors, heartbeats, health checks |
-| `recipes` | Recipes and runs |
-| `teams` | Teams, members, invitations, roles |
-| `providers` | Providers, regions, sizes, credentials, VPCs |
-| `storage` | Storage providers |
-| `commands` | Arbitrary commands on sites (disabled by default) |
-
-## Tools
+### Tools
 
 | Tool | Toolset | Description |
 |---|---|---|
 | `forge_list_organizations` | core | List accessible organizations and their slugs |
 | `forge_list_servers` | core | List servers with filters, sorting and pagination |
+| `forge_get_server` | core | Every detail of a server |
+| `forge_list_sites` | core | Sites of an organization, a server or all organizations, with latest deployment |
+| `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_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 |
+| `forge_deploy_site` | deployments | Deploy a site and (optionally) wait for the result, with progress notifications |
+| `forge_reset_deployment_state` | deployments | Unblock a stuck deployment |
+| `forge_get_deployment_script` | deployments | Read the deployment script |
+| `forge_update_deployment_script` | deployments | Replace the deployment script |
+| `forge_set_push_to_deploy` | deployments | Enable or disable push to deploy |
+| `forge_list_deployment_webhooks` | deployments | Webhooks notified after deployments |
+| `forge_create_deployment_webhook` | deployments | Add a deployment webhook |
+| `forge_delete_deployment_webhook` | deployments | Remove a deployment webhook |
+| `forge_get_deploy_key` | deployments | The site's SSH deploy key |
+| `forge_create_deploy_key` | deployments | Create a deploy key |
+| `forge_delete_deploy_key` | deployments | Remove the deploy key |
+| `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.
+
+### 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
 
@@ -108,7 +116,7 @@ npm run spec:update    # download the latest spec and regenerate types
 npm run check          # typecheck + tests + coverage
 ```
 
-Releases are automated: see [RELEASING.md](RELEASING.md).
+Every push to `main` with `feat:` or `fix:` commits is released to npm automatically, based on [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/): see [RELEASING.md](RELEASING.md).
 
 ### Project structure
 

package/dist/server.js

@@ -7,15 +7,16 @@ const INSTRUCTIONS = `Tools for managing Laravel Forge (servers, sites, deployme
 - Every resource belongs to an organization. If an "organization" argument is required and unknown, call forge_list_organizations first.
 - Resources are addressed by ID. Use the list tools (e.g. forge_list_servers) to find IDs instead of guessing.
 - List tools are paginated: when "has_more" is true, pass "next_cursor" as "cursor" to get the next page.
-- Many write operations are asynchronous in Forge: an accepted request is not yet completed.`;
-export function createServer({ config, client, tools }) {
+- Many write operations are asynchronous in Forge: an accepted request is not yet completed. Follow the outcome with the tool named in the result, or with forge_list_server_events and forge_get_server_event.
+- Site and deployment tools need both the server ID and the site ID: forge_list_sites returns both.`;
+export function createServer({ config, client, tools, sleep = abortableSleep }) {
     const server = new McpServer({ name: SERVER_NAME, version: VERSION }, { instructions: INSTRUCTIONS });
     for (const tool of tools ?? selectTools(config)) {
-        registerTool(server, tool, config, client);
+        registerTool(server, tool, config, client, sleep);
     }
     return server;
 }
-function registerTool(server, tool, config, client) {
+function registerTool(server, tool, config, client, sleep) {
     server.registerTool(tool.name, {
         title: tool.title,
         description: describe(tool),
@@ -33,6 +34,16 @@ function registerTool(server, tool, config, client) {
             client,
             config,
             signal: extra.signal,
+            sleep: (ms) => sleep(ms, extra.signal),
+            progress: async (progress, total, message) => {
+                const progressToken = extra._meta?.progressToken;
+                if (progressToken === undefined)
+                    return;
+                await extra.sendNotification({
+                    method: 'notifications/progress',
+                    params: { progressToken, progress, ...(total !== undefined ? { total } : {}), message },
+                });
+            },
             organization: (explicit) => {
                 const slug = explicit ?? config.organization;
                 if (!slug)
@@ -55,7 +66,24 @@ function registerTool(server, tool, config, client) {
         }
     });
 }
+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) => {
+        if (signal.aborted)
+            return reject(signal.reason);
+        const timer = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
 }

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

@@ -0,0 +1,31 @@
+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({
+    name: 'forge_create_deploy_key',
+    title: 'Create deploy key',
+    description: 'Create an SSH deploy key for the site (returns the existing key if there is one). Add the returned public key as a deploy key in the Git provider so the server can pull that repository.',
+    toolset: 'deployments',
+    operations: ['organizations.servers.sites.deploy-key.store'],
+    permissions: ['site:manage-deploys'],
+    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: { ...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: { 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

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.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', '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: {
+        ...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 },
+        });
+        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-deploy-key.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput, sitePath } from './shared.js';
+export const deleteDeployKey = defineTool({
+    name: 'forge_delete_deploy_key',
+    title: 'Delete deploy key',
+    description: "Remove the site's SSH deploy key. Deployments will fail if the repository is only reachable through this key.",
+    toolset: 'deployments',
+    operations: ['organizations.servers.sites.deploy-key.destroy'],
+    permissions: ['site:manage-deploys'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: siteScopeInput,
+    outputSchema: {
+        deleted: z.boolean(),
+    },
+    async handler(args, { client, organization, signal }) {
+        await client.delete(`${sitePath(organization(args.organization), args.server, args.site)}/deploy-key`, { signal });
+        return { structured: { deleted: true }, summary: 'Deploy key removed from the site.' };
+    },
+});

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

@@ -0,0 +1,38 @@
+import { defineTool } from '../define-tool.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', '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: 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

@@ -0,0 +1,84 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+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',
+    description: "Deploy a site now by running its deployment script. By default waits for the deployment to finish (up to `timeout_seconds`) and returns its final status with the end of the log; with `wait: false` returns as soon as Forge queues it. Check the deployment script first with forge_get_deployment_script if unsure what it runs.",
+    toolset: 'deployments',
+    operations: [
+        'organizations.servers.sites.deployments.store',
+        'organizations.servers.sites.deployments.show',
+        'organizations.servers.sites.deployments.log.show',
+    ],
+    permissions: ['site:manage-deploys', 'server:view'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    async: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        ...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(),
+        ...logOutput,
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const base = sitePath(organization(args.organization), args.server, args.site);
+        const created = await client.post(`${base}/deployments`, { signal });
+        const noLog = { log: null, log_truncated: false, log_total_lines: null, log_unavailable_reason: null };
+        if (!created.data?.data) {
+            // Accepted without a deployment in the body: nothing to follow by ID.
+            return {
+                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.',
+            };
+        }
+        const queuedDeployment = formatDeployment(flattenSingle(created.data));
+        if (!args.wait) {
+            return {
+                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 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;
+        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/get-deploy-hook.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput, sitePath } from './shared.js';
+export const deployHookOutput = {
+    url: z.string().nullable().describe('Calling this URL (GET or POST) triggers a deployment. Treat it as a secret.'),
+};
+export const getDeployHook = defineTool({
+    name: 'forge_get_deploy_hook',
+    title: 'Get deploy hook URL',
+    description: 'Get the deployment trigger URL of a site, used by CI services to deploy it. Anyone with this URL can deploy the site.',
+    toolset: 'deployments',
+    operations: ['organizations.servers.sites.deployments.deploy-hook.show'],
+    permissions: ['site:manage-deploys'],
+    readOnly: true,
+    exposesSecrets: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: siteScopeInput,
+    outputSchema: deployHookOutput,
+    async handler(args, { client, organization, signal }) {
+        const response = await client.get(`${sitePath(organization(args.organization), args.server, args.site)}/deployments/deploy-hook`, { signal });
+        return {
+            structured: { url: flattenSingle(response.data).url ?? null },
+            summary: 'Deploy hook URL retrieved. Keep it secret: calling it deploys the site.',
+        };
+    },
+});

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

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput, sitePath } from './shared.js';
+export const deployKeyOutput = {
+    key: z.string().nullable().describe('Public SSH key to add as a read-only deploy key in the Git provider, or null if none.'),
+};
+export const getDeployKey = defineTool({
+    name: 'forge_get_deploy_key',
+    title: 'Get deploy key',
+    description: "Get the site's public SSH deploy key, which grants the server access to a single repository. Create one with forge_create_deploy_key.",
+    toolset: 'deployments',
+    operations: ['organizations.servers.sites.deploy-key.show'],
+    permissions: ['site:manage-deploys'],
+    readOnly: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: siteScopeInput,
+    outputSchema: deployKeyOutput,
+    async handler(args, { client, organization, signal }) {
+        const response = await client.get(`${sitePath(organization(args.organization), args.server, args.site)}/deploy-key`, { signal });
+        const key = flattenSingle(response.data).key ?? null;
+        return {
+            structured: { key },
+            summary: key ? 'The site has a deploy key.' : 'The site has no deploy key; create one with forge_create_deploy_key.',
+        };
+    },
+});

package/dist/tools/deployments/get-deployment-script.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput, sitePath } from './shared.js';
+export const deploymentScriptOutput = {
+    content: z.string().nullable().describe('The deployment script (bash).'),
+    auto_source: z.boolean().nullable().describe('Whether environment variables are sourced automatically before the script runs.'),
+};
+export const getDeploymentScript = defineTool({
+    name: 'forge_get_deployment_script',
+    title: 'Get deployment script',
+    description: 'Get the bash script Forge runs when the site is deployed.',
+    toolset: 'deployments',
+    operations: ['organizations.servers.sites.deployments.script.show'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: siteScopeInput,
+    outputSchema: deploymentScriptOutput,
+    async handler(args, { client, organization, signal }) {
+        const response = await client.get(`${sitePath(organization(args.organization), args.server, args.site)}/deployments/script`, { signal });
+        const flat = flattenSingle(response.data);
+        const content = flat.content ?? null;
+        return {
+            structured: { content, auto_source: flat.auto_source ?? null },
+            summary: content ? `The deployment script has ${content.split('\n').length} line(s).` : 'The site has no deployment script.',
+        };
+    },
+});

package/dist/tools/deployments/get-deployment-status.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput, sitePath } from './shared.js';
+export const getDeploymentStatus = defineTool({
+    name: 'forge_get_deployment_status',
+    title: 'Get deployment status',
+    description: 'Check whether a deployment is currently running on a site. A null status means no deployment is in progress. If a deployment looks stuck, forge_reset_deployment_state clears it.',
+    toolset: 'deployments',
+    operations: ['organizations.servers.sites.deployments.status.show'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: siteScopeInput,
+    outputSchema: {
+        status: z.string().nullable().describe('Current deployment status, or null when nothing is running.'),
+        started_at: z.string().nullable(),
+    },
+    async handler(args, { client, organization, signal }) {
+        const response = await client.get(`${sitePath(organization(args.organization), args.server, args.site)}/deployments/status`, { signal });
+        const flat = flattenSingle(response.data);
+        const status = flat.status ?? null;
+        const startedAt = flat.started_at ?? null;
+        return {
+            structured: { status, started_at: startedAt },
+            summary: status
+                ? `A deployment is ${status}${startedAt ? ` since ${startedAt}` : ''}.`
+                : 'No deployment is currently running on this site.',
+        };
+    },
+});

package/dist/tools/deployments/get-deployment.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { idInput } from '../shared/schemas.js';
+import { deploymentOutput, fetchLog, formatDeployment, logLinesInput, logOutput, siteScopeInput, sitePath } from './shared.js';
+export const getDeployment = defineTool({
+    name: 'forge_get_deployment',
+    title: 'Get deployment',
+    description: 'Get a deployment with its status, commit, timing and the end of its log. Use it to understand why a deployment failed.',
+    toolset: 'deployments',
+    operations: ['organizations.servers.sites.deployments.show', 'organizations.servers.sites.deployments.log.show'],
+    permissions: ['server:view', 'site:manage-deploys'],
+    readOnly: true,
+    notFoundHint: 'Check the deployment ID with forge_list_deployments.',
+    inputSchema: {
+        ...siteScopeInput,
+        deployment: idInput('Deployment ID. Use forge_list_deployments to find it.'),
+        include_log: z.boolean().default(true).describe('Also fetch the deployment log.'),
+        log_lines: logLinesInput(100),
+    },
+    outputSchema: {
+        deployment: deploymentOutput,
+        ...logOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const base = sitePath(organization(args.organization), args.server, args.site);
+        const [response, log] = await Promise.all([
+            client.get(`${base}/deployments/${encodeURIComponent(String(args.deployment))}`, { signal }),
+            args.include_log
+                ? fetchLog(client, base, args.deployment, args.log_lines, signal)
+                : Promise.resolve({ log: null, log_truncated: false, log_total_lines: null, log_unavailable_reason: null }),
+        ]);
+        const deployment = formatDeployment(flattenSingle(response.data));
+        return {
+            structured: { deployment, ...log },
+            summary: `Deployment ${deployment.id} is ${deployment.status}${deployment.commit_message ? ` (commit: "${deployment.commit_message}")` : ''}.${log.log_unavailable_reason ? ` ${log.log_unavailable_reason}` : ''}`,
+        };
+    },
+});

package/dist/tools/deployments/list-deployment-webhooks.js

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+import { flattenCollection, flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { idInput, paginationInput, paginationOutput, paginationSummary, pick } from '../shared/schemas.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput, sitePath } from './shared.js';
+const WEBHOOK_FIELDS = ['id', 'url', 'created_at', 'updated_at'];
+const webhookOutput = z.looseObject({
+    id: z.string(),
+    url: z.string().nullable().describe('URL notified after every deployment.'),
+    created_at: z.string().nullable(),
+    updated_at: z.string().nullable(),
+});
+export const listDeploymentWebhooks = defineTool({
+    name: 'forge_list_deployment_webhooks',
+    title: 'List deployment webhooks',
+    description: 'List the URLs Forge notifies after each deployment of a site, or get one webhook by ID with `webhook`.',
+    toolset: 'deployments',
+    operations: ['organizations.servers.sites.webhooks.index', 'organizations.servers.sites.webhooks.show'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        webhook: idInput('Return only this webhook.').optional(),
+        ...paginationInput,
+    },
+    outputSchema: {
+        webhooks: z.array(webhookOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const base = `${sitePath(organization(args.organization), args.server, args.site)}/webhooks`;
+        if (args.webhook !== undefined) {
+            const response = await client.get(`${base}/${encodeURIComponent(String(args.webhook))}`, { signal });
+            const webhook = pick(flattenSingle(response.data), WEBHOOK_FIELDS);
+            return { structured: { webhooks: [webhook], next_cursor: null, has_more: false }, summary: `Webhook ${webhook.id}: ${webhook.url}.` };
+        }
+        const response = await client.get(base, {
+            query: { page: { size: args.page_size, cursor: args.cursor } },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const webhooks = page.items.map((item) => pick(item, WEBHOOK_FIELDS));
+        return {
+            structured: { webhooks, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: webhooks.length === 0
+                ? 'The site has no deployment webhooks.'
+                : `Found ${webhooks.length} deployment webhook(s).${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

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

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { apiPath } from '../../forge/path.js';
+import { defineTool } from '../define-tool.js';
+import { idInput, organizationInput, paginationInput, paginationOutput, paginationSummary, serverInput } from '../shared/schemas.js';
+import { deploymentOutput, formatDeployment, sitePath } from './shared.js';
+export const listDeployments = defineTool({
+    name: 'forge_list_deployments',
+    title: 'List deployments',
+    description: 'List recent deployments of a site, or of every site on a server when `site` is omitted, newest first by default. Shows status, commit and timing. Use forge_get_deployment for the log of one deployment.',
+    toolset: 'deployments',
+    operations: ['organizations.servers.sites.deployments.index', 'organizations.servers.deployments.index'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: 'Check the server and site IDs with forge_list_sites.',
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        site: idInput('Only list deployments of this site. Omit to list deployments of every site on the server.').optional(),
+        commit_hash: z.string().min(1).optional().describe('Filter by commit hash.'),
+        commit_message: z.string().min(1).optional().describe('Filter by commit message.'),
+        commit_author: z.string().min(1).optional().describe('Filter by commit author.'),
+        sort: z.enum(['-created_at', 'created_at']).default('-created_at').describe('Sort by creation date.'),
+        ...paginationInput,
+    },
+    outputSchema: {
+        deployments: z.array(deploymentOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const org = organization(args.organization);
+        const onSite = args.site !== undefined;
+        const path = onSite
+            ? `${sitePath(org, args.server, args.site)}/deployments`
+            : apiPath `/orgs/${org}/servers/${args.server}/deployments`;
+        const response = await client.get(path, {
+            query: {
+                filter: { commit_hash: args.commit_hash, commit_message: args.commit_message, commit_author: args.commit_author },
+                sort: [args.sort],
+                include: onSite ? undefined : ['site', 'initiator'],
+                page: { size: args.page_size, cursor: args.cursor },
+            },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const deployments = page.items.map(formatDeployment);
+        const scope = onSite ? `site ${args.site}` : `server ${args.server}`;
+        return {
+            structured: { deployments, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: deployments.length === 0
+                ? `No deployments found for ${scope}.`
+                : `Found ${deployments.length} deployment(s) for ${scope}; the first is ${deployments[0].status}.${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});