@studiometa/forge-mcp 0.0.1 → 0.2.0

package/README.md

@@ -0,0 +1,152 @@
+# @studiometa/forge-mcp
+
+[![npm version](https://img.shields.io/npm/v/@studiometa/forge-mcp?style=flat&colorB=3e63dd&colorA=414853)](https://www.npmjs.com/package/@studiometa/forge-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat&colorB=3e63dd&colorA=414853)](https://opensource.org/licenses/MIT)
+
+MCP (Model Context Protocol) server for [Laravel Forge](https://forge.laravel.com). Enables Claude Desktop and other MCP clients to manage servers, sites, deployments, and more through natural language.
+
+## Features
+
+- **Two tools with clear safety split** — `forge` (read) and `forge_write` (write)
+- MCP clients auto-approve `forge` reads, always prompt for `forge_write` writes
+- Resource/action routing from centralized constants
+- Built-in help system — `action=help` for any resource
+- Stdio and Streamable HTTP transports
+- Configuration tools for interactive token setup
+
+## Installation
+
+```bash
+npm install -g @studiometa/forge-mcp
+```
+
+## Claude Desktop Configuration
+
+Add to your Claude Desktop config:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "forge": {
+      "command": "forge-mcp",
+      "env": {
+        "FORGE_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+Alternatively, omit the `env` block and ask Claude to configure credentials using the `forge_configure` tool.
+
+### Read-Only Mode
+
+To guarantee no write operations are possible at the server level:
+
+```json
+{
+  "mcpServers": {
+    "forge": {
+      "command": "forge-mcp",
+      "args": ["--read-only"],
+      "env": {
+        "FORGE_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+Or via environment variable: `FORGE_READ_ONLY=true`.
+
+When enabled, the `forge_write` tool is not registered at all — only `forge`, `forge_configure`, and `forge_get_config` are available.
+
+## Tools
+
+### `forge` — Read Operations
+
+Safe, read-only queries. Annotated `readOnlyHint: true` so MCP clients can auto-approve.
+
+**Actions**: `list`, `get`, `help`, `schema`
+
+```json
+{ "resource": "servers", "action": "list" }
+{ "resource": "servers", "action": "get", "id": "123" }
+{ "resource": "sites", "action": "list", "server_id": "123" }
+{ "resource": "servers", "action": "help" }
+```
+
+### `forge_write` — Write Operations
+
+Mutating operations. Annotated `destructiveHint: true` so MCP clients always prompt for confirmation.
+
+**Actions**: `create`, `update`, `delete`, `deploy`, `reboot`, `restart`, `activate`, `run`
+
+```json
+{ "resource": "deployments", "action": "deploy", "server_id": "123", "site_id": "456" }
+// deploy blocks until complete, returning: status, deployment log, elapsed time
+{ "resource": "servers", "action": "reboot", "id": "123" }
+{ "resource": "daemons", "action": "create", "server_id": "123", "command": "php artisan queue:work" }
+```
+
+### Resources & Actions
+
+| Resource        | Read Actions | Write Actions            | Required Fields            |
+| --------------- | ------------ | ------------------------ | -------------------------- |
+| servers         | list, get    | create, delete, reboot   | id (for get/delete/reboot) |
+| sites           | list, get    | create, delete           | server_id                  |
+| deployments     | list         | deploy, update           | server_id, site_id         |
+| env             | get          | update                   | server_id, site_id         |
+| nginx           | get          | update                   | server_id, site_id         |
+| certificates    | list, get    | create, delete, activate | server_id, site_id         |
+| databases       | list, get    | create, delete           | server_id                  |
+| daemons         | list, get    | create, delete, restart  | server_id                  |
+| firewall-rules  | list, get    | create, delete           | server_id                  |
+| ssh-keys        | list, get    | create, delete           | server_id                  |
+| security-rules  | list, get    | create, delete           | server_id, site_id         |
+| redirect-rules  | list, get    | create, delete           | server_id, site_id         |
+| monitors        | list, get    | create, delete           | server_id                  |
+| nginx-templates | list, get    | create, update, delete   | server_id                  |
+| recipes         | list, get    | create, delete, run      | id (for get/delete/run)    |
+
+### Discovery
+
+Use `action: "help"` with any resource:
+
+```json
+{ "resource": "servers", "action": "help" }
+{ "resource": "deployments", "action": "help" }
+```
+
+## Stdio-Only Tools
+
+| Tool               | Description                        |
+| ------------------ | ---------------------------------- |
+| `forge_configure`  | Save API token to local config     |
+| `forge_get_config` | Show current config (token masked) |
+
+## Audit Logging
+
+All write operations (`forge_write` tool calls) are automatically logged for traceability:
+
+- **Default path**: `~/.config/forge-tools/audit.log`
+- **Override**: Set `FORGE_AUDIT_LOG` environment variable
+- **Format**: JSON lines (via pino) with timestamp, resource, action, sanitized args, and status
+- **Safety**: Logging never interrupts operations — silent on failure
+
+The CLI also logs write commands to the same audit log.
+
+## Getting Your API Token
+
+1. Log into [Laravel Forge](https://forge.laravel.com)
+2. Go to **Account → API Tokens**
+3. Create a new token with the scopes you need
+4. Copy the token (it's only shown once)
+
+## License
+
+MIT © [Studio Meta](https://www.studiometa.fr)

package/dist/auth.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Authentication utilities for Forge MCP HTTP server
+ */
+export interface ForgeCredentials {
+    apiToken: string;
+}
+/**
+ * Parse Bearer token containing Forge API credentials.
+ * Token format: raw Forge API token (no base64 encoding needed).
+ *
+ * @param authHeader - Authorization header value (e.g., "Bearer <token>")
+ * @returns Parsed credentials or null if invalid
+ */
+export declare function parseAuthHeader(authHeader: string | undefined | null): ForgeCredentials | null;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,gBAAgB,GAAG,IAAI,CAiB9F"}

package/dist/auth.js

@@ -0,0 +1,18 @@
+/**
+* Parse Bearer token containing Forge API credentials.
+* Token format: raw Forge API token (no base64 encoding needed).
+*
+* @param authHeader - Authorization header value (e.g., "Bearer <token>")
+* @returns Parsed credentials or null if invalid
+*/
+function parseAuthHeader(authHeader) {
+	if (!authHeader) return null;
+	const match = authHeader.match(/^Bearer\s+(.+)$/i);
+	if (!match) return null;
+	const token = match[1].trim();
+	if (!token) return null;
+	return { apiToken: token };
+}
+export { parseAuthHeader };
+
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","names":[],"sources":["../src/auth.ts"],"sourcesContent":["/**\n * Authentication utilities for Forge MCP HTTP server\n */\n\nexport interface ForgeCredentials {\n  apiToken: string;\n}\n\n/**\n * Parse Bearer token containing Forge API credentials.\n * Token format: raw Forge API token (no base64 encoding needed).\n *\n * @param authHeader - Authorization header value (e.g., \"Bearer <token>\")\n * @returns Parsed credentials or null if invalid\n */\nexport function parseAuthHeader(authHeader: string | undefined | null): ForgeCredentials | null {\n  if (!authHeader) {\n    return null;\n  }\n\n  const match = authHeader.match(/^Bearer\\s+(.+)$/i);\n  if (!match) {\n    return null;\n  }\n\n  const token = match[1].trim();\n\n  if (!token) {\n    return null;\n  }\n\n  return { apiToken: token };\n}\n"],"mappings":";;;;;;;AAeA,SAAgB,gBAAgB,YAAgE;AAC9F,KAAI,CAAC,WACH,QAAO;CAGT,MAAM,QAAQ,WAAW,MAAM,mBAAmB;AAClD,KAAI,CAAC,MACH,QAAO;CAGT,MAAM,QAAQ,MAAM,GAAG,MAAM;AAE7B,KAAI,CAAC,MACH,QAAO;AAGT,QAAO,EAAE,UAAU,OAAO"}

package/dist/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+export declare class UserInputError extends Error {
+    readonly hints?: string[];
+    constructor(message: string, hints?: string[]);
+    /**
+     * Format error message with hints for LLM consumption
+     */
+    toFormattedMessage(): string;
+}
+/**
+ * Error messages with guidance for common validation failures
+ */
+export declare const ErrorMessages: {
+    readonly missingId: (action: string) => UserInputError;
+    readonly missingRequiredFields: (resource: string, fields: string[]) => UserInputError;
+    readonly invalidAction: (action: string, resource: string, validActions: string[]) => UserInputError;
+    readonly unknownResource: (resource: string, validResources: string[]) => UserInputError;
+    readonly noUpdateFieldsSpecified: (allowedFields: string[]) => UserInputError;
+    readonly apiError: (statusCode: number, message: string) => UserInputError;
+};
+/**
+ * Check if an error is a UserInputError
+ */
+export declare function isUserInputError(error: unknown): error is UserInputError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,SAAgB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;gBAErB,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE;IAM7C;;OAEG;IACH,kBAAkB,IAAI,MAAM;CAO7B;AAED;;GAEG;AACH,eAAO,MAAM,aAAa;iCAEJ,MAAM;+CAMQ,MAAM,UAAU,MAAM,EAAE;qCAUlC,MAAM,YAAY,MAAM,gBAAgB,MAAM,EAAE;yCAO5C,MAAM,kBAAkB,MAAM,EAAE;sDAOnB,MAAM,EAAE;oCAO1B,MAAM,WAAW,MAAM;CAsBtC,CAAC;AAEX;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,cAAc,CAExE"}

package/dist/formatters.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Response formatters for MCP tool output.
+ *
+ * This module contains per-resource formatter functions that convert
+ * executor data payloads into human-readable text for MCP responses.
+ *
+ * Keeping formatting in the MCP layer ensures executors remain pure data
+ * functions that can be reused by any adapter (CLI, SDK, etc.).
+ */
+import type { ForgeBackupConfig, ForgeCertificate, ForgeCommand, ForgeDaemon, ForgeDatabase, ForgeDatabaseUser, ForgeDeployment, ForgeFirewallRule, ForgeMonitor, ForgeNginxTemplate, ForgeRecipe, ForgeRedirectRule, ForgeScheduledJob, ForgeSecurityRule, ForgeServer, ForgeSite, ForgeSshKey, ForgeUser } from "@studiometa/forge-api";
+/**
+ * Format a list of servers.
+ */
+export declare function formatServerList(servers: ForgeServer[]): string;
+/**
+ * Format a single server.
+ */
+export declare function formatServer(server: ForgeServer): string;
+/**
+ * Format a list of sites.
+ */
+export declare function formatSiteList(sites: ForgeSite[], serverId?: string): string;
+/**
+ * Format a single site.
+ */
+export declare function formatSite(site: ForgeSite): string;
+/**
+ * Format a list of databases.
+ */
+export declare function formatDatabaseList(databases: ForgeDatabase[]): string;
+/**
+ * Format a single database.
+ */
+export declare function formatDatabase(db: ForgeDatabase): string;
+/**
+ * Format a list of database users.
+ */
+export declare function formatDatabaseUserList(users: ForgeDatabaseUser[]): string;
+/**
+ * Format a single database user.
+ */
+export declare function formatDatabaseUser(user: ForgeDatabaseUser): string;
+/**
+ * Format a list of deployments.
+ */
+export declare function formatDeploymentList(deployments: ForgeDeployment[]): string;
+/**
+ * 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.
+ */
+export declare function formatDeployAction(siteId: string, serverId: string, result?: {
+    status: "success" | "failed";
+    log: string;
+    elapsed_ms: number;
+}): string;
+/**
+ * Format deployment script content.
+ */
+export declare function formatDeploymentScript(script: string): string;
+/**
+ * Format deployment output.
+ */
+export declare function formatDeploymentOutput(deploymentId: string, output: string): string;
+/**
+ * Format a deployment script update confirmation.
+ */
+export declare function formatDeploymentScriptUpdated(siteId: string, serverId: string): string;
+/**
+ * Format a list of certificates.
+ */
+export declare function formatCertificateList(certificates: ForgeCertificate[]): string;
+/**
+ * Format a single certificate.
+ */
+export declare function formatCertificate(cert: ForgeCertificate): string;
+/**
+ * Format a list of daemons.
+ */
+export declare function formatDaemonList(daemons: ForgeDaemon[]): string;
+/**
+ * Format a single daemon.
+ */
+export declare function formatDaemon(daemon: ForgeDaemon): string;
+/**
+ * Format a list of firewall rules.
+ */
+export declare function formatFirewallRuleList(rules: ForgeFirewallRule[]): string;
+/**
+ * Format a single firewall rule.
+ */
+export declare function formatFirewallRule(rule: ForgeFirewallRule): string;
+/**
+ * Format a list of monitors.
+ */
+export declare function formatMonitorList(monitors: ForgeMonitor[]): string;
+/**
+ * Format a single monitor.
+ */
+export declare function formatMonitor(monitor: ForgeMonitor): string;
+/**
+ * Format a list of SSH keys.
+ */
+export declare function formatSshKeyList(keys: ForgeSshKey[]): string;
+/**
+ * Format a single SSH key.
+ */
+export declare function formatSshKey(key: ForgeSshKey): string;
+/**
+ * Format a list of scheduled jobs.
+ */
+export declare function formatScheduledJobList(jobs: ForgeScheduledJob[]): string;
+/**
+ * Format a single scheduled job.
+ */
+export declare function formatScheduledJob(job: ForgeScheduledJob): string;
+/**
+ * Format a list of security rules.
+ */
+export declare function formatSecurityRuleList(rules: ForgeSecurityRule[]): string;
+/**
+ * Format a single security rule.
+ */
+export declare function formatSecurityRule(rule: ForgeSecurityRule): string;
+/**
+ * Format a list of redirect rules.
+ */
+export declare function formatRedirectRuleList(rules: ForgeRedirectRule[]): string;
+/**
+ * Format a single redirect rule.
+ */
+export declare function formatRedirectRule(rule: ForgeRedirectRule): string;
+/**
+ * Format nginx configuration content.
+ */
+export declare function formatNginxConfig(content: string): string;
+/**
+ * Format a list of nginx templates.
+ */
+export declare function formatNginxTemplateList(templates: ForgeNginxTemplate[]): string;
+/**
+ * Format a single nginx template.
+ */
+export declare function formatNginxTemplate(template: ForgeNginxTemplate): string;
+/**
+ * Format a list of backup configurations.
+ */
+export declare function formatBackupConfigList(backups: ForgeBackupConfig[]): string;
+/**
+ * Format a single backup configuration.
+ */
+export declare function formatBackupConfig(backup: ForgeBackupConfig): string;
+/**
+ * Format a list of recipes.
+ */
+export declare function formatRecipeList(recipes: ForgeRecipe[]): string;
+/**
+ * Format a single recipe.
+ */
+export declare function formatRecipe(recipe: ForgeRecipe): string;
+/**
+ * Format a list of commands.
+ */
+export declare function formatCommandList(commands: ForgeCommand[]): string;
+/**
+ * Format a single command.
+ */
+export declare function formatCommand(command: ForgeCommand): string;
+/**
+ * Format environment variables content.
+ */
+export declare function formatEnv(content: string): string;
+/**
+ * Format the authenticated user.
+ */
+export declare function formatUser(user: ForgeUser): string;
+/**
+ * Format a deleted resource confirmation.
+ */
+export declare function formatDeleted(resource: string, id: string): string;
+/**
+ * Format a created resource confirmation (for simple cases).
+ */
+export declare function formatCreated(resource: string, name: string, id: number | string): string;
+//# sourceMappingURL=formatters.d.ts.map

package/dist/formatters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatters.d.ts","sourceRoot":"","sources":["../src/formatters.ts"],"names":[],"mappings":"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"}

package/dist/handlers/backups.d.ts

@@ -0,0 +1,2 @@
+export declare const handleBackups: (action: string, args: import("./types.ts").CommonArgs, ctx: import("./types.ts").HandlerContext) => Promise<import("./types.ts").ToolResult>;
+//# sourceMappingURL=backups.d.ts.map

package/dist/handlers/backups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backups.d.ts","sourceRoot":"","sources":["../../src/handlers/backups.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,aAAa,+IA8BxB,CAAC"}

package/dist/handlers/certificates.d.ts

@@ -0,0 +1,2 @@
+export declare const handleCertificates: (action: string, args: import("./types.ts").CommonArgs, ctx: import("./types.ts").HandlerContext) => Promise<import("./types.ts").ToolResult>;
+//# sourceMappingURL=certificates.d.ts.map

package/dist/handlers/certificates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"certificates.d.ts","sourceRoot":"","sources":["../../src/handlers/certificates.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,kBAAkB,+IAsC7B,CAAC"}

package/dist/handlers/commands.d.ts

@@ -0,0 +1,2 @@
+export declare const handleCommands: (action: string, args: import("./types.ts").CommonArgs, ctx: import("./types.ts").HandlerContext) => Promise<import("./types.ts").ToolResult>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/handlers/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/handlers/commands.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,cAAc,+IA0BzB,CAAC"}

package/dist/handlers/daemons.d.ts

@@ -0,0 +1,2 @@
+export declare const handleDaemons: (action: string, args: import("./types.ts").CommonArgs, ctx: import("./types.ts").HandlerContext) => Promise<import("./types.ts").ToolResult>;
+//# sourceMappingURL=daemons.d.ts.map

package/dist/handlers/daemons.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemons.d.ts","sourceRoot":"","sources":["../../src/handlers/daemons.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,aAAa,+IAsCxB,CAAC"}

package/dist/handlers/database-users.d.ts

@@ -0,0 +1,2 @@
+export declare const handleDatabaseUsers: (action: string, args: import("./types.ts").CommonArgs, ctx: import("./types.ts").HandlerContext) => Promise<import("./types.ts").ToolResult>;
+//# sourceMappingURL=database-users.d.ts.map

package/dist/handlers/database-users.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database-users.d.ts","sourceRoot":"","sources":["../../src/handlers/database-users.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,mBAAmB,+IAkC9B,CAAC"}

package/dist/handlers/databases.d.ts

@@ -0,0 +1,2 @@
+export declare const handleDatabases: (action: string, args: import("./types.ts").CommonArgs, ctx: import("./types.ts").HandlerContext) => Promise<import("./types.ts").ToolResult>;
+//# sourceMappingURL=databases.d.ts.map

package/dist/handlers/databases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"databases.d.ts","sourceRoot":"","sources":["../../src/handlers/databases.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,eAAe,+IAkC1B,CAAC"}

package/dist/handlers/deployments.d.ts

@@ -0,0 +1,9 @@
+import type { CommonArgs, HandlerContext, ToolResult } from "./types.ts";
+/**
+ * Handle deployment resource actions.
+ *
+ * Not using the factory because the `get` action has special logic
+ * (with id → output, without id → script).
+ */
+export declare function handleDeployments(action: string, args: CommonArgs, ctx: HandlerContext): Promise<ToolResult>;
+//# sourceMappingURL=deployments.d.ts.map

package/dist/handlers/deployments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deployments.d.ts","sourceRoot":"","sources":["../../src/handlers/deployments.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAIzE;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,UAAU,CAAC,CAyDrB"}

package/dist/handlers/env.d.ts

@@ -0,0 +1,2 @@
+export declare const handleEnv: (action: string, args: import("./types.ts").CommonArgs, ctx: import("./types.ts").HandlerContext) => Promise<import("./types.ts").ToolResult>;
+//# sourceMappingURL=env.d.ts.map

package/dist/handlers/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/handlers/env.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,SAAS,+IA2BpB,CAAC"}

package/dist/handlers/factory.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Factory for creating Forge resource handlers.
+ *
+ * Encapsulates the repetitive list/get/create/update/delete pattern
+ * shared by all MCP resource handlers.
+ */
+import type { ExecutorContext, ExecutorResult } from "@studiometa/forge-core";
+import type { ContextualHints } from "../hints.ts";
+import type { CommonArgs, HandlerContext, ToolResult } from "./types.ts";
+/**
+ * Configuration for a resource handler.
+ */
+export interface ResourceHandlerConfig {
+    /** Resource name for error messages */
+    resource: string;
+    /** Valid actions for this resource */
+    actions: string[];
+    /** Fields required per action (in addition to defaults) */
+    requiredFields?: Record<string, string[]>;
+    /** Executor functions keyed by action name */
+    executors: Record<string, (options: any, ctx: ExecutorContext) => Promise<ExecutorResult<unknown>>>;
+    /**
+     * Generate contextual hints for the get action response.
+     *
+     * Called with the executor result data and the resource id.
+     * Only injected when `ctx.includeHints` is true.
+     */
+    hints?: (data: unknown, id: string) => ContextualHints;
+    /** Map tool args to executor options. Defaults to pass-through. */
+    mapOptions?: (action: string, args: CommonArgs) => Record<string, unknown>;
+    /**
+     * Format the executor result data into human-readable text for MCP output.
+     *
+     * Called with the executor result data and the tool args when compact mode
+     * is enabled. If not provided, the data is JSON-serialized.
+     */
+    formatResult?: (action: string, data: any, args: CommonArgs) => string;
+}
+/**
+ * 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.';
+ *   },
+ * });
+ * ```
+ */
+export declare function createResourceHandler(config: ResourceHandlerConfig): (action: string, args: CommonArgs, ctx: HandlerContext) => Promise<ToolResult>;
+//# sourceMappingURL=factory.d.ts.map

package/dist/handlers/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/handlers/factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE9E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAIzE;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IAEjB,sCAAsC;IACtC,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAE1C,8CAA8C;IAE9C,SAAS,EAAE,MAAM,CACf,MAAM,EAEN,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CACzE,CAAC;IAEF;;;;;OAKG;IACH,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,KAAK,eAAe,CAAC;IAEvD,mEAAmE;IACnE,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAE3E;;;;;OAKG;IAEH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,UAAU,KAAK,MAAM,CAAC;CACxE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,GAC5B,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,cAAc,KAAK,OAAO,CAAC,UAAU,CAAC,CA8EhF"}

package/dist/handlers/firewall-rules.d.ts

@@ -0,0 +1,2 @@
+export declare const handleFirewallRules: (action: string, args: import("./types.ts").CommonArgs, ctx: import("./types.ts").HandlerContext) => Promise<import("./types.ts").ToolResult>;
+//# sourceMappingURL=firewall-rules.d.ts.map

package/dist/handlers/firewall-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"firewall-rules.d.ts","sourceRoot":"","sources":["../../src/handlers/firewall-rules.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,mBAAmB,+IAkC9B,CAAC"}

package/dist/handlers/help.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Help handler — provides detailed documentation for each resource.
+ *
+ * Follows the productive-tools convention: per-resource docs with
+ * actions, required fields, field descriptions, and examples.
+ */
+import type { ToolResult } from "./types.ts";
+/**
+ * Handle help action — returns documentation for a specific resource.
+ */
+export declare function handleHelp(resource: string): ToolResult;
+/**
+ * Get help for all resources (overview).
+ */
+export declare function handleHelpOverview(): ToolResult;
+//# sourceMappingURL=help.d.ts.map

package/dist/handlers/help.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/handlers/help.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA0oB7C;;GAEG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,CAQvD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,UAAU,CAa/C"}

package/dist/handlers/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tool execution handlers for Forge MCP server.
+ * Shared between stdio and HTTP transports.
+ *
+ * Two tools with clear separation:
+ * - forge: read-only operations (list, get, help, schema)
+ * - forge_write: write operations (create, update, delete, deploy, reboot, etc.)
+ */
+import type { ToolResult } from "./types.ts";
+export type { ToolResult } from "./types.ts";
+/**
+ * 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).
+ */
+export declare function executeToolWithCredentials(name: string, args: Record<string, unknown>, credentials: {
+    apiToken: string;
+}): Promise<ToolResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/handlers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,KAAK,EAA8B,UAAU,EAAE,MAAM,YAAY,CAAC;AA8BzE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAwE7C;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAChC,OAAO,CAAC,UAAU,CAAC,CAyFrB"}

package/dist/handlers/monitors.d.ts

@@ -0,0 +1,2 @@
+export declare const handleMonitors: (action: string, args: import("./types.ts").CommonArgs, ctx: import("./types.ts").HandlerContext) => Promise<import("./types.ts").ToolResult>;
+//# sourceMappingURL=monitors.d.ts.map

package/dist/handlers/monitors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitors.d.ts","sourceRoot":"","sources":["../../src/handlers/monitors.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,cAAc,+IA8BzB,CAAC"}

package/dist/handlers/nginx-config.d.ts

@@ -0,0 +1,2 @@
+export declare const handleNginxConfig: (action: string, args: import("./types.ts").CommonArgs, ctx: import("./types.ts").HandlerContext) => Promise<import("./types.ts").ToolResult>;
+//# sourceMappingURL=nginx-config.d.ts.map

package/dist/handlers/nginx-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nginx-config.d.ts","sourceRoot":"","sources":["../../src/handlers/nginx-config.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,iBAAiB,+IA2B5B,CAAC"}