@francescomalatesta/laravel-forge-mcp 0.11.0 → 0.12.0

package/README.md

@@ -174,6 +174,24 @@ npm run build
 | `forge_update_background_process` | jobs | Rename or replace the Supervisor configuration |
 | `forge_run_background_process_action` | jobs | Start, stop or restart a background process, or empty its log |
 | `forge_delete_background_process` | jobs | Stop and remove a background process |
+| `forge_list_firewall_rules` | security | Open and blocked ports of a server |
+| `forge_create_firewall_rule` | security | Allow or deny a port (range) for everyone or an IP/subnet |
+| `forge_delete_firewall_rule` | security | Remove a firewall rule |
+| `forge_list_security_rules` | security | Password-protected (basic auth) paths of a site |
+| `forge_create_security_rule` | security | Protect a site or a path with a password |
+| `forge_update_security_rule` | security | Change name, path or users of a security rule |
+| `forge_delete_security_rule` | security | Remove a password protection |
+| `forge_list_redirect_rules` | security | Redirect rules of a site |
+| `forge_create_redirect_rule` | security | Add a 301 or 302 redirect |
+| `forge_delete_redirect_rule` | security | Remove a redirect |
+| `forge_reorder_redirect_rules` | security | Set the evaluation order of the redirects |
+| `forge_export_redirect_rules` | security | Redirects as CSV, in evaluation order |
+| `forge_import_redirect_rules` | security | Import redirects from CSV (append or replace) |
+| `forge_list_ssh_keys` | security | SSH keys authorized on a server |
+| `forge_add_ssh_key` | security | Authorize a public key |
+| `forge_delete_ssh_key` | security | Revoke an SSH key |
+| `forge_get_server_public_key` | security | The server's own public key (for Git providers, other servers) |
+| `forge_regenerate_server_key` | security | Replace the server's own key pair |
 | `forge_get_site_integrations` | integrations | Horizon, Octane, Reverb, Pulse, Inertia SSR, scheduler and maintenance mode status |
 | `forge_enable_site_integration` | integrations | Enable an integration (e.g. put the site in maintenance mode) and wait until it is active |
 | `forge_disable_site_integration` | integrations | Disable an integration (e.g. bring the site back up) |

package/dist/forge/client.js

@@ -78,11 +78,15 @@ export class ForgeClient {
     send(method, url, options) {
         const headers = {
             Authorization: `Bearer ${this.apiToken}`,
-            Accept: 'application/json',
+            Accept: options.accept ?? 'application/json',
             'User-Agent': this.userAgent,
         };
         let body;
-        if (options.body !== undefined) {
+        if (options.body instanceof FormData) {
+            // fetch sets the multipart Content-Type with its boundary.
+            body = options.body;
+        }
+        else if (options.body !== undefined) {
             headers['Content-Type'] = 'application/json';
             body = JSON.stringify(options.body);
         }

package/dist/tools/backups/create-backup-configuration.js

@@ -1,10 +1,11 @@
 import { z } from 'zod';
 import { defineTool } from '../define-tool.js';
 import { operationOutput, outcome, waitFor, waitInput } from '../shared/async.js';
+import { findNew, listNewestFirst } from '../shared/read.js';
 import { organizationInput, serverInput } from '../shared/schemas.js';
 import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
 import { databaseRefsInput, resolveDatabaseIds } from '../databases/shared.js';
-import { backupConfigurationOutput, backupConfigurationPhase, backupConfigurationsPath, formatBackupConfiguration, newestFirst, resolveStorageProviderId, scheduleBody, scheduleInput, storageProviderRefInput, } from './shared.js';
+import { backupConfigurationOutput, backupConfigurationPhase, backupConfigurationsPath, formatBackupConfiguration, resolveStorageProviderId, scheduleBody, scheduleInput, storageProviderRefInput, } from './shared.js';
 const CHECK_WITH = 'forge_list_backup_configurations';
 export const createBackupConfiguration = defineTool({
     name: 'forge_create_backup_configuration',
@@ -48,7 +49,7 @@ export const createBackupConfiguration = defineTool({
         const databaseIds = await resolveDatabaseIds(client, org, args.server, args.databases, signal);
         const base = backupConfigurationsPath(org, args.server);
         // Forge returns no body: remember the existing configurations to spot the new one.
-        const existing = args.wait ? new Set((await newestFirst(client, base, signal)).map((item) => item.id)) : undefined;
+        const existing = args.wait ? new Set((await listNewestFirst(client, base, signal)).map((item) => item.id)) : undefined;
         await client.post(base, {
             body: {
                 storage_provider_id: storageProviderId,
@@ -71,7 +72,7 @@ export const createBackupConfiguration = defineTool({
             };
         }
         const result = await waitFor({
-            poll: async () => (await newestFirst(client, base, signal)).find((item) => !existing.has(item.id)) ?? null,
+            poll: async () => findNew(await listNewestFirst(client, base, signal), existing),
             phase: (configuration) => (configuration ? backupConfigurationPhase(configuration.status) : 'pending'),
             describe: (configuration) => (configuration ? `Backup configuration is ${configuration.status}` : 'Waiting for the configuration to appear'),
             timeoutSeconds: args.timeout_seconds,

package/dist/tools/backups/create-backup.js

@@ -1,7 +1,8 @@
 import { defineTool } from '../define-tool.js';
 import { operationOutput, outcome, waitFor, waitInput } from '../shared/async.js';
+import { findNew, listNewestFirst } from '../shared/read.js';
 import { organizationInput, serverInput } from '../shared/schemas.js';
-import { BACKUP_CONFIGURATION_NOT_FOUND_HINT, backupConfigurationInput, backupOutput, backupPhase, backupsPath, formatBackup, newestFirst, } from './shared.js';
+import { BACKUP_CONFIGURATION_NOT_FOUND_HINT, backupConfigurationInput, backupOutput, backupPhase, backupsPath, formatBackup, } from './shared.js';
 const CHECK_WITH = 'forge_list_backups';
 export const createBackup = defineTool({
     name: 'forge_create_backup',
@@ -28,7 +29,7 @@ export const createBackup = defineTool({
     async handler(args, { client, organization, signal, sleep, progress }) {
         const base = backupsPath(organization(args.organization), args.server, args.backup_configuration);
         // Forge returns no body: remember the existing backups to spot the new one.
-        const existing = args.wait ? new Set((await newestFirst(client, base, signal)).map((item) => item.id)) : undefined;
+        const existing = args.wait ? new Set((await listNewestFirst(client, base, signal)).map((item) => item.id)) : undefined;
         await client.post(base, { signal });
         const action = `back up configuration ${args.backup_configuration}`;
         if (!existing) {
@@ -38,7 +39,7 @@ export const createBackup = defineTool({
             };
         }
         const result = await waitFor({
-            poll: async () => (await newestFirst(client, base, signal)).find((item) => !existing.has(item.id)) ?? null,
+            poll: async () => findNew(await listNewestFirst(client, base, signal), existing),
             phase: (backup) => (backup ? backupPhase(backup.status) : 'pending'),
             describe: (backup) => (backup ? `Backup is ${backup.status}` : 'Waiting for the backup to start'),
             timeoutSeconds: args.timeout_seconds,

package/dist/tools/backups/shared.js

@@ -100,11 +100,6 @@ export function formatBackup(flat) {
 export function backupPhase(status) {
     return phaseOf(status, { completed: ['finished'], failed: ['failed'] });
 }
-/** First page of a collection, newest first: used to spot items created by a write that returns no body. */
-export async function newestFirst(client, path, signal) {
-    const response = await client.get(path, { query: { sort: ['-created_at'], page: { size: 100 } }, signal });
-    return flattenCollection(response.data).items;
-}
 /** Resolves a storage provider ID or name to its ID. */
 export async function resolveStorageProviderId(client, org, ref, signal) {
     if (typeof ref === 'number' || /^\d+$/.test(ref))

package/dist/tools/firewall/create-firewall-rule.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { installationPhase, operationOutput, outcome, waitFor, waitInput } from '../shared/async.js';
+import { findNew, listNewestFirst } from '../shared/read.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { firewallRuleOutput, firewallRulesPath, formatFirewallRule } from './shared.js';
+const CHECK_WITH = 'forge_list_firewall_rules';
+export const createFirewallRule = defineTool({
+    name: 'forge_create_firewall_rule',
+    title: 'Create firewall rule',
+    description: 'Open (allow) or block (deny) a port or port range on a server, for everyone or for an IP address or subnet. Waits until the rule is installed unless `wait` is false.',
+    toolset: 'security',
+    operations: ['organizations.servers.firewall-rules.store', 'organizations.servers.firewall-rules.index'],
+    permissions: ['server:manage-network'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        name: z.string().min(1).max(50).describe('Name of the rule, e.g. "MySQL from office".'),
+        port: z.string().min(1).optional().describe('Port or range, e.g. "3306" or "8000:8010". Omit for every port.'),
+        ip_address: z.string().min(1).optional().describe('IP address or subnet allowed/blocked, e.g. "203.0.113.4" or "10.0.0.0/16". Omit for any address.'),
+        type: z.enum(['allow', 'deny']).default('allow'),
+        ...waitInput(60),
+    },
+    outputSchema: {
+        ...operationOutput,
+        rule: firewallRuleOutput.nullable().describe('The new rule once it shows up.'),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const base = firewallRulesPath(organization(args.organization), args.server);
+        // Forge returns no body: remember the existing rules with this name to spot the new one.
+        const lookup = () => listNewestFirst(client, base, signal, { name: args.name });
+        const existing = args.wait ? new Set((await lookup()).map((rule) => rule.id)) : undefined;
+        await client.post(base, { body: { name: args.name, port: args.port, ip_address: args.ip_address, type: args.type }, signal });
+        const action = `${args.type} ${args.port ? `port ${args.port}` : 'every port'}${args.ip_address ? ` from ${args.ip_address}` : ''}`;
+        if (!existing) {
+            return {
+                structured: { status: 'queued', check_with: CHECK_WITH, rule: null },
+                summary: `Forge accepted the request to ${action}; it runs in the background. Check it with ${CHECK_WITH}.`,
+            };
+        }
+        const result = await waitFor({
+            poll: async () => findNew(await lookup(), existing),
+            phase: (rule) => (rule ? installationPhase(rule.status) : 'pending'),
+            describe: (rule) => (rule ? `Firewall rule is ${rule.status}` : 'Waiting for the rule to appear'),
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const rule = result.value ? formatFirewallRule(result.value) : null;
+        const done = outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds, detail: rule ? `Rule ID: ${rule.id}.` : undefined });
+        return { structured: { ...done.structured, rule }, summary: done.summary };
+    },
+});

package/dist/tools/firewall/delete-firewall-rule.js

@@ -0,0 +1,41 @@
+import { defineTool } from '../define-tool.js';
+import { operationOutput, orGone, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { FIREWALL_RULE_NOT_FOUND_HINT, firewallRuleInput, firewallRulesPath } from './shared.js';
+const CHECK_WITH = 'forge_list_firewall_rules';
+export const deleteFirewallRule = defineTool({
+    name: 'forge_delete_firewall_rule',
+    title: 'Delete firewall rule',
+    description: 'Remove a firewall rule from a server. Removing an allow rule closes the port: check that nothing (SSH, HTTP) depends on it.',
+    toolset: 'security',
+    operations: ['organizations.servers.firewall-rules.destroy', 'organizations.servers.firewall-rules.show'],
+    permissions: ['server:manage-network'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: FIREWALL_RULE_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        rule: firewallRuleInput,
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = `${firewallRulesPath(organization(args.organization), args.server)}/${encodeURIComponent(String(args.rule))}`;
+        await client.delete(path, { signal });
+        const action = `delete firewall rule ${args.rule}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(() => readResource(client, path, signal)),
+            phase: (rule) => (rule === null ? 'completed' : 'pending'),
+            describe: (rule) => `Firewall rule is ${rule?.status ?? 'removing'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/firewall/list-firewall-rules.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, paginationInput, paginationOutput, paginationSummary, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { firewallRuleInput, firewallRuleOutput, firewallRulesPath, formatFirewallRule } from './shared.js';
+const SORT = ['created_at', '-created_at', 'updated_at', '-updated_at'];
+export const listFirewallRules = defineTool({
+    name: 'forge_list_firewall_rules',
+    title: 'List firewall rules',
+    description: 'List the firewall rules of a server (which ports are open to which addresses), or get one with `rule`.',
+    toolset: 'security',
+    operations: ['organizations.servers.firewall-rules.index', 'organizations.servers.firewall-rules.show'],
+    permissions: ['server:manage-network'],
+    readOnly: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        rule: firewallRuleInput.optional().describe('Return only this rule.'),
+        name: z.string().min(1).optional().describe('Filter by name.'),
+        port: z.string().min(1).optional().describe('Filter by port, e.g. "3306".'),
+        ip_address: z.string().min(1).optional().describe('Filter by IP address or subnet.'),
+        type: z.enum(['allow', 'deny']).optional().describe('Filter by type.'),
+        status: z.string().min(1).optional().describe('Filter by status, e.g. "installed".'),
+        sort: z.array(z.enum(SORT)).min(1).optional(),
+        ...paginationInput,
+    },
+    outputSchema: {
+        rules: z.array(firewallRuleOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const base = firewallRulesPath(organization(args.organization), args.server);
+        if (args.rule !== undefined) {
+            const rule = formatFirewallRule(await readResource(client, `${base}/${encodeURIComponent(String(args.rule))}`, signal));
+            return { structured: { rules: [rule], next_cursor: null, has_more: false }, summary: `Firewall rule ${rule.name} is ${rule.status}.` };
+        }
+        const response = await client.get(base, {
+            query: {
+                filter: { name: args.name, port: args.port, ip_address: args.ip_address, type: args.type, status: args.status },
+                sort: args.sort,
+                page: { size: args.page_size, cursor: args.cursor },
+            },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const rules = page.items.map(formatFirewallRule);
+        return {
+            structured: { rules, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: rules.length === 0
+                ? 'No firewall rules found.'
+                : `Found ${rules.length} firewall rule(s): ${rules
+                    .map((r) => `${r.type} ${r.port ?? 'all ports'} from ${r.ip_address ?? 'anywhere'} (${r.id})`)
+                    .join(', ')}.${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

package/dist/tools/firewall/shared.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { idInput, pick } from '../shared/schemas.js';
+import { serverPath } from '../servers/shared.js';
+export function firewallRulesPath(org, server) {
+    return `${serverPath(org, server)}/firewall-rules`;
+}
+export const firewallRuleInput = idInput('Firewall rule ID. Use forge_list_firewall_rules to find it.');
+export const FIREWALL_RULE_NOT_FOUND_HINT = 'Check the firewall rule ID with forge_list_firewall_rules.';
+const FIELDS = ['id', 'name', 'type', 'port', 'ip_address', 'status', 'created_at', 'updated_at'];
+export const firewallRuleOutput = z.looseObject({
+    id: z.string(),
+    name: z.string().nullable(),
+    type: z.string().nullable().describe('allow or deny.'),
+    port: z.string().nullable().describe('Port or range, e.g. "80" or "8000:8010"; null for every port.'),
+    ip_address: z.string().nullable().describe('IP address or subnet; null for any address.'),
+    status: z.string().nullable().describe('e.g. installing, installed, removing.'),
+    created_at: z.string().nullable(),
+    updated_at: z.string().nullable(),
+});
+export function formatFirewallRule(flat) {
+    return pick(flat, FIELDS);
+}

package/dist/tools/redirects/create-redirect-rule.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { installationPhase, operationOutput, outcome, waitFor, waitInput } from '../shared/async.js';
+import { findNew, listNewestFirst } from '../shared/read.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput } from '../shared/site-scope.js';
+import { formatRedirectRule, redirectRuleOutput, redirectRulesPath, redirectTypeInput } from './shared.js';
+const CHECK_WITH = 'forge_list_redirect_rules';
+export const createRedirectRule = defineTool({
+    name: 'forge_create_redirect_rule',
+    title: 'Create redirect rule',
+    description: 'Redirect a path of the site to another path or URL (Nginx rewrite). Waits until the rule is installed unless `wait` is false. For many rules use forge_import_redirect_rules.',
+    toolset: 'security',
+    operations: ['organizations.servers.sites.redirect-rules.store', 'organizations.servers.sites.redirect-rules.index'],
+    permissions: ['site:manage-redirects'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    async: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        from: z.string().min(1).describe('Source path, e.g. "/old-page".'),
+        to: z.string().min(1).describe('Destination path or URL, e.g. "/new-page" or "https://example.com/".'),
+        type: redirectTypeInput.default('permanent'),
+        ...waitInput(60),
+    },
+    outputSchema: {
+        ...operationOutput,
+        rule: redirectRuleOutput.nullable().describe('The new rule once it shows up.'),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const base = redirectRulesPath(organization(args.organization), args.server, args.site);
+        // Forge returns no body: remember the existing rules for this path to spot the new one.
+        const lookup = () => listNewestFirst(client, base, signal, { from: args.from });
+        const existing = args.wait ? new Set((await lookup()).map((rule) => rule.id)) : undefined;
+        await client.post(base, { body: { from: args.from, to: args.to, type: args.type }, signal });
+        const action = `redirect ${args.from} to ${args.to}`;
+        if (!existing) {
+            return {
+                structured: { status: 'queued', check_with: CHECK_WITH, rule: null },
+                summary: `Forge accepted the request to ${action}; it runs in the background. Check it with ${CHECK_WITH}.`,
+            };
+        }
+        const result = await waitFor({
+            poll: async () => findNew(await lookup(), existing),
+            phase: (rule) => (rule ? installationPhase(rule.status) : 'pending'),
+            describe: (rule) => (rule ? `Redirect rule is ${rule.status}` : 'Waiting for the rule to appear'),
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const rule = result.value ? formatRedirectRule(result.value) : null;
+        const done = outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds, detail: rule ? `Rule ID: ${rule.id}.` : undefined });
+        return { structured: { ...done.structured, rule }, summary: done.summary };
+    },
+});

package/dist/tools/redirects/delete-redirect-rule.js

@@ -0,0 +1,40 @@
+import { defineTool } from '../define-tool.js';
+import { operationOutput, orGone, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { readResource } from '../shared/read.js';
+import { siteScopeInput } from '../shared/site-scope.js';
+import { redirectRuleInput, redirectRulesPath } from './shared.js';
+const CHECK_WITH = 'forge_list_redirect_rules';
+export const deleteRedirectRule = defineTool({
+    name: 'forge_delete_redirect_rule',
+    title: 'Delete redirect rule',
+    description: 'Remove a redirect rule from a site.',
+    toolset: 'security',
+    operations: ['organizations.servers.sites.redirect-rules.destroy', 'organizations.servers.sites.redirect-rules.show'],
+    permissions: ['site:manage-redirects'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: 'Check the redirect rule ID with forge_list_redirect_rules.',
+    inputSchema: {
+        ...siteScopeInput,
+        rule: redirectRuleInput,
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = `${redirectRulesPath(organization(args.organization), args.server, args.site)}/${encodeURIComponent(String(args.rule))}`;
+        await client.delete(path, { signal });
+        const action = `delete redirect rule ${args.rule}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(() => readResource(client, path, signal)),
+            phase: (rule) => (rule === null ? 'completed' : 'pending'),
+            describe: (rule) => `Redirect rule is ${rule?.status ?? 'removing'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/redirects/export-redirect-rules.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput } from '../shared/site-scope.js';
+import { redirectRulesPath } from './shared.js';
+export const exportRedirectRules = defineTool({
+    name: 'forge_export_redirect_rules',
+    title: 'Export redirect rules',
+    description: 'Export every redirect rule of a site as CSV (from,to,type header) in evaluation order: use it to review the order, back them up or copy them to another site with forge_import_redirect_rules.',
+    toolset: 'security',
+    operations: ['organizations.servers.sites.redirect-rules.export'],
+    permissions: ['site:manage-redirects'],
+    readOnly: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+    },
+    outputSchema: {
+        csv: z.string().describe('CSV with a from,to,type header row.'),
+        rules: z.number().int().describe('Number of rules (rows after the header).'),
+    },
+    async handler(args, { client, organization, signal }) {
+        const response = await client.get(`${redirectRulesPath(organization(args.organization), args.server, args.site)}/export`, {
+            accept: 'text/csv',
+            signal,
+        });
+        const csv = typeof response.data === 'string' ? response.data : '';
+        const rules = Math.max(0, csv.split('\n').filter((line) => line.trim() !== '').length - 1);
+        return { structured: { csv, rules }, summary: `Exported ${rules} redirect rule(s).` };
+    },
+});

package/dist/tools/redirects/import-redirect-rules.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { ToolInputError } from '../errors.js';
+import { operationOutput } from '../shared/async.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput } from '../shared/site-scope.js';
+import { redirectRulesPath } from './shared.js';
+const skippedRow = z.looseObject({
+    line: z.string(),
+    reason: z.string().nullable(),
+    from: z.string(),
+    to: z.string(),
+    type: z.string(),
+});
+export const importRedirectRules = defineTool({
+    name: 'forge_import_redirect_rules',
+    title: 'Import redirect rules',
+    description: 'Import redirect rules from CSV text with a from,to,type header (type: redirect or permanent). `append` adds them to the existing rules; `replace` DELETES every existing rule first. Invalid and duplicate rows are skipped and reported.',
+    toolset: 'security',
+    operations: ['organizations.servers.sites.redirect-rules.import'],
+    permissions: ['site:manage-redirects'],
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
+    async: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        csv: z.string().min(1).describe('CSV content, e.g. "from,to,type\\n/old,/new,permanent".'),
+        mode: z.enum(['append', 'replace']).describe('append: add to the existing rules; replace: remove every existing rule first.'),
+    },
+    outputSchema: {
+        ...operationOutput,
+        imported: z.number().int().describe('Rules imported.'),
+        invalid: z.array(skippedRow).describe('Rows skipped because they are invalid.'),
+        duplicates: z.array(skippedRow).describe('Rows skipped because they repeat a row or an existing rule.'),
+    },
+    async handler(args, { client, organization, signal }) {
+        const header = args.csv.replace(/^\uFEFF/, '').trimStart().split('\n', 1)[0].trim().toLowerCase().replace(/\s/g, '');
+        if (header !== 'from,to,type')
+            throw new ToolInputError('The CSV must start with the header row "from,to,type".');
+        const form = new FormData();
+        form.append('file', new Blob([args.csv], { type: 'text/csv' }), 'redirects.csv');
+        form.append('mode', args.mode);
+        const response = await client.post(`${redirectRulesPath(organization(args.organization), args.server, args.site)}/import`, {
+            body: form,
+            signal,
+        });
+        const report = { imported: response.data?.imported ?? 0, invalid: response.data?.invalid ?? [], duplicates: response.data?.duplicates ?? [] };
+        const skipped = report.invalid.length + report.duplicates.length;
+        // The import report is final; Nginx picks up the rules in the background.
+        return {
+            structured: { status: 'queued', check_with: 'forge_list_redirect_rules', ...report },
+            summary: `Imported ${report.imported} redirect rule(s)${args.mode === 'replace' ? ', replacing the existing ones' : ''}${skipped > 0 ? `; skipped ${report.invalid.length} invalid and ${report.duplicates.length} duplicate row(s)` : ''}. Forge installs them in the background: check them with forge_list_redirect_rules.`,
+        };
+    },
+});

package/dist/tools/redirects/list-redirect-rules.js

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { readResource } from '../shared/read.js';
+import { paginationInput, paginationOutput, paginationSummary } from '../shared/schemas.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput } from '../shared/site-scope.js';
+import { formatRedirectRule, REDIRECT_TYPES, redirectRuleInput, redirectRuleOutput, redirectRulesPath } from './shared.js';
+const SORT = ['created_at', '-created_at', 'updated_at', '-updated_at'];
+export const listRedirectRules = defineTool({
+    name: 'forge_list_redirect_rules',
+    title: 'List redirect rules',
+    description: 'List the redirect rules of a site (from → to, 301 or 302), or get one with `rule`. Use forge_export_redirect_rules to see them in evaluation order.',
+    toolset: 'security',
+    operations: ['organizations.servers.sites.redirect-rules.index', 'organizations.servers.sites.redirect-rules.show'],
+    permissions: ['site:manage-redirects'],
+    readOnly: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        rule: redirectRuleInput.optional().describe('Return only this rule.'),
+        from: z.string().min(1).optional().describe('Filter by source path.'),
+        to: z.string().min(1).optional().describe('Filter by destination.'),
+        type: z.enum(REDIRECT_TYPES).optional().describe('Filter by type.'),
+        status: z.enum(['installing', 'installed', 'removing']).optional().describe('Filter by status.'),
+        sort: z.array(z.enum(SORT)).min(1).optional(),
+        ...paginationInput,
+    },
+    outputSchema: {
+        rules: z.array(redirectRuleOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const base = redirectRulesPath(organization(args.organization), args.server, args.site);
+        if (args.rule !== undefined) {
+            const rule = formatRedirectRule(await readResource(client, `${base}/${encodeURIComponent(String(args.rule))}`, signal));
+            return { structured: { rules: [rule], next_cursor: null, has_more: false }, summary: `${rule.from} → ${rule.to} (${rule.type}) is ${rule.status}.` };
+        }
+        const response = await client.get(base, {
+            query: {
+                filter: { from: args.from, to: args.to, type: args.type, status: args.status },
+                sort: args.sort,
+                page: { size: args.page_size, cursor: args.cursor },
+            },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const rules = page.items.map(formatRedirectRule);
+        return {
+            structured: { rules, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: rules.length === 0 ? 'No redirect rules found.' : `Found ${rules.length} redirect rule(s).${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

package/dist/tools/redirects/reorder-redirect-rules.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { operationOutput, queued } from '../shared/async.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput } from '../shared/site-scope.js';
+import { redirectRulesPath } from './shared.js';
+export const reorderRedirectRules = defineTool({
+    name: 'forge_reorder_redirect_rules',
+    title: 'Reorder redirect rules',
+    description: 'Set the order in which Nginx evaluates the redirect rules of a site (the first match wins), by listing their IDs in the desired order. IDs that do not belong to the site are ignored.',
+    toolset: 'security',
+    operations: ['organizations.servers.sites.redirect-rules.reorder'],
+    permissions: ['site:manage-redirects'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    async: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        rules: z
+            .array(z.union([z.number().int().nonnegative(), z.string().regex(/^\d+$/)]))
+            .min(1)
+            .describe('Redirect rule IDs in evaluation order, e.g. [12, 9, 15].'),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal }) {
+        await client.put(`${redirectRulesPath(organization(args.organization), args.server, args.site)}/reorder`, {
+            body: { redirects: args.rules.map(Number) },
+            signal,
+        });
+        // The rule resources carry no position: the export (in evaluation order) shows the result.
+        return queued('reorder the redirect rules', 'forge_export_redirect_rules');
+    },
+});

package/dist/tools/redirects/shared.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { idInput, pick } from '../shared/schemas.js';
+import { sitePath } from '../shared/site-scope.js';
+export function redirectRulesPath(org, server, site) {
+    return `${sitePath(org, server, site)}/redirect-rules`;
+}
+export const redirectRuleInput = idInput('Redirect rule ID. Use forge_list_redirect_rules to find it.');
+export const REDIRECT_TYPES = ['redirect', 'permanent'];
+export const redirectTypeInput = z
+    .enum(REDIRECT_TYPES)
+    .describe('"permanent" (301, cached by browsers and search engines) or "redirect" (302, temporary).');
+const FIELDS = ['id', 'from', 'to', 'type', 'status', 'created_at', 'updated_at'];
+export const redirectRuleOutput = z.looseObject({
+    id: z.string(),
+    from: z.string().nullable(),
+    to: z.string().nullable(),
+    type: z.string().nullable().describe('redirect (302) or permanent (301).'),
+    status: z.string().nullable().describe('installing, installed or removing.'),
+    created_at: z.string().nullable(),
+    updated_at: z.string().nullable(),
+});
+export function formatRedirectRule(flat) {
+    return pick(flat, FIELDS);
+}

package/dist/tools/registry.js

@@ -54,6 +54,9 @@ import { runDomainAction } from './domains/run-domain-action.js';
 import { updateDomain } from './domains/update-domain.js';
 import { getServerEvent } from './events/get-server-event.js';
 import { listServerEvents } from './events/list-server-events.js';
+import { createFirewallRule } from './firewall/create-firewall-rule.js';
+import { deleteFirewallRule } from './firewall/delete-firewall-rule.js';
+import { listFirewallRules } from './firewall/list-firewall-rules.js';
 import { disableSiteIntegration } from './integrations/disable-site-integration.js';
 import { enableSiteIntegration } from './integrations/enable-site-integration.js';
 import { getSiteIntegrations } from './integrations/get-site-integrations.js';
@@ -68,10 +71,20 @@ 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 { createRedirectRule } from './redirects/create-redirect-rule.js';
+import { deleteRedirectRule } from './redirects/delete-redirect-rule.js';
+import { exportRedirectRules } from './redirects/export-redirect-rules.js';
+import { importRedirectRules } from './redirects/import-redirect-rules.js';
+import { listRedirectRules } from './redirects/list-redirect-rules.js';
+import { reorderRedirectRules } from './redirects/reorder-redirect-rules.js';
 import { createScheduledJob } from './scheduled-jobs/create-scheduled-job.js';
 import { deleteScheduledJob } from './scheduled-jobs/delete-scheduled-job.js';
 import { getScheduledJob } from './scheduled-jobs/get-scheduled-job.js';
 import { listScheduledJobs } from './scheduled-jobs/list-scheduled-jobs.js';
+import { createSecurityRule } from './security-rules/create-security-rule.js';
+import { deleteSecurityRule } from './security-rules/delete-security-rule.js';
+import { listSecurityRules } from './security-rules/list-security-rules.js';
+import { updateSecurityRule } from './security-rules/update-security-rule.js';
 import { archiveServer } from './servers/archive-server.js';
 import { clearServerLog } from './servers/clear-server-log.js';
 import { deleteServer } from './servers/delete-server.js';
@@ -101,6 +114,11 @@ import { updateSiteEnvironment } from './sites/update-site-environment.js';
 import { updateSiteHealthcheck } from './sites/update-site-healthcheck.js';
 import { updateSiteNginxConfig } from './sites/update-site-nginx-config.js';
 import { updateSiteRepository } from './sites/update-site-repository.js';
+import { addSshKey } from './ssh-keys/add-ssh-key.js';
+import { deleteSshKey } from './ssh-keys/delete-ssh-key.js';
+import { getServerPublicKey } from './ssh-keys/get-server-public-key.js';
+import { listSshKeys } from './ssh-keys/list-ssh-keys.js';
+import { regenerateServerKey } from './ssh-keys/regenerate-server-key.js';
 import { createStorageProvider } from './storage/create-storage-provider.js';
 import { deleteStorageProvider } from './storage/delete-storage-provider.js';
 import { listStorageProviders } from './storage/list-storage-providers.js';
@@ -217,6 +235,25 @@ export const ALL_TOOLS = [
     updateBackgroundProcess,
     runBackgroundProcessAction,
     deleteBackgroundProcess,
+    // security
+    listFirewallRules,
+    createFirewallRule,
+    deleteFirewallRule,
+    listSecurityRules,
+    createSecurityRule,
+    updateSecurityRule,
+    deleteSecurityRule,
+    listRedirectRules,
+    createRedirectRule,
+    deleteRedirectRule,
+    reorderRedirectRules,
+    exportRedirectRules,
+    importRedirectRules,
+    listSshKeys,
+    addSshKey,
+    deleteSshKey,
+    getServerPublicKey,
+    regenerateServerKey,
     // integrations
     getSiteIntegrations,
     enableSiteIntegration,

package/dist/tools/security-rules/create-security-rule.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { installationPhase, operationOutput, outcome, waitFor, waitInput } from '../shared/async.js';
+import { readResource } from '../shared/read.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput } from '../shared/site-scope.js';
+import { credentialsInput, formatSecurityRule, securityRuleOutput, securityRulesPath } from './shared.js';
+const CHECK_WITH = 'forge_list_security_rules';
+export const createSecurityRule = defineTool({
+    name: 'forge_create_security_rule',
+    title: 'Create security rule',
+    description: 'Password-protect a site, or one path of it, with HTTP basic auth (e.g. a staging site or /admin). Waits until the rule is installed unless `wait` is false.',
+    toolset: 'security',
+    operations: ['organizations.servers.sites.security-rules.store', 'organizations.servers.sites.security-rules.show'],
+    permissions: ['site:manage-security'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    async: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        name: z.string().min(1).max(255).describe('Name of the rule, e.g. "Staging access".'),
+        path: z.string().min(1).max(255).optional().describe('Path to protect, e.g. "/admin". Omit to protect the whole site.'),
+        credentials: credentialsInput,
+        ...waitInput(60),
+    },
+    outputSchema: {
+        ...operationOutput,
+        rule: securityRuleOutput.nullable(),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const base = securityRulesPath(organization(args.organization), args.server, args.site);
+        const response = await client.post(base, {
+            body: { name: args.name, path: args.path, credentials: args.credentials },
+            signal,
+        });
+        const initial = response.data?.data ? flattenSingle(response.data) : undefined;
+        const action = `protect ${args.path ?? 'the site'} with a password`;
+        if (!initial || !args.wait) {
+            return {
+                structured: { status: 'queued', check_with: CHECK_WITH, rule: initial ? formatSecurityRule(initial) : null },
+                summary: `Forge accepted the request to ${action}. Check it with ${CHECK_WITH}.`,
+            };
+        }
+        const result = await waitFor({
+            initial,
+            poll: () => readResource(client, `${base}/${encodeURIComponent(initial.id)}`, signal),
+            phase: (rule) => installationPhase(rule.status),
+            describe: (rule) => `Security rule is ${rule.status}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const rule = formatSecurityRule(result.value ?? initial);
+        const done = outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds, detail: `Rule ID: ${rule.id}.` });
+        return { structured: { ...done.structured, rule }, summary: done.summary };
+    },
+});

package/dist/tools/security-rules/delete-security-rule.js

@@ -0,0 +1,40 @@
+import { defineTool } from '../define-tool.js';
+import { operationOutput, orGone, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { readResource } from '../shared/read.js';
+import { siteScopeInput } from '../shared/site-scope.js';
+import { SECURITY_RULE_NOT_FOUND_HINT, securityRuleInput, securityRulesPath } from './shared.js';
+const CHECK_WITH = 'forge_list_security_rules';
+export const deleteSecurityRule = defineTool({
+    name: 'forge_delete_security_rule',
+    title: 'Delete security rule',
+    description: 'Remove the password protection of a security rule: the path becomes public.',
+    toolset: 'security',
+    operations: ['organizations.servers.sites.security-rules.destroy', 'organizations.servers.sites.security-rules.show'],
+    permissions: ['site:manage-security'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: SECURITY_RULE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        rule: securityRuleInput,
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = `${securityRulesPath(organization(args.organization), args.server, args.site)}/${encodeURIComponent(String(args.rule))}`;
+        await client.delete(path, { signal });
+        const action = `delete security rule ${args.rule}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(() => readResource(client, path, signal)),
+            phase: (rule) => (rule === null ? 'completed' : 'pending'),
+            describe: (rule) => `Security rule is ${rule?.status ?? 'removing'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/security-rules/list-security-rules.js

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { readResource } from '../shared/read.js';
+import { paginationInput, paginationOutput, paginationSummary } from '../shared/schemas.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput } from '../shared/site-scope.js';
+import { formatSecurityRule, securityRuleInput, securityRuleOutput, securityRulesPath } from './shared.js';
+const SORT = ['path', '-path', 'status', '-status', 'created_at', '-created_at', 'updated_at', '-updated_at'];
+export const listSecurityRules = defineTool({
+    name: 'forge_list_security_rules',
+    title: 'List security rules',
+    description: 'List the password-protected (HTTP basic auth) paths of a site, or get one with `rule`. Credentials are never returned.',
+    toolset: 'security',
+    operations: ['organizations.servers.sites.security-rules.index', 'organizations.servers.sites.security-rules.show'],
+    permissions: ['site:manage-security'],
+    readOnly: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        rule: securityRuleInput.optional().describe('Return only this rule.'),
+        path: z.string().min(1).optional().describe('Filter by path.'),
+        status: z.string().min(1).optional().describe('Filter by status, e.g. "installed".'),
+        sort: z.array(z.enum(SORT)).min(1).optional(),
+        ...paginationInput,
+    },
+    outputSchema: {
+        rules: z.array(securityRuleOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const base = securityRulesPath(organization(args.organization), args.server, args.site);
+        if (args.rule !== undefined) {
+            const rule = formatSecurityRule(await readResource(client, `${base}/${encodeURIComponent(String(args.rule))}`, signal));
+            return { structured: { rules: [rule], next_cursor: null, has_more: false }, summary: `Security rule ${rule.name} is ${rule.status}.` };
+        }
+        const response = await client.get(base, {
+            query: { filter: { path: args.path, status: args.status }, sort: args.sort, page: { size: args.page_size, cursor: args.cursor } },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const rules = page.items.map(formatSecurityRule);
+        return {
+            structured: { rules, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: rules.length === 0
+                ? 'No security rules: no path of this site is password protected.'
+                : `Found ${rules.length} security rule(s): ${rules.map((r) => `${r.path ?? 'whole site'} (${r.id})`).join(', ')}.${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

package/dist/tools/security-rules/shared.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { idInput, pick } from '../shared/schemas.js';
+import { sitePath } from '../shared/site-scope.js';
+export function securityRulesPath(org, server, site) {
+    return `${sitePath(org, server, site)}/security-rules`;
+}
+export const securityRuleInput = idInput('Security rule ID. Use forge_list_security_rules to find it.');
+export const SECURITY_RULE_NOT_FOUND_HINT = 'Check the security rule ID with forge_list_security_rules.';
+export const credentialsInput = z
+    .array(z.object({
+    username: z.string().min(1).max(50),
+    password: z.string().min(1).describe('Never returned by any tool.'),
+}))
+    .min(1)
+    .describe('Users allowed through the password prompt.');
+const FIELDS = ['id', 'name', 'path', 'status', 'created_at', 'updated_at'];
+export const securityRuleOutput = z.looseObject({
+    id: z.string(),
+    name: z.string().nullable(),
+    path: z.string().nullable().describe('Protected path; null protects the whole site.'),
+    status: z.string().nullable().describe('e.g. installing, installed, removing.'),
+    created_at: z.string().nullable(),
+    updated_at: z.string().nullable(),
+});
+export function formatSecurityRule(flat) {
+    return pick(flat, FIELDS);
+}

package/dist/tools/security-rules/update-security-rule.js

@@ -0,0 +1,58 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { installationPhase, operationOutput, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { readResource } from '../shared/read.js';
+import { siteScopeInput } from '../shared/site-scope.js';
+import { credentialsInput, formatSecurityRule, SECURITY_RULE_NOT_FOUND_HINT, securityRuleInput, securityRuleOutput, securityRulesPath } from './shared.js';
+const CHECK_WITH = 'forge_list_security_rules';
+export const updateSecurityRule = defineTool({
+    name: 'forge_update_security_rule',
+    title: 'Update security rule',
+    description: 'Change the name, protected path or users of a security rule. Forge cannot return the current passwords, so `credentials` must list every user that should keep access.',
+    toolset: 'security',
+    operations: ['organizations.servers.sites.security-rules.update', 'organizations.servers.sites.security-rules.show'],
+    permissions: ['site:manage-security'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    async: true,
+    notFoundHint: SECURITY_RULE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        rule: securityRuleInput,
+        credentials: credentialsInput.describe('Every user allowed through the password prompt (replaces the list).'),
+        name: z.string().min(1).max(255).optional().describe('New name.'),
+        path: z.string().min(1).max(255).nullable().optional().describe('New protected path; null protects the whole site.'),
+        ...waitInput(60),
+    },
+    outputSchema: {
+        ...operationOutput,
+        rule: securityRuleOutput.nullable(),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = `${securityRulesPath(organization(args.organization), args.server, args.site)}/${encodeURIComponent(String(args.rule))}`;
+        const current = await readResource(client, path, signal);
+        const name = args.name ?? current.name;
+        const protectedPath = args.path === undefined ? current.path : args.path;
+        await client.put(path, { body: { name, path: protectedPath, credentials: args.credentials }, signal });
+        const action = `update security rule ${args.rule}`;
+        const changed = (args.name !== undefined && args.name !== current.name) || (args.path !== undefined && args.path !== current.path);
+        if (!args.wait || !changed) {
+            // Credentials are never returned: only name and path changes can be verified.
+            const accepted = queued(action, CHECK_WITH, changed ? undefined : '(credentials are never returned, so the change cannot be verified)');
+            return { ...accepted, structured: { ...accepted.structured, rule: null } };
+        }
+        const result = await waitFor({
+            poll: () => readResource(client, path, signal),
+            phase: (rule) => {
+                const phase = installationPhase(rule.status);
+                return phase === 'completed' && (rule.name !== name || (rule.path ?? null) !== (protectedPath ?? null)) ? 'pending' : phase;
+            },
+            describe: (rule) => `Security rule is ${rule.status}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const done = outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+        return { structured: { ...done.structured, rule: result.value ? formatSecurityRule(result.value) : null }, summary: done.summary };
+    },
+});

package/dist/tools/shared/async.js

@@ -50,6 +50,10 @@ export function phaseOf(status, lists) {
         return lists.completed.includes(value) ? 'completed' : 'pending';
     return lists.pending?.includes(value) ? 'pending' : 'completed';
 }
+/** The common lifecycle of installable resources (rules, keys, jobs…): installing → installed → removing. */
+export function installationPhase(status) {
+    return phaseOf(status, { pending: ['installing', 'updating', 'removing'], failed: ['failed'] });
+}
 /**
  * Polls every POLL_INTERVAL_MS until the phase is final or the timeout expires,
  * sending MCP progress notifications. Read errors stop the wait without failing

package/dist/tools/shared/read.js

@@ -1,6 +1,18 @@
-import { flattenSingle } from '../../forge/jsonapi.js';
+import { flattenCollection, flattenSingle } from '../../forge/jsonapi.js';
 /** Reads a single JSON:API resource and flattens it. */
 export async function readResource(client, path, signal) {
     const response = await client.get(path, { signal });
     return flattenSingle(response.data);
 }
+/**
+ * First page of a collection, newest first: used to spot the item created by a
+ * write that returns no body (remember the IDs before, find the new one after).
+ */
+export async function listNewestFirst(client, path, signal, filter = {}) {
+    const response = await client.get(path, { query: { filter, sort: ['-created_at'], page: { size: 100 } }, signal });
+    return flattenCollection(response.data).items;
+}
+/** Returns the first item whose ID is not in `known`, or null. */
+export function findNew(items, known) {
+    return items.find((item) => !known.has(item.id)) ?? null;
+}

package/dist/tools/ssh-keys/add-ssh-key.js

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { installationPhase, operationOutput, outcome, waitFor, waitInput } from '../shared/async.js';
+import { findNew, listNewestFirst } from '../shared/read.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { formatSshKey, sshKeyOutput, sshKeysPath } from './shared.js';
+const CHECK_WITH = 'forge_list_ssh_keys';
+export const addSshKey = defineTool({
+    name: 'forge_add_ssh_key',
+    title: 'Add SSH key',
+    description: "Authorize a public SSH key to log in to a server (added to the user's authorized_keys). Waits until it is installed unless `wait` is false.",
+    toolset: 'security',
+    operations: ['organizations.servers.ssh-keys.store', 'organizations.servers.ssh-keys.index'],
+    permissions: ['server:create-keys', 'server:view'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    async: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        name: z.string().min(1).describe('Name of the key, e.g. "Jane laptop".'),
+        key: z
+            .string()
+            .trim()
+            .regex(/^(ssh-|ecdsa-|sk-)/, 'Pass the public key (it starts with ssh-ed25519, ssh-rsa, ecdsa-…), never a private key.')
+            .describe('Public key, e.g. "ssh-ed25519 AAAA… jane@laptop".'),
+        user: z.string().min(1).optional().describe('Server user the key logs in as (default: forge).'),
+        ...waitInput(60),
+    },
+    outputSchema: {
+        ...operationOutput,
+        ssh_key: sshKeyOutput.nullable().describe('The new key once it shows up.'),
+    },
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const base = sshKeysPath(organization(args.organization), args.server);
+        // Forge returns no body: remember the existing keys with this name to spot the new one.
+        const lookup = () => listNewestFirst(client, base, signal, { name: args.name });
+        const existing = args.wait ? new Set((await lookup()).map((key) => key.id)) : undefined;
+        await client.post(base, { body: { name: args.name, key: args.key, user: args.user }, signal });
+        const action = `add the SSH key ${args.name}`;
+        if (!existing) {
+            return {
+                structured: { status: 'queued', check_with: CHECK_WITH, ssh_key: null },
+                summary: `Forge accepted the request to ${action}; it runs in the background. Check it with ${CHECK_WITH}.`,
+            };
+        }
+        const result = await waitFor({
+            poll: async () => findNew(await lookup(), existing),
+            phase: (key) => (key ? installationPhase(key.status) : 'pending'),
+            describe: (key) => (key ? `SSH key is ${key.status}` : 'Waiting for the key to appear'),
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        const sshKey = result.value ? formatSshKey(result.value) : null;
+        const done = outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds, detail: sshKey ? `Key ID: ${sshKey.id}.` : undefined });
+        return { structured: { ...done.structured, ssh_key: sshKey }, summary: done.summary };
+    },
+});

package/dist/tools/ssh-keys/delete-ssh-key.js

@@ -0,0 +1,41 @@
+import { defineTool } from '../define-tool.js';
+import { operationOutput, orGone, outcome, queued, waitFor, waitInput } from '../shared/async.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, serverInput } from '../shared/schemas.js';
+import { sshKeyInput, sshKeysPath } from './shared.js';
+const CHECK_WITH = 'forge_list_ssh_keys';
+export const deleteSshKey = defineTool({
+    name: 'forge_delete_ssh_key',
+    title: 'Delete SSH key',
+    description: 'Revoke an SSH key: it can no longer log in to the server.',
+    toolset: 'security',
+    operations: ['organizations.servers.ssh-keys.destroy', 'organizations.servers.ssh-keys.show'],
+    permissions: ['server:delete-keys', 'server:view'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    async: true,
+    notFoundHint: 'Check the key ID with forge_list_ssh_keys.',
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        key: sshKeyInput,
+        ...waitInput(60),
+    },
+    outputSchema: operationOutput,
+    async handler(args, { client, organization, signal, sleep, progress }) {
+        const path = `${sshKeysPath(organization(args.organization), args.server)}/${encodeURIComponent(String(args.key))}`;
+        await client.delete(path, { signal });
+        const action = `delete SSH key ${args.key}`;
+        if (!args.wait)
+            return queued(action, CHECK_WITH);
+        const result = await waitFor({
+            poll: () => orGone(() => readResource(client, path, signal)),
+            phase: (key) => (key === null ? 'completed' : 'pending'),
+            describe: (key) => `SSH key is ${key?.status ?? 'removing'}`,
+            timeoutSeconds: args.timeout_seconds,
+            context: { sleep, progress },
+        });
+        return outcome(result, { action, checkWith: CHECK_WITH, timeoutSeconds: args.timeout_seconds });
+    },
+});

package/dist/tools/ssh-keys/get-server-public-key.js

@@ -0,0 +1,27 @@
+import { defineTool } from '../define-tool.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, pick, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT, serverPath } from '../servers/shared.js';
+import { serverKeyOutput } from './shared.js';
+export const getServerPublicKey = defineTool({
+    name: 'forge_get_server_public_key',
+    title: 'Get server public key',
+    description: "The server's own public SSH key: add it to a Git provider or to another server so this server can connect to them.",
+    toolset: 'security',
+    operations: ['organizations.servers.key.show'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+    },
+    outputSchema: serverKeyOutput.shape,
+    async handler(args, { client, organization, signal }) {
+        const key = pick(await readResource(client, `${serverPath(organization(args.organization), args.server)}/key`, signal), [
+            'public_key',
+            'fingerprint',
+        ]);
+        return { structured: key, summary: `Server public key fingerprint: ${key.fingerprint}.` };
+    },
+});

package/dist/tools/ssh-keys/list-ssh-keys.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { readResource } from '../shared/read.js';
+import { organizationInput, paginationInput, paginationOutput, paginationSummary, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT } from '../servers/shared.js';
+import { formatSshKey, sshKeyInput, sshKeyOutput, sshKeysPath } from './shared.js';
+export const listSshKeys = defineTool({
+    name: 'forge_list_ssh_keys',
+    title: 'List SSH keys',
+    description: 'List the SSH keys authorized to log in to a server (name, user, status), or get one with `key`. Key contents are not returned.',
+    toolset: 'security',
+    operations: ['organizations.servers.ssh-keys.index', 'organizations.servers.ssh-keys.show'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+        key: sshKeyInput.optional().describe('Return only this key.'),
+        name: z.string().min(1).optional().describe('Filter by name.'),
+        user: z.string().min(1).optional().describe('Filter by server user.'),
+        ...paginationInput,
+    },
+    outputSchema: {
+        keys: z.array(sshKeyOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, organization, signal }) {
+        const base = sshKeysPath(organization(args.organization), args.server);
+        if (args.key !== undefined) {
+            const key = formatSshKey(await readResource(client, `${base}/${encodeURIComponent(String(args.key))}`, signal));
+            return { structured: { keys: [key], next_cursor: null, has_more: false }, summary: `SSH key ${key.name} (${key.user}) is ${key.status}.` };
+        }
+        const response = await client.get(base, {
+            query: { filter: { name: args.name, user: args.user }, page: { size: args.page_size, cursor: args.cursor } },
+            signal,
+        });
+        const page = flattenCollection(response.data);
+        const keys = page.items.map(formatSshKey);
+        return {
+            structured: { keys, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: keys.length === 0
+                ? 'No SSH keys found.'
+                : `Found ${keys.length} SSH key(s): ${keys.map((k) => `${k.name} → ${k.user} (${k.id})`).join(', ')}.${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

package/dist/tools/ssh-keys/regenerate-server-key.js

@@ -0,0 +1,30 @@
+import { defineTool } from '../define-tool.js';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { organizationInput, pick, serverInput } from '../shared/schemas.js';
+import { SERVER_NOT_FOUND_HINT, serverPath } from '../servers/shared.js';
+import { serverKeyOutput } from './shared.js';
+export const regenerateServerKey = defineTool({
+    name: 'forge_regenerate_server_key',
+    title: 'Regenerate server key',
+    description: "Replace the server's own SSH key pair. Everything that trusted the old public key (Git providers, other servers) rejects the server until the new public key is added there: confirm with the user first.",
+    toolset: 'security',
+    operations: ['organizations.servers.key.update'],
+    permissions: ['server:delete'],
+    readOnly: false,
+    destructive: true,
+    idempotent: false,
+    notFoundHint: SERVER_NOT_FOUND_HINT,
+    inputSchema: {
+        organization: organizationInput,
+        server: serverInput,
+    },
+    outputSchema: serverKeyOutput.shape,
+    async handler(args, { client, organization, signal }) {
+        const response = await client.put(`${serverPath(organization(args.organization), args.server)}/key`, { signal });
+        const key = pick(flattenSingle(response.data), ['public_key', 'fingerprint']);
+        return {
+            structured: key,
+            summary: `Generated a new key pair (fingerprint ${key.fingerprint}). Add the new public key wherever the old one was trusted.`,
+        };
+    },
+});

package/dist/tools/ssh-keys/shared.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { idInput, pick } from '../shared/schemas.js';
+import { serverPath } from '../servers/shared.js';
+export function sshKeysPath(org, server) {
+    return `${serverPath(org, server)}/ssh-keys`;
+}
+export const sshKeyInput = idInput('SSH key ID. Use forge_list_ssh_keys to find it.');
+const FIELDS = ['id', 'name', 'user', 'status', 'created_by', 'created_at', 'updated_at'];
+export const sshKeyOutput = z.looseObject({
+    id: z.string(),
+    name: z.string().nullable(),
+    user: z.string().nullable().describe('Server user the key logs in as.'),
+    status: z.string().nullable().describe('e.g. installing, installed, removing.'),
+    created_by: z.number().nullable().describe('Forge user who added the key.'),
+    created_at: z.string().nullable(),
+    updated_at: z.string().nullable(),
+});
+export function formatSshKey(flat) {
+    return pick(flat, FIELDS);
+}
+export const serverKeyOutput = z.looseObject({
+    public_key: z.string().nullable().describe('Add it where the server must authenticate (Git providers, other servers).'),
+    fingerprint: z.string().nullable(),
+});

package/package.json

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