@francescomalatesta/laravel-forge-mcp 0.11.0 → 0.13.0

package/README.md

@@ -106,6 +106,11 @@ 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_list_package_credentials` | sites | Credentials for private Composer repositories and npm registries (secrets hidden) |
+| `forge_set_package_credentials` | sites | Add or replace Composer or npm credentials |
+| `forge_delete_package_credentials` | sites | Remove Composer or npm credentials |
+| `forge_get_load_balancer` | sites | Servers a load-balanced site sends traffic to |
+| `forge_update_load_balancer` | sites | Replace the nodes and balancing method, take nodes out of rotation |
 | `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) |
@@ -113,6 +118,10 @@ npm run build
 | `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_nginx_templates` | servers | Custom Nginx templates for new sites |
+| `forge_create_nginx_template` | servers | Save an Nginx template |
+| `forge_update_nginx_template` | servers | Rename or replace an Nginx template |
+| `forge_delete_nginx_template` | servers | Delete an Nginx template |
 | `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 |
@@ -174,6 +183,31 @@ 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_list_heartbeats` | monitoring | Heartbeats of a site and whether they are missing |
+| `forge_create_heartbeat` | monitoring | Alert when a scheduled task stops pinging |
+| `forge_update_heartbeat` | monitoring | Change name, schedule or grace period |
+| `forge_delete_heartbeat` | monitoring | Delete a heartbeat |
+| `forge_list_monitors` | monitoring | CPU, disk and memory monitors and their alert state |
+| `forge_create_monitor` | monitoring | Alert by email when a metric crosses a threshold |
+| `forge_delete_monitor` | monitoring | Remove a monitor |
 | `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/heartbeats/create-heartbeat.js

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { SITE_NOT_FOUND_HINT, siteScopeInput } from '../shared/site-scope.js';
+import { REDACTED } from '../shared/secrets.js';
+import { cronInput, formatHeartbeat, frequencyInput, gracePeriodInput, heartbeatOutput, heartbeatsPath, scheduleBody } from './shared.js';
+export const createHeartbeat = defineTool({
+    name: 'forge_create_heartbeat',
+    title: 'Create heartbeat',
+    description: 'Create a heartbeat: Forge alerts when the job does not request its ping URL on schedule (e.g. `->thenPing($url)` on a Laravel scheduled task). Pass `frequency` or `cron`.',
+    toolset: 'monitoring',
+    operations: ['organizations.servers.sites.heartbeats.store'],
+    permissions: ['site:manage-heartbeats'],
+    readOnly: false,
+    destructive: false,
+    idempotent: false,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        name: z.string().min(1).max(255).describe('Name, e.g. "Nightly reports".'),
+        frequency: frequencyInput.optional(),
+        cron: cronInput.optional(),
+        grace_period: gracePeriodInput.default(5),
+    },
+    outputSchema: {
+        heartbeat: heartbeatOutput,
+    },
+    async handler(args, { client, config, organization, signal }) {
+        const response = await client.post(heartbeatsPath(organization(args.organization), args.server, args.site), {
+            body: { name: args.name, grace_period: args.grace_period, ...scheduleBody(args.frequency, args.cron) },
+            signal,
+        });
+        const heartbeat = formatHeartbeat(flattenSingle(response.data), config.allowSecrets);
+        return {
+            structured: { heartbeat },
+            summary: `Created heartbeat ${heartbeat.name} (ID ${heartbeat.id}).${heartbeat.ping_url === REDACTED ? ' Its ping URL is hidden: enable FORGE_ALLOW_SECRETS or copy it from the Forge dashboard.' : ` Ping URL: ${heartbeat.ping_url}`}`,
+        };
+    },
+});

package/dist/tools/heartbeats/delete-heartbeat.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { siteScopeInput } from '../shared/site-scope.js';
+import { HEARTBEAT_NOT_FOUND_HINT, heartbeatInput, heartbeatsPath } from './shared.js';
+export const deleteHeartbeat = defineTool({
+    name: 'forge_delete_heartbeat',
+    title: 'Delete heartbeat',
+    description: 'Delete a heartbeat: Forge stops alerting when the job does not ping.',
+    toolset: 'monitoring',
+    operations: ['organizations.servers.sites.heartbeats.destroy'],
+    permissions: ['site:manage-heartbeats'],
+    readOnly: false,
+    destructive: true,
+    idempotent: true,
+    notFoundHint: HEARTBEAT_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        heartbeat: heartbeatInput,
+    },
+    outputSchema: {
+        deleted: z.boolean(),
+    },
+    async handler(args, { client, organization, signal }) {
+        await client.delete(`${heartbeatsPath(organization(args.organization), args.server, args.site)}/${encodeURIComponent(String(args.heartbeat))}`, {
+            signal,
+        });
+        return { structured: { deleted: true }, summary: `Deleted heartbeat ${args.heartbeat}.` };
+    },
+});

package/dist/tools/heartbeats/list-heartbeats.js

@@ -0,0 +1,44 @@
+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 { formatHeartbeat, heartbeatInput, heartbeatOutput, heartbeatsPath } from './shared.js';
+export const listHeartbeats = defineTool({
+    name: 'forge_list_heartbeats',
+    title: 'List heartbeats',
+    description: 'List the heartbeats of a site (scheduled tasks that must ping Forge regularly) with their status: missing means the job stopped running. Get one with `heartbeat`.',
+    toolset: 'monitoring',
+    operations: ['organizations.servers.sites.heartbeats.index', 'organizations.servers.sites.heartbeats.show'],
+    permissions: ['server:view'],
+    readOnly: true,
+    notFoundHint: SITE_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        heartbeat: heartbeatInput.optional().describe('Return only this heartbeat.'),
+        ...paginationInput,
+    },
+    outputSchema: {
+        heartbeats: z.array(heartbeatOutput),
+        ...paginationOutput,
+    },
+    async handler(args, { client, config, organization, signal }) {
+        const base = heartbeatsPath(organization(args.organization), args.server, args.site);
+        const format = (flat) => formatHeartbeat(flat, config.allowSecrets);
+        if (args.heartbeat !== undefined) {
+            const heartbeat = format(await readResource(client, `${base}/${encodeURIComponent(String(args.heartbeat))}`, signal));
+            return { structured: { heartbeats: [heartbeat], next_cursor: null, has_more: false }, summary: `Heartbeat ${heartbeat.name} is ${heartbeat.status}.` };
+        }
+        const response = await client.get(base, { query: { page: { size: args.page_size, cursor: args.cursor } }, signal });
+        const page = flattenCollection(response.data);
+        const heartbeats = page.items.map(format);
+        const missing = heartbeats.filter((heartbeat) => heartbeat.status === 'missing');
+        return {
+            structured: { heartbeats, next_cursor: page.nextCursor, has_more: page.nextCursor !== null },
+            summary: heartbeats.length === 0
+                ? 'No heartbeats found.'
+                : `Found ${heartbeats.length} heartbeat(s)${missing.length > 0 ? `; missing: ${missing.map((h) => h.name).join(', ')}` : ''}.${paginationSummary(page.nextCursor)}`,
+        };
+    },
+});

package/dist/tools/heartbeats/shared.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { ToolInputError } from '../errors.js';
+import { redact } from '../shared/secrets.js';
+import { idInput, pick } from '../shared/schemas.js';
+import { sitePath } from '../shared/site-scope.js';
+export function heartbeatsPath(org, server, site) {
+    return `${sitePath(org, server, site)}/heartbeats`;
+}
+export const heartbeatInput = idInput('Heartbeat ID. Use forge_list_heartbeats to find it.');
+export const HEARTBEAT_NOT_FOUND_HINT = 'Check the heartbeat ID with forge_list_heartbeats.';
+/** Minutes between expected pings (-1 = custom cron). */
+const FREQUENCIES = [1, 5, 10, 30, 60, 1440, 10080, 312480];
+const GRACE_PERIODS = [1, 2, 5, 10, 30, 60];
+export const frequencyInput = z.literal(FREQUENCIES).describe('Minutes between expected pings: 1, 5, 10, 30, 60, 1440 (daily), 10080 (weekly) or 312480. Use `cron` instead for other schedules.');
+export const cronInput = z.string().min(1).describe('Cron expression of the expected pings, e.g. "0 3 * * *" (instead of `frequency`).');
+export const gracePeriodInput = z.literal(GRACE_PERIODS).describe('Minutes of delay tolerated before the heartbeat is reported missing: 1, 2, 5, 10, 30 or 60.');
+/** Maps `frequency` / `cron` to the API fields (frequency -1 means custom). */
+export function scheduleBody(frequency, cron) {
+    if ((frequency === undefined) === (cron === undefined))
+        throw new ToolInputError('Pass either `frequency` or `cron`.');
+    return cron === undefined ? { frequency } : { frequency: -1, custom_frequency: cron };
+}
+const FIELDS = ['id', 'name', 'status', 'frequency', 'custom_frequency', 'grace_period', 'ping_url'];
+export const heartbeatOutput = z.looseObject({
+    id: z.string(),
+    name: z.string().nullable(),
+    status: z.string().nullable().describe('pending (no ping yet), beating or missing.'),
+    frequency: z.number().nullable().describe('Minutes between expected pings; -1 = custom cron.'),
+    custom_frequency: z.string().nullable(),
+    grace_period: z.number().nullable(),
+    ping_url: z.string().nullable().describe('URL the job must request after each run (hidden unless secrets are allowed).'),
+});
+/** The ping URL lets anyone report the job as alive: it is a secret. */
+export function formatHeartbeat(flat, allowSecrets) {
+    return redact(pick(flat, FIELDS), ['ping_url'], allowSecrets);
+}

package/dist/tools/heartbeats/update-heartbeat.js

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { flattenSingle } from '../../forge/jsonapi.js';
+import { defineTool } from '../define-tool.js';
+import { ToolInputError } from '../errors.js';
+import { readResource } from '../shared/read.js';
+import { siteScopeInput } from '../shared/site-scope.js';
+import { cronInput, formatHeartbeat, frequencyInput, gracePeriodInput, HEARTBEAT_NOT_FOUND_HINT, heartbeatInput, heartbeatOutput, heartbeatsPath, scheduleBody, } from './shared.js';
+export const updateHeartbeat = defineTool({
+    name: 'forge_update_heartbeat',
+    title: 'Update heartbeat',
+    description: 'Change the name, schedule (`frequency` or `cron`) or grace period of a heartbeat. Fields not passed keep their value.',
+    toolset: 'monitoring',
+    operations: ['organizations.servers.sites.heartbeats.update', 'organizations.servers.sites.heartbeats.show'],
+    permissions: ['site:manage-heartbeats', 'server:view'],
+    readOnly: false,
+    destructive: false,
+    idempotent: true,
+    notFoundHint: HEARTBEAT_NOT_FOUND_HINT,
+    inputSchema: {
+        ...siteScopeInput,
+        heartbeat: heartbeatInput,
+        name: z.string().min(1).max(255).optional().describe('New name.'),
+        frequency: frequencyInput.optional(),
+        cron: cronInput.optional(),
+        grace_period: gracePeriodInput.optional(),
+    },
+    outputSchema: {
+        heartbeat: heartbeatOutput,
+    },
+    async handler(args, { client, config, organization, signal }) {
+        if (args.name === undefined && args.frequency === undefined && args.cron === undefined && args.grace_period === undefined) {
+            throw new ToolInputError('Pass at least one setting to change.');
+        }
+        const path = `${heartbeatsPath(organization(args.organization), args.server, args.site)}/${encodeURIComponent(String(args.heartbeat))}`;
+        const current = await readResource(client, path, signal);
+        const schedule = args.frequency !== undefined || args.cron !== undefined
+            ? scheduleBody(args.frequency, args.cron)
+            : current.frequency === -1
+                ? { frequency: -1, custom_frequency: current.custom_frequency }
+                : { frequency: current.frequency };
+        const response = await client.put(path, {
+            body: { name: args.name ?? current.name, grace_period: args.grace_period ?? current.grace_period, ...schedule },
+            signal,
+        });
+        const heartbeat = formatHeartbeat(flattenSingle(response.data), config.allowSecrets);
+        return { structured: { heartbeat }, summary: `Updated heartbeat ${heartbeat.name}.` };
+    },
+});

package/dist/tools/load-balancing/get-load-balancer.js

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { defineTool } from '../define-tool.js';
+import { siteScopeInput } from '../shared/site-scope.js';
+import { nodeOutput, nodesPath, readNodes } from './shared.js';
+export const getLoadBalancer = defineTool({
+    name: 'forge_get_load_balancer',
+    title: 'Get load balancer nodes',
+    description: 'List the servers a load-balanced site sends traffic to, with weight, port and backup/down flags.',
+    toolset: 'sites',
+    operations: ['organizations.servers.sites.load-balancing-nodes.index'],
+    permissions: ['site:manage-project'],
+    readOnly: true,
+    notFoundHint: 'Check the load balancer server and site IDs with forge_list_sites.',
+    inputSchema: {
+        ...siteScopeInput,
+    },
+    outputSchema: {
+        nodes: z.array(nodeOutput),
+    },
+    async handler(args, { client, organization, signal }) {
+        const nodes = await readNodes(client, nodesPath(organization(args.organization), args.server, args.site), signal);
+        return {
+            structured: { nodes },
+            summary: nodes.length === 0
+                ? 'This site has no load balancing nodes.'
+                : `Traffic goes to server(s) ${nodes.map((n) => `${n.server_id} (weight ${n.weight}${n.down ? ', down' : ''}${n.backup ? ', backup' : ''})`).join(', ')}.`,
+        };
+    },
+});

package/dist/tools/load-balancing/shared.js

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import { flattenCollection } from '../../forge/jsonapi.js';
+import { sitePath } from '../shared/site-scope.js';
+export function nodesPath(org, server, site) {
+    return `${sitePath(org, server, site)}/load-balancing-nodes`;
+}
+export const nodeOutput = z.looseObject({
+    server_id: z.string().nullable().describe('Server receiving traffic.'),
+    port: z.number().nullable(),
+    weight: z.number().nullable().describe('Relative share of traffic.'),
+    backup: z.boolean().nullable().describe('Only used when the other servers are unavailable.'),
+    down: z.boolean().nullable().describe('Out of rotation.'),
+});
+export function formatNode(flat) {
+    return {
+        server_id: flat.server_id === undefined || flat.server_id === null ? null : String(flat.server_id),
+        port: flat.port ?? null,
+        weight: flat.weight ?? null,
+        backup: flat.backup ?? null,
+        down: flat.down ?? null,
+    };
+}
+/** Every node of the load balancer (one page of 100 covers any realistic pool). */
+export async function readNodes(client, path, signal) {
+    const response = await client.get(path, { query: { page: { size: 100 } }, signal });
+    return flattenCollection(response.data).items.map(formatNode);
+}