@francescomalatesta/laravel-forge-mcp 0.5.0 → 0.6.0

package/README.md

@@ -106,6 +106,17 @@ 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_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/registry.js

@@ -28,8 +28,19 @@ 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 { 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 +94,18 @@ export const ALL_TOOLS = [
     createCertificate,
     runCertificateAction,
     deleteCertificate,
+    // servers
+    runServiceAction,
+    runServerAction,
+    getServerLog,
+    clearServerLog,
+    updateServer,
+    getServerNetwork,
+    updateServerNetwork,
+    listArchivedServers,
+    archiveServer,
+    unarchiveServer,
+    deleteServer,
     // 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.6.0",
   "description": "Unofficial Model Context Protocol (MCP) server for the Laravel Forge API",
   "keywords": [
     "mcp",