@francescomalatesta/laravel-forge-mcp 0.9.0 → 0.10.0

package/README.md

@@ -164,9 +164,18 @@ 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_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/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,36 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { readResource } from '../shared/read.js';
+import { siteScopeInput } from '../shared/site-scope.js';
+import { commandInput, commandOutput, commandsPath, fetchOutput, formatCommand, NO_OUTPUT, outputFields, outputLinesInput } 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,74 @@
+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 { commandOutput, commandPhase, commandsPath, fetchOutput, formatCommand, NO_OUTPUT, outputFields, outputLinesInput } 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,52 @@
+import { z } from 'zod';
+import { ForgeApiError } from '../../forge/errors.js';
+import { phaseOf } from '../shared/async.js';
+import { readResource } from '../shared/read.js';
+import { idInput, pick, tail } 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;
+}
+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('Command output (last `output_lines` lines), or null when unavailable.'),
+    output_truncated: z.boolean(),
+    output_total_lines: z.number().int().nullable(),
+};
+export const NO_OUTPUT = { output: null, output_truncated: false, output_total_lines: null };
+/** Reads the output of a command run; null output when there is none yet. */
+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/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

@@ -11,6 +11,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 +48,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';
@@ -189,6 +196,15 @@ export const ALL_TOOLS = [
     getDeployKey,
     createDeployKey,
     deleteDeployKey,
+    // 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/package.json

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