@francescomalatesta/laravel-forge-mcp 0.9.0 → 0.11.0

package/README.md

@@ -164,9 +164,28 @@ npm run build
 | `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 |
+| `forge_list_scheduled_jobs` | jobs | Scheduled jobs (cron) of a server or a site |
+| `forge_get_scheduled_job` | jobs | A scheduled job with the output of its last run |
+| `forge_create_scheduled_job` | jobs | Schedule a command, optionally with a heartbeat |
+| `forge_delete_scheduled_job` | jobs | Remove a scheduled job |
+| `forge_list_background_processes` | jobs | Supervisor daemons (queue workers, …) and their status |
+| `forge_get_background_process_log` | jobs | End of a background process log |
+| `forge_create_background_process` | jobs | Run a command permanently under Supervisor and wait until it is running |
+| `forge_update_background_process` | jobs | Rename or replace the Supervisor configuration |
+| `forge_run_background_process_action` | jobs | Start, stop or restart a background process, or empty its log |
+| `forge_delete_background_process` | jobs | Stop and remove a background process |
+| `forge_get_site_integrations` | integrations | Horizon, Octane, Reverb, Pulse, Inertia SSR, scheduler and maintenance mode status |
+| `forge_enable_site_integration` | integrations | Enable an integration (e.g. put the site in maintenance mode) and wait until it is active |
+| `forge_disable_site_integration` | integrations | Disable an integration (e.g. bring the site back up) |
+| `forge_run_site_command` | commands | Run a command in the site directory and return its output |
+| `forge_list_site_commands` | commands | Commands run on a site with status and exit code |
+| `forge_get_site_command` | commands | A command run with the end of its output |
+| `forge_delete_site_command` | commands | Remove a command run from the history |
 
 🔑 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.
 
+The `commands` toolset runs arbitrary shell commands with the privileges of the site user: enable it explicitly (e.g. `FORGE_TOOLSETS=default,commands`) only when you need it. Note that `all` includes it.
+
 ### 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`.

package/dist/tools/background-processes/create-background-process.js

@@ -0,0 +1,81 @@
+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 { readResource } from '../shared/read.js';
+import { idInput, organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { backgroundProcessOutput, backgroundProcessesPath, formatBackgroundProcess, processPhase } from './shared.js';
+const CHECK_WITH = 'forge_list_background_processes';
+export const createBackgroundProcess = defineTool({
+    name: 'forge_create_background_process',
+    title: 'Create background process',
+    description: 'Run a command permanently in the background under Supervisor (e.g. `php artisan queue:work`), restarting it when it exits. For Horizon, Octane, Reverb, Pulse or Inertia SSR prefer forge_enable_site_integration. Waits until it is running unless `wait` is false.',
+    toolset: 'jobs',
+    operations: ['organizations.servers.background-processes.store', 'organizations.servers.background-processes.show'],
+    permissions: ['server:create-daemons', 'server:view'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        name: z.string().min(1).describe('Name of the background process, e.g. "Queue worker".'),
+        command: z.string().min(1).describe('Command to run, e.g. "php artisan queue:work --tries=3".'),
+        user: z.enum(['forge', 'root']).default('forge').describe('User the process runs as.'),
+        site: idInput('Site the process belongs to.').optional(),
+        directory: z.string().min(1).optional().describe('Working directory, e.g. "/home/forge/example.com/current".'),
+        processes: z.number().int().min(1).default(1).describe('Number of processes to keep running.'),
+        startsecs: z.number().int().min(0).optional().describe('Seconds the process must stay up to be considered started.'),
+        stopwaitsecs: z.number().int().min(0).optional().describe('Seconds to wait for a graceful stop before killing it.'),
+        stopsignal: z.string().min(1).optional().describe('Signal sent to stop it, e.g. "SIGTERM".'),
+        ...waitInput(120),
+    },
+    outputSchema: {
+        ...operationOutput,
+        background_process: backgroundProcessOutput.nullable(),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const base = backgroundProcessesPath(organization(args.organization), args.server);
+        const response = await client.post(base, {
+            body: {
+                name: args.name,
+                site_id: args.site === undefined ? undefined : Number(args.site),
+                command: args.command,
+                user: args.user,
+                directory: args.directory,
+                processes: args.processes,
+                startsecs: args.startsecs,
+                stopwaitsecs: args.stopwaitsecs,
+                stopsignal: args.stopsignal,
+            },
+            signal,
+        });
+        const initial = response.data?.data ? flattenSingle(response.data) : undefined;
+        const action = `start \`${args.command}\` in the background`;
+        if (!initial || !args.wait) {
+            return {
+                structured: { status: 'queued', check_with: CHECK_WITH, background_process: initial ? formatBackgroundProcess(initial) : null },
+                summary: `Forge accepted the request to ${action}. Check it with ${CHECK_WITH}.`,
+            };
+        }
+        const result = await waitFor({
+            initial,
+            poll: () => readResource(client, `${base}/${encodeURIComponent(initial.id)}`, signal),
+            phase: (process) => processPhase(process.status, 'running'),
+            describe: (process) => `Background process is ${process.status}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const process = formatBackgroundProcess(result.value ?? initial);
+        const done = outcome(result, {
+            action,
+            checkWith: CHECK_WITH,
+            timeoutSeconds: args.timeout_seconds,
+            detail: `Process ID: ${process.id}.${result.status === 'failed' ? ' Read why with forge_get_background_process_log.' : ''}`,
+        });
+        return { structured: { ...done.structured, background_process: process }, summary: done.summary };
+    },
+});

package/dist/tools/background-processes/delete-background-process.js

@@ -0,0 +1,41 @@
+import { defineTool } from '../define-tool.js';
+import { operationOutput, orGone, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { BACKGROUND_PROCESS_NOT_FOUND_HINT, backgroundProcessInput, backgroundProcessPath } from './shared.js';
+const CHECK_WITH = 'forge_list_background_processes';
+export const deleteBackgroundProcess = defineTool({
+    name: 'forge_delete_background_process',
+    title: 'Delete background process',
+    description: 'Stop a background process and remove it from Supervisor.',
+    toolset: 'jobs',
+    operations: ['organizations.servers.background-processes.destroy', 'organizations.servers.background-processes.show'],
+    permissions: ['server:delete-daemons', 'server:view'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: BACKGROUND_PROCESS_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        background_process: backgroundProcessInput,
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = backgroundProcessPath(organization(args.organization), args.server, args.background_process);
+        await client.delete(path, { signal });
+        const action = `delete background process ${args.background_process}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(() => readResource(client, path, signal)),
+            phase: (process) => (process === null ? 'completed' : 'pending'),
+            describe: (process) => `Background process is ${process?.status ?? 'removing'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/background-processes/get-background-process-log.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, serverInput, tail } from '../shared/schemas.js';
+import { BACKGROUND_PROCESS_NOT_FOUND_HINT, backgroundProcessInput, backgroundProcessPath } from './shared.js';
+export const getBackgroundProcessLog = defineTool({
+    name: 'forge_get_background_process_log',
+    title: 'Get background process log',
+    description: 'Read the end of the log of a background process (what the worker printed, crash traces). Empty it with forge_run_background_process_action.',
+    toolset: 'jobs',
+    operations: ['organizations.servers.background-processes.log.show'],
+    permissions: ['server:create-daemons'],
+    readOnly: true,
+    notFoundHint: BACKGROUND_PROCESS_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        background_process: backgroundProcessInput,
+        lines: z.number().int().min(0).max(5000).default(100).describe('Return only the last N lines (0 = whole log).'),
+    },
+    outputSchema: {
+        log: z.string(),
+        truncated: z.boolean(),
+        total_lines: z.number().int(),
+    },
+    async handler(args, { client, organization, signal }) {
+        const path = `${backgroundProcessPath(organization(args.organization), args.server, args.background_process)}/log`;
+        const log = tail((await readResource(client, path, signal)).content, args.lines);
+        return {
+            structured: { log: log.text, truncated: log.truncated, total_lines: log.total_lines },
+            summary: log.total_lines === 0 ? 'The log is empty.' : `Showing ${log.truncated ? `the last ${args.lines} of ` : ''}${log.total_lines} line(s).`,
+        };
+    },
+});

package/dist/tools/background-processes/list-background-processes.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { readResource } from '../shared/read.js';
+import { idInput, organizationInput, paginationInput, paginationOutput, paginationSummary, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { backgroundProcessInput, backgroundProcessOutput, backgroundProcessPath, backgroundProcessesPath, formatBackgroundProcess, } from './shared.js';
+export const listBackgroundProcesses = defineTool({
+    name: 'forge_list_background_processes',
+    title: 'List background processes',
+    description: 'List the background processes (Supervisor daemons such as queue workers, Horizon or Reverb) on a server with their status, or get one with `background_process`. Filter by site, user or directory.',
+    toolset: 'jobs',
+    operations: ['organizations.servers.background-processes.index', 'organizations.servers.background-processes.show'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        background_process: backgroundProcessInput.optional().describe('Return only this background process.'),
+        site: idInput('Only processes of this site.').optional(),
+        user: z.string().min(1).optional().describe('Only processes running as this user.'),
+        directory: z.string().min(1).optional().describe('Only processes running in this directory.'),
+        sort: z.array(z.enum(['user', '-user'])).min(1).optional(),
+        ...paginationInput,
+    },
+    outputSchema: {
+        background_processes: z.array(backgroundProcessOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const org = organization(args.organization);
+        if (args.background_process !== undefined) {
+            const process = formatBackgroundProcess(await readResource(client, backgroundProcessPath(org, args.server, args.background_process), signal));
+            return {
+                structured: { background_processes: [process], next_cursor: null, has_more: false },
+                summary: `\`${process.command}\` is ${process.status}.`,
+            };
+        }
+        const response = await client.get(backgroundProcessesPath(org, args.server), {
+            query: {
+                filter: { site_id: args.site === undefined ? undefined : String(args.site), user: args.user, directory: args.directory },
+                sort: args.sort,
+                page: { size: args.page_size, cursor: args.cursor },
+            },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const processes = page.items.map(formatBackgroundProcess);
+        const notRunning = processes.filter((process) => process.status !== 'running');
+        return {
+            structured: { background_processes: processes, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: processes.length === 0
+                ? 'No background processes found.'
+                : `Found ${processes.length} background process(es)${notRunning.length > 0 ? `; not running: ${notRunning.map((p) => `${p.id} (${p.status})`).join(', ')}` : ', all running'}.${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

package/dist/tools/background-processes/run-background-process-action.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { BACKGROUND_PROCESS_NOT_FOUND_HINT, backgroundProcessInput, backgroundProcessOutput, backgroundProcessPath, formatBackgroundProcess, processPhase, } from './shared.js';
+const CHECK_WITH = 'forge_list_background_processes';
+const TARGET = { start: 'running', stop: 'stopped' };
+export const runBackgroundProcessAction = defineTool({
+    name: 'forge_run_background_process_action',
+    title: 'Run background process action',
+    description: 'Start, stop or restart a background process (e.g. restart queue workers after changing code outside a deployment), or empty its log. Waits for start and stop; restart and empty-log cannot be observed through the API.',
+    toolset: 'jobs',
+    operations: ['organizations.servers.background-processes.actions.store', 'organizations.servers.background-processes.show'],
+    permissions: ['server:create-daemons', 'server:view'],
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
+    async: true,
+    notFoundHint: BACKGROUND_PROCESS_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        background_process: backgroundProcessInput,
+        action: z.enum(['restart', 'start', 'stop', 'empty-log']).describe('Action to run.'),
+        ...waitInput(60),
+    },
+    outputSchema: {
+        ...operationOutput,
+        background_process: backgroundProcessOutput.nullable(),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = backgroundProcessPath(organization(args.organization), args.server, args.background_process);
+        await client.post(`${path}/actions`, { body: { action: args.action }, signal });
+        const action = `${args.action} background process ${args.background_process}`;
+        const target = args.action === 'start' || args.action === 'stop' ? TARGET[args.action] : undefined;
+        if (!target || !args.wait) {
+            // A restart ends in "running" like before it, and the log content is not compared: nothing to wait for.
+            const accepted = queued(action, CHECK_WITH);
+            return { ...accepted, structured: { ...accepted.structured, background_process: null } };
+        }
+        const result = await waitFor({
+            poll: () => readResource(client, path, signal),
+            phase: (process) => processPhase(process.status, target),
+            describe: (process) => `Background process is ${process.status}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const done = outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+        return {
+            structured: { ...done.structured, background_process: result.value ? formatBackgroundProcess(result.value) : null },
+            summary: done.summary,
+        };
+    },
+});

package/dist/tools/background-processes/shared.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { phaseOf } from '../shared/async.js';
+import { idInput, pick } from '../shared/schemas.js';
+import { serverPath } from '../servers/shared.js';
+export function backgroundProcessesPath(org, server) {
+    return `${serverPath(org, server)}/background-processes`;
+}
+export function backgroundProcessPath(org, server, process) {
+    return `${backgroundProcessesPath(org, server)}/${encodeURIComponent(String(process))}`;
+}
+export const backgroundProcessInput = idInput('Background process ID. Use forge_list_background_processes to find it.');
+export const BACKGROUND_PROCESS_NOT_FOUND_HINT = 'Check the background process ID with forge_list_background_processes.';
+const FIELDS = ['id', 'command', 'user', 'directory', 'processes', 'status', 'created_at'];
+export const backgroundProcessOutput = z.looseObject({
+    id: z.string(),
+    command: z.string().nullable(),
+    user: z.string().nullable(),
+    directory: z.string().nullable(),
+    processes: z.number().nullable().describe('Number of processes Supervisor keeps running.'),
+    status: z
+        .string()
+        .nullable()
+        .describe('installing, removing, restarting, starting, stopping, running, stopped, fatal, backoff, exited or unknown.'),
+    created_at: z.string().nullable(),
+});
+export function formatBackgroundProcess(flat) {
+    return pick(flat, FIELDS);
+}
+/** Waits for `target`; fatal and exited mean Supervisor gave up (backoff is still retrying). */
+export function processPhase(status, target) {
+    return phaseOf(status, { completed: [target], failed: ['fatal', 'exited'] });
+}

package/dist/tools/background-processes/update-background-process.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, queued } from '../shared/async.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { BACKGROUND_PROCESS_NOT_FOUND_HINT, backgroundProcessInput, backgroundProcessPath } from './shared.js';
+export const updateBackgroundProcess = defineTool({
+    name: 'forge_update_background_process',
+    title: 'Update background process',
+    description: 'Rename a background process and/or replace its Supervisor configuration (the [program:…] section: command, numprocs, user, stopwaitsecs, …). Supervisor reloads it.',
+    toolset: 'jobs',
+    operations: ['organizations.servers.background-processes.update'],
+    permissions: ['server:create-daemons'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    async: true,
+    notFoundHint: BACKGROUND_PROCESS_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        background_process: backgroundProcessInput,
+        name: z.string().min(1).describe('Name of the background process (required by Forge: pass the current one to keep it).'),
+        config: z.string().min(1).optional().describe('Complete Supervisor configuration replacing the current one.'),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal }) {
+        await client.put(backgroundProcessPath(organization(args.organization), args.server, args.background_process), {
+            body: { name: args.name, config: args.config },
+            signal,
+        });
+        // Neither the name nor the configuration is exposed by the API: nothing to compare.
+        return queued(`update background process ${args.background_process}`, 'forge_list_background_processes', '(its status shows whether it is running again)');
+    },
+});

package/dist/tools/commands/delete-site-command.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { siteScopeInput } from '../shared/site-scope.js';
+import { commandInput, commandsPath } from './shared.js';
+export const deleteSiteCommand = defineTool({
+    name: 'forge_delete_site_command',
+    title: 'Delete site command',
+    description: 'Delete a command run and its output from the site history.',
+    toolset: 'commands',
+    operations: ['organizations.servers.sites.commands.destroy'],
+    permissions: ['site:manage-commands'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    notFoundHint: 'Check the command ID with forge_list_site_commands.',
+    inputSchema: {
+        ...siteScopeInput,
+        command: commandInput,
+    },
+    outputSchema: {
+        deleted: z.boolean(),
+    },
+    async handler(args, { client, organization, signal }) {
+        await client.delete(`${commandsPath(organization(args.organization), args.server, args.site)}/${encodeURIComponent(String(args.command))}`, {
+            signal,
+        });
+        return { structured: { deleted: true }, summary: `Deleted command ${args.command} from the history.` };
+    },
+});

package/dist/tools/commands/get-site-command.js

@@ -0,0 +1,37 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { readResource } from '../shared/read.js';
+import { siteScopeInput } from '../shared/site-scope.js';
+import { fetchOutput, NO_OUTPUT, outputFields, outputLinesInput } from '../shared/output.js';
+import { commandInput, commandOutput, commandsPath, formatCommand } from './shared.js';
+export const getSiteCommand = defineTool({
+    name: 'forge_get_site_command',
+    title: 'Get site command',
+    description: 'Get a command run on a site with its status, exit code and the end of its output.',
+    toolset: 'commands',
+    operations: ['organizations.servers.sites.commands.show', 'organizations.servers.sites.commands.output.show'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: 'Check the command ID with forge_list_site_commands.',
+    inputSchema: {
+        ...siteScopeInput,
+        command: commandInput,
+        include_output: z.boolean().default(true).describe('Also fetch the output.'),
+        output_lines: outputLinesInput(100),
+    },
+    outputSchema: {
+        command: commandOutput,
+        ...outputFields,
+    },
+    async handler(args, { client, organization, signal }) {
+        const path = `${commandsPath(organization(args.organization), args.server, args.site)}/${encodeURIComponent(String(args.command))}`;
+        const [command, output] = await Promise.all([
+            readResource(client, path, signal).then(formatCommand),
+            args.include_output ? fetchOutput(client, path, args.output_lines, signal) : Promise.resolve(NO_OUTPUT),
+        ]);
+        return {
+            structured: { command, ...output },
+            summary: `\`${command.command}\` is ${command.status}${command.exit_code === null ? '' : ` (exit code ${command.exit_code})`}.${command.error_output ? ` Error: ${command.error_output}` : ''}`,
+        };
+    },
+});

package/dist/tools/commands/list-site-commands.js

@@ -0,0 +1,47 @@
+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 } from '../shared/site-scope.js';
+import { COMMAND_STATUSES, commandOutput, commandsPath, formatCommand } from './shared.js';
+const SORT = ['status', '-status', 'created_at', '-created_at', 'updated_at', '-updated_at'];
+export const listSiteCommands = defineTool({
+    name: 'forge_list_site_commands',
+    title: 'List site commands',
+    description: 'List the commands run on a site (newest first by default) with status and exit code. Read the output of one with forge_get_site_command.',
+    toolset: 'commands',
+    operations: ['organizations.servers.sites.commands.index'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        status: z.enum(COMMAND_STATUSES).optional().describe('Filter by status.'),
+        command: z.string().min(1).optional().describe('Filter by command text.'),
+        user_id: z.union([z.number().int(), z.string().min(1)]).optional().describe('Filter by the user who ran it.'),
+        sort: z.array(z.enum(SORT)).min(1).optional().describe('Defaults to newest first.'),
+        ...paginationInput,
+    },
+    outputSchema: {
+        commands: z.array(commandOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const response = await client.get(commandsPath(organization(args.organization), args.server, args.site), {
+            query: {
+                filter: { status: args.status, command: args.command, user_id: args.user_id === undefined ? undefined : String(args.user_id) },
+                sort: args.sort ?? ['-created_at'],
+                page: { size: args.page_size, cursor: args.cursor },
+            },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const commands = page.items.map(formatCommand);
+        return {
+            structured: { commands, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: commands.length === 0
+                ? 'No commands found.'
+                : `Found ${commands.length} command(s); latest: \`${commands[0].command}\` (${commands[0].status}).${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

package/dist/tools/commands/run-site-command.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { flattenCollection } 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 } from '../shared/site-scope.js';
+import { fetchOutput, NO_OUTPUT, outputFields, outputLinesInput } from '../shared/output.js';
+import { commandOutput, commandPhase, commandsPath, formatCommand } from './shared.js';
+const CHECK_WITH = 'forge_get_site_command';
+export const runSiteCommand = defineTool({
+    name: 'forge_run_site_command',
+    title: 'Run site command',
+    description: 'Run a shell command in the site directory as the site user (e.g. `php artisan migrate --force`, `php artisan cache:clear`). It runs with the same privileges as the application: confirm commands that change data with the user. Waits for the result and returns the end of the output unless `wait` is false.',
+    toolset: 'commands',
+    operations: [
+        'organizations.servers.sites.commands.store',
+        'organizations.servers.sites.commands.index',
+        'organizations.servers.sites.commands.output.show',
+    ],
+    permissions: ['site:manage-commands', 'server:view'],
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
+    async: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        command: z.string().min(1).describe('Command to run, e.g. "php artisan migrate --force".'),
+        output_lines: outputLinesInput(100),
+        ...waitInput(120),
+    },
+    outputSchema: {
+        ...operationOutput,
+        command: commandOutput.nullable().describe('The command run once it shows up.'),
+        ...outputFields,
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const base = commandsPath(organization(args.organization), args.server, args.site);
+        const runs = async () => {
+            const response = await client.get(base, {
+                query: { filter: { command: args.command }, sort: ['-created_at'], page: { size: 100 } },
+                signal,
+            });
+            return flattenCollection(response.data).items;
+        };
+        // Forge returns no body: remember earlier runs of the same command to spot the new one.
+        const earlier = args.wait ? new Set((await runs()).map((run) => run.id)) : undefined;
+        await client.post(base, { body: { command: args.command }, signal });
+        const action = `run \`${args.command}\``;
+        if (!earlier) {
+            return {
+                structured: { status: 'queued', check_with: 'forge_list_site_commands', command: null, ...NO_OUTPUT },
+                summary: `Forge queued ${action}. Find it with forge_list_site_commands, then read its output with ${CHECK_WITH}.`,
+            };
+        }
+        const result = await waitFor({
+            poll: async () => (await runs()).find((run) => !earlier.has(run.id)) ?? null,
+            phase: (run) => (run ? commandPhase(run) : 'pending'),
+            describe: (run) => (run ? `Command is ${run.status}` : 'Waiting for the command to start'),
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const command = result.value ? formatCommand(result.value) : null;
+        const finished = command && (result.status === 'completed' || result.status === 'failed');
+        const output = finished ? await fetchOutput(client, `${base}/${encodeURIComponent(command.id)}`, args.output_lines, signal) : NO_OUTPUT;
+        const done = outcome(result, {
+            action,
+            checkWith: CHECK_WITH,
+            timeoutSeconds: args.timeout_seconds,
+            detail: command
+                ? `Command ID: ${command.id}${command.exit_code === null ? '' : `, exit code ${command.exit_code}`}.${command.error_output ? ` Error: ${command.error_output}` : ''}`
+                : undefined,
+        });
+        return { structured: { ...done.structured, command, ...output }, summary: done.summary };
+    },
+});

package/dist/tools/commands/shared.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { phaseOf } from '../shared/async.js';
+import { idInput, pick } from '../shared/schemas.js';
+import { sitePath } from '../shared/site-scope.js';
+export const COMMAND_STATUSES = ['waiting', 'running', 'finished', 'timeout', 'failed'];
+export function commandsPath(org, server, site) {
+    return `${sitePath(org, server, site)}/commands`;
+}
+export const commandInput = idInput('Command run ID. Use forge_list_site_commands to find it.');
+const FIELDS = ['id', 'command', 'status', 'exit_code', 'error_output', 'duration', 'user_id', 'created_at', 'updated_at'];
+export const commandOutput = z.looseObject({
+    id: z.string(),
+    command: z.string().nullable(),
+    status: z.string().nullable().describe('waiting, running, finished, timeout or failed.'),
+    exit_code: z.number().nullable().describe('Null while running, or when the command never produced one (SSH failure, timeout).'),
+    error_output: z.string().nullable().describe('Failure detail when the command did not succeed.'),
+    duration: z.string().nullable(),
+    user_id: z.number().nullable().describe('User who ran the command.'),
+    created_at: z.string().nullable(),
+    updated_at: z.string().nullable(),
+});
+export function formatCommand(flat) {
+    return pick(flat, FIELDS);
+}
+/** Finished with a non-zero exit code counts as a failure. */
+export function commandPhase(command) {
+    const phase = phaseOf(command.status, { completed: ['finished'], failed: ['failed', 'timeout'] });
+    if (phase === 'completed' && typeof command.exit_code === 'number' && command.exit_code !== 0)
+        return 'failed';
+    return phase;
+}

package/dist/tools/integrations/disable-site-integration.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput } from '../shared/site-scope.js';
+import { describeIntegration, integrationOperation, integrationOutput, integrationPath, readIntegration } from './shared.js';
+const CHECK_WITH = 'forge_get_site_integrations';
+/** Inertia SSR has no disable endpoint in the API. */
+const DISABLEABLE = ['horizon', 'octane', 'reverb', 'pulse', 'scheduler', 'maintenance'];
+export const disableSiteIntegration = defineTool({
+    name: 'forge_disable_site_integration',
+    title: 'Disable site integration',
+    description: 'Disable a Laravel integration on a site: horizon, octane, reverb or pulse (removes their daemon: queues or servers stop), scheduler (removes the scheduled job) or maintenance (brings the site back up). Inertia SSR cannot be disabled through the API. Waits until it is disabled unless `wait` is false.',
+    toolset: 'integrations',
+    operations: [...DISABLEABLE.map((name) => integrationOperation(name, 'destroy')), ...DISABLEABLE.map((name) => integrationOperation(name, 'show'))],
+    permissions: ['server:delete-daemons', 'server:delete-schedulers', 'site:manage-commands', 'server:view'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        integration: z.enum(DISABLEABLE).describe('Integration to disable.'),
+        ...waitInput(90),
+    },
+    outputSchema: {
+        ...operationOutput,
+        integration: integrationOutput.nullable().describe('State after the wait.'),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = integrationPath(organization(args.organization), args.server, args.site, args.integration);
+        await client.delete(path, { signal });
+        const action = `disable ${args.integration}`;
+        if (!args.wait) {
+            const accepted = queued(action, CHECK_WITH);
+            return { ...accepted, structured: { ...accepted.structured, integration: null } };
+        }
+        const result = await waitFor({
+            poll: () => readIntegration(client, path, args.integration, signal),
+            phase: (state) => (state.enabled === false && state.status !== 'disabling' ? 'completed' : 'pending'),
+            describe: describeIntegration,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const done = outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+        return { structured: { ...done.structured, integration: result.value ?? null }, summary: done.summary };
+    },
+});

package/dist/tools/integrations/enable-site-integration.js

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { ToolInputError } from '../errors.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput } from '../shared/site-scope.js';
+import { describeIntegration, INTEGRATION_NAMES, INTEGRATIONS_DESCRIPTION, integrationOperation, integrationOutput, integrationPath, readIntegration, } from './shared.js';
+const CHECK_WITH = 'forge_get_site_integrations';
+const TRANSITIONS = ['enabling', 'disabling'];
+/** Inputs each integration accepts; any other integration-specific input is rejected. */
+const ALLOWED = {
+    horizon: [],
+    octane: ['octane_server', 'port'],
+    reverb: ['host', 'port', 'connections'],
+    pulse: [],
+    inertia: [],
+    scheduler: [],
+    maintenance: ['maintenance_status', 'maintenance_secret', 'maintenance_redirect'],
+};
+const SPECIFIC = ['octane_server', 'port', 'host', 'connections', 'maintenance_status', 'maintenance_secret', 'maintenance_redirect'];
+export const enableSiteIntegration = defineTool({
+    name: 'forge_enable_site_integration',
+    title: 'Enable site integration',
+    description: `Enable a Laravel integration on a site: ${INTEGRATIONS_DESCRIPTION} Forge creates the daemon or scheduled job it needs. Octane needs \`octane_server\` and \`port\`; Reverb needs \`host\`, \`port\` and \`connections\`; maintenance mode accepts a bypass secret and a redirect. Waits until the integration is enabled unless \`wait\` is false.`,
+    toolset: 'integrations',
+    operations: [...INTEGRATION_NAMES.map((name) => integrationOperation(name, 'store')), ...INTEGRATION_NAMES.map((name) => integrationOperation(name, 'show'))],
+    permissions: ['server:create-daemons', 'server:create-schedulers', 'site:manage-commands', 'server:view'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    async: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        integration: z.enum(INTEGRATION_NAMES).describe('Integration to enable.'),
+        octane_server: z.enum(['swoole', 'roadrunner', 'frankenphp']).optional().describe('Octane only: application server.'),
+        port: z.number().int().min(1).max(65535).optional().describe('Octane and Reverb: port the server listens on, e.g. 8000 or 8080.'),
+        host: z.string().min(1).optional().describe('Reverb only: public host name of the WebSocket server, e.g. "ws.example.com".'),
+        connections: z.number().int().min(1).max(50000).optional().describe('Reverb only: maximum concurrent connections.'),
+        maintenance_status: z
+            .union([z.literal(503), z.literal(410), z.literal(307), z.literal(304)])
+            .optional()
+            .describe('Maintenance only: HTTP status returned while down (default 503).'),
+        maintenance_secret: z.string().min(1).optional().describe('Maintenance only: secret path that bypasses maintenance mode (https://site/{secret}).'),
+        maintenance_redirect: z.string().min(1).optional().describe('Maintenance only: path or URL every request is redirected to.'),
+        ...waitInput(90),
+    },
+    outputSchema: {
+        ...operationOutput,
+        integration: integrationOutput.nullable().describe('State after the wait.'),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const { integration } = args;
+        const unexpected = SPECIFIC.filter((field) => args[field] !== undefined && !ALLOWED[integration].includes(field));
+        if (unexpected.length > 0)
+            throw new ToolInputError(`${unexpected.map((f) => `\`${f}\``).join(', ')} not used by ${integration}.`);
+        let body;
+        if (integration === 'octane') {
+            if (!args.octane_server || args.port === undefined)
+                throw new ToolInputError('Octane needs `octane_server` and `port`.');
+            body = { server: args.octane_server, port: String(args.port) };
+        }
+        else if (integration === 'reverb') {
+            if (!args.host || args.port === undefined || args.connections === undefined) {
+                throw new ToolInputError('Reverb needs `host`, `port` and `connections`.');
+            }
+            body = { host: args.host, port: String(args.port), connections: args.connections };
+        }
+        else if (integration === 'maintenance') {
+            body = { status: args.maintenance_status ?? 503, secret: args.maintenance_secret, redirect: args.maintenance_redirect };
+        }
+        const path = integrationPath(organization(args.organization), args.server, args.site, integration);
+        await client.post(path, { body, signal });
+        const action = `enable ${integration}`;
+        if (!args.wait) {
+            const accepted = queued(action, CHECK_WITH);
+            return { ...accepted, structured: { ...accepted.structured, integration: null } };
+        }
+        const result = await waitFor({
+            poll: () => readIntegration(client, path, integration, signal),
+            phase: (state) => (state.enabled === true && !TRANSITIONS.includes(state.status ?? '') ? 'completed' : 'pending'),
+            describe: describeIntegration,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const done = outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+        return { structured: { ...done.structured, integration: result.value ?? null }, summary: done.summary };
+    },
+});

package/dist/tools/integrations/get-site-integrations.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput } from '../shared/site-scope.js';
+import { describeIntegration, INTEGRATION_NAMES, INTEGRATIONS_DESCRIPTION, integrationOperation, integrationOutput, integrationPath, readIntegration } from './shared.js';
+export const getSiteIntegrations = defineTool({
+    name: 'forge_get_site_integrations',
+    title: 'Get site integrations',
+    description: `Show which Laravel integrations are enabled on a site: ${INTEGRATIONS_DESCRIPTION} Pass \`integration\` to read only one.`,
+    toolset: 'integrations',
+    operations: INTEGRATION_NAMES.map((name) => integrationOperation(name, 'show')),
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        integration: z.enum(INTEGRATION_NAMES).optional().describe('Read only this integration (default: all of them).'),
+    },
+    outputSchema: {
+        integrations: z.array(integrationOutput),
+    },
+    async handler(args, { client, organization, signal }) {
+        const org = organization(args.organization);
+        const names = args.integration ? [args.integration] : INTEGRATION_NAMES;
+        const integrations = await Promise.all(names.map((name) => readIntegration(client, integrationPath(org, args.server, args.site, name), name, signal)));
+        const enabled = integrations.filter((state) => state.enabled).map((state) => state.integration);
+        return {
+            structured: { integrations },
+            summary: args.integration
+                ? `${describeIntegration(integrations[0])}.`
+                : enabled.length === 0
+                    ? 'No integrations are enabled on this site.'
+                    : `Enabled integrations: ${enabled.join(', ')}.`,
+        };
+    },
+});

package/dist/tools/integrations/shared.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { relatedId } from '../shared/relationships.js';
+import { readResource } from '../shared/read.js';
+import { sitePath } from '../shared/site-scope.js';
+/** Integration name → API path segment and fields of its resource. */
+export const INTEGRATIONS = {
+    horizon: { segment: 'horizon', installed: 'horizon_installed', settings: [] },
+    octane: { segment: 'octane', installed: 'octane_installed', settings: ['port'] },
+    reverb: { segment: 'reverb', installed: 'reverb_installed', settings: ['host', 'port', 'connections'] },
+    pulse: { segment: 'pulse', installed: 'pulse_installed', settings: [] },
+    inertia: { segment: 'inertia', installed: 'inertia_installed', settings: [] },
+    scheduler: { segment: 'laravel-scheduler', installed: 'laravel_installed', settings: [] },
+    maintenance: { segment: 'laravel-maintenance', installed: 'laravel_installed', settings: [] },
+};
+export const INTEGRATION_NAMES = Object.keys(INTEGRATIONS);
+export const INTEGRATIONS_DESCRIPTION = 'horizon (queue dashboard and workers), octane (application server), reverb (WebSocket server), pulse (monitoring), inertia (SSR server), scheduler (runs `schedule:run` every minute), maintenance (Laravel maintenance mode).';
+/** OperationId of an integration endpoint, e.g. "organizations.servers.sites.integrations.horizon.store". */
+export function integrationOperation(integration, verb) {
+    return `organizations.servers.sites.integrations.${INTEGRATIONS[integration].segment}.${verb}`;
+}
+export function integrationPath(org, server, site, integration) {
+    return `${sitePath(org, server, site)}/integrations/${INTEGRATIONS[integration].segment}`;
+}
+export const integrationOutput = z.looseObject({
+    integration: z.enum(INTEGRATION_NAMES),
+    enabled: z.boolean().nullable().describe('Whether the integration is enabled on the site.'),
+    status: z.string().nullable().describe('Transition in progress (maintenance: enabling or disabling), or the raw state when Forge reports one.'),
+    package_installed: z.boolean().nullable().describe('Whether the Laravel package (or Laravel itself) is installed in the site.'),
+    settings: z.record(z.string(), z.unknown()).describe('Port, host, connections (Octane and Reverb).'),
+    background_process_id: z.string().nullable().describe('Daemon running the integration (Horizon, Octane, Reverb, Pulse, Inertia).'),
+    scheduled_job_id: z.string().nullable().describe('Scheduled job running the scheduler.'),
+});
+const TRUE = new Set(['true', '1', 'yes', 'enabled', 'on', 'active', 'installed']);
+const FALSE = new Set(['false', '0', 'no', 'disabled', 'off', 'inactive', '']);
+/** Some integrations report `enabled` as a string: normalize it, keeping unknown values as the status. */
+export function formatIntegration(integration, flat) {
+    const raw = flat.enabled;
+    let enabled = null;
+    let status = typeof flat.status === 'string' ? flat.status : null;
+    if (typeof raw === 'boolean')
+        enabled = raw;
+    else if (typeof raw === 'number')
+        enabled = raw !== 0;
+    else if (typeof raw === 'string') {
+        const value = raw.trim().toLowerCase();
+        if (TRUE.has(value))
+            enabled = true;
+        else if (FALSE.has(value))
+            enabled = false;
+        else
+            status ??= raw;
+    }
+    const { installed, settings } = INTEGRATIONS[integration];
+    return {
+        integration,
+        enabled,
+        status,
+        package_installed: typeof flat[installed] === 'boolean' ? flat[installed] : null,
+        settings: Object.fromEntries(settings.map((key) => [key, flat[key] ?? null])),
+        background_process_id: relatedId(flat, 'backgroundProcess'),
+        scheduled_job_id: relatedId(flat, 'job'),
+    };
+}
+export async function readIntegration(client, path, integration, signal) {
+    return formatIntegration(integration, await readResource(client, path, signal));
+}
+export function describeIntegration(state) {
+    return `${state.integration} is ${state.status ?? (state.enabled === null ? 'in an unknown state' : state.enabled ? 'enabled' : 'disabled')}`;
+}

package/dist/tools/registry.js

@@ -1,3 +1,9 @@
+import { createBackgroundProcess } from './background-processes/create-background-process.js';
+import { deleteBackgroundProcess } from './background-processes/delete-background-process.js';
+import { getBackgroundProcessLog } from './background-processes/get-background-process-log.js';
+import { listBackgroundProcesses } from './background-processes/list-background-processes.js';
+import { runBackgroundProcessAction } from './background-processes/run-background-process-action.js';
+import { updateBackgroundProcess } from './background-processes/update-background-process.js';
 import { createBackup } from './backups/create-backup.js';
 import { createBackupConfiguration } from './backups/create-backup-configuration.js';
 import { deleteBackup } from './backups/delete-backup.js';
@@ -11,6 +17,10 @@ import { deleteCertificate } from './certificates/delete-certificate.js';
 import { getCertificate } from './certificates/get-certificate.js';
 import { listCertificates } from './certificates/list-certificates.js';
 import { runCertificateAction } from './certificates/run-certificate-action.js';
+import { deleteSiteCommand } from './commands/delete-site-command.js';
+import { getSiteCommand } from './commands/get-site-command.js';
+import { listSiteCommands } from './commands/list-site-commands.js';
+import { runSiteCommand } from './commands/run-site-command.js';
 import { createDatabase } from './databases/create-database.js';
 import { createDatabaseUser } from './databases/create-database-user.js';
 import { deleteDatabase } from './databases/delete-database.js';
@@ -44,6 +54,9 @@ import { runDomainAction } from './domains/run-domain-action.js';
 import { updateDomain } from './domains/update-domain.js';
 import { getServerEvent } from './events/get-server-event.js';
 import { listServerEvents } from './events/list-server-events.js';
+import { disableSiteIntegration } from './integrations/disable-site-integration.js';
+import { enableSiteIntegration } from './integrations/enable-site-integration.js';
+import { getSiteIntegrations } from './integrations/get-site-integrations.js';
 import { listOrganizations } from './organizations/list-organizations.js';
 import { getPhpConfig } from './php/get-php-config.js';
 import { getPhpSettings } from './php/get-php-settings.js';
@@ -55,6 +68,10 @@ import { uninstallPhpVersion } from './php/uninstall-php-version.js';
 import { updatePhpConfig } from './php/update-php-config.js';
 import { updatePhpLimits } from './php/update-php-limits.js';
 import { upgradePhpVersion } from './php/upgrade-php-version.js';
+import { createScheduledJob } from './scheduled-jobs/create-scheduled-job.js';
+import { deleteScheduledJob } from './scheduled-jobs/delete-scheduled-job.js';
+import { getScheduledJob } from './scheduled-jobs/get-scheduled-job.js';
+import { listScheduledJobs } from './scheduled-jobs/list-scheduled-jobs.js';
 import { archiveServer } from './servers/archive-server.js';
 import { clearServerLog } from './servers/clear-server-log.js';
 import { deleteServer } from './servers/delete-server.js';
@@ -189,6 +206,26 @@ export const ALL_TOOLS = [
     getDeployKey,
     createDeployKey,
     deleteDeployKey,
+    // jobs
+    listScheduledJobs,
+    getScheduledJob,
+    createScheduledJob,
+    deleteScheduledJob,
+    listBackgroundProcesses,
+    getBackgroundProcessLog,
+    createBackgroundProcess,
+    updateBackgroundProcess,
+    runBackgroundProcessAction,
+    deleteBackgroundProcess,
+    // integrations
+    getSiteIntegrations,
+    enableSiteIntegration,
+    disableSiteIntegration,
+    // commands
+    runSiteCommand,
+    listSiteCommands,
+    getSiteCommand,
+    deleteSiteCommand,
 ];
 /** Tools enabled by the configuration (toolsets, read-only mode, secrets opt-in). */
 export function selectTools(config, tools = ALL_TOOLS) {

package/dist/tools/scheduled-jobs/create-scheduled-job.js

@@ -0,0 +1,83 @@
+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 { readResource } from '../shared/read.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { SITE_NOT_FOUND_HINT } from '../shared/site-scope.js';
+import { CRON_FREQUENCIES, formatScheduledJob, jobSiteInput, scheduledJobOperations, scheduledJobOutput, scheduledJobPhase, scheduledJobsPath, } from './shared.js';
+const CHECK_WITH = 'forge_list_scheduled_jobs';
+export const createScheduledJob = defineTool({
+    name: 'forge_create_scheduled_job',
+    title: 'Create scheduled job',
+    description: 'Schedule a command (cron) on a server, or for a site with `site`. For the Laravel scheduler prefer forge_enable_site_integration with integration "scheduler". Optionally creates a heartbeat that alerts when the job stops running. Waits until it is installed unless `wait` is false.',
+    toolset: 'jobs',
+    operations: [...scheduledJobOperations('store'), ...scheduledJobOperations('show')],
+    permissions: ['server:view'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    async: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        site: jobSiteInput,
+        command: z.string().min(1).describe('Command to run, e.g. "php /home/forge/example.com/current/artisan reports:send".'),
+        frequency: z.enum(CRON_FREQUENCIES).describe('How often it runs; "custom" needs `cron`, "reboot" runs at boot.'),
+        cron: z.string().min(1).optional().describe('Custom frequency only: cron expression, e.g. "*/15 * * * *".'),
+        user: z.string().min(1).default('forge').describe('User the job runs as.'),
+        name: z.string().min(1).optional().describe('Name of the job.'),
+        heartbeat: z.boolean().optional().describe('Create a heartbeat that alerts when the job does not run.'),
+        grace_period: z
+            .union([z.literal(1), z.literal(2), z.literal(5), z.literal(10), z.literal(30), z.literal(60)])
+            .optional()
+            .describe('Heartbeat only: minutes of delay tolerated before alerting.'),
+        ...waitInput(60),
+    },
+    outputSchema: {
+        ...operationOutput,
+        job: scheduledJobOutput.nullable(),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        if (args.frequency === 'custom' && !args.cron)
+            throw new ToolInputError('A custom frequency needs a `cron` expression.');
+        if (args.frequency !== 'custom' && args.cron)
+            throw new ToolInputError('`cron` is only used with frequency "custom".');
+        if (args.grace_period !== undefined && !args.heartbeat)
+            throw new ToolInputError('`grace_period` is only used with `heartbeat: true`.');
+        const base = scheduledJobsPath(organization(args.organization), args.server, args.site);
+        const response = await client.post(base, {
+            body: {
+                name: args.name,
+                command: args.command,
+                user: args.user,
+                frequency: args.frequency,
+                cron: args.cron,
+                heartbeat: args.heartbeat,
+                grace_period: args.grace_period,
+            },
+            signal,
+        });
+        const initial = response.data?.data ? flattenSingle(response.data) : undefined;
+        const action = `schedule \`${args.command}\``;
+        if (!initial || !args.wait) {
+            return {
+                structured: { status: 'queued', check_with: CHECK_WITH, job: initial ? formatScheduledJob(initial) : null },
+                summary: `Forge accepted the request to ${action}. Check it with ${CHECK_WITH}.`,
+            };
+        }
+        const result = await waitFor({
+            initial,
+            poll: () => readResource(client, `${base}/${encodeURIComponent(initial.id)}`, signal),
+            phase: (job) => scheduledJobPhase(job.status),
+            describe: (job) => `Scheduled job is ${job.status}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const job = formatScheduledJob(result.value ?? initial);
+        const done = outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds, detail: `Job ID: ${job.id}.` });
+        return { structured: { ...done.structured, job }, summary: done.summary };
+    },
+});

package/dist/tools/scheduled-jobs/delete-scheduled-job.js

@@ -0,0 +1,42 @@
+import { defineTool } from '../define-tool.js';
+import { operationOutput, orGone, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { JOB_NOT_FOUND_HINT, jobInput, jobSiteInput, scheduledJobOperations, scheduledJobPath } from './shared.js';
+const CHECK_WITH = 'forge_list_scheduled_jobs';
+export const deleteScheduledJob = defineTool({
+    name: 'forge_delete_scheduled_job',
+    title: 'Delete scheduled job',
+    description: 'Remove a scheduled job from a server (or site, with `site`): the command stops running.',
+    toolset: 'jobs',
+    operations: [...scheduledJobOperations('destroy'), ...scheduledJobOperations('show')],
+    permissions: ['server:view'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: JOB_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        site: jobSiteInput,
+        job: jobInput,
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = scheduledJobPath(organization(args.organization), args.server, args.site, args.job);
+        await client.delete(path, { signal });
+        const action = `delete scheduled job ${args.job}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(() => readResource(client, path, signal)),
+            phase: (job) => (job === null ? 'completed' : 'pending'),
+            describe: (job) => `Scheduled job is ${job?.status ?? 'removing'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/scheduled-jobs/get-scheduled-job.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { fetchOutput, NO_OUTPUT, outputFields, outputLinesInput } from '../shared/output.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { formatScheduledJob, JOB_NOT_FOUND_HINT, jobInput, jobSiteInput, scheduledJobOperations, scheduledJobOutput, scheduledJobPath, } from './shared.js';
+export const getScheduledJob = defineTool({
+    name: 'forge_get_scheduled_job',
+    title: 'Get scheduled job',
+    description: 'Get a scheduled job with the end of the output of its last run. Pass `site` for jobs that belong to a site.',
+    toolset: 'jobs',
+    operations: [...scheduledJobOperations('show'), ...scheduledJobOperations('outputs.show')],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: JOB_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        site: jobSiteInput,
+        job: jobInput,
+        include_output: z.boolean().default(true).describe('Also fetch the output of the last run.'),
+        output_lines: outputLinesInput(100),
+    },
+    outputSchema: {
+        job: scheduledJobOutput,
+        ...outputFields,
+    },
+    async handler(args, { client, organization, signal }) {
+        const path = scheduledJobPath(organization(args.organization), args.server, args.site, args.job);
+        const [job, output] = await Promise.all([
+            readResource(client, path, signal).then(formatScheduledJob),
+            args.include_output ? fetchOutput(client, path, args.output_lines, signal) : Promise.resolve(NO_OUTPUT),
+        ]);
+        return {
+            structured: { job, ...output },
+            summary: `\`${job.command}\` runs ${job.frequency} (${job.cron}) as ${job.user}; next run: ${job.next_run_time}.`,
+        };
+    },
+});

package/dist/tools/scheduled-jobs/list-scheduled-jobs.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { organizationInput, paginationInput, paginationOutput, paginationSummary, serverInput } from '../shared/schemas.js';
+import { SITE_NOT_FOUND_HINT } from '../shared/site-scope.js';
+import { formatScheduledJob, jobSiteInput, scheduledJobOperations, scheduledJobOutput, scheduledJobsPath } from './shared.js';
+const SORT = ['created_at', '-created_at', 'updated_at', '-updated_at', 'status', '-status'];
+export const listScheduledJobs = defineTool({
+    name: 'forge_list_scheduled_jobs',
+    title: 'List scheduled jobs',
+    description: 'List the scheduled jobs (cron) of a server, or of one site with `site`: command, user, frequency, next run. Read the output of the last run with forge_get_scheduled_job.',
+    toolset: 'jobs',
+    operations: scheduledJobOperations('index'),
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        site: jobSiteInput,
+        status: z.string().min(1).optional().describe('Filter by status, e.g. "installed".'),
+        user: z.string().min(1).optional().describe('Filter by the user the job runs as.'),
+        sort: z.array(z.enum(SORT)).min(1).optional(),
+        ...paginationInput,
+    },
+    outputSchema: {
+        jobs: z.array(scheduledJobOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const response = await client.get(scheduledJobsPath(organization(args.organization), args.server, args.site), {
+            query: { filter: { status: args.status, user: args.user }, sort: args.sort, page: { size: args.page_size, cursor: args.cursor } },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const jobs = page.items.map(formatScheduledJob);
+        return {
+            structured: { jobs, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: jobs.length === 0
+                ? 'No scheduled jobs found.'
+                : `Found ${jobs.length} scheduled job(s): ${jobs.map((job) => `\`${job.command}\` (${job.id}, ${job.frequency})`).join(', ')}.${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

package/dist/tools/scheduled-jobs/shared.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { phaseOf } from '../shared/async.js';
+import { idInput, pick, siteInput } from '../shared/schemas.js';
+import { sitePath } from '../shared/site-scope.js';
+import { serverPath } from '../servers/shared.js';
+export const CRON_FREQUENCIES = ['minutely', 'hourly', 'nightly', 'weekly', 'monthly', 'reboot', 'custom'];
+/** Scheduled jobs exist on servers and on sites: the same endpoints with or without the site segment. */
+export function scheduledJobsPath(org, server, site) {
+    return `${site === undefined ? serverPath(org, server) : sitePath(org, server, site)}/scheduled-jobs`;
+}
+export function scheduledJobPath(org, server, site, job) {
+    return `${scheduledJobsPath(org, server, site)}/${encodeURIComponent(String(job))}`;
+}
+/** OperationIds of an endpoint at both levels, e.g. "organizations.servers.scheduled-jobs.show" and the site one. */
+export function scheduledJobOperations(suffix) {
+    return [`organizations.servers.scheduled-jobs.${suffix}`, `organizations.servers.sites.scheduled-jobs.${suffix}`];
+}
+export const jobSiteInput = siteInput
+    .optional()
+    .describe('Site ID for jobs that belong to a site; omit for server-level jobs. Use forge_list_sites to find it.');
+export const jobInput = idInput('Scheduled job ID. Use forge_list_scheduled_jobs to find it.');
+export const JOB_NOT_FOUND_HINT = 'Check the job ID with forge_list_scheduled_jobs, using the same server and (for site jobs) site.';
+const FIELDS = ['id', 'name', 'command', 'user', 'frequency', 'cron', 'status', 'next_run_time', 'created_at', 'updated_at'];
+export const scheduledJobOutput = z.looseObject({
+    id: z.string(),
+    name: z.string().nullable(),
+    command: z.string().nullable(),
+    user: z.string().nullable(),
+    frequency: z.string().nullable(),
+    cron: z.string().nullable().describe('Cron expression the job runs on.'),
+    status: z.string().nullable().describe('e.g. installing, installed, removing.'),
+    next_run_time: z.string().nullable(),
+    created_at: z.string().nullable(),
+    updated_at: z.string().nullable(),
+});
+export function formatScheduledJob(flat) {
+    return pick(flat, FIELDS);
+}
+export function scheduledJobPhase(status) {
+    return phaseOf(status, { pending: ['installing', 'removing', 'updating'], failed: ['failed'] });
+}

package/dist/tools/shared/output.js

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+import { ForgeApiError } from '../../forge/errors.js';
+import { readResource } from './read.js';
+import { tail } from './schemas.js';
+/** Output of a command or scheduled job run, read from `{path}/output`. */
+export const outputLinesInput = (fallback) => z.number().int().min(0).max(5000).default(fallback).describe('Return only the last N lines of the output (0 = full output).');
+export const outputFields = {
+    output: z.string().nullable().describe('Output (last `output_lines` lines), or null when there is none yet.'),
+    output_truncated: z.boolean(),
+    output_total_lines: z.number().int().nullable(),
+};
+export const NO_OUTPUT = { output: null, output_truncated: false, output_total_lines: null };
+export async function fetchOutput(client, path, lines, signal) {
+    try {
+        const output = tail((await readResource(client, `${path}/output`, signal)).output, lines);
+        return { output: output.text, output_truncated: output.truncated, output_total_lines: output.total_lines };
+    }
+    catch (error) {
+        if (error instanceof ForgeApiError && error.status === 404)
+            return NO_OUTPUT;
+        throw error;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@francescomalatesta/laravel-forge-mcp",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Unofficial Model Context Protocol (MCP) server for the Laravel Forge API",
   "keywords": [
     "mcp",