@francescomalatesta/laravel-forge-mcp 0.5.0 → 0.7.0

package/README.md

@@ -106,6 +106,27 @@ npm run build
 | `forge_create_certificate` | sites | Let's Encrypt, existing, CSR or cloned certificate, waiting until installed |
 | `forge_run_certificate_action` | sites | Activate or deactivate a certificate |
 | `forge_delete_certificate` | sites | Delete a certificate |
+| `forge_run_service_action` | servers | Restart or stop Nginx, MySQL, Postgres, Redis, Supervisor; restart or reload PHP-FPM |
+| `forge_run_server_action` | servers | Reboot or power-cycle a server |
+| `forge_get_server_log` | servers | End of a server log (Nginx, PHP-FPM, MySQL, cron, daemons) |
+| `forge_clear_server_log` | servers | Empty a server log |
+| `forge_update_server` | servers | Rename, change IP addresses, timezone or tags |
+| `forge_get_server_network` | servers | Servers that can reach each other on the private network |
+| `forge_update_server_network` | servers | Set the server network |
+| `forge_list_archived_servers` | servers | Archived servers |
+| `forge_archive_server` | servers | Archive a server (Forge stops managing it) |
+| `forge_unarchive_server` | servers | Restore an archived server |
+| `forge_delete_server` | servers | Delete a server (optionally keeping it at the provider) |
+| `forge_list_php_versions` | servers | Installed PHP versions |
+| `forge_get_php_settings` | servers | Default CLI and site versions, upload and execution limits, OPcache |
+| `forge_install_php_version` | servers | Install a PHP version (optionally as default) and wait until installed |
+| `forge_upgrade_php_version` | servers | Update a PHP version to its latest patch release |
+| `forge_uninstall_php_version` | servers | Uninstall a PHP version |
+| `forge_set_default_php_version` | servers | Default PHP version for the CLI or for new sites |
+| `forge_update_php_limits` | servers | Max upload size and max execution time |
+| `forge_set_php_opcache` | servers | Enable or disable OPcache |
+| `forge_get_php_config` | servers | FPM or CLI php.ini, or the FPM pool configuration |
+| `forge_update_php_config` | servers | Replace a PHP configuration file |
 | `forge_list_deployments` | deployments | Deployments of a site or of every site on a server |
 | `forge_get_deployment` | deployments | A deployment with the end of its log |
 | `forge_get_deployment_status` | deployments | Whether a deployment is running |

package/dist/tools/php/config-files.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+export const phpConfigInput = z
+    .enum(['fpm', 'cli', 'pool'])
+    .describe('"fpm": php.ini used by PHP-FPM (web requests); "cli": php.ini of the `php` command; "pool": PHP-FPM pool configuration (workers, user).');
+export const poolUserInput = z
+    .string()
+    .min(1)
+    .optional()
+    .describe('Pool only: the Linux user of an isolated site\'s pool (default: the "forge" pool).');
+export async function readPhpConfig(client, path, user, signal) {
+    const response = await client.get(path, { query: { user }, signal });
+    return flattenSingle(response.data).configuration ?? '';
+}

package/dist/tools/php/get-php-config.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { phpConfigInput, poolUserInput, readPhpConfig } from './config-files.js';
+import { phpVersionRefInput, phpVersionsPath, resolvePhpVersionId } from './shared.js';
+export const getPhpConfig = defineTool({
+    name: 'forge_get_php_config',
+    title: 'Get PHP configuration file',
+    description: 'Read a configuration file of an installed PHP version: the FPM or CLI php.ini, or the PHP-FPM pool configuration.',
+    toolset: 'servers',
+    operations: [
+        'organizations.servers.php.versions.configs.fpm.show',
+        'organizations.servers.php.versions.configs.cli.show',
+        'organizations.servers.php.versions.configs.pool.show',
+        'organizations.servers.php.versions.index',
+    ],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        php_version: phpVersionRefInput,
+        config: phpConfigInput,
+        user: poolUserInput,
+    },
+    outputSchema: {
+        content: z.string().describe('Content of the configuration file.'),
+    },
+    async handler(args, { client, organization, signal }) {
+        const org = organization(args.organization);
+        const id = await resolvePhpVersionId(client, org, args.server, args.php_version, signal);
+        const path = `${phpVersionsPath(org, args.server)}/${encodeURIComponent(id)}/configs/${args.config}`;
+        const content = await readPhpConfig(client, path, args.config === 'pool' ? args.user : undefined, signal);
+        return { structured: { content }, summary: `The ${args.config} configuration has ${content.trimEnd().split('\n').length} line(s).` };
+    },
+});

package/dist/tools/php/get-php-settings.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { readPhpSetting } from './settings.js';
+export const getPhpSettings = defineTool({
+    name: 'forge_get_php_settings',
+    title: 'Get PHP settings',
+    description: "Get a server's PHP settings in one call: default CLI version, default version for new sites, max upload size, max execution time and whether OPcache is enabled.",
+    toolset: 'servers',
+    operations: [
+        'organizations.servers.php.cli-version.show',
+        'organizations.servers.php.site-version.show',
+        'organizations.servers.php.max-upload-size.show',
+        'organizations.servers.php.max-execution-time.show',
+        'organizations.servers.php.opcache.show',
+    ],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+    },
+    outputSchema: {
+        cli_version: z.string().nullable().describe('Version used by the `php` command, e.g. "8.3".'),
+        site_version: z.string().nullable().describe('Default version for new sites.'),
+        max_upload_size: z.number().nullable().describe('Max upload size in MB.'),
+        max_execution_time: z.number().nullable().describe('Max execution time in seconds.'),
+        opcache_enabled: z.boolean().nullable(),
+    },
+    async handler(args, { client, organization, signal }) {
+        const org = organization(args.organization);
+        const read = (name) => readPhpSetting(client, org, args.server, name, signal);
+        const [cli, site, upload, execution, opcache] = await Promise.all([
+            read('cli-version'),
+            read('site-version'),
+            read('max-upload-size'),
+            read('max-execution-time'),
+            read('opcache'),
+        ]);
+        const settings = {
+            cli_version: cli.version ?? null,
+            site_version: site.version ?? null,
+            max_upload_size: upload.max_upload_size ?? null,
+            max_execution_time: execution.max_execution_time ?? null,
+            opcache_enabled: opcache.opcache_enabled ?? null,
+        };
+        return {
+            structured: settings,
+            summary: `PHP CLI ${settings.cli_version}, sites ${settings.site_version}, upload ${settings.max_upload_size} MB, execution ${settings.max_execution_time}s, OPcache ${settings.opcache_enabled ? 'on' : 'off'}.`,
+        };
+    },
+});

package/dist/tools/php/install-php-version.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { PHP_VERSIONS } from '../sites/shared.js';
+import { findPhpVersion, phpVersionOutput, phpVersionPhase, phpVersionsPath, versionNumber } from './shared.js';
+const CHECK_WITH = 'forge_list_php_versions';
+export const installPhpVersion = defineTool({
+    name: 'forge_install_php_version',
+    title: 'Install PHP version',
+    description: 'Install another PHP version on a server, optionally making it the default for the CLI and/or new sites. Waits until it is installed unless `wait` is false.',
+    toolset: 'servers',
+    operations: ['organizations.servers.php.versions.store', 'organizations.servers.php.versions.index'],
+    permissions: ['server:manage-php', 'server:view'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        version: z.enum(PHP_VERSIONS).describe('Version to install, e.g. "php84".'),
+        cli_default: z.boolean().optional().describe('Make it the version used by the `php` command.'),
+        site_default: z.boolean().optional().describe('Make it the default for new sites.'),
+        ...waitInput(300),
+    },
+    outputSchema: {
+        ...operationOutput,
+        php_version: phpVersionOutput.nullable(),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const org = organization(args.organization);
+        await client.post(phpVersionsPath(org, args.server), {
+            body: { version: args.version, cli_default: args.cli_default, site_default: args.site_default },
+            signal,
+        });
+        const action = `install ${args.version}`;
+        const number = versionNumber(args.version);
+        if (!args.wait || !number) {
+            const accepted = queued(action, CHECK_WITH);
+            return { ...accepted, structured: { ...accepted.structured, php_version: null } };
+        }
+        // Forge returns no body: follow the version once it appears in the list.
+        const result = await waitFor({
+            poll: () => findPhpVersion(client, org, args.server, number, signal).then((found) => found ?? null),
+            phase: (found) => (found ? phpVersionPhase(found.status) : 'pending'),
+            describe: (found) => `PHP ${number} is ${found?.status ?? 'queued'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const done = outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+        return { structured: { ...done.structured, php_version: result.value ?? null }, summary: done.summary };
+    },
+});

package/dist/tools/php/list-php-versions.js

@@ -0,0 +1,47 @@
+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 { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { formatPhpVersion, phpVersionOutput, phpVersionsPath } from './shared.js';
+const SORT = ['version', '-version', 'status', '-status', 'created_at', '-created_at', 'updated_at', '-updated_at'];
+export const listPhpVersions = defineTool({
+    name: 'forge_list_php_versions',
+    title: 'List PHP versions',
+    description: 'List the PHP versions installed on a server with their IDs and status. Default CLI and site versions are in forge_get_php_settings.',
+    toolset: 'servers',
+    operations: ['organizations.servers.php.versions.index'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        version: z.string().min(1).optional().describe('Filter by version, e.g. "8.3".'),
+        status: z.string().min(1).optional().describe('Filter by status, e.g. "installed".'),
+        sort: z.array(z.enum(SORT)).min(1).optional(),
+        ...paginationInput,
+    },
+    outputSchema: {
+        php_versions: z.array(phpVersionOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const response = await client.get(phpVersionsPath(organization(args.organization), args.server), {
+            query: {
+                filter: { version: args.version, status: args.status },
+                sort: args.sort,
+                page: { size: args.page_size, cursor: args.cursor },
+            },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const versions = page.items.map(formatPhpVersion);
+        return {
+            structured: { php_versions: versions, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: versions.length === 0
+                ? 'No PHP versions found.'
+                : `Installed: ${versions.map((v) => `${v.version} (${v.status}, ID ${v.id})`).join(', ')}.${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

package/dist/tools/php/set-default-php-version.js

@@ -0,0 +1,54 @@
+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 { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT, serverPath } from '../servers/shared.js';
+import { readPhpSetting } from './settings.js';
+import { versionNumber } from './shared.js';
+const CHECK_WITH = 'forge_get_php_settings';
+export const setDefaultPhpVersion = defineTool({
+    name: 'forge_set_default_php_version',
+    title: 'Set default PHP version',
+    description: 'Set the PHP version used by the `php` command on the server ("cli") or the default for new sites ("site"). The version must be installed (forge_list_php_versions). Existing sites keep their version: change it with forge_update_site.',
+    toolset: 'servers',
+    operations: [
+        'organizations.servers.php.cli-version.update',
+        'organizations.servers.php.site-version.update',
+        'organizations.servers.php.cli-version.show',
+        'organizations.servers.php.site-version.show',
+    ],
+    permissions: ['server:manage-php', 'server:view'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        target: z.enum(['cli', 'site']).describe('"cli" for the `php` command, "site" for new sites.'),
+        php_version: z.string().min(1).describe('Version, e.g. "8.3" or "php83".'),
+        ...waitInput(120),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const number = versionNumber(args.php_version);
+        if (!number)
+            throw new ToolInputError(`Unknown PHP version "${args.php_version}": use a version like "8.3".`);
+        const org = organization(args.organization);
+        const setting = args.target === 'cli' ? 'cli-version' : 'site-version';
+        await client.put(`${serverPath(org, args.server)}/php/${setting}`, { body: { php_version: number }, signal });
+        const action = `set the default ${args.target} PHP version to ${number}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: async () => (await readPhpSetting(client, org, args.server, setting, signal)).version,
+            phase: (version) => (version === number ? 'completed' : 'pending'),
+            describe: (version) => `Default ${args.target} PHP version is ${version}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/php/set-php-opcache.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT, serverPath } from '../servers/shared.js';
+import { readPhpSetting } from './settings.js';
+const CHECK_WITH = 'forge_get_php_settings';
+export const setPhpOpcache = defineTool({
+    name: 'forge_set_php_opcache',
+    title: 'Enable or disable OPcache',
+    description: 'Enable or disable PHP OPcache on the server. Enabled OPcache speeds up PHP; with it, code changes are picked up only after PHP-FPM reloads (Forge deployments reload it).',
+    toolset: 'servers',
+    operations: [
+        'organizations.servers.php.opcache.store',
+        'organizations.servers.php.opcache.destroy',
+        'organizations.servers.php.opcache.show',
+    ],
+    permissions: ['server:manage-php', 'server:view'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        enabled: z.boolean(),
+        ...waitInput(120),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const org = organization(args.organization);
+        const path = `${serverPath(org, args.server)}/php/opcache`;
+        if (args.enabled) {
+            await client.post(path, { signal });
+        }
+        else {
+            await client.delete(path, { signal });
+        }
+        const action = `${args.enabled ? 'enable' : 'disable'} OPcache`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: async () => (await readPhpSetting(client, org, args.server, 'opcache', signal)).opcache_enabled,
+            phase: (enabled) => (enabled === args.enabled ? 'completed' : 'pending'),
+            describe: () => `Waiting for OPcache to be ${args.enabled ? 'enabled' : 'disabled'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/php/settings.js

@@ -0,0 +1,7 @@
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { serverPath } from '../servers/shared.js';
+/** Reads one PHP setting endpoint (`/php/<name>`) and returns its attributes. */
+export async function readPhpSetting(client, org, server, name, signal) {
+    const response = await client.get(`${serverPath(org, server)}/php/${name}`, { signal });
+    return flattenSingle(response.data);
+}

package/dist/tools/php/shared.js

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { phaseOf } from '../shared/async.js';
+import { pick } from '../shared/schemas.js';
+import { ToolInputError } from '../errors.js';
+import { serverPath } from '../servers/shared.js';
+/** Version numbers used by the default-version endpoints, matching the install identifiers. */
+const VERSION_NUMBERS = {
+    php56: '5.6',
+    php70: '7.0',
+    php71: '7.1',
+    php72: '7.2',
+    php73: '7.3',
+    php74: '7.4',
+    php80: '8.0',
+    php81: '8.1',
+    php82: '8.2',
+    php83: '8.3',
+    php84: '8.4',
+    php85: '8.5',
+};
+export const PHP_VERSION_NUMBERS = ['5.6', '7.0', '7.1', '7.2', '7.3', '7.4', '8.0', '8.1', '8.2', '8.3', '8.4', '8.5'];
+/** "php83", "8.3", "php8.3" or "PHP 8.3" → "8.3"; undefined when not a known version. */
+export function versionNumber(value) {
+    const compact = value.trim().toLowerCase().replace(/\s+/g, '');
+    const dotted = compact.replace(/^php/, '');
+    if (PHP_VERSION_NUMBERS.includes(dotted))
+        return dotted;
+    return VERSION_NUMBERS[compact];
+}
+export const phpVersionRefInput = z
+    .union([z.number().int().nonnegative(), z.string().min(1)])
+    .describe('Installed PHP version: its ID (from forge_list_php_versions) or the version, e.g. "8.3" or "php83".');
+export function phpVersionsPath(org, server) {
+    return `${serverPath(org, server)}/php/versions`;
+}
+export const phpVersionOutput = z.looseObject({
+    id: z.string().describe('PHP version ID.'),
+    version: z.string().nullable().describe('e.g. "8.3".'),
+    binary_name: z.string().nullable().describe('e.g. "php8.3".'),
+    status: z.string().nullable(),
+    created_at: z.string().nullable(),
+});
+export function formatPhpVersion(flat) {
+    return pick(flat, ['id', 'version', 'binary_name', 'status', 'created_at']);
+}
+/** Installed version with this number, or undefined. */
+export async function findPhpVersion(client, org, server, number, signal) {
+    const response = await client.get(phpVersionsPath(org, server), {
+        query: { filter: { version: number }, page: { size: 100 } },
+        signal,
+    });
+    const match = flattenCollection(response.data).items.find((item) => item.version === number);
+    return match ? formatPhpVersion(match) : undefined;
+}
+/** Resolves an ID or a version ("8.3", "php83") to the ID of the installed version. */
+export async function resolvePhpVersionId(client, org, server, ref, signal) {
+    // Digits only is an ID; versions are written with a dot ("8.3") or a "php" prefix.
+    if (typeof ref === 'number' || /^\d+$/.test(ref))
+        return String(ref);
+    const number = versionNumber(ref);
+    if (!number)
+        throw new ToolInputError(`Unknown PHP version "${ref}": use an ID from forge_list_php_versions or a version like "8.3".`);
+    const installed = await findPhpVersion(client, org, server, number, signal);
+    if (!installed) {
+        throw new ToolInputError(`PHP ${number} is not installed on server ${server}. Install it with forge_install_php_version.`);
+    }
+    return installed.id;
+}
+export function phpVersionPhase(status) {
+    return phaseOf(status, { pending: ['installing', 'updating', 'removing', 'uninstalling'], failed: ['failed'] });
+}

package/dist/tools/php/uninstall-php-version.js

@@ -0,0 +1,48 @@
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, orGone, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { phpVersionRefInput, phpVersionsPath, resolvePhpVersionId } from './shared.js';
+const CHECK_WITH = 'forge_list_php_versions';
+export const uninstallPhpVersion = defineTool({
+    name: 'forge_uninstall_php_version',
+    title: 'Uninstall PHP version',
+    description: 'Uninstall a PHP version from a server. Sites still using it stop working: move them first with forge_update_site.',
+    toolset: 'servers',
+    operations: [
+        'organizations.servers.php.versions.destroy',
+        'organizations.servers.php.versions.show',
+        'organizations.servers.php.versions.index',
+    ],
+    permissions: ['server:manage-php', 'server:view'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        php_version: phpVersionRefInput,
+        ...waitInput(180),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const org = organization(args.organization);
+        const id = await resolvePhpVersionId(client, org, args.server, args.php_version, signal);
+        const path = `${phpVersionsPath(org, args.server)}/${encodeURIComponent(id)}`;
+        await client.delete(path, { signal });
+        const action = `uninstall PHP ${args.php_version}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(async () => flattenSingle((await client.get(path, { signal })).data)),
+            phase: (version) => (version === null ? 'completed' : 'pending'),
+            describe: (version) => `PHP ${args.php_version} is ${version?.status ?? 'removing'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/php/update-php-config.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { phpConfigInput, poolUserInput, readPhpConfig } from './config-files.js';
+import { phpVersionRefInput, phpVersionsPath, resolvePhpVersionId } from './shared.js';
+const CHECK_WITH = 'forge_get_php_config';
+export const updatePhpConfig = defineTool({
+    name: 'forge_update_php_config',
+    title: 'Replace PHP configuration file',
+    description: 'Replace a whole configuration file of an installed PHP version (FPM or CLI php.ini, or the FPM pool) and reload PHP. Read it first with forge_get_php_config and send the complete new file: an invalid file can stop PHP-FPM and every site using it.',
+    toolset: 'servers',
+    operations: [
+        'organizations.servers.php.versions.configs.fpm.update',
+        'organizations.servers.php.versions.configs.cli.update',
+        'organizations.servers.php.versions.configs.pool.update',
+        'organizations.servers.php.versions.configs.fpm.show',
+        'organizations.servers.php.versions.configs.cli.show',
+        'organizations.servers.php.versions.configs.pool.show',
+        'organizations.servers.php.versions.index',
+    ],
+    permissions: ['server:manage-php', 'server:view'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        php_version: phpVersionRefInput,
+        config: phpConfigInput,
+        content: z.string().min(1).describe('The complete new configuration file.'),
+        user: poolUserInput,
+        ...waitInput(120),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const org = organization(args.organization);
+        const id = await resolvePhpVersionId(client, org, args.server, args.php_version, signal);
+        const path = `${phpVersionsPath(org, args.server)}/${encodeURIComponent(id)}/configs/${args.config}`;
+        const user = args.config === 'pool' ? args.user : undefined;
+        await client.put(path, { body: { config: args.content, ...(user ? { user } : {}) }, signal });
+        const action = `update the ${args.config} configuration`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => readPhpConfig(client, path, user, signal),
+            phase: (content) => (content.trimEnd() === args.content.trimEnd() ? 'completed' : 'pending'),
+            describe: () => `Waiting for the ${args.config} configuration to be applied`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, {
+            action,
+            checkWith: CHECK_WITH,
+            timeoutSeconds: args.timeout_seconds,
+            detail: result.status === 'in_progress' ? 'If PHP rejected the file, check forge_list_server_events.' : undefined,
+        });
+    },
+});

package/dist/tools/php/update-php-limits.js

@@ -0,0 +1,64 @@
+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 { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT, serverPath } from '../servers/shared.js';
+import { readPhpSetting } from './settings.js';
+const CHECK_WITH = 'forge_get_php_settings';
+export const updatePhpLimits = defineTool({
+    name: 'forge_update_php_limits',
+    title: 'Update PHP limits',
+    description: 'Change the max upload size and/or max execution time of every PHP version on the server. PHP-FPM is reloaded.',
+    toolset: 'servers',
+    operations: [
+        'organizations.servers.php.max-upload-size.update',
+        'organizations.servers.php.max-execution-time.update',
+        'organizations.servers.php.max-upload-size.show',
+        'organizations.servers.php.max-execution-time.show',
+    ],
+    permissions: ['server:manage-php', 'server:view'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        max_upload_size: z.number().int().min(1).optional().describe('Max upload size in MB.'),
+        max_execution_time: z.number().int().min(1).optional().describe('Max execution time in seconds.'),
+        ...waitInput(120),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        if (args.max_upload_size === undefined && args.max_execution_time === undefined) {
+            throw new ToolInputError('Pass `max_upload_size` and/or `max_execution_time`.');
+        }
+        const org = organization(args.organization);
+        const base = `${serverPath(org, args.server)}/php`;
+        if (args.max_upload_size !== undefined) {
+            await client.put(`${base}/max-upload-size`, { body: { max_upload_size: args.max_upload_size }, signal });
+        }
+        if (args.max_execution_time !== undefined) {
+            await client.put(`${base}/max-execution-time`, { body: { max_execution_time: args.max_execution_time }, signal });
+        }
+        const action = 'update the PHP limits';
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: async () => ({
+                upload: args.max_upload_size === undefined ? undefined : (await readPhpSetting(client, org, args.server, 'max-upload-size', signal)).max_upload_size,
+                execution: args.max_execution_time === undefined ? undefined : (await readPhpSetting(client, org, args.server, 'max-execution-time', signal)).max_execution_time,
+            }),
+            phase: (current) => (args.max_upload_size === undefined || current.upload === args.max_upload_size) &&
+                (args.max_execution_time === undefined || current.execution === args.max_execution_time)
+                ? 'completed'
+                : 'pending',
+            describe: () => 'Waiting for the PHP limits to be applied',
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/php/upgrade-php-version.js

@@ -0,0 +1,31 @@
+import { defineTool } from '../define-tool.js';
+import { operationOutput, queued } from '../shared/async.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { phpVersionRefInput, phpVersionsPath, resolvePhpVersionId } from './shared.js';
+export const upgradePhpVersion = defineTool({
+    name: 'forge_upgrade_php_version',
+    title: 'Upgrade PHP to the latest patch release',
+    description: 'Update an installed PHP version to its latest patch release (e.g. 8.3.x). PHP-FPM restarts during the update.',
+    toolset: 'servers',
+    operations: ['organizations.servers.php.versions.update', 'organizations.servers.php.versions.index'],
+    permissions: ['server:manage-php', 'server:view'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        php_version: phpVersionRefInput,
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal }) {
+        const org = organization(args.organization);
+        const id = await resolvePhpVersionId(client, org, args.server, args.php_version, signal);
+        await client.put(`${phpVersionsPath(org, args.server)}/${encodeURIComponent(id)}`, { signal });
+        // The patch level is not exposed by the API: the server events record the outcome.
+        return queued(`upgrade PHP ${args.php_version}`, 'forge_list_server_events', `(server ${args.server})`);
+    },
+});

package/dist/tools/registry.js

@@ -28,8 +28,29 @@ import { updateDomain } from './domains/update-domain.js';
 import { getServerEvent } from './events/get-server-event.js';
 import { listServerEvents } from './events/list-server-events.js';
 import { listOrganizations } from './organizations/list-organizations.js';
+import { getPhpConfig } from './php/get-php-config.js';
+import { getPhpSettings } from './php/get-php-settings.js';
+import { installPhpVersion } from './php/install-php-version.js';
+import { listPhpVersions } from './php/list-php-versions.js';
+import { setDefaultPhpVersion } from './php/set-default-php-version.js';
+import { setPhpOpcache } from './php/set-php-opcache.js';
+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 { archiveServer } from './servers/archive-server.js';
+import { clearServerLog } from './servers/clear-server-log.js';
+import { deleteServer } from './servers/delete-server.js';
 import { getServer } from './servers/get-server.js';
+import { getServerLog } from './servers/get-server-log.js';
+import { getServerNetwork } from './servers/get-server-network.js';
+import { listArchivedServers } from './servers/list-archived-servers.js';
 import { listServers } from './servers/list-servers.js';
+import { runServerAction } from './servers/run-server-action.js';
+import { runServiceAction } from './servers/run-service-action.js';
+import { unarchiveServer } from './servers/unarchive-server.js';
+import { updateServer } from './servers/update-server.js';
+import { updateServerNetwork } from './servers/update-server-network.js';
 import { clearSiteLog } from './sites/clear-site-log.js';
 import { createBalancedSite } from './sites/create-balanced-site.js';
 import { createSite } from './sites/create-site.js';
@@ -83,6 +104,29 @@ export const ALL_TOOLS = [
     createCertificate,
     runCertificateAction,
     deleteCertificate,
+    // servers
+    runServiceAction,
+    runServerAction,
+    getServerLog,
+    clearServerLog,
+    updateServer,
+    getServerNetwork,
+    updateServerNetwork,
+    listArchivedServers,
+    archiveServer,
+    unarchiveServer,
+    deleteServer,
+    // servers: PHP
+    listPhpVersions,
+    getPhpSettings,
+    installPhpVersion,
+    upgradePhpVersion,
+    uninstallPhpVersion,
+    setDefaultPhpVersion,
+    updatePhpLimits,
+    setPhpOpcache,
+    getPhpConfig,
+    updatePhpConfig,
     // deployments
     listDeployments,
     getDeployment,

package/dist/tools/servers/archive-server.js

@@ -0,0 +1,40 @@
+import { apiPath } from '../../forge/path.js';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT, archivedServerIds } from './shared.js';
+const CHECK_WITH = 'forge_list_archived_servers';
+export const archiveServer = defineTool({
+    name: 'forge_archive_server',
+    title: 'Archive server',
+    description: 'Archive a server: Forge stops managing it (no deployments, no monitoring) but the machine keeps running at the provider and can be restored with forge_unarchive_server.',
+    toolset: 'servers',
+    operations: ['organizations.servers.archives.store', 'organizations.servers.archives.index'],
+    permissions: ['server:archive', 'server:view'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        ...waitInput(120),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const org = organization(args.organization);
+        await client.post(apiPath `/orgs/${org}/servers/archives`, { body: { server_id: Number(args.server) }, signal });
+        const action = `archive server ${args.server}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => archivedServerIds(client, org, signal),
+            phase: (ids) => (ids.has(String(args.server)) ? 'completed' : 'pending'),
+            describe: () => `Waiting for server ${args.server} to be archived`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/servers/clear-server-log.js

@@ -0,0 +1,45 @@
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { serverLogKeyInput } from './server-logs.js';
+import { SERVER_NOT_FOUND_HINT, serverPath } from './shared.js';
+const CHECK_WITH = 'forge_get_server_log';
+export const clearServerLog = defineTool({
+    name: 'forge_clear_server_log',
+    title: 'Clear server log',
+    description: 'Empty a server-level log. The previous content is lost.',
+    toolset: 'servers',
+    operations: ['organizations.servers.logs.destroy', 'organizations.servers.logs.show'],
+    permissions: ['server:manage-logs'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        key: serverLogKeyInput,
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = `${serverPath(organization(args.organization), args.server)}/logs/${encodeURIComponent(args.key)}`;
+        await client.delete(path, { signal });
+        const action = `clear the ${args.key} log`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: async () => {
+                const response = await client.get(path, { signal });
+                return (flattenSingle(response.data).content ?? '').trim();
+            },
+            phase: (content) => (content === '' ? 'completed' : 'pending'),
+            describe: () => `Waiting for the ${args.key} log to be cleared`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/servers/delete-server.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, orGone, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT, readServer, serverPath } from './shared.js';
+const CHECK_WITH = 'forge_list_servers';
+export const deleteServer = defineTool({
+    name: 'forge_delete_server',
+    title: 'Delete server',
+    description: 'Delete a server from Forge and destroy it at the provider, with every site and database on it. With `preserve_at_provider: true` it is only removed from Forge and keeps running at the provider. This cannot be undone: consider forge_archive_server instead.',
+    toolset: 'servers',
+    operations: ['organizations.servers.destroy', 'organizations.servers.show'],
+    permissions: ['server:delete', 'server:view'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        preserve_at_provider: z.boolean().default(false).describe('Only remove the server from Forge, keeping the machine at the provider.'),
+        ...waitInput(300),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const org = organization(args.organization);
+        await client.delete(serverPath(org, args.server), {
+            query: { preserve_at_provider: args.preserve_at_provider ? 'true' : undefined },
+            signal,
+        });
+        const action = `delete server ${args.server}${args.preserve_at_provider ? ' from Forge (keeping it at the provider)' : ''}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(() => readServer(client, org, args.server, signal)),
+            phase: (server) => (server === null ? 'completed' : 'pending'),
+            describe: () => `Waiting for server ${args.server} to be deleted`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/servers/get-server-log.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { organizationInput, serverInput, tail } from '../shared/schemas.js';
+import { serverLogKeyInput } from './server-logs.js';
+import { serverPath } from './shared.js';
+export const getServerLog = defineTool({
+    name: 'forge_get_server_log',
+    title: 'Get server log',
+    description: 'Read the end of a server-level log (Nginx, PHP-FPM, MySQL, cron, daemons). For site logs use forge_get_site_log.',
+    toolset: 'servers',
+    operations: ['organizations.servers.logs.show'],
+    permissions: ['server:manage-logs'],
+    readOnly: true,
+    notFoundHint: 'Check the server ID with forge_list_servers; the log key may not exist on this server (the service may not be installed).',
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        key: serverLogKeyInput,
+        lines: z.number().int().min(0).max(5000).default(100).describe('Return only the last N lines (0 = everything Forge returns).'),
+    },
+    outputSchema: {
+        key: z.string(),
+        content: z.string(),
+        truncated: z.boolean(),
+        total_lines: z.number().int(),
+    },
+    async handler(args, { client, organization, signal }) {
+        const path = `${serverPath(organization(args.organization), args.server)}/logs/${encodeURIComponent(args.key)}`;
+        const response = await client.get(path, { signal });
+        const output = tail(flattenSingle(response.data).content, args.lines);
+        return {
+            structured: { key: args.key, content: output.text, truncated: output.truncated, total_lines: output.total_lines },
+            summary: output.total_lines === 0
+                ? `The ${args.key} log is empty.`
+                : `${args.key} log: ${output.truncated ? `last ${args.lines} of ${output.total_lines}` : output.total_lines} line(s).`,
+        };
+    },
+});

package/dist/tools/servers/get-server-network.js

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { formatServer, serverOutput } from './format.js';
+import { SERVER_NOT_FOUND_HINT, serverPath } from './shared.js';
+export const getServerNetwork = defineTool({
+    name: 'forge_get_server_network',
+    title: 'Get server network',
+    description: 'List the servers in this server\'s network: Forge opens the firewall between them so they can reach each other (e.g. an app server and its database or cache server).',
+    toolset: 'servers',
+    operations: ['organizations.servers.network.show'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+    },
+    outputSchema: {
+        servers: z.array(serverOutput),
+    },
+    async handler(args, { client, organization, signal }) {
+        const response = await client.get(`${serverPath(organization(args.organization), args.server)}/network`, { signal });
+        const servers = flattenCollection(response.data).items.map((item) => formatServer(item, false));
+        return {
+            structured: { servers },
+            summary: servers.length === 0
+                ? 'No other servers are in this server\'s network.'
+                : `${servers.length} server(s) in the network: ${servers.map((s) => `${s.name} (${s.id})`).join(', ')}.`,
+        };
+    },
+});

package/dist/tools/servers/list-archived-servers.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { apiPath } from '../../forge/path.js';
+import { defineTool } from '../define-tool.js';
+import { organizationInput, paginationInput, paginationOutput, paginationSummary, responseFormatInput } from '../shared/schemas.js';
+import { formatServer, serverOutput } from './format.js';
+export const listArchivedServers = defineTool({
+    name: 'forge_list_archived_servers',
+    title: 'List archived servers',
+    description: 'List the archived servers of the organization: servers Forge no longer manages but kept so they can be restored.',
+    toolset: 'servers',
+    operations: ['organizations.servers.archives.index'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: 'Check the organization slug with forge_list_organizations.',
+    inputSchema: {
+        organization: organizationInput,
+        sort: z.array(z.enum(['created_at', '-created_at', 'updated_at', '-updated_at'])).min(1).optional(),
+        ...paginationInput,
+        response_format: responseFormatInput,
+    },
+    outputSchema: {
+        servers: z.array(serverOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const response = await client.get(apiPath `/orgs/${organization(args.organization)}/servers/archives`, {
+            query: { sort: args.sort, page: { size: args.page_size, cursor: args.cursor } },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const servers = page.items.map((item) => formatServer(item, args.response_format === 'detailed'));
+        return {
+            structured: { servers, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: servers.length === 0 ? 'No archived servers.' : `Found ${servers.length} archived server(s).${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

package/dist/tools/servers/run-server-action.js

@@ -0,0 +1,29 @@
+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 { SERVER_NOT_FOUND_HINT, serverPath } from './shared.js';
+export const runServerAction = defineTool({
+    name: 'forge_run_server_action',
+    title: 'Reboot or power-cycle a server',
+    description: 'Reboot the server ("reboot", a clean OS restart) or power-cycle it ("power-cycle", a hard restart through the provider, for unresponsive servers). Every site on the server is unavailable meanwhile.',
+    toolset: 'servers',
+    operations: ['organizations.servers.actions.store'],
+    permissions: ['server:manage-services'],
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        action: z.enum(['reboot', 'power-cycle']),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal }) {
+        await client.post(`${serverPath(organization(args.organization), args.server)}/actions`, { body: { action: args.action }, signal });
+        // The server resource exposes no reliable reboot state to wait for.
+        return queued(`${args.action} server ${args.server}`, 'forge_list_server_events', `(server ${args.server})`);
+    },
+});

package/dist/tools/servers/run-service-action.js

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { ToolInputError } from '../errors.js';
+import { operationOutput, queued } from '../shared/async.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { PHP_VERSIONS } from '../sites/shared.js';
+import { SERVER_NOT_FOUND_HINT, serverPath } from './shared.js';
+/** Actions each service endpoint accepts, from the spec. */
+const SERVICE_ACTIONS = {
+    nginx: ['reboot', 'stop'],
+    mysql: ['reboot', 'stop'],
+    postgres: ['reboot', 'stop'],
+    redis: ['reboot'],
+    supervisor: ['reboot'],
+    php: ['reboot', 'reload'],
+};
+export const runServiceAction = defineTool({
+    name: 'forge_run_service_action',
+    title: 'Restart, reload or stop a service',
+    description: [
+        'Run an action on a service of the server.',
+        '"reboot" restarts it (nginx, mysql, postgres, redis, supervisor, php);',
+        '"stop" stops it (nginx, mysql, postgres);',
+        '"reload" gracefully reloads PHP-FPM (php).',
+        'For php, pass `php_version`. Restarting a service briefly interrupts the sites that use it.',
+    ].join(' '),
+    toolset: 'servers',
+    operations: [
+        'organizations.servers.services.nginx.actions.store',
+        'organizations.servers.services.mysql.actions.store',
+        'organizations.servers.services.postgres.actions.store',
+        'organizations.servers.services.redis.actions.store',
+        'organizations.servers.services.supervisor.actions.store',
+        'organizations.servers.services.php.actions.store',
+    ],
+    permissions: ['server:manage-services'],
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        service: z.enum(Object.keys(SERVICE_ACTIONS)),
+        action: z.enum(['reboot', 'stop', 'reload']).default('reboot'),
+        php_version: z.enum(PHP_VERSIONS).optional().describe('PHP version whose FPM to act on (required for php), e.g. "php83".'),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal }) {
+        const allowed = SERVICE_ACTIONS[args.service];
+        if (!allowed.includes(args.action)) {
+            throw new ToolInputError(`${args.service} supports: ${allowed.join(', ')}.`);
+        }
+        if (args.service === 'php' && !args.php_version) {
+            throw new ToolInputError('Pass `php_version` (e.g. "php83") to act on PHP-FPM. The server PHP versions are in forge_get_server.');
+        }
+        await client.post(`${serverPath(organization(args.organization), args.server)}/services/${args.service}/actions`, {
+            body: { action: args.action, ...(args.service === 'php' ? { version: args.php_version } : {}) },
+            signal,
+        });
+        const target = args.service === 'php' ? `${args.php_version} FPM` : args.service;
+        // Service state is not exposed by the API: the server events record the outcome.
+        return queued(`${args.action} ${target}`, 'forge_list_server_events', `(server ${args.server})`);
+    },
+});

package/dist/tools/servers/server-logs.js

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+export const serverLogKeyInput = z
+    .string()
+    .regex(/^[a-z0-9][a-z0-9._-]*$/)
+    .describe('Log to read. Common keys: "nginx-access", "nginx-error", "php" (PHP-FPM of the default version), "mysql", "cron", "daemon"; availability depends on the installed services.');

package/dist/tools/servers/shared.js

@@ -0,0 +1,18 @@
+import { flattenCollection, flattenSingle } from '../../forge/jsonapi.js';
+import { apiPath } from '../../forge/path.js';
+export function serverPath(org, server) {
+    return apiPath `/orgs/${org}/servers/${server}`;
+}
+export const SERVER_NOT_FOUND_HINT = 'Check the server ID with forge_list_servers.';
+export async function readServer(client, org, server, signal) {
+    const response = await client.get(serverPath(org, server), { signal });
+    return flattenSingle(response.data);
+}
+/** IDs of the archived servers on the first page (most recently updated first). */
+export async function archivedServerIds(client, org, signal) {
+    const response = await client.get(apiPath `/orgs/${org}/servers/archives`, {
+        query: { sort: ['-updated_at'], page: { size: 100 } },
+        signal,
+    });
+    return new Set(flattenCollection(response.data).items.map((server) => server.id));
+}

package/dist/tools/servers/unarchive-server.js

@@ -0,0 +1,40 @@
+import { apiPath } from '../../forge/path.js';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { archivedServerIds } from './shared.js';
+const CHECK_WITH = 'forge_list_servers';
+export const unarchiveServer = defineTool({
+    name: 'forge_unarchive_server',
+    title: 'Unarchive server',
+    description: 'Restore an archived server so Forge manages it again.',
+    toolset: 'servers',
+    operations: ['organizations.servers.archives.destroy', 'organizations.servers.archives.index'],
+    permissions: ['server:archive', 'server:view'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    async: true,
+    notFoundHint: 'Check the server ID with forge_list_archived_servers.',
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput.describe('ID of the archived server. Use forge_list_archived_servers to find it.'),
+        ...waitInput(120),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const org = organization(args.organization);
+        await client.delete(apiPath `/orgs/${org}/servers/archives/${args.server}`, { signal });
+        const action = `unarchive server ${args.server}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => archivedServerIds(client, org, signal),
+            phase: (ids) => (ids.has(String(args.server)) ? 'pending' : 'completed'),
+            describe: () => `Waiting for server ${args.server} to be restored`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/servers/update-server-network.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT, serverPath } from './shared.js';
+const CHECK_WITH = 'forge_get_server_network';
+export const updateServerNetwork = defineTool({
+    name: 'forge_update_server_network',
+    title: 'Update server network',
+    description: "Set which servers are in this server's network (the full list: servers not listed are removed). Read the current list first with forge_get_server_network.",
+    toolset: 'servers',
+    operations: ['organizations.servers.network.update', 'organizations.servers.network.show'],
+    permissions: ['server:manage-network', 'server:view'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        servers: z.array(z.number().int()).describe('IDs of every server that should be in the network (can be empty).'),
+        ...waitInput(120),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = `${serverPath(organization(args.organization), args.server)}/network`;
+        await client.put(path, { body: { servers: args.servers }, signal });
+        const action = 'update the server network';
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const wanted = [...new Set(args.servers.map(String))].sort().join(',');
+        const result = await waitFor({
+            poll: async () => {
+                const response = await client.get(path, { signal });
+                return flattenCollection(response.data).items.map((item) => item.id).sort().join(',');
+            },
+            phase: (current) => (current === wanted ? 'completed' : 'pending'),
+            describe: () => 'Waiting for the network to be updated',
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/servers/update-server.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { ToolInputError } from '../errors.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { formatServer, serverOutput } from './format.js';
+import { SERVER_NOT_FOUND_HINT, serverPath } from './shared.js';
+export const updateServer = defineTool({
+    name: 'forge_update_server',
+    title: 'Update server',
+    description: "Change a server's name, public or private IP address (when the provider changed it), timezone or tags in Forge. Only the given fields change.",
+    toolset: 'servers',
+    operations: ['organizations.servers.update'],
+    permissions: ['server:manage-meta'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        name: z.string().min(1).optional(),
+        ip_address: z.string().min(1).optional().describe('Public IP address Forge uses to connect.'),
+        private_ip_address: z.string().min(1).optional(),
+        timezone: z.string().min(1).optional().describe('IANA timezone, e.g. "Europe/Rome".'),
+        tags: z.array(z.string().min(1)).optional().describe('Replaces the server tags.'),
+    },
+    outputSchema: {
+        server: serverOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const { organization: _org, server: id, ...body } = args;
+        if (Object.values(body).every((value) => value === undefined)) {
+            throw new ToolInputError('Nothing to update: pass at least one field to change.');
+        }
+        const response = await client.put(serverPath(organization(args.organization), id), { body, signal });
+        const server = formatServer(flattenSingle(response.data), true);
+        const changed = Object.entries(body).filter(([, value]) => value !== undefined).map(([field]) => field);
+        return { structured: { server }, summary: `Server ${server.id} updated: ${changed.join(', ')}.` };
+    },
+});

package/package.json

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