@studiometa/forge-mcp 0.0.1 → 0.2.0

package/dist/version-DaD5zvGh.js

@@ -0,0 +1,3470 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { HttpClient, isForgeApiError } from "@studiometa/forge-api";
+import { RESOURCES, activateCertificate, createAuditLogger, createBackupConfig, createCertificate, createCommand, createDaemon, createDatabase, createDatabaseUser, createFirewallRule, createMonitor, createNginxTemplate, createRecipe, createRedirectRule, createScheduledJob, createSecurityRule, createServer, createSite, createSshKey, deleteBackupConfig, deleteCertificate, deleteDaemon, deleteDatabase, deleteDatabaseUser, deleteFirewallRule, deleteMonitor, deleteNginxTemplate, deleteRecipe, deleteRedirectRule, deleteScheduledJob, deleteSecurityRule, deleteServer, deleteSite, deleteSshKey, deploySiteAndWait, getBackupConfig, getCertificate, getCommand, getDaemon, getDatabase, getDatabaseUser, getDeploymentOutput, getDeploymentScript, getEnv, getFirewallRule, getMonitor, getNginxConfig, getNginxTemplate, getRecipe, getRedirectRule, getScheduledJob, getSecurityRule, getServer, getSite, getSshKey, getUser, listBackupConfigs, listCertificates, listCommands, listDaemons, listDatabaseUsers, listDatabases, listDeployments, listFirewallRules, listMonitors, listNginxTemplates, listRecipes, listRedirectRules, listScheduledJobs, listSecurityRules, listServers, listSites, listSshKeys, rebootServer, restartDaemon, runRecipe, updateDeploymentScript, updateEnv, updateNginxConfig, updateNginxTemplate } from "@studiometa/forge-core";
+/**
+* MCP Server Instructions
+*
+* These instructions are sent to MCP clients during initialization
+* and used as context/hints for the LLM. Ensures the AI agent
+* knows how to properly use the Forge MCP server.
+*
+* The content is derived from skills/SKILL.md (without YAML frontmatter).
+*/
+var __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+* Load instructions from SKILL.md file.
+* Removes YAML frontmatter (content between --- markers).
+*/
+function loadInstructions() {
+	try {
+		return readFileSync(join(__dirname, "..", "skills", "SKILL.md"), "utf-8").replace(/^---\n[\s\S]*?\n---\n+/, "").trim();
+	} catch {
+		return "Laravel Forge MCP Server - Use the forge tool with resource and action parameters. Call action=\"help\" for documentation.";
+	}
+}
+const INSTRUCTIONS = loadInstructions();
+/**
+* Format a list of servers.
+*/
+function formatServerList(servers) {
+	if (servers.length === 0) return "No servers found.";
+	const lines = servers.map((s) => `• ${s.name} (ID: ${s.id}) — ${s.provider} ${s.region} — ${s.ip_address} — ${s.is_ready ? "ready" : "provisioning"}`);
+	return `${servers.length} server(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single server.
+*/
+function formatServer(server) {
+	return [
+		`Server: ${server.name} (ID: ${server.id})`,
+		`Provider: ${server.provider} (${server.region})`,
+		`IP: ${server.ip_address}`,
+		`PHP: ${server.php_version}`,
+		`Ubuntu: ${server.ubuntu_version}`,
+		`Status: ${server.is_ready ? "ready" : "provisioning"}`,
+		`Created: ${server.created_at}`
+	].join("\n");
+}
+/**
+* Format a list of sites.
+*/
+function formatSiteList(sites, serverId) {
+	if (sites.length === 0) return serverId ? `No sites on server ${serverId}.` : "No sites found.";
+	const lines = sites.map((s) => `• ${s.name} (ID: ${s.id}) — ${s.project_type} — ${s.status}`);
+	return `${serverId ? `${sites.length} site(s) on server ${serverId}:` : `${sites.length} site(s):`}\n${lines.join("\n")}`;
+}
+/**
+* Format a single site.
+*/
+function formatSite(site) {
+	return [
+		`Site: ${site.name} (ID: ${site.id})`,
+		`Type: ${site.project_type}`,
+		`Directory: ${site.directory}`,
+		`Repository: ${site.repository ?? "none"}`,
+		`Branch: ${site.repository_branch ?? "none"}`,
+		`Status: ${site.status}`,
+		`Deploy status: ${site.deployment_status ?? "none"}`,
+		`Quick deploy: ${site.quick_deploy ? "enabled" : "disabled"}`,
+		`PHP: ${site.php_version}`,
+		`Created: ${site.created_at}`
+	].join("\n");
+}
+/**
+* Format a list of databases.
+*/
+function formatDatabaseList(databases) {
+	if (databases.length === 0) return "No databases found.";
+	const lines = databases.map((d) => `• ${d.name} (ID: ${d.id}) — ${d.status}`);
+	return `${databases.length} database(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single database.
+*/
+function formatDatabase(db) {
+	return `Database: ${db.name} (ID: ${db.id})\nStatus: ${db.status}\nCreated: ${db.created_at}`;
+}
+/**
+* Format a list of database users.
+*/
+function formatDatabaseUserList(users) {
+	if (users.length === 0) return "No database users found.";
+	const lines = users.map((u) => `• ${u.name} (ID: ${u.id}) — ${u.status}`);
+	return `${users.length} database user(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single database user.
+*/
+function formatDatabaseUser(user) {
+	return [
+		`Database User: ${user.name} (ID: ${user.id})`,
+		`Status: ${user.status}`,
+		`Databases: ${user.databases.length > 0 ? user.databases.join(", ") : "none"}`,
+		`Created: ${user.created_at}`
+	].join("\n");
+}
+/**
+* Format a list of deployments.
+*/
+function formatDeploymentList(deployments) {
+	if (deployments.length === 0) return "No deployments found.";
+	const lines = deployments.map((d) => `• #${d.id} — ${d.status} — ${d.commit_hash?.slice(0, 7) ?? "no commit"} — ${d.started_at}`);
+	return `${deployments.length} deployment(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a deployment action result.
+*
+* When a `DeployResult` is provided the output includes status, elapsed time,
+* and the deployment log.  When called with just IDs (legacy) it falls back to
+* the simple confirmation message so existing tests keep passing.
+*/
+function formatDeployAction(siteId, serverId, result) {
+	if (!result) return `Deployment triggered for site ${siteId} on server ${serverId}.`;
+	const elapsedSec = (result.elapsed_ms / 1e3).toFixed(1);
+	const lines = [`Deployment ${result.status === "success" ? "✓ succeeded" : "✗ failed"} for site ${siteId} on server ${serverId} (${elapsedSec}s).`];
+	if (result.log) lines.push("", "Deployment log:", result.log);
+	return lines.join("\n");
+}
+/**
+* Format deployment script content.
+*/
+function formatDeploymentScript(script) {
+	return `Deployment script:\n${script}`;
+}
+/**
+* Format deployment output.
+*/
+function formatDeploymentOutput(deploymentId, output) {
+	return `Deployment ${deploymentId} output:\n${output}`;
+}
+/**
+* Format a deployment script update confirmation.
+*/
+function formatDeploymentScriptUpdated(siteId, serverId) {
+	return `Deployment script updated for site ${siteId} on server ${serverId}.`;
+}
+/**
+* Format a list of certificates.
+*/
+function formatCertificateList(certificates) {
+	if (certificates.length === 0) return "No certificates found.";
+	const lines = certificates.map((c) => `• ${c.domain} (ID: ${c.id}) — ${c.type} — ${c.active ? "active" : "inactive"} — ${c.status}`);
+	return `${certificates.length} certificate(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single certificate.
+*/
+function formatCertificate(cert) {
+	return `Certificate: ${cert.domain} (ID: ${cert.id})\nType: ${cert.type}\nStatus: ${cert.status}\nActive: ${cert.active}`;
+}
+/**
+* Format a list of daemons.
+*/
+function formatDaemonList(daemons) {
+	if (daemons.length === 0) return "No daemons found.";
+	const lines = daemons.map((d) => `• ${d.command} (ID: ${d.id}) — user: ${d.user} — ${d.status}`);
+	return `${daemons.length} daemon(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single daemon.
+*/
+function formatDaemon(daemon) {
+	return `Daemon: ${daemon.command} (ID: ${daemon.id})\nUser: ${daemon.user}\nProcesses: ${daemon.processes}\nStatus: ${daemon.status}`;
+}
+/**
+* Format a list of firewall rules.
+*/
+function formatFirewallRuleList(rules) {
+	if (rules.length === 0) return "No firewall rules found.";
+	const lines = rules.map((r) => `• ${r.name} (ID: ${r.id}) — port: ${r.port} — ${r.ip_address} — ${r.status}`);
+	return `${rules.length} firewall rule(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single firewall rule.
+*/
+function formatFirewallRule(rule) {
+	return `Firewall Rule: ${rule.name} (ID: ${rule.id})\nPort: ${rule.port}\nType: ${rule.type}\nIP: ${rule.ip_address}\nStatus: ${rule.status}`;
+}
+/**
+* Format a list of monitors.
+*/
+function formatMonitorList(monitors) {
+	if (monitors.length === 0) return "No monitors found.";
+	const lines = monitors.map((m) => `• ${m.type} ${m.operator} ${m.threshold} (ID: ${m.id}) — ${m.state}`);
+	return `${monitors.length} monitor(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single monitor.
+*/
+function formatMonitor(monitor) {
+	return `Monitor: ${monitor.type} ${monitor.operator} ${monitor.threshold} (ID: ${monitor.id})\nState: ${monitor.state}\nMinutes: ${monitor.minutes}`;
+}
+/**
+* Format a list of SSH keys.
+*/
+function formatSshKeyList(keys) {
+	if (keys.length === 0) return "No SSH keys found.";
+	const lines = keys.map((k) => `• ${k.name} (ID: ${k.id}) — ${k.status}`);
+	return `${keys.length} SSH key(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single SSH key.
+*/
+function formatSshKey(key) {
+	return `SSH Key: ${key.name} (ID: ${key.id})\nStatus: ${key.status}\nCreated: ${key.created_at}`;
+}
+/**
+* Format a list of scheduled jobs.
+*/
+function formatScheduledJobList(jobs) {
+	if (jobs.length === 0) return "No scheduled jobs found.";
+	const lines = jobs.map((j) => `• ${j.command} (ID: ${j.id}) — ${j.frequency} — ${j.status} — user: ${j.user}`);
+	return `${jobs.length} scheduled job(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single scheduled job.
+*/
+function formatScheduledJob(job) {
+	return [
+		`Job: ${job.command} (ID: ${job.id})`,
+		`User: ${job.user}`,
+		`Frequency: ${job.frequency}`,
+		`Cron: ${job.cron}`,
+		`Status: ${job.status}`,
+		`Created: ${job.created_at}`
+	].join("\n");
+}
+/**
+* Format a list of security rules.
+*/
+function formatSecurityRuleList(rules) {
+	if (rules.length === 0) return "No security rules found.";
+	const lines = rules.map((r) => `• ${r.name} (ID: ${r.id}) — path: ${r.path ?? "/"}`);
+	return `${rules.length} security rule(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single security rule.
+*/
+function formatSecurityRule(rule) {
+	return `Security Rule: ${rule.name} (ID: ${rule.id})\nPath: ${rule.path ?? "/"}`;
+}
+/**
+* Format a list of redirect rules.
+*/
+function formatRedirectRuleList(rules) {
+	if (rules.length === 0) return "No redirect rules found.";
+	const lines = rules.map((r) => `• ${r.from} → ${r.to} (ID: ${r.id}) — ${r.type}`);
+	return `${rules.length} redirect rule(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single redirect rule.
+*/
+function formatRedirectRule(rule) {
+	return `Redirect Rule: ${rule.from} → ${rule.to} (ID: ${rule.id})\nType: ${rule.type}`;
+}
+/**
+* Format nginx configuration content.
+*/
+function formatNginxConfig(content) {
+	return `Nginx configuration:\n${content}`;
+}
+/**
+* Format a list of nginx templates.
+*/
+function formatNginxTemplateList(templates) {
+	if (templates.length === 0) return "No nginx templates found.";
+	const lines = templates.map((t) => `• ${t.name} (ID: ${t.id})`);
+	return `${templates.length} nginx template(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single nginx template.
+*/
+function formatNginxTemplate(template) {
+	return `Nginx Template: ${template.name} (ID: ${template.id})\n\n${template.content}`;
+}
+/**
+* Format a list of backup configurations.
+*/
+function formatBackupConfigList(backups) {
+	if (backups.length === 0) return "No backup configurations found.";
+	const lines = backups.map((b) => `• ${b.provider_name} (ID: ${b.id}) — ${b.frequency} — ${b.status} — last: ${b.last_backup_time ?? "never"}`);
+	return `${backups.length} backup config(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single backup configuration.
+*/
+function formatBackupConfig(backup) {
+	return [
+		`Backup Config: ${backup.provider_name} (ID: ${backup.id})`,
+		`Frequency: ${backup.frequency}`,
+		`Status: ${backup.status}`,
+		`Retention: ${backup.retention} backups`,
+		`Databases: ${backup.databases.map((d) => d.name).join(", ") || "none"}`,
+		`Last backup: ${backup.last_backup_time ?? "never"}`
+	].join("\n");
+}
+/**
+* Format a list of recipes.
+*/
+function formatRecipeList(recipes) {
+	if (recipes.length === 0) return "No recipes found.";
+	const lines = recipes.map((r) => `• ${r.name} (ID: ${r.id}) — user: ${r.user}`);
+	return `${recipes.length} recipe(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single recipe.
+*/
+function formatRecipe(recipe) {
+	return `Recipe: ${recipe.name} (ID: ${recipe.id})\nUser: ${recipe.user}\nScript:\n${recipe.script}`;
+}
+/**
+* Format a list of commands.
+*/
+function formatCommandList(commands) {
+	if (commands.length === 0) return "No commands found.";
+	const lines = commands.map((c) => `• #${c.id} — ${c.status} — ${c.user_name} — ${c.command.slice(0, 60)}`);
+	return `${commands.length} command(s):\n${lines.join("\n")}`;
+}
+/**
+* Format a single command.
+*/
+function formatCommand(command) {
+	return [
+		`Command #${command.id}`,
+		`Command: ${command.command}`,
+		`Status: ${command.status}`,
+		`User: ${command.user_name}`,
+		`Created: ${command.created_at}`
+	].join("\n");
+}
+/**
+* Format environment variables content.
+*/
+function formatEnv(content) {
+	return `Environment variables:\n${content}`;
+}
+/**
+* Format the authenticated user.
+*/
+function formatUser(user) {
+	return [
+		`User: ${user.name} (ID: ${user.id})`,
+		`Email: ${user.email}`,
+		`GitHub: ${user.connected_to_github ? "connected" : "not connected"}`,
+		`GitLab: ${user.connected_to_gitlab ? "connected" : "not connected"}`,
+		`2FA: ${user.two_factor_enabled ? "enabled" : "disabled"}`
+	].join("\n");
+}
+/**
+* Custom error classes for MCP server
+*
+* These provide structured error handling with LLM-friendly messages
+* that include guidance on how to resolve issues.
+*/
+/**
+* Error thrown when user input validation fails.
+* These errors should be returned to the user directly.
+*
+* Includes optional hints for how to resolve the issue.
+*/
+var UserInputError = class extends Error {
+	hints;
+	constructor(message, hints) {
+		super(message);
+		this.name = "UserInputError";
+		this.hints = hints;
+	}
+	/**
+	* Format error message with hints for LLM consumption
+	*/
+	toFormattedMessage() {
+		let msg = `**Input Error:** ${this.message}`;
+		if (this.hints && this.hints.length > 0) msg += "\n\n**Hints:**\n" + this.hints.map((h) => `- ${h}`).join("\n");
+		return msg;
+	}
+};
+/**
+* Check if an error is a UserInputError
+*/
+function isUserInputError(error) {
+	return error instanceof UserInputError;
+}
+/**
+* Create a successful result with both human-readable text and structured content.
+*
+* - When `data` is a string, `structuredContent` wraps it as `{ result: data }`.
+* - When `data` is an object/array, `structuredContent` is `{ result: data }` and
+*   the text representation is the JSON-serialized form.
+*/
+function jsonResult(data) {
+	return {
+		content: [{
+			type: "text",
+			text: typeof data === "string" ? data : JSON.stringify(data, null, 2)
+		}],
+		structuredContent: {
+			success: true,
+			result: data
+		}
+	};
+}
+/**
+* Validate an ID-like value (must be alphanumeric/dashes only).
+* Prevents path traversal via `../` in URL segments.
+*
+* @returns true if the value is safe, false otherwise.
+*/
+function sanitizeId(value) {
+	return /^[\w-]+$/.test(value);
+}
+/**
+* Create an error result with structured error content.
+*/
+function errorResult(message) {
+	return {
+		content: [{
+			type: "text",
+			text: `Error: ${message}`
+		}],
+		structuredContent: {
+			success: false,
+			error: message
+		},
+		isError: true
+	};
+}
+/**
+* Create a resource handler from configuration.
+*
+* Returns a function that routes actions to the correct executor,
+* validates required fields, and formats results.
+*
+* @example
+* ```typescript
+* export const handleDatabases = createResourceHandler({
+*   resource: 'databases',
+*   actions: ['list', 'get', 'create', 'delete'],
+*   requiredFields: {
+*     list: ['server_id'],
+*     get: ['server_id', 'id'],
+*     create: ['server_id', 'name'],
+*     delete: ['server_id', 'id'],
+*   },
+*   executors: {
+*     list: listDatabases,
+*     get: getDatabase,
+*     create: createDatabase,
+*     delete: deleteDatabase,
+*   },
+*   formatResult: (action, data) => {
+*     if (action === 'list') return formatDatabaseList(data);
+*     if (action === 'get') return formatDatabase(data);
+*     return 'Done.';
+*   },
+* });
+* ```
+*/
+function createResourceHandler(config) {
+	const { resource, actions, requiredFields = {}, executors, hints, mapOptions, formatResult } = config;
+	return async (action, args, ctx) => {
+		if (!actions.includes(action)) return errorResult(`Unknown action "${action}" for ${resource}. Valid actions: ${actions.join(", ")}.`);
+		const required = requiredFields[action] ?? [];
+		for (const field of required) if (!args[field]) return errorResult(`Missing required field: ${field}`);
+		for (const field of [
+			"id",
+			"server_id",
+			"site_id"
+		]) {
+			const value = args[field];
+			if (value !== void 0 && !sanitizeId(String(value))) return errorResult(`Invalid ${field}: "${value}". IDs must be alphanumeric.`);
+		}
+		const executor = executors[action];
+		if (!executor) return errorResult(`Action "${action}" is not yet implemented for ${resource}.`);
+		let options;
+		if (mapOptions) options = mapOptions(action, args);
+		else {
+			const { resource: _r, action: _a, compact: _c, ...rest } = args;
+			options = rest;
+		}
+		const result = await executor(options, ctx.executorContext);
+		if (result.data === void 0) return jsonResult(formatResult ? formatResult(action, void 0, args) : "Done.");
+		if (ctx.compact && formatResult) return jsonResult(formatResult(action, result.data, args));
+		if (action === "get" && ctx.includeHints && hints) {
+			/* v8 ignore start */
+			const id = args.id ?? args.server_id ?? "";
+			return jsonResult({
+				...result.data,
+				_hints: hints(result.data, String(id))
+			});
+		}
+		return jsonResult(result.data);
+	};
+}
+const handleBackups = createResourceHandler({
+	resource: "backups",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"delete"
+	],
+	requiredFields: {
+		list: ["server_id"],
+		get: ["server_id", "id"],
+		create: [
+			"server_id",
+			"provider",
+			"credentials",
+			"frequency",
+			"databases"
+		],
+		delete: ["server_id", "id"]
+	},
+	executors: {
+		list: listBackupConfigs,
+		get: getBackupConfig,
+		create: createBackupConfig,
+		delete: deleteBackupConfig
+	},
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatBackupConfigList(data);
+			case "get": return formatBackupConfig(data);
+			case "create": return formatBackupConfig(data);
+			case "delete": return `Backup config ${args.id} deleted.`;
+			default: return "Done.";
+		}
+	}
+});
+/**
+* Hints after getting a server.
+*/
+function getServerHints(serverId) {
+	return {
+		related_resources: [
+			{
+				resource: "sites",
+				description: "List sites on this server",
+				example: {
+					resource: "sites",
+					action: "list",
+					server_id: serverId
+				}
+			},
+			{
+				resource: "databases",
+				description: "List databases",
+				example: {
+					resource: "databases",
+					action: "list",
+					server_id: serverId
+				}
+			},
+			{
+				resource: "daemons",
+				description: "List background processes",
+				example: {
+					resource: "daemons",
+					action: "list",
+					server_id: serverId
+				}
+			},
+			{
+				resource: "firewall-rules",
+				description: "List firewall rules",
+				example: {
+					resource: "firewall-rules",
+					action: "list",
+					server_id: serverId
+				}
+			},
+			{
+				resource: "ssh-keys",
+				description: "List SSH keys on this server",
+				example: {
+					resource: "ssh-keys",
+					action: "list",
+					server_id: serverId
+				}
+			}
+		],
+		common_actions: [{
+			action: "Reboot server",
+			example: {
+				resource: "servers",
+				action: "reboot",
+				id: serverId
+			}
+		}]
+	};
+}
+/**
+* Hints after getting a site.
+*/
+function getSiteHints(serverId, siteId) {
+	return {
+		related_resources: [
+			{
+				resource: "deployments",
+				description: "List deployments for this site",
+				example: {
+					resource: "deployments",
+					action: "list",
+					server_id: serverId,
+					site_id: siteId
+				}
+			},
+			{
+				resource: "env",
+				description: "Get environment variables",
+				example: {
+					resource: "env",
+					action: "get",
+					server_id: serverId,
+					site_id: siteId
+				}
+			},
+			{
+				resource: "certificates",
+				description: "List SSL certificates",
+				example: {
+					resource: "certificates",
+					action: "list",
+					server_id: serverId,
+					site_id: siteId
+				}
+			},
+			{
+				resource: "nginx",
+				description: "Get nginx configuration",
+				example: {
+					resource: "nginx",
+					action: "get",
+					server_id: serverId,
+					site_id: siteId
+				}
+			}
+		],
+		common_actions: [{
+			action: "Deploy this site",
+			example: {
+				resource: "deployments",
+				action: "deploy",
+				server_id: serverId,
+				site_id: siteId
+			}
+		}]
+	};
+}
+/**
+* Hints after getting a database.
+*/
+function getDatabaseHints(serverId, databaseId) {
+	return {
+		related_resources: [{
+			resource: "databases",
+			description: "List all databases on this server",
+			example: {
+				resource: "databases",
+				action: "list",
+				server_id: serverId
+			}
+		}],
+		common_actions: [{
+			action: "Delete this database",
+			example: {
+				resource: "databases",
+				action: "delete",
+				server_id: serverId,
+				id: databaseId
+			}
+		}]
+	};
+}
+/**
+* Hints after getting a database user.
+*/
+function getDatabaseUserHints(serverId, userId) {
+	return {
+		related_resources: [{
+			resource: "database-users",
+			description: "List all database users on this server",
+			example: {
+				resource: "database-users",
+				action: "list",
+				server_id: serverId
+			}
+		}, {
+			resource: "databases",
+			description: "List databases on this server",
+			example: {
+				resource: "databases",
+				action: "list",
+				server_id: serverId
+			}
+		}],
+		common_actions: [{
+			action: "Delete this database user",
+			example: {
+				resource: "database-users",
+				action: "delete",
+				server_id: serverId,
+				id: userId
+			}
+		}]
+	};
+}
+/**
+* Hints after getting a daemon.
+*/
+function getDaemonHints(serverId, daemonId) {
+	return {
+		related_resources: [{
+			resource: "daemons",
+			description: "List all daemons on this server",
+			example: {
+				resource: "daemons",
+				action: "list",
+				server_id: serverId
+			}
+		}],
+		common_actions: [{
+			action: "Restart this daemon",
+			example: {
+				resource: "daemons",
+				action: "restart",
+				server_id: serverId,
+				id: daemonId
+			}
+		}, {
+			action: "Delete this daemon",
+			example: {
+				resource: "daemons",
+				action: "delete",
+				server_id: serverId,
+				id: daemonId
+			}
+		}]
+	};
+}
+/**
+* Hints after getting a certificate.
+*/
+function getCertificateHints(serverId, siteId, certificateId) {
+	return {
+		related_resources: [{
+			resource: "certificates",
+			description: "List all certificates for this site",
+			example: {
+				resource: "certificates",
+				action: "list",
+				server_id: serverId,
+				site_id: siteId
+			}
+		}],
+		common_actions: [{
+			action: "Activate this certificate",
+			example: {
+				resource: "certificates",
+				action: "activate",
+				server_id: serverId,
+				site_id: siteId,
+				id: certificateId
+			}
+		}, {
+			action: "Delete this certificate",
+			example: {
+				resource: "certificates",
+				action: "delete",
+				server_id: serverId,
+				site_id: siteId,
+				id: certificateId
+			}
+		}]
+	};
+}
+/**
+* Hints after getting a firewall rule.
+*/
+function getFirewallRuleHints(serverId, ruleId) {
+	return {
+		related_resources: [{
+			resource: "firewall-rules",
+			description: "List all firewall rules on this server",
+			example: {
+				resource: "firewall-rules",
+				action: "list",
+				server_id: serverId
+			}
+		}],
+		common_actions: [{
+			action: "Delete this firewall rule",
+			example: {
+				resource: "firewall-rules",
+				action: "delete",
+				server_id: serverId,
+				id: ruleId
+			}
+		}]
+	};
+}
+/**
+* Hints after getting an SSH key.
+*/
+function getSshKeyHints(serverId, keyId) {
+	return {
+		related_resources: [{
+			resource: "ssh-keys",
+			description: "List all SSH keys on this server",
+			example: {
+				resource: "ssh-keys",
+				action: "list",
+				server_id: serverId
+			}
+		}],
+		common_actions: [{
+			action: "Delete this SSH key",
+			example: {
+				resource: "ssh-keys",
+				action: "delete",
+				server_id: serverId,
+				id: keyId
+			}
+		}]
+	};
+}
+/**
+* Hints after getting a recipe.
+*/
+function getRecipeHints(recipeId) {
+	return {
+		related_resources: [{
+			resource: "recipes",
+			description: "List all recipes",
+			example: {
+				resource: "recipes",
+				action: "list"
+			}
+		}],
+		common_actions: [{
+			action: "Run this recipe on servers",
+			example: {
+				resource: "recipes",
+				action: "run",
+				id: recipeId,
+				servers: []
+			}
+		}, {
+			action: "Delete this recipe",
+			example: {
+				resource: "recipes",
+				action: "delete",
+				id: recipeId
+			}
+		}]
+	};
+}
+/**
+* Hints after getting an nginx template.
+*/
+function getNginxTemplateHints(serverId, templateId) {
+	return {
+		related_resources: [{
+			resource: "nginx-templates",
+			description: "List all nginx templates on this server",
+			example: {
+				resource: "nginx-templates",
+				action: "list",
+				server_id: serverId
+			}
+		}],
+		common_actions: [{
+			action: "Update this nginx template",
+			example: {
+				resource: "nginx-templates",
+				action: "update",
+				server_id: serverId,
+				id: templateId,
+				content: "<nginx config content>"
+			}
+		}, {
+			action: "Delete this nginx template",
+			example: {
+				resource: "nginx-templates",
+				action: "delete",
+				server_id: serverId,
+				id: templateId
+			}
+		}]
+	};
+}
+const handleCertificates = createResourceHandler({
+	resource: "certificates",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"delete",
+		"activate"
+	],
+	requiredFields: {
+		list: ["server_id", "site_id"],
+		get: [
+			"server_id",
+			"site_id",
+			"id"
+		],
+		create: [
+			"server_id",
+			"site_id",
+			"domain"
+		],
+		delete: [
+			"server_id",
+			"site_id",
+			"id"
+		],
+		activate: [
+			"server_id",
+			"site_id",
+			"id"
+		]
+	},
+	executors: {
+		list: listCertificates,
+		get: getCertificate,
+		create: createCertificate,
+		delete: deleteCertificate,
+		activate: activateCertificate
+	},
+	hints: (data, id) => {
+		const cert = data;
+		return getCertificateHints(String(cert.server_id), String(cert.site_id), id);
+	},
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatCertificateList(data);
+			case "get": return formatCertificate(data);
+			case "create": return formatCertificate(data);
+			case "delete": return `Certificate ${args.id} deleted.`;
+			case "activate": return `Certificate ${args.id} activated.`;
+			default: return "Done.";
+		}
+	}
+});
+const handleCommands = createResourceHandler({
+	resource: "commands",
+	actions: [
+		"list",
+		"get",
+		"create"
+	],
+	requiredFields: {
+		list: ["server_id", "site_id"],
+		get: [
+			"server_id",
+			"site_id",
+			"id"
+		],
+		create: [
+			"server_id",
+			"site_id",
+			"command"
+		]
+	},
+	executors: {
+		list: listCommands,
+		get: getCommand,
+		create: createCommand
+	},
+	formatResult: (action, data) => {
+		switch (action) {
+			case "list": return formatCommandList(data);
+			case "get": return formatCommand(data);
+			case "create": return formatCommand(data);
+			default: return "Done.";
+		}
+	}
+});
+const handleDaemons = createResourceHandler({
+	resource: "daemons",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"delete",
+		"restart"
+	],
+	requiredFields: {
+		list: ["server_id"],
+		get: ["server_id", "id"],
+		create: ["server_id", "command"],
+		delete: ["server_id", "id"],
+		restart: ["server_id", "id"]
+	},
+	executors: {
+		list: listDaemons,
+		get: getDaemon,
+		create: createDaemon,
+		delete: deleteDaemon,
+		restart: restartDaemon
+	},
+	hints: (data, id) => {
+		const daemon = data;
+		return getDaemonHints(String(daemon.server_id), id);
+	},
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatDaemonList(data);
+			case "get": return formatDaemon(data);
+			case "create": return formatDaemon(data);
+			case "delete": return `Daemon ${args.id} deleted.`;
+			case "restart": return `Daemon ${args.id} restarted.`;
+			default: return "Done.";
+		}
+	}
+});
+const handleDatabases = createResourceHandler({
+	resource: "databases",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"delete"
+	],
+	requiredFields: {
+		list: ["server_id"],
+		get: ["server_id", "id"],
+		create: ["server_id", "name"],
+		delete: ["server_id", "id"]
+	},
+	executors: {
+		list: listDatabases,
+		get: getDatabase,
+		create: createDatabase,
+		delete: deleteDatabase
+	},
+	hints: (data, id) => {
+		const db = data;
+		return getDatabaseHints(String(db.server_id), id);
+	},
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatDatabaseList(data);
+			case "get": return formatDatabase(data);
+			case "create": return formatDatabase(data);
+			case "delete": return `Database ${args.id} deleted.`;
+			default: return "Done.";
+		}
+	}
+});
+const handleDatabaseUsers = createResourceHandler({
+	resource: "database-users",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"delete"
+	],
+	requiredFields: {
+		list: ["server_id"],
+		get: ["server_id", "id"],
+		create: [
+			"server_id",
+			"name",
+			"password"
+		],
+		delete: ["server_id", "id"]
+	},
+	executors: {
+		list: listDatabaseUsers,
+		get: getDatabaseUser,
+		create: createDatabaseUser,
+		delete: deleteDatabaseUser
+	},
+	hints: (data, id) => {
+		const user = data;
+		return getDatabaseUserHints(String(user.server_id), id);
+	},
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatDatabaseUserList(data);
+			case "get": return formatDatabaseUser(data);
+			case "create": return formatDatabaseUser(data);
+			case "delete": return `Database user ${args.id} deleted.`;
+			default: return "Done.";
+		}
+	}
+});
+/**
+* Handle deployment resource actions.
+*
+* Not using the factory because the `get` action has special logic
+* (with id → output, without id → script).
+*/
+async function handleDeployments(action, args, ctx) {
+	if (!args.server_id) return errorResult("Missing required field: server_id");
+	if (!args.site_id) return errorResult("Missing required field: site_id");
+	if (!sanitizeId(args.server_id)) return errorResult(`Invalid server_id: "${args.server_id}". IDs must be alphanumeric.`);
+	if (!sanitizeId(args.site_id)) return errorResult(`Invalid site_id: "${args.site_id}". IDs must be alphanumeric.`);
+	if (args.id && !sanitizeId(args.id)) return errorResult(`Invalid id: "${args.id}". IDs must be alphanumeric.`);
+	const opts = {
+		server_id: args.server_id,
+		site_id: args.site_id
+	};
+	switch (action) {
+		case "list": {
+			const result = await listDeployments(opts, ctx.executorContext);
+			if (ctx.compact) return jsonResult(formatDeploymentList(result.data));
+			return jsonResult(result.data);
+		}
+		case "deploy": {
+			const deployResult = await deploySiteAndWait(opts, ctx.executorContext);
+			return jsonResult(formatDeployAction(args.site_id, args.server_id, deployResult.data));
+		}
+		case "get":
+			if (args.id) {
+				const result = await getDeploymentOutput({
+					...opts,
+					deployment_id: args.id
+				}, ctx.executorContext);
+				return jsonResult(formatDeploymentOutput(args.id, result.data));
+			}
+			return jsonResult(formatDeploymentScript((await getDeploymentScript(opts, ctx.executorContext)).data));
+		case "update":
+			if (!args.content) return errorResult("Missing required field: content");
+			await updateDeploymentScript({
+				...opts,
+				content: args.content
+			}, ctx.executorContext);
+			return jsonResult(formatDeploymentScriptUpdated(args.site_id, args.server_id));
+		default: return errorResult(`Unknown action "${action}" for deployments. Valid actions: list, deploy, get, update.`);
+	}
+}
+const handleEnv = createResourceHandler({
+	resource: "env",
+	actions: ["get", "update"],
+	requiredFields: {
+		get: ["server_id", "site_id"],
+		update: [
+			"server_id",
+			"site_id",
+			"content"
+		]
+	},
+	executors: {
+		get: getEnv,
+		update: updateEnv
+	},
+	mapOptions: (_action, args) => ({
+		server_id: args.server_id,
+		site_id: args.site_id,
+		content: args.content
+	}),
+	formatResult: (action, data) => {
+		switch (action) {
+			case "get": return formatEnv(data);
+			case "update": return "Environment variables updated.";
+			default: return "Done.";
+		}
+	}
+});
+const handleFirewallRules = createResourceHandler({
+	resource: "firewall-rules",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"delete"
+	],
+	requiredFields: {
+		list: ["server_id"],
+		get: ["server_id", "id"],
+		create: [
+			"server_id",
+			"name",
+			"port"
+		],
+		delete: ["server_id", "id"]
+	},
+	executors: {
+		list: listFirewallRules,
+		get: getFirewallRule,
+		create: createFirewallRule,
+		delete: deleteFirewallRule
+	},
+	hints: (data, id) => {
+		const rule = data;
+		return getFirewallRuleHints(String(rule.server_id), id);
+	},
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatFirewallRuleList(data);
+			case "get": return formatFirewallRule(data);
+			case "create": return formatFirewallRule(data);
+			case "delete": return `Firewall rule ${args.id} deleted.`;
+			default: return "Done.";
+		}
+	}
+});
+var RESOURCE_HELP = {
+	servers: {
+		description: "Manage Laravel Forge servers — provisioned cloud instances (DigitalOcean, AWS, Hetzner, etc.)",
+		scope: "global (no parent ID needed)",
+		actions: {
+			list: "List all servers in your Forge account",
+			get: "Get a single server by ID with full details",
+			create: "Provision a new server (requires provider, type, region, name)",
+			delete: "Delete a server by ID (irreversible)",
+			reboot: "Reboot a server by ID"
+		},
+		fields: {
+			id: "Server ID",
+			name: "Server name (hostname)",
+			provider: "Cloud provider (hetzner, ocean2, aws, linode, vultr, custom)",
+			region: "Provider region code",
+			ip_address: "Public IP address",
+			is_ready: "Whether the server has finished provisioning",
+			php_version: "Default PHP version (php84, php83, etc.)"
+		},
+		examples: [
+			{
+				description: "List all servers",
+				params: {
+					resource: "servers",
+					action: "list"
+				}
+			},
+			{
+				description: "Get server details",
+				params: {
+					resource: "servers",
+					action: "get",
+					id: "123"
+				}
+			},
+			{
+				description: "Reboot a server",
+				params: {
+					resource: "servers",
+					action: "reboot",
+					id: "123"
+				}
+			}
+		]
+	},
+	sites: {
+		description: "Manage sites on a Forge server — web applications, PHP projects, static sites",
+		scope: "server (requires server_id)",
+		actions: {
+			list: "List all sites on a server",
+			get: "Get a single site by ID",
+			create: "Create a new site (requires domain, project_type)",
+			delete: "Delete a site by ID"
+		},
+		fields: {
+			id: "Site ID",
+			server_id: "Parent server ID",
+			name: "Domain name (e.g. example.com)",
+			project_type: "Project type (php, html, symfony, symfony_dev, symfony_four, laravel)",
+			directory: "Web root directory (e.g. /public)",
+			repository: "Git repository URL (if connected)",
+			deployment_status: "Last deployment status (null, deploying, deployed, failed)"
+		},
+		examples: [
+			{
+				description: "List sites on a server",
+				params: {
+					resource: "sites",
+					action: "list",
+					server_id: "123"
+				}
+			},
+			{
+				description: "Get site details",
+				params: {
+					resource: "sites",
+					action: "get",
+					server_id: "123",
+					id: "456"
+				}
+			},
+			{
+				description: "Create a Laravel site",
+				params: {
+					resource: "sites",
+					action: "create",
+					server_id: "123",
+					domain: "app.example.com",
+					project_type: "php",
+					directory: "/public"
+				}
+			}
+		]
+	},
+	deployments: {
+		description: "Manage site deployments — trigger, monitor, and configure deploy scripts",
+		scope: "site (requires server_id + site_id)",
+		actions: {
+			list: "List recent deployments for a site",
+			deploy: "Trigger a new deployment",
+			get: "Get deployment output (requires deployment_id in 'id' field)",
+			update: "Update the deployment script (provide 'content' field)"
+		},
+		fields: {
+			id: "Deployment ID",
+			server_id: "Parent server ID",
+			site_id: "Parent site ID",
+			status: "Deployment status (null, deploying, deployed, failed)",
+			displayable_type: "Type of deployment trigger",
+			ended_at: "Completion timestamp"
+		},
+		examples: [
+			{
+				description: "Deploy a site",
+				params: {
+					resource: "deployments",
+					action: "deploy",
+					server_id: "123",
+					site_id: "456"
+				}
+			},
+			{
+				description: "List deployments",
+				params: {
+					resource: "deployments",
+					action: "list",
+					server_id: "123",
+					site_id: "456"
+				}
+			},
+			{
+				description: "Get deployment output",
+				params: {
+					resource: "deployments",
+					action: "get",
+					server_id: "123",
+					site_id: "456",
+					id: "789"
+				}
+			},
+			{
+				description: "Update deploy script",
+				params: {
+					resource: "deployments",
+					action: "update",
+					server_id: "123",
+					site_id: "456",
+					content: "cd /home/forge/app.example.com\ngit pull\ncomposer install\nphp artisan migrate --force"
+				}
+			}
+		]
+	},
+	env: {
+		description: "Manage environment variables (.env file) for a site",
+		scope: "site (requires server_id + site_id)",
+		actions: {
+			get: "Get the current .env file content",
+			update: "Replace the entire .env file (provide 'content' field)"
+		},
+		examples: [{
+			description: "Get env variables",
+			params: {
+				resource: "env",
+				action: "get",
+				server_id: "123",
+				site_id: "456"
+			}
+		}, {
+			description: "Update env",
+			params: {
+				resource: "env",
+				action: "update",
+				server_id: "123",
+				site_id: "456",
+				content: "APP_ENV=production\nAPP_DEBUG=false\nDB_HOST=127.0.0.1"
+			}
+		}]
+	},
+	nginx: {
+		description: "Manage Nginx configuration for a site",
+		scope: "site (requires server_id + site_id)",
+		actions: {
+			get: "Get the current Nginx config",
+			update: "Replace the Nginx config (provide 'content' field)"
+		},
+		examples: [{
+			description: "Get nginx config",
+			params: {
+				resource: "nginx",
+				action: "get",
+				server_id: "123",
+				site_id: "456"
+			}
+		}]
+	},
+	certificates: {
+		description: "Manage SSL/TLS certificates for a site — Let's Encrypt, custom, or cloned",
+		scope: "site (requires server_id + site_id)",
+		actions: {
+			list: "List certificates for a site",
+			get: "Get certificate details",
+			create: "Create/request a new certificate",
+			delete: "Delete a certificate",
+			activate: "Activate a certificate (make it the active cert for the site)"
+		},
+		examples: [
+			{
+				description: "List certificates",
+				params: {
+					resource: "certificates",
+					action: "list",
+					server_id: "123",
+					site_id: "456"
+				}
+			},
+			{
+				description: "Create Let's Encrypt cert",
+				params: {
+					resource: "certificates",
+					action: "create",
+					server_id: "123",
+					site_id: "456",
+					domain: "example.com",
+					type: "new"
+				}
+			},
+			{
+				description: "Activate a certificate",
+				params: {
+					resource: "certificates",
+					action: "activate",
+					server_id: "123",
+					site_id: "456",
+					id: "789"
+				}
+			}
+		]
+	},
+	databases: {
+		description: "Manage MySQL/PostgreSQL databases on a server",
+		scope: "server (requires server_id)",
+		actions: {
+			list: "List databases on a server",
+			get: "Get database details",
+			create: "Create a new database (optionally with user)",
+			delete: "Delete a database"
+		},
+		fields: {
+			name: "Database name",
+			user: "(create only) Create a database user",
+			password: "(create only) User password"
+		},
+		examples: [{
+			description: "List databases",
+			params: {
+				resource: "databases",
+				action: "list",
+				server_id: "123"
+			}
+		}, {
+			description: "Create database with user",
+			params: {
+				resource: "databases",
+				action: "create",
+				server_id: "123",
+				name: "myapp",
+				user: "admin",
+				password: "secret123"
+			}
+		}]
+	},
+	"database-users": {
+		description: "Manage database users on a server",
+		scope: "server (requires server_id)",
+		actions: {
+			list: "List database users on a server",
+			get: "Get database user details",
+			create: "Create a new database user",
+			delete: "Delete a database user"
+		},
+		fields: {
+			name: "Database user name",
+			password: "User password",
+			databases: "(create only) Array of database IDs to grant access to"
+		},
+		examples: [{
+			description: "List database users",
+			params: {
+				resource: "database-users",
+				action: "list",
+				server_id: "123"
+			}
+		}, {
+			description: "Create a database user",
+			params: {
+				resource: "database-users",
+				action: "create",
+				server_id: "123",
+				name: "forge",
+				password: "secret123",
+				databases: [1, 2]
+			}
+		}]
+	},
+	daemons: {
+		description: "Manage background processes (daemons) — queue workers, websocket servers, etc.",
+		scope: "server (requires server_id)",
+		actions: {
+			list: "List daemons on a server",
+			get: "Get daemon details",
+			create: "Create a new daemon",
+			delete: "Delete a daemon",
+			restart: "Restart a daemon"
+		},
+		fields: {
+			command: "Shell command to run",
+			user: "Execution user (default: forge)",
+			directory: "Working directory",
+			processes: "Number of processes (default: 1)"
+		},
+		examples: [
+			{
+				description: "List daemons",
+				params: {
+					resource: "daemons",
+					action: "list",
+					server_id: "123"
+				}
+			},
+			{
+				description: "Create queue worker",
+				params: {
+					resource: "daemons",
+					action: "create",
+					server_id: "123",
+					command: "php artisan queue:work --tries=3",
+					user: "forge"
+				}
+			},
+			{
+				description: "Restart a daemon",
+				params: {
+					resource: "daemons",
+					action: "restart",
+					server_id: "123",
+					id: "456"
+				}
+			}
+		]
+	},
+	"firewall-rules": {
+		description: "Manage UFW firewall rules on a server",
+		scope: "server (requires server_id)",
+		actions: {
+			list: "List firewall rules",
+			get: "Get rule details",
+			create: "Create a new firewall rule",
+			delete: "Delete a firewall rule"
+		},
+		fields: {
+			name: "Rule name/description",
+			port: "Port number or range (e.g. 80, 8000-9000)",
+			type: "allow or deny (default: allow)",
+			ip_address: "Restrict to specific IP (optional)"
+		},
+		examples: [{
+			description: "List firewall rules",
+			params: {
+				resource: "firewall-rules",
+				action: "list",
+				server_id: "123"
+			}
+		}, {
+			description: "Open port 3000",
+			params: {
+				resource: "firewall-rules",
+				action: "create",
+				server_id: "123",
+				name: "Allow Node.js",
+				port: 3e3
+			}
+		}]
+	},
+	"ssh-keys": {
+		description: "Manage SSH keys on a server",
+		scope: "server (requires server_id)",
+		actions: {
+			list: "List SSH keys",
+			get: "Get key details",
+			create: "Add an SSH key to the server",
+			delete: "Remove an SSH key"
+		},
+		fields: {
+			name: "Key label/description",
+			key: "Public key content (ssh-rsa ...)",
+			username: "User to add the key to (optional)"
+		},
+		examples: [{
+			description: "List SSH keys",
+			params: {
+				resource: "ssh-keys",
+				action: "list",
+				server_id: "123"
+			}
+		}, {
+			description: "Add SSH key",
+			params: {
+				resource: "ssh-keys",
+				action: "create",
+				server_id: "123",
+				name: "Deploy Key",
+				key: "ssh-rsa AAAA..."
+			}
+		}]
+	},
+	"security-rules": {
+		description: "Manage HTTP Basic Auth security rules for a site",
+		scope: "site (requires server_id + site_id)",
+		actions: {
+			list: "List security rules",
+			get: "Get rule details",
+			create: "Create a security rule with credentials",
+			delete: "Delete a security rule"
+		},
+		examples: [{
+			description: "List security rules",
+			params: {
+				resource: "security-rules",
+				action: "list",
+				server_id: "123",
+				site_id: "456"
+			}
+		}, {
+			description: "Create basic auth",
+			params: {
+				resource: "security-rules",
+				action: "create",
+				server_id: "123",
+				site_id: "456",
+				name: "Staging Auth",
+				credentials: [{
+					username: "admin",
+					password: "secret"
+				}]
+			}
+		}]
+	},
+	"redirect-rules": {
+		description: "Manage URL redirect rules for a site",
+		scope: "site (requires server_id + site_id)",
+		actions: {
+			list: "List redirect rules",
+			get: "Get rule details",
+			create: "Create a redirect rule",
+			delete: "Delete a redirect rule"
+		},
+		fields: {
+			from: "Source path (regex supported)",
+			to: "Destination URL",
+			type: "redirect (302, default) or permanent (301)"
+		},
+		examples: [{
+			description: "List redirects",
+			params: {
+				resource: "redirect-rules",
+				action: "list",
+				server_id: "123",
+				site_id: "456"
+			}
+		}, {
+			description: "Create redirect",
+			params: {
+				resource: "redirect-rules",
+				action: "create",
+				server_id: "123",
+				site_id: "456",
+				from: "/old-page",
+				to: "/new-page",
+				type: "permanent"
+			}
+		}]
+	},
+	monitors: {
+		description: "Manage server monitoring alerts — CPU, disk, memory thresholds",
+		scope: "server (requires server_id)",
+		actions: {
+			list: "List monitors",
+			get: "Get monitor details",
+			create: "Create a monitor",
+			delete: "Delete a monitor"
+		},
+		fields: {
+			type: "Monitor type (disk, cpu, memory)",
+			operator: "Comparison operator (gte, lte)",
+			threshold: "Threshold value (e.g. 80 for 80%)",
+			minutes: "Check interval in minutes"
+		},
+		examples: [{
+			description: "List monitors",
+			params: {
+				resource: "monitors",
+				action: "list",
+				server_id: "123"
+			}
+		}, {
+			description: "Alert on high disk usage",
+			params: {
+				resource: "monitors",
+				action: "create",
+				server_id: "123",
+				type: "disk",
+				operator: "gte",
+				threshold: 80,
+				minutes: 5
+			}
+		}]
+	},
+	"nginx-templates": {
+		description: "Manage reusable Nginx configuration templates on a server",
+		scope: "server (requires server_id)",
+		actions: {
+			list: "List nginx templates",
+			get: "Get template with content",
+			create: "Create a new template",
+			update: "Update template name or content",
+			delete: "Delete a template"
+		},
+		examples: [{
+			description: "List templates",
+			params: {
+				resource: "nginx-templates",
+				action: "list",
+				server_id: "123"
+			}
+		}, {
+			description: "Get template content",
+			params: {
+				resource: "nginx-templates",
+				action: "get",
+				server_id: "123",
+				id: "456"
+			}
+		}]
+	},
+	backups: {
+		description: "Manage backup configurations — automated database backups to S3, Spaces, or other providers",
+		scope: "server (requires server_id)",
+		actions: {
+			list: "List backup configurations on a server",
+			get: "Get backup config details (databases, schedule, retention)",
+			create: "Create a new backup configuration",
+			delete: "Delete a backup configuration"
+		},
+		fields: {
+			provider: "Backup provider (s3, spaces, custom)",
+			credentials: "Provider credentials (keys, bucket, region)",
+			frequency: "Backup frequency (daily, weekly, custom)",
+			databases: "Array of database IDs to back up",
+			retention: "Number of backups to retain"
+		},
+		examples: [{
+			description: "List backup configs",
+			params: {
+				resource: "backups",
+				action: "list",
+				server_id: "123"
+			}
+		}, {
+			description: "Get backup config details",
+			params: {
+				resource: "backups",
+				action: "get",
+				server_id: "123",
+				id: "456"
+			}
+		}]
+	},
+	commands: {
+		description: "Execute and list site commands — run artisan commands or shell scripts on a site",
+		scope: "site (requires server_id + site_id)",
+		actions: {
+			list: "List commands executed on a site",
+			get: "Get command details and status",
+			create: "Execute a new command on the site"
+		},
+		fields: { command: "Shell command to execute" },
+		examples: [{
+			description: "List commands",
+			params: {
+				resource: "commands",
+				action: "list",
+				server_id: "123",
+				site_id: "456"
+			}
+		}, {
+			description: "Run a command",
+			params: {
+				resource: "commands",
+				action: "create",
+				server_id: "123",
+				site_id: "456",
+				command: "php artisan migrate --force"
+			}
+		}]
+	},
+	"scheduled-jobs": {
+		description: "Manage cron jobs (scheduled tasks) on a server",
+		scope: "server (requires server_id)",
+		actions: {
+			list: "List scheduled jobs on a server",
+			get: "Get job details (command, frequency, cron expression)",
+			create: "Create a new scheduled job",
+			delete: "Delete a scheduled job"
+		},
+		fields: {
+			command: "Shell command to schedule",
+			user: "Execution user (default: forge)",
+			frequency: "Frequency preset (minutely, hourly, nightly, weekly, monthly, custom)",
+			minute: "(custom frequency) Minute field",
+			hour: "(custom frequency) Hour field",
+			day: "(custom frequency) Day of month field",
+			month: "(custom frequency) Month field",
+			weekday: "(custom frequency) Day of week field"
+		},
+		examples: [{
+			description: "List scheduled jobs",
+			params: {
+				resource: "scheduled-jobs",
+				action: "list",
+				server_id: "123"
+			}
+		}, {
+			description: "Create minutely scheduler",
+			params: {
+				resource: "scheduled-jobs",
+				action: "create",
+				server_id: "123",
+				command: "php /home/forge/app.com/artisan schedule:run",
+				frequency: "minutely",
+				user: "forge"
+			}
+		}]
+	},
+	user: {
+		description: "Get the currently authenticated Forge user profile",
+		scope: "global (no parent ID needed)",
+		actions: { get: "Get the authenticated user's profile (name, email, connected services)" },
+		examples: [{
+			description: "Get user profile",
+			params: {
+				resource: "user",
+				action: "get"
+			}
+		}]
+	},
+	recipes: {
+		description: "Manage and run server recipes — reusable bash scripts executed on one or more servers",
+		scope: "global (no parent ID needed)",
+		actions: {
+			list: "List all recipes",
+			get: "Get recipe details and script content",
+			create: "Create a new recipe",
+			delete: "Delete a recipe",
+			run: "Run a recipe on specified servers (provide 'servers' as array of server IDs)"
+		},
+		fields: {
+			name: "Recipe name",
+			script: "Bash script content",
+			user: "Execution user (default: root)",
+			servers: "(run only) Array of server IDs to run on"
+		},
+		examples: [
+			{
+				description: "List recipes",
+				params: {
+					resource: "recipes",
+					action: "list"
+				}
+			},
+			{
+				description: "Create a recipe",
+				params: {
+					resource: "recipes",
+					action: "create",
+					name: "Clear caches",
+					script: "php artisan cache:clear\nphp artisan view:clear"
+				}
+			},
+			{
+				description: "Run recipe on servers",
+				params: {
+					resource: "recipes",
+					action: "run",
+					id: "123",
+					servers: [
+						1,
+						2,
+						3
+					]
+				}
+			}
+		]
+	}
+};
+/**
+* Handle help action — returns documentation for a specific resource.
+*/
+function handleHelp(resource) {
+	const help = RESOURCE_HELP[resource];
+	if (!help) return handleHelpOverview();
+	return jsonResult({
+		resource,
+		...help
+	});
+}
+/**
+* Get help for all resources (overview).
+*/
+function handleHelpOverview() {
+	return jsonResult({
+		message: "Use action=\"help\" with a specific resource for detailed documentation",
+		resources: Object.entries(RESOURCE_HELP).map(([resource, help]) => ({
+			resource,
+			description: help.description,
+			scope: help.scope,
+			actions: Object.keys(help.actions)
+		})),
+		_tip: "Always call { action: 'help', resource: '<name>' } before your first interaction with any resource to learn required fields and examples."
+	});
+}
+const handleMonitors = createResourceHandler({
+	resource: "monitors",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"delete"
+	],
+	requiredFields: {
+		list: ["server_id"],
+		get: ["server_id", "id"],
+		create: [
+			"server_id",
+			"type",
+			"operator",
+			"threshold",
+			"minutes"
+		],
+		delete: ["server_id", "id"]
+	},
+	executors: {
+		list: listMonitors,
+		get: getMonitor,
+		create: createMonitor,
+		delete: deleteMonitor
+	},
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatMonitorList(data);
+			case "get": return formatMonitor(data);
+			case "create": return formatMonitor(data);
+			case "delete": return `Monitor ${args.id} deleted.`;
+			default: return "Done.";
+		}
+	}
+});
+const handleNginxConfig = createResourceHandler({
+	resource: "nginx",
+	actions: ["get", "update"],
+	requiredFields: {
+		get: ["server_id", "site_id"],
+		update: [
+			"server_id",
+			"site_id",
+			"content"
+		]
+	},
+	executors: {
+		get: getNginxConfig,
+		update: updateNginxConfig
+	},
+	mapOptions: (_action, args) => ({
+		server_id: args.server_id,
+		site_id: args.site_id,
+		content: args.content
+	}),
+	formatResult: (action, data) => {
+		switch (action) {
+			case "get": return formatNginxConfig(data);
+			case "update": return "Nginx configuration updated.";
+			default: return "Done.";
+		}
+	}
+});
+const handleNginxTemplates = createResourceHandler({
+	resource: "nginx-templates",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"update",
+		"delete"
+	],
+	requiredFields: {
+		list: ["server_id"],
+		get: ["server_id", "id"],
+		create: [
+			"server_id",
+			"name",
+			"content"
+		],
+		update: ["server_id", "id"],
+		delete: ["server_id", "id"]
+	},
+	executors: {
+		list: listNginxTemplates,
+		get: getNginxTemplate,
+		create: createNginxTemplate,
+		update: updateNginxTemplate,
+		delete: deleteNginxTemplate
+	},
+	hints: (data, id) => {
+		const template = data;
+		return getNginxTemplateHints(String(template.server_id), id);
+	},
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatNginxTemplateList(data);
+			case "get": return formatNginxTemplate(data);
+			case "create": return formatNginxTemplate(data);
+			case "update": return formatNginxTemplate(data);
+			case "delete": return `Nginx template ${args.id} deleted.`;
+			default: return "Done.";
+		}
+	}
+});
+const handleRecipes = createResourceHandler({
+	resource: "recipes",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"delete",
+		"run"
+	],
+	requiredFields: {
+		get: ["id"],
+		create: ["name", "script"],
+		delete: ["id"],
+		run: ["id", "servers"]
+	},
+	executors: {
+		list: listRecipes,
+		get: getRecipe,
+		create: createRecipe,
+		delete: deleteRecipe,
+		run: runRecipe
+	},
+	hints: (_data, id) => getRecipeHints(id),
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatRecipeList(data);
+			case "get": return formatRecipe(data);
+			case "create": return formatRecipe(data);
+			case "delete": return `Recipe ${args.id} deleted.`;
+			case "run": {
+				const servers = args.servers;
+				const count = Array.isArray(servers) ? servers.length : 1;
+				return `Recipe ${args.id} run on ${count} server(s).`;
+			}
+			default: return "Done.";
+		}
+	}
+});
+const handleRedirectRules = createResourceHandler({
+	resource: "redirect-rules",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"delete"
+	],
+	requiredFields: {
+		list: ["server_id", "site_id"],
+		get: [
+			"server_id",
+			"site_id",
+			"id"
+		],
+		create: [
+			"server_id",
+			"site_id",
+			"from",
+			"to"
+		],
+		delete: [
+			"server_id",
+			"site_id",
+			"id"
+		]
+	},
+	executors: {
+		list: listRedirectRules,
+		get: getRedirectRule,
+		create: createRedirectRule,
+		delete: deleteRedirectRule
+	},
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatRedirectRuleList(data);
+			case "get": return formatRedirectRule(data);
+			case "create": return formatRedirectRule(data);
+			case "delete": return `Redirect rule ${args.id} deleted.`;
+			default: return "Done.";
+		}
+	}
+});
+const handleScheduledJobs = createResourceHandler({
+	resource: "scheduled-jobs",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"delete"
+	],
+	requiredFields: {
+		list: ["server_id"],
+		get: ["server_id", "id"],
+		create: ["server_id", "command"],
+		delete: ["server_id", "id"]
+	},
+	executors: {
+		list: listScheduledJobs,
+		get: getScheduledJob,
+		create: createScheduledJob,
+		delete: deleteScheduledJob
+	},
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatScheduledJobList(data);
+			case "get": return formatScheduledJob(data);
+			case "create": return formatScheduledJob(data);
+			case "delete": return `Scheduled job ${args.id} deleted.`;
+			default: return "Done.";
+		}
+	}
+});
+var RESOURCE_SCHEMAS = {
+	servers: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"delete",
+			"reboot"
+		],
+		scope: "global",
+		required: {
+			get: ["id"],
+			create: [
+				"provider",
+				"type",
+				"region",
+				"name"
+			],
+			delete: ["id"],
+			reboot: ["id"]
+		},
+		create: {
+			provider: {
+				required: true,
+				type: "string — hetzner, ocean2, aws, etc."
+			},
+			type: {
+				required: true,
+				type: "string — app, web, worker, etc."
+			},
+			region: {
+				required: true,
+				type: "string — provider-specific region code"
+			},
+			name: {
+				required: true,
+				type: "string"
+			},
+			credential_id: {
+				required: false,
+				type: "string — provider credential ID"
+			},
+			php_version: {
+				required: false,
+				type: "string — php84, php83, etc."
+			},
+			database: {
+				required: false,
+				type: "string — database name to create"
+			}
+		}
+	},
+	sites: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"delete"
+		],
+		scope: "server",
+		required: {
+			list: ["server_id"],
+			get: ["server_id", "id"],
+			create: [
+				"server_id",
+				"domain",
+				"project_type"
+			],
+			delete: ["server_id", "id"]
+		},
+		create: {
+			domain: {
+				required: true,
+				type: "string — e.g. example.com"
+			},
+			project_type: {
+				required: true,
+				type: "string — php, html, symfony, etc."
+			},
+			directory: {
+				required: false,
+				type: "string — web root (/public)"
+			}
+		}
+	},
+	deployments: {
+		actions: [
+			"list",
+			"deploy",
+			"get",
+			"update"
+		],
+		scope: "site",
+		required: {
+			list: ["server_id", "site_id"],
+			deploy: ["server_id", "site_id"],
+			get: [
+				"server_id",
+				"site_id",
+				"id"
+			],
+			update: [
+				"server_id",
+				"site_id",
+				"content"
+			]
+		}
+	},
+	env: {
+		actions: ["get", "update"],
+		scope: "site",
+		required: {
+			get: ["server_id", "site_id"],
+			update: [
+				"server_id",
+				"site_id",
+				"content"
+			]
+		}
+	},
+	nginx: {
+		actions: ["get", "update"],
+		scope: "site",
+		required: {
+			get: ["server_id", "site_id"],
+			update: [
+				"server_id",
+				"site_id",
+				"content"
+			]
+		}
+	},
+	certificates: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"delete",
+			"activate"
+		],
+		scope: "site",
+		required: {
+			list: ["server_id", "site_id"],
+			get: [
+				"server_id",
+				"site_id",
+				"id"
+			],
+			create: [
+				"server_id",
+				"site_id",
+				"domain"
+			],
+			delete: [
+				"server_id",
+				"site_id",
+				"id"
+			],
+			activate: [
+				"server_id",
+				"site_id",
+				"id"
+			]
+		},
+		create: {
+			type: {
+				required: false,
+				type: "string — new, existing, clone (default: new)"
+			},
+			domain: {
+				required: true,
+				type: "string"
+			}
+		}
+	},
+	databases: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"delete"
+		],
+		scope: "server",
+		required: {
+			list: ["server_id"],
+			get: ["server_id", "id"],
+			create: ["server_id", "name"],
+			delete: ["server_id", "id"]
+		},
+		create: {
+			name: {
+				required: true,
+				type: "string — database name"
+			},
+			user: {
+				required: false,
+				type: "string — database user to create"
+			},
+			password: {
+				required: false,
+				type: "string — user password"
+			}
+		}
+	},
+	"database-users": {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"delete"
+		],
+		scope: "server",
+		required: {
+			list: ["server_id"],
+			get: ["server_id", "id"],
+			create: [
+				"server_id",
+				"name",
+				"password"
+			],
+			delete: ["server_id", "id"]
+		},
+		create: {
+			name: {
+				required: true,
+				type: "string — database user name"
+			},
+			password: {
+				required: true,
+				type: "string — user password"
+			},
+			databases: {
+				required: false,
+				type: "array — database IDs to grant access to"
+			}
+		}
+	},
+	daemons: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"delete",
+			"restart"
+		],
+		scope: "server",
+		required: {
+			list: ["server_id"],
+			get: ["server_id", "id"],
+			create: ["server_id", "command"],
+			delete: ["server_id", "id"],
+			restart: ["server_id", "id"]
+		},
+		create: {
+			command: {
+				required: true,
+				type: "string — e.g. php artisan queue:work"
+			},
+			user: {
+				required: false,
+				type: "string — default: forge"
+			},
+			directory: {
+				required: false,
+				type: "string — working directory"
+			},
+			processes: {
+				required: false,
+				type: "number — default: 1"
+			}
+		}
+	},
+	"firewall-rules": {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"delete"
+		],
+		scope: "server",
+		required: {
+			list: ["server_id"],
+			get: ["server_id", "id"],
+			create: [
+				"server_id",
+				"name",
+				"port"
+			],
+			delete: ["server_id", "id"]
+		},
+		create: {
+			name: {
+				required: true,
+				type: "string"
+			},
+			port: {
+				required: true,
+				type: "number|string — e.g. 80, 443, 8000-9000"
+			},
+			type: {
+				required: false,
+				type: "string — allow (default) or deny"
+			},
+			ip_address: {
+				required: false,
+				type: "string — restrict to IP"
+			}
+		}
+	},
+	"ssh-keys": {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"delete"
+		],
+		scope: "server",
+		required: {
+			list: ["server_id"],
+			get: ["server_id", "id"],
+			create: [
+				"server_id",
+				"name",
+				"key"
+			],
+			delete: ["server_id", "id"]
+		},
+		create: {
+			name: {
+				required: true,
+				type: "string — key label"
+			},
+			key: {
+				required: true,
+				type: "string — public key content"
+			},
+			username: {
+				required: false,
+				type: "string — user to add key to"
+			}
+		}
+	},
+	"security-rules": {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"delete"
+		],
+		scope: "site",
+		required: {
+			list: ["server_id", "site_id"],
+			get: [
+				"server_id",
+				"site_id",
+				"id"
+			],
+			create: [
+				"server_id",
+				"site_id",
+				"name",
+				"credentials"
+			],
+			delete: [
+				"server_id",
+				"site_id",
+				"id"
+			]
+		},
+		create: {
+			name: {
+				required: true,
+				type: "string — rule name"
+			},
+			path: {
+				required: false,
+				type: "string — protected path (default: /)"
+			},
+			credentials: {
+				required: true,
+				type: "array — [{username, password}]"
+			}
+		}
+	},
+	"redirect-rules": {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"delete"
+		],
+		scope: "site",
+		required: {
+			list: ["server_id", "site_id"],
+			get: [
+				"server_id",
+				"site_id",
+				"id"
+			],
+			create: [
+				"server_id",
+				"site_id",
+				"from",
+				"to"
+			],
+			delete: [
+				"server_id",
+				"site_id",
+				"id"
+			]
+		},
+		create: {
+			from: {
+				required: true,
+				type: "string — source path"
+			},
+			to: {
+				required: true,
+				type: "string — destination URL"
+			},
+			type: {
+				required: false,
+				type: "string — redirect (302) or permanent (301)"
+			}
+		}
+	},
+	monitors: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"delete"
+		],
+		scope: "server",
+		required: {
+			list: ["server_id"],
+			get: ["server_id", "id"],
+			create: [
+				"server_id",
+				"type",
+				"operator",
+				"threshold",
+				"minutes"
+			],
+			delete: ["server_id", "id"]
+		},
+		create: {
+			type: {
+				required: true,
+				type: "string — disk, cpu, memory, etc."
+			},
+			operator: {
+				required: true,
+				type: "string — gte, lte"
+			},
+			threshold: {
+				required: true,
+				type: "number — e.g. 80"
+			},
+			minutes: {
+				required: true,
+				type: "number — check interval in minutes"
+			}
+		}
+	},
+	"nginx-templates": {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"update",
+			"delete"
+		],
+		scope: "server",
+		required: {
+			list: ["server_id"],
+			get: ["server_id", "id"],
+			create: [
+				"server_id",
+				"name",
+				"content"
+			],
+			update: ["server_id", "id"],
+			delete: ["server_id", "id"]
+		},
+		create: {
+			name: {
+				required: true,
+				type: "string — template name"
+			},
+			content: {
+				required: true,
+				type: "string — nginx configuration template"
+			}
+		}
+	},
+	backups: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"delete"
+		],
+		scope: "server",
+		required: {
+			list: ["server_id"],
+			get: ["server_id", "id"],
+			create: [
+				"server_id",
+				"provider",
+				"credentials",
+				"frequency",
+				"databases"
+			],
+			delete: ["server_id", "id"]
+		},
+		create: {
+			provider: {
+				required: true,
+				type: "string — s3, spaces, custom"
+			},
+			credentials: {
+				required: true,
+				type: "object — provider credentials (key, secret, etc.)"
+			},
+			frequency: {
+				required: true,
+				type: "string — daily, weekly, custom"
+			},
+			databases: {
+				required: true,
+				type: "array — database IDs to back up"
+			},
+			directory: {
+				required: false,
+				type: "string — backup directory"
+			},
+			email: {
+				required: false,
+				type: "string — notification email"
+			},
+			retention: {
+				required: false,
+				type: "number — backups to retain (default: 7)"
+			}
+		}
+	},
+	commands: {
+		actions: [
+			"list",
+			"get",
+			"create"
+		],
+		scope: "site",
+		required: {
+			list: ["server_id", "site_id"],
+			get: [
+				"server_id",
+				"site_id",
+				"id"
+			],
+			create: [
+				"server_id",
+				"site_id",
+				"command"
+			]
+		},
+		create: { command: {
+			required: true,
+			type: "string — shell command to execute"
+		} }
+	},
+	"scheduled-jobs": {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"delete"
+		],
+		scope: "server",
+		required: {
+			list: ["server_id"],
+			get: ["server_id", "id"],
+			create: ["server_id", "command"],
+			delete: ["server_id", "id"]
+		},
+		create: {
+			command: {
+				required: true,
+				type: "string — command to schedule"
+			},
+			user: {
+				required: false,
+				type: "string — execution user (default: forge)"
+			},
+			frequency: {
+				required: false,
+				type: "string — minutely, hourly, nightly, weekly, monthly, custom"
+			},
+			minute: {
+				required: false,
+				type: "string — cron minute field (custom frequency)"
+			},
+			hour: {
+				required: false,
+				type: "string — cron hour field"
+			},
+			day: {
+				required: false,
+				type: "string — cron day field"
+			},
+			month: {
+				required: false,
+				type: "string — cron month field"
+			},
+			weekday: {
+				required: false,
+				type: "string — cron weekday field"
+			}
+		}
+	},
+	user: {
+		actions: ["get"],
+		scope: "global",
+		required: {}
+	},
+	recipes: {
+		actions: [
+			"list",
+			"get",
+			"create",
+			"delete",
+			"run"
+		],
+		scope: "global",
+		required: {
+			get: ["id"],
+			create: ["name", "script"],
+			delete: ["id"],
+			run: ["id", "servers"]
+		},
+		create: {
+			name: {
+				required: true,
+				type: "string — recipe name"
+			},
+			script: {
+				required: true,
+				type: "string — bash script content"
+			},
+			user: {
+				required: false,
+				type: "string — execution user (default: root)"
+			}
+		}
+	}
+};
+/**
+* Handle schema action — returns compact spec for a specific resource.
+*/
+function handleSchema(resource) {
+	const schema = RESOURCE_SCHEMAS[resource];
+	if (!schema) return jsonResult({
+		error: `Unknown resource: ${resource}`,
+		available_resources: Object.keys(RESOURCE_SCHEMAS)
+	});
+	return jsonResult({
+		resource,
+		...schema
+	});
+}
+/**
+* Get schema overview for all resources.
+*/
+function handleSchemaOverview() {
+	return jsonResult({
+		_tip: "Use action=\"schema\" with a specific resource for full required/create spec",
+		resources: Object.entries(RESOURCE_SCHEMAS).map(([resource, schema]) => ({
+			resource,
+			actions: schema.actions,
+			scope: schema.scope
+		}))
+	});
+}
+const handleSecurityRules = createResourceHandler({
+	resource: "security-rules",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"delete"
+	],
+	requiredFields: {
+		list: ["server_id", "site_id"],
+		get: [
+			"server_id",
+			"site_id",
+			"id"
+		],
+		create: [
+			"server_id",
+			"site_id",
+			"name",
+			"credentials"
+		],
+		delete: [
+			"server_id",
+			"site_id",
+			"id"
+		]
+	},
+	executors: {
+		list: listSecurityRules,
+		get: getSecurityRule,
+		create: createSecurityRule,
+		delete: deleteSecurityRule
+	},
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatSecurityRuleList(data);
+			case "get": return formatSecurityRule(data);
+			case "create": return formatSecurityRule(data);
+			case "delete": return `Security rule ${args.id} deleted.`;
+			default: return "Done.";
+		}
+	}
+});
+const handleServers = createResourceHandler({
+	resource: "servers",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"delete",
+		"reboot"
+	],
+	requiredFields: {
+		get: ["id"],
+		create: [
+			"provider",
+			"name",
+			"type",
+			"region"
+		],
+		delete: ["id"],
+		reboot: ["id"]
+	},
+	executors: {
+		list: listServers,
+		get: getServer,
+		create: createServer,
+		delete: deleteServer,
+		reboot: rebootServer
+	},
+	hints: (_data, id) => getServerHints(id),
+	mapOptions: (action, args) => {
+		switch (action) {
+			case "get":
+			case "delete":
+			case "reboot": return { server_id: args.id };
+			case "create": return {
+				provider: args.provider,
+				credential_id: Number(args.credential_id) || 0,
+				name: args.name,
+				type: args.type ?? "app",
+				size: args.size ?? "",
+				region: args.region
+			};
+			default: return {};
+		}
+	},
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatServerList(data);
+			case "get": return formatServer(data);
+			case "create": return formatServer(data);
+			case "delete": return `Server ${args.id} deleted.`;
+			case "reboot": return `Server ${args.id} reboot initiated.`;
+			default: return "Done.";
+		}
+	}
+});
+const handleSites = createResourceHandler({
+	resource: "sites",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"delete"
+	],
+	requiredFields: {
+		list: ["server_id"],
+		get: ["server_id", "id"],
+		create: ["server_id", "domain"],
+		delete: ["server_id", "id"]
+	},
+	executors: {
+		list: listSites,
+		get: getSite,
+		create: createSite,
+		delete: deleteSite
+	},
+	hints: (data, id) => {
+		const site = data;
+		return getSiteHints(String(site.server_id), id);
+	},
+	mapOptions: (action, args) => {
+		switch (action) {
+			case "list": return { server_id: args.server_id };
+			case "get": return {
+				server_id: args.server_id,
+				site_id: args.id
+			};
+			case "create": return {
+				server_id: args.server_id,
+				domain: args.domain,
+				project_type: args.project_type ?? "php",
+				directory: args.directory
+			};
+			case "delete": return {
+				server_id: args.server_id,
+				site_id: args.id
+			};
+			default: return {};
+		}
+	},
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatSiteList(data, args.server_id);
+			case "get": return formatSite(data);
+			case "create": return formatSite(data);
+			case "delete": return `Site ${args.id} deleted from server ${args.server_id}.`;
+			default: return "Done.";
+		}
+	}
+});
+const handleSshKeys = createResourceHandler({
+	resource: "ssh-keys",
+	actions: [
+		"list",
+		"get",
+		"create",
+		"delete"
+	],
+	requiredFields: {
+		list: ["server_id"],
+		get: ["server_id", "id"],
+		create: [
+			"server_id",
+			"name",
+			"key"
+		],
+		delete: ["server_id", "id"]
+	},
+	executors: {
+		list: listSshKeys,
+		get: getSshKey,
+		create: createSshKey,
+		delete: deleteSshKey
+	},
+	hints: (data, id) => {
+		const key = data;
+		return getSshKeyHints(String(key.server_id), id);
+	},
+	formatResult: (action, data, args) => {
+		switch (action) {
+			case "list": return formatSshKeyList(data);
+			case "get": return formatSshKey(data);
+			case "create": return formatSshKey(data);
+			case "delete": return `SSH key ${args.id} deleted.`;
+			default: return "Done.";
+		}
+	}
+});
+const handleUser = createResourceHandler({
+	resource: "user",
+	actions: ["get"],
+	executors: { get: getUser },
+	formatResult: (_action, data) => {
+		return formatUser(data);
+	}
+});
+/**
+* Read-only actions — safe operations that don't modify server state.
+*/
+const READ_ACTIONS = [
+	"list",
+	"get",
+	"help",
+	"schema"
+];
+/**
+* Write actions — operations that modify server state.
+* These are separated into the `forge_write` tool for safety.
+*/
+const WRITE_ACTIONS = [
+	"create",
+	"update",
+	"delete",
+	"deploy",
+	"reboot",
+	"restart",
+	"activate",
+	"run"
+];
+/**
+* Check if an action is a write action.
+*/
+function isWriteAction(action) {
+	return WRITE_ACTIONS.includes(action);
+}
+/**
+* Check if an action is a read action.
+*/
+function isReadAction(action) {
+	return READ_ACTIONS.includes(action);
+}
+/**
+* Output schema shared by all forge tools.
+*
+* All tools return a consistent envelope:
+* - success: true/false
+* - result: the resource data (shape varies by resource and action)
+* - error: error message (only when success is false)
+*
+* The `result` field contains resource-specific data:
+* - list actions → array of resource objects
+* - get actions → single resource object (or string for env/nginx/scripts)
+* - help/schema → documentation text or schema object
+* - write actions → confirmation message or updated resource
+*/
+var OUTPUT_SCHEMA = {
+	type: "object",
+	properties: {
+		success: {
+			type: "boolean",
+			description: "Whether the operation succeeded"
+		},
+		result: { description: "Operation result — shape varies by resource and action (array for list, object for get, string for text content)" },
+		error: {
+			type: "string",
+			description: "Error message (only present on failure)"
+		}
+	},
+	required: ["success"]
+};
+/**
+* Shared input schema properties used by both forge and forge_write tools.
+*/
+var SHARED_INPUT_PROPERTIES = {
+	resource: {
+		type: "string",
+		enum: [...RESOURCES],
+		description: "Forge resource to operate on"
+	},
+	id: {
+		type: "string",
+		description: "Resource ID (for get, delete, update actions)"
+	},
+	server_id: {
+		type: "string",
+		description: "Server ID (required for most resources)"
+	},
+	site_id: {
+		type: "string",
+		description: "Site ID (required for site-level resources: deployments, env, certificates, etc.)"
+	},
+	compact: {
+		type: "boolean",
+		description: "Compact output (default: true for list, false for get)"
+	}
+};
+/**
+* Core tools available in both stdio and HTTP transports.
+*
+* Split into two tools for safety:
+* - `forge` — read-only operations (auto-approvable by MCP clients)
+* - `forge_write` — write operations (always requires confirmation)
+*/
+const TOOLS = [{
+	name: "forge",
+	title: "Laravel Forge",
+	description: [
+		"Laravel Forge API — read operations.",
+		`Resources: ${RESOURCES.join(", ")}.`,
+		`Actions: ${[...READ_ACTIONS].join(", ")}.`,
+		"Discovery: action=help with any resource for filters and examples.",
+		"Server operations require id. Site operations require server_id.",
+		"Deployment operations require server_id and site_id."
+	].join("\n"),
+	annotations: {
+		title: "Laravel Forge",
+		readOnlyHint: true,
+		destructiveHint: false,
+		idempotentHint: true,
+		openWorldHint: true
+	},
+	inputSchema: {
+		type: "object",
+		properties: {
+			...SHARED_INPUT_PROPERTIES,
+			action: {
+				type: "string",
+				enum: [...READ_ACTIONS],
+				description: "Read action to perform. Use \"help\" for resource documentation."
+			}
+		},
+		required: ["resource", "action"]
+	},
+	outputSchema: OUTPUT_SCHEMA
+}, {
+	name: "forge_write",
+	title: "Laravel Forge (Write)",
+	description: [
+		"Laravel Forge API — write operations (create, update, delete, deploy, reboot, etc.).",
+		`Resources: ${RESOURCES.join(", ")}.`,
+		`Actions: ${[...WRITE_ACTIONS].join(", ")}.`,
+		"Server operations require id. Site operations require server_id.",
+		"Deployment operations require server_id and site_id.",
+		"Use forge tool with action=help for resource documentation."
+	].join("\n"),
+	annotations: {
+		title: "Laravel Forge (Write)",
+		readOnlyHint: false,
+		destructiveHint: true,
+		idempotentHint: false,
+		openWorldHint: true
+	},
+	inputSchema: {
+		type: "object",
+		properties: {
+			...SHARED_INPUT_PROPERTIES,
+			action: {
+				type: "string",
+				enum: [...WRITE_ACTIONS],
+				description: "Write action to perform"
+			},
+			name: {
+				type: "string",
+				description: "Resource name (servers, databases, daemons, etc.)"
+			},
+			provider: {
+				type: "string",
+				description: "Server provider (e.g. ocean2, linode, aws)"
+			},
+			region: {
+				type: "string",
+				description: "Server region (e.g. nyc3, us-east-1)"
+			},
+			size: {
+				type: "string",
+				description: "Server size (e.g. s-1vcpu-1gb)"
+			},
+			credential_id: {
+				type: "string",
+				description: "Provider credential ID for server creation"
+			},
+			type: {
+				type: "string",
+				description: "Resource type (e.g. app, web, worker for servers; mysql, postgres for databases; disk_usage, used_memory for monitors)"
+			},
+			domain: {
+				type: "string",
+				description: "Site domain name (e.g. example.com)"
+			},
+			project_type: {
+				type: "string",
+				description: "Site project type (e.g. php, html, symfony, laravel)"
+			},
+			directory: {
+				type: "string",
+				description: "Web directory relative to site root (e.g. /public)"
+			},
+			content: {
+				type: "string",
+				description: "Content body for env variables, nginx config, or deployment script updates"
+			},
+			command: {
+				type: "string",
+				description: "Shell command to execute (daemons: background process command; recipes: bash script inline; commands: site command)"
+			},
+			user: {
+				type: "string",
+				description: "Unix user to run as (daemons, scheduled jobs; e.g. forge, root)"
+			},
+			port: {
+				type: ["string", "number"],
+				description: "Port number or range (firewall rules, e.g. 80 or 8000-9000)"
+			},
+			ip_address: {
+				type: "string",
+				description: "IP address to allow/block (firewall rules, e.g. 192.168.1.1)"
+			},
+			key: {
+				type: "string",
+				description: "Public SSH key content (ssh-rsa ... or ssh-ed25519 ...)"
+			},
+			from: {
+				type: "string",
+				description: "Source path for redirect rules (e.g. /old-page)"
+			},
+			to: {
+				type: "string",
+				description: "Destination URL for redirect rules (e.g. /new-page)"
+			},
+			credentials: {
+				type: "array",
+				description: "HTTP basic auth credentials for security rules [{username, password}]",
+				items: { type: "object" }
+			},
+			operator: {
+				type: "string",
+				description: "Comparison operator for monitors (e.g. gte, lte)"
+			},
+			threshold: {
+				type: "number",
+				description: "Threshold value that triggers the monitor alert"
+			},
+			minutes: {
+				type: "number",
+				description: "Check interval in minutes for monitors (e.g. 5)"
+			},
+			frequency: {
+				type: "string",
+				description: "Cron frequency for scheduled jobs (e.g. minutely, hourly, nightly, custom)"
+			},
+			script: {
+				type: "string",
+				description: "Bash script content for recipes"
+			},
+			servers: {
+				type: "array",
+				description: "Server IDs to run a recipe on (e.g. [123, 456])",
+				items: { type: "number" }
+			}
+		},
+		required: ["resource", "action"]
+	},
+	outputSchema: OUTPUT_SCHEMA
+}];
+/**
+* Get the list of core tools, optionally filtered.
+*
+* In read-only mode, forge_write is excluded entirely — it won't appear
+* in the tool listing and cannot be called.
+*/
+function getTools(options) {
+	if (options?.readOnly) return TOOLS.filter((t) => t.name !== "forge_write");
+	return [...TOOLS];
+}
+/**
+* Additional tools only available in stdio mode.
+*/
+const STDIO_ONLY_TOOLS = [{
+	name: "forge_configure",
+	title: "Configure Forge",
+	description: "Configure Laravel Forge API token. The token is stored locally in the XDG config directory.",
+	annotations: {
+		title: "Configure Forge",
+		readOnlyHint: false,
+		destructiveHint: false,
+		idempotentHint: true,
+		openWorldHint: false
+	},
+	inputSchema: {
+		type: "object",
+		properties: { apiToken: {
+			type: "string",
+			description: "Your Laravel Forge API token"
+		} },
+		required: ["apiToken"]
+	},
+	outputSchema: {
+		type: "object",
+		properties: {
+			success: { type: "boolean" },
+			message: {
+				type: "string",
+				description: "Confirmation message"
+			},
+			apiToken: {
+				type: "string",
+				description: "Masked API token (last 4 chars)"
+			}
+		},
+		required: ["success"]
+	}
+}, {
+	name: "forge_get_config",
+	title: "Get Forge Config",
+	description: "Get current Forge configuration (shows masked token and config status).",
+	annotations: {
+		title: "Get Forge Config",
+		readOnlyHint: true,
+		destructiveHint: false,
+		idempotentHint: true,
+		openWorldHint: false
+	},
+	inputSchema: {
+		type: "object",
+		properties: {}
+	},
+	outputSchema: {
+		type: "object",
+		properties: {
+			apiToken: {
+				type: "string",
+				description: "Masked API token or 'not configured'"
+			},
+			configured: {
+				type: "boolean",
+				description: "Whether a token is configured"
+			}
+		},
+		required: ["configured"]
+	}
+}];
+/** Valid resources derived from core constants */
+var VALID_RESOURCES = [...RESOURCES];
+var _auditLogger = null;
+function getAuditLogger() {
+	if (!_auditLogger) _auditLogger = createAuditLogger("mcp");
+	return _auditLogger;
+}
+/**
+* Route to the appropriate resource handler.
+*/
+function routeToHandler(resource, action, args, ctx) {
+	switch (resource) {
+		case "servers": return handleServers(action, args, ctx);
+		case "sites": return handleSites(action, args, ctx);
+		case "deployments": return handleDeployments(action, args, ctx);
+		case "env": return handleEnv(action, args, ctx);
+		case "nginx": return handleNginxConfig(action, args, ctx);
+		case "certificates": return handleCertificates(action, args, ctx);
+		case "databases": return handleDatabases(action, args, ctx);
+		case "database-users": return handleDatabaseUsers(action, args, ctx);
+		case "daemons": return handleDaemons(action, args, ctx);
+		case "firewall-rules": return handleFirewallRules(action, args, ctx);
+		case "ssh-keys": return handleSshKeys(action, args, ctx);
+		case "security-rules": return handleSecurityRules(action, args, ctx);
+		case "redirect-rules": return handleRedirectRules(action, args, ctx);
+		case "monitors": return handleMonitors(action, args, ctx);
+		case "nginx-templates": return handleNginxTemplates(action, args, ctx);
+		case "recipes": return handleRecipes(action, args, ctx);
+		case "backups": return handleBackups(action, args, ctx);
+		case "commands": return handleCommands(action, args, ctx);
+		case "scheduled-jobs": return handleScheduledJobs(action, args, ctx);
+		case "user": return handleUser(action, args, ctx);
+		default: return Promise.resolve(errorResult(`Unknown resource "${resource}". Valid resources: ${VALID_RESOURCES.join(", ")}. Use action="help" for documentation.`));
+	}
+}
+/**
+* Execute a tool call with provided credentials.
+*
+* This is the main entry point shared between stdio and HTTP transports.
+* Validates that the action matches the tool (read vs write).
+*/
+async function executeToolWithCredentials(name, args, credentials) {
+	const { resource, action, compact, ...rest } = args;
+	if (!resource || !action) return errorResult("Missing required fields: \"resource\" and \"action\".");
+	if (name === "forge" && isWriteAction(action)) return errorResult(`Action "${action}" is a write operation. Use the "forge_write" tool instead.`);
+	if (name === "forge_write" && isReadAction(action)) return errorResult(`Action "${action}" is a read operation. Use the "forge" tool instead.`);
+	if (action === "help")
+ /* v8 ignore start */
+	return resource ? handleHelp(resource) : handleHelpOverview();
+	if (action === "schema")
+ /* v8 ignore start */
+	return resource ? handleSchema(resource) : handleSchemaOverview();
+	if (!VALID_RESOURCES.includes(resource)) return errorResult(`Unknown resource "${resource}". Valid resources: ${VALID_RESOURCES.join(", ")}. Use action="help" for documentation.`);
+	const handlerContext = {
+		executorContext: { client: new HttpClient({ token: credentials.apiToken }) },
+		compact: compact ?? action !== "get",
+		includeHints: action === "get"
+	};
+	try {
+		const result = await routeToHandler(resource, action, {
+			resource,
+			action,
+			...rest
+		}, handlerContext);
+		if (name === "forge_write") getAuditLogger().log({
+			source: "mcp",
+			resource,
+			action,
+			args: rest,
+			status: result.isError ? "error" : "success"
+		});
+		return result;
+	} catch (error) {
+		let errorMessage;
+		if (isUserInputError(error)) errorMessage = error.toFormattedMessage();
+		else if (isForgeApiError(error)) errorMessage = `Forge API error (${error.status}): ${error.message}`;
+		else
+ /* v8 ignore start */
+		errorMessage = error instanceof Error ? error.message : String(error);
+		if (name === "forge_write") getAuditLogger().log({
+			source: "mcp",
+			resource,
+			action,
+			args: rest,
+			status: "error",
+			error: errorMessage
+		});
+		return errorResult(errorMessage);
+	}
+}
+const VERSION = "0.2.0";
+export { INSTRUCTIONS as a, getTools as i, executeToolWithCredentials as n, STDIO_ONLY_TOOLS as r, VERSION as t };
+
+//# sourceMappingURL=version-DaD5zvGh.js.map