@francescomalatesta/laravel-forge-mcp 0.6.0 → 0.7.0

package/README.md

@@ -117,6 +117,16 @@ npm run build
 | `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,6 +28,16 @@ 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';
@@ -106,6 +116,17 @@ export const ALL_TOOLS = [
     archiveServer,
     unarchiveServer,
     deleteServer,
+    // servers: PHP
+    listPhpVersions,
+    getPhpSettings,
+    installPhpVersion,
+    upgradePhpVersion,
+    uninstallPhpVersion,
+    setDefaultPhpVersion,
+    updatePhpLimits,
+    setPhpOpcache,
+    getPhpConfig,
+    updatePhpConfig,
     // deployments
     listDeployments,
     getDeployment,

package/package.json

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