@studiometa/forge-mcp 0.2.3 → 0.2.4

package/skills/SKILL.md

@@ -22,9 +22,9 @@ Before your first interaction with any resource, call `action="help"` with that
 
 ### `forge` — Read Operations
 
-Safe, read-only queries. Use for listing, getting details, help, and schema.
+Safe, read-only queries. Use for listing, getting details, resolving names, fetching context snapshots, help, and schema.
 
-**Actions**: `list`, `get`, `help`, `schema`
+**Actions**: `list`, `get`, `resolve`, `context`, `help`, `schema`
 
 ```
 forge(resource, action, [parameters...])
@@ -42,24 +42,29 @@ 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 |
+| Resource          | Read Actions (`forge`)              | Write Actions (`forge_write`)  | Scope  |
+| ----------------- | ----------------------------------- | ------------------------------ | ------ |
+| `servers`         | `list`, `get`, `resolve`, `context` | `create`, `delete`, `reboot`   | global |
+| `sites`           | `list`, `get`, `resolve`, `context` | `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 |
+| `scheduled-jobs`  | `list`, `get`                       | `create`, `delete`             | server |
+| `backups`         | `list`, `get`                       | `create`, `delete`             | server |
+| `commands`        | `list`, `get`                       | `create`                       | site   |
+| `user`            | `get`                               | —                              | global |
+| `batch`           | `run`                               | —                              | global |
 
 ### Scope Guide
 
@@ -67,6 +72,31 @@ forge_write(resource, action, [parameters...])
 - **server**: Requires `server_id` (e.g. `sites`, `databases`, `daemons`)
 - **site**: Requires `server_id` + `site_id` (e.g. `deployments`, `env`, `certificates`)
 
+### Auto-Resolve: Names Instead of IDs
+
+`server_id` and `site_id` accept **name strings** in addition to numeric IDs. When a non-numeric value is provided, the server automatically performs a case-insensitive partial match against known resources:
+
+- **`server_id`**: Matched against server names (e.g. `"prod"` resolves `"production-web-01"`)
+- **`site_id`**: Matched against site domains (e.g. `"myapp"` resolves `"myapp.example.com"`)
+
+Resolution rules:
+
+- **Exact single match** → resolved silently, the call proceeds normally
+- **Ambiguous (multiple matches)** → error listing all candidates; use a more specific name or numeric ID
+- **No match** → error with a hint to use `action: "resolve"` to search
+
+This applies to **every** resource and action automatically — no special syntax needed.
+
+Use `action: "resolve"` explicitly when you need to search or preview matches before acting:
+
+```json
+// Search servers by name
+{ "resource": "servers", "action": "resolve", "query": "prod" }
+
+// Search sites on a server by domain
+{ "resource": "sites", "action": "resolve", "server_id": "123", "query": "myapp" }
+```
+
 ### Getting Help
 
 Use `action: "help"` to get detailed documentation for any resource:
@@ -84,15 +114,17 @@ Use `action: "schema"` for a compact machine-readable spec:
 
 ## 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` |
+| 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 **or name** — numeric IDs are used as-is; names are auto-resolved via partial match           |
+| `site_id`    | string  | Site ID **or domain name** — auto-resolved via partial match; requires `server_id`                      |
+| `query`      | string  | Search query for `resolve` action (partial, case-insensitive match against resource names/domains)      |
+| `compact`    | boolean | Compact output (default: true)                                                                          |
+| `content`    | string  | Content for env/nginx `update` and deployment script `update`                                           |
+| `operations` | array   | Array of operations for `batch` `run` (max 10). Each item needs `resource`, `action`, and extra params. |
 
 ## Common Workflows
 
@@ -172,6 +204,93 @@ Use `action: "schema"` for a compact machine-readable spec:
 { "resource": "recipes", "action": "run", "id": "456", "servers": [1, 2, 3] }
 ```
 
+### Auto-Resolve: Deploy Using Names Instead of IDs
+
+No need to look up numeric IDs first — just pass names directly:
+
+```json
+// Deploy using server name and site domain (forge_write)
+// "prod" and "myapp.example.com" are auto-resolved to numeric IDs
+{ "resource": "deployments", "action": "deploy", "server_id": "prod", "site_id": "myapp.example.com" }
+
+// Update env using a partial server name and domain fragment
+{ "resource": "env", "action": "get", "server_id": "production", "site_id": "myapp" }
+```
+
+### Resolve: Find Resources by Name
+
+Use `action: "resolve"` to search resources by name before acting:
+
+```json
+// Find servers matching "prod" (forge)
+{ "resource": "servers", "action": "resolve", "query": "prod" }
+// → returns matches: [{ id: 123, name: "production-web-01" }, ...]
+
+// Find sites on a server matching a domain fragment (forge)
+{ "resource": "sites", "action": "resolve", "server_id": "123", "query": "myapp" }
+// → returns matches: [{ id: 456, name: "myapp.example.com" }, ...]
+```
+
+### Context: Get a Full Snapshot in One Call
+
+`action: "context"` fetches a resource plus all its sub-resources in a single parallel call — ideal for orientation at the start of a session:
+
+```json
+// Server context (forge) — returns server + sites, databases, database_users,
+//                           daemons, firewall_rules, scheduled_jobs
+{ "resource": "servers", "action": "context", "id": "123" }
+
+// Site context (forge) — returns site + deployments (last 5), certificates,
+//                          redirect_rules, security_rules
+{ "resource": "sites", "action": "context", "server_id": "123", "id": "456" }
+
+// Combine with auto-resolve: use names instead of IDs
+{ "resource": "servers", "action": "context", "id": "prod" }
+```
+
+### Batch: Multiple Reads in a Single Call
+
+`resource: "batch"` with `action: "run"` executes up to 10 read operations in parallel, reducing round-trips:
+
+```json
+// Fetch servers list + user info in one call (forge)
+{
+  "resource": "batch",
+  "action": "run",
+  "operations": [
+    { "resource": "servers", "action": "list" },
+    { "resource": "user", "action": "get" }
+  ]
+}
+
+// Fetch multiple site sub-resources in parallel (forge)
+{
+  "resource": "batch",
+  "action": "run",
+  "operations": [
+    { "resource": "env",          "action": "get",  "server_id": "123", "site_id": "456" },
+    { "resource": "certificates", "action": "list", "server_id": "123", "site_id": "456" },
+    { "resource": "deployments",  "action": "list", "server_id": "123", "site_id": "456" }
+  ]
+}
+```
+
+Result shape:
+
+```json
+{
+  "_batch": { "total": 2, "succeeded": 2, "failed": 0 },
+  "results": [
+    { "index": 0, "resource": "servers", "action": "list", "data": [...] },
+    { "index": 1, "resource": "user",    "action": "get",  "data": {...} }
+  ]
+}
+```
+
+Per-operation failures are isolated — a single error doesn't abort the rest.
+
+> **Note**: Batch only supports read actions (`list`, `get`, `resolve`, `context`, `help`, `schema`). Write operations must use `forge_write` individually.
+
 ## Authentication
 
 ### Stdio Mode (Claude Desktop)
@@ -217,3 +336,7 @@ All `forge_write` operations are automatically logged to `~/.config/forge-tools/
 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
+7. **Use names, not IDs**: Pass server names and site domains directly — they are auto-resolved to numeric IDs
+8. **Use `context` for orientation**: One call fetches a server or site plus all its sub-resources in parallel
+9. **Use `batch` to cut round-trips**: Bundle up to 10 read operations into a single `forge` call
+10. **Use `resolve` to preview**: Search for resources by name before committing to an action