diff --git a/skills/supercraft/game-servers/SKILL.md b/skills/supercraft/game-servers/SKILL.md new file mode 100644 index 00000000000..d110c4c6212 --- /dev/null +++ b/skills/supercraft/game-servers/SKILL.md @@ -0,0 +1,122 @@ +--- +name: supercraft-game-servers +description: Order, configure, and manage dedicated game servers (17+ games) via Supercraft REST API +homepage: https://claws.supercraft.host +user-invocable: true +--- + +You can manage dedicated game servers through the Supercraft Agentic API. This is a REST API — no additional binaries or MCP servers are needed, just HTTP requests with a Bearer JWT token. + +## API Base + +``` +https://claws.supercraft.host +``` + +## Authentication + +All `/servers/*` endpoints require a Bearer JWT token in the `Authorization` header. + +To get a token, use the login-link flow: + +1. `POST /auth/login-link` with `{"email": "user@example.com"}` — sends a magic link email +2. User clicks the link, which contains a magic token +3. `GET /auth/claim?magic=` — poll this until it returns a JWT + +```bash +# After obtaining the JWT: +curl -H "Authorization: Bearer " https://claws.supercraft.host/servers +``` + +## Available Endpoints + +### Server Management (requires auth) + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/servers` | List all user's servers with status | +| GET | `/servers/{id}` | Detailed server info with live status | +| POST | `/servers/{id}/start` | Start the server | +| POST | `/servers/{id}/stop` | Stop the server | +| POST | `/servers/{id}/restart` | Restart the server | +| GET | `/servers/{id}/config` | Get current server configuration | +| PUT | `/servers/{id}/config` | Update server configuration | +| GET | `/servers/{id}/config/schema` | Get config field definitions (types, ranges) | +| GET | `/servers/{id}/connection` | Get connection details (IP, port, password) | +| POST | `/servers/{id}/console` | Send RCON/console command | +| GET | `/servers/{id}/logs` | Get recent server log lines | + +### Catalog (no auth needed) + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/catalog/games` | List all available games | +| GET | `/catalog/games/{code}` | Game details with plans and pricing | +| GET | `/catalog/regions` | Available server regions | + +### Purchasing (no auth needed) + +| Method | Endpoint | Description | +|--------|----------|-------------| +| POST | `/orders/purchase` | Purchase a new server plan (returns checkout URL) | + +## Purchase & Login Flow — CRITICAL + +When generating a `checkout_url` (via `POST /orders/purchase`) or `login_url` (via `POST /auth/login-link`), you **MUST send the link to the user as a message BEFORE calling any tools** (curl, exec, cron). If you call a tool first, the message with the link gets blocked and the user never sees it. + +Correct sequence: +1. **Reply to the user** with the `checkout_url` or `login_url` +2. **After the reply**, set up a cron (every 30s) to poll `GET /auth/claim?magic=...` +3. When claim returns `status: "ready"`, save the JWT token securely + +Do NOT use `while`/`sleep` loops — use a cron job or poll on the user's next message. + +## Supported Games + +ARK: Survival Ascended, Counter-Strike 2, Enshrouded, Factorio, HumanitZ, Hytale, Necesse, Palworld, Project Zomboid, Rust, Satisfactory, Sons of the Forest, Terraria, Unturned, V Rising, Valheim, and Vintage Story. + +## Example Usage + +When the user asks about their game server, follow this pattern: + +1. List servers (`GET /servers`) to find the right deployment +2. Check status (`GET /servers/{id}`) before taking action +3. Confirm destructive operations (restart, config changes) before executing + +**Check server status:** +```bash +curl -H "Authorization: Bearer $TOKEN" https://claws.supercraft.host/servers +``` + +**Start a server:** +```bash +curl -X POST -H "Authorization: Bearer $TOKEN" https://claws.supercraft.host/servers/42/start +``` + +**Update config:** +```bash +curl -X PUT -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"max_players": 20}' \ + https://claws.supercraft.host/servers/42/config +``` + +**Send console command:** +```bash +curl -X POST -H "Authorization: Bearer $TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"command": "say Hello everyone!"}' \ + https://claws.supercraft.host/servers/42/console +``` + +**Browse available games:** +```bash +curl https://claws.supercraft.host/catalog/games +``` + +## Documentation + +- [Getting Started Guide](https://claws.supercraft.host/documentation-for-agents/getting-started.md) +- [OpenAPI Reference](https://claws.supercraft.host/docs) +- [Machine-readable discovery](https://supercraft.host/llms.txt) +- Per-game API guides: `https://claws.supercraft.host/{game-slug}-server-api` diff --git a/skills/supercraft/game-servers/_meta.json b/skills/supercraft/game-servers/_meta.json new file mode 100644 index 00000000000..cb883b707ce --- /dev/null +++ b/skills/supercraft/game-servers/_meta.json @@ -0,0 +1,9 @@ +{ + "owner": "supercraft", + "slug": "game-servers", + "displayName": "Supercraft Game Servers", + "latest": { + "version": "1.0.0" + }, + "history": [] +}