@studiometa/forge-mcp 0.0.1 → 0.2.0

package/skills/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: forge-mcp
+description: MCP server for Laravel Forge — manage servers, sites, deployments, SSL, databases, and more via AI agents
+keywords:
+  - forge
+  - laravel
+  - servers
+  - deployment
+  - devops
+  - mcp
+---
+
+# Laravel Forge MCP Server
+
+MCP (Model Context Protocol) server for [Laravel Forge](https://forge.laravel.com). Provides two tools: `forge` for read operations and `forge_write` for write operations.
+
+## Quick Start
+
+Before your first interaction with any resource, call `action="help"` with that resource to discover required fields and examples.
+
+## Tools
+
+### `forge` — Read Operations
+
+Safe, read-only queries. Use for listing, getting details, help, and schema.
+
+**Actions**: `list`, `get`, `help`, `schema`
+
+```
+forge(resource, action, [parameters...])
+```
+
+### `forge_write` — Write Operations
+
+Mutating operations that modify server state. Always requires confirmation.
+
+**Actions**: `create`, `update`, `delete`, `deploy`, `reboot`, `restart`, `activate`, `run`
+
+```
+forge_write(resource, action, [parameters...])
+```
+
+### Resources & Actions
+
+| Resource          | Read Actions (`forge`) | Write Actions (`forge_write`)  | Scope  |
+| ----------------- | ---------------------- | ------------------------------ | ------ |
+| `servers`         | `list`, `get`          | `create`, `delete`, `reboot`   | global |
+| `sites`           | `list`, `get`          | `create`, `delete`             | server |
+| `deployments`     | `list`                 | `deploy`, `update`             | site   |
+| `env`             | `get`                  | `update`                       | site   |
+| `nginx`           | `get`                  | `update`                       | site   |
+| `certificates`    | `list`, `get`          | `create`, `delete`, `activate` | site   |
+| `databases`       | `list`, `get`          | `create`, `delete`             | server |
+| `database-users`  | `list`, `get`          | `create`, `delete`             | server |
+| `daemons`         | `list`, `get`          | `create`, `delete`, `restart`  | server |
+| `firewall-rules`  | `list`, `get`          | `create`, `delete`             | server |
+| `ssh-keys`        | `list`, `get`          | `create`, `delete`             | server |
+| `security-rules`  | `list`, `get`          | `create`, `delete`             | site   |
+| `redirect-rules`  | `list`, `get`          | `create`, `delete`             | site   |
+| `monitors`        | `list`, `get`          | `create`, `delete`             | server |
+| `nginx-templates` | `list`, `get`          | `create`, `update`, `delete`   | server |
+| `recipes`         | `list`, `get`          | `create`, `delete`, `run`      | global |
+
+### Scope Guide
+
+- **global**: No parent ID needed (e.g. `servers`, `recipes`)
+- **server**: Requires `server_id` (e.g. `sites`, `databases`, `daemons`)
+- **site**: Requires `server_id` + `site_id` (e.g. `deployments`, `env`, `certificates`)
+
+### Getting Help
+
+Use `action: "help"` to get detailed documentation for any resource:
+
+```json
+{ "resource": "servers", "action": "help" }
+{ "resource": "deployments", "action": "help" }
+```
+
+Use `action: "schema"` for a compact machine-readable spec:
+
+```json
+{ "resource": "sites", "action": "schema" }
+```
+
+## Common Parameters
+
+| Parameter   | Type    | Description                                                   |
+| ----------- | ------- | ------------------------------------------------------------- |
+| `resource`  | string  | **Required**. Resource type (see table above)                 |
+| `action`    | string  | **Required**. Action to perform                               |
+| `id`        | string  | Resource ID (for `get`, `delete`, `activate`, `restart`)      |
+| `server_id` | string  | Server ID (for server-scoped and site-scoped resources)       |
+| `site_id`   | string  | Site ID (for site-scoped resources)                           |
+| `compact`   | boolean | Compact output (default: true)                                |
+| `content`   | string  | Content for env/nginx `update` and deployment script `update` |
+
+## Common Workflows
+
+### Deploy a Site
+
+```json
+// 1. Find the server (forge tool — read)
+{ "resource": "servers", "action": "list" }
+
+// 2. Find the site (forge tool — read)
+{ "resource": "sites", "action": "list", "server_id": "123" }
+
+// 3. Deploy (forge_write tool — write, blocks until complete)
+{ "resource": "deployments", "action": "deploy", "server_id": "123", "site_id": "456" }
+// Returns: deployment status, log output, and elapsed time
+```
+
+### Check Server Status
+
+```json
+// Get server details (forge)
+{ "resource": "servers", "action": "get", "id": "123" }
+
+// List sites on server (forge)
+{ "resource": "sites", "action": "list", "server_id": "123" }
+
+// List databases (forge)
+{ "resource": "databases", "action": "list", "server_id": "123" }
+
+// List background processes (forge)
+{ "resource": "daemons", "action": "list", "server_id": "123" }
+```
+
+### Manage SSL Certificates
+
+```json
+// List existing certs (forge)
+{ "resource": "certificates", "action": "list", "server_id": "123", "site_id": "456" }
+
+// Request a new Let's Encrypt cert (forge_write)
+{ "resource": "certificates", "action": "create", "server_id": "123", "site_id": "456", "domain": "example.com", "type": "new" }
+
+// Activate it (forge_write)
+{ "resource": "certificates", "action": "activate", "server_id": "123", "site_id": "456", "id": "789" }
+```
+
+### Update Environment Variables
+
+```json
+// Get current env (forge)
+{ "resource": "env", "action": "get", "server_id": "123", "site_id": "456" }
+
+// Update env (forge_write)
+{ "resource": "env", "action": "update", "server_id": "123", "site_id": "456", "content": "APP_ENV=production\nAPP_DEBUG=false" }
+```
+
+### Create a Queue Worker
+
+```json
+// forge_write
+{
+  "resource": "daemons",
+  "action": "create",
+  "server_id": "123",
+  "command": "php artisan queue:work --tries=3",
+  "user": "forge"
+}
+```
+
+### Run a Recipe on Multiple Servers
+
+```json
+// Create recipe (forge_write)
+{ "resource": "recipes", "action": "create", "name": "Clear caches", "script": "php artisan cache:clear" }
+
+// Run it on servers (forge_write)
+{ "resource": "recipes", "action": "run", "id": "456", "servers": [1, 2, 3] }
+```
+
+## Authentication
+
+### Stdio Mode (Claude Desktop)
+
+Set `FORGE_API_TOKEN` environment variable, or use the `forge_configure` tool:
+
+```json
+// Configure interactively
+{ tool: "forge_configure", arguments: { api_token: "your-token" } }
+
+// Check current config
+{ tool: "forge_get_config", arguments: {} }
+```
+
+### Getting Your API Token
+
+1. Log into [Laravel Forge](https://forge.laravel.com)
+2. Go to **Account → API Tokens**
+3. Create a new token
+4. Copy the token (shown only once)
+
+## Read-Only Mode
+
+The server can run in read-only mode where the `forge_write` tool is not available at all:
+
+```bash
+forge-mcp --read-only
+# or
+FORGE_READ_ONLY=true forge-mcp
+```
+
+When enabled, only `forge` (read operations), `forge_configure`, and `forge_get_config` are registered.
+
+## Audit Logging
+
+All `forge_write` operations are automatically logged to `~/.config/forge-tools/audit.log` (configurable via `FORGE_AUDIT_LOG` env var). Sensitive fields (tokens, passwords) are redacted. Logging never interrupts operations.
+
+## Tips for Efficient Usage
+
+1. **Use help first**: Call `action="help"` for any resource before using it
+2. **Use schema for specs**: Call `action="schema"` for compact field metadata
+3. **Start with list**: Use `action="list"` to discover existing resources
+4. **Chain operations**: List servers → list sites → deploy (follow the hierarchy)
+5. **Scope matters**: Server-scoped resources need `server_id`, site-scoped need both `server_id` and `site_id`
+6. **Read vs Write**: Use `forge` for queries, `forge_write` for mutations — MCP clients enforce this split