gameye-mcp 0.1.2 → 0.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 A [Model Context Protocol](https://modelcontextprotocol.io) server for the [Gameye](https://gameye.com) game server orchestration API. It lets an AI agent (Claude Code, Claude Desktop, Cursor, or any MCP client) launch and inspect game server sessions, check image tags and regions, and fetch logs and artifacts. You talk to it in plain language, and you don't have to leave your editor.
 
-> **Status: beta** (`0.x`). Tools, inputs and outputs may change between releases, and there may be bugs. The server says so to every client that connects, on startup, and in `gameye_context`. It is published on npm as [`gameye-mcp`](https://www.npmjs.com/package/gameye-mcp); see the [changelog](https://github.com/Gameye/gameye-mcp/blob/main/CHANGELOG.md) for what changed in each release.
+> **Status: beta** (`0.x`). Tools, inputs and outputs may change between releases, and there may be bugs. The server says so to every client that connects, on startup, and in `gameye_context`. It is published on npm as [`gameye-mcp`](https://www.npmjs.com/package/gameye-mcp), as a container image at `ghcr.io/gameye/gameye-mcp`, and in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.Gameye/gameye-mcp`; see the [changelog](https://github.com/Gameye/gameye-mcp/blob/main/CHANGELOG.md) for what changed in each release.
 
 ## Quick start
 
@@ -30,7 +30,6 @@ The environment is a property of the server process. No tool takes an environmen
 | `GAMEYE_API_TOKEN` | **Yes** | — | Gameye API token. Use the least-privileged scopes you need (see below). |
 | `GAMEYE_ENV` | No | `sandbox` | `sandbox` or `production`. Selects the API host. |
 | `GAMEYE_API_URL` | No | — | Overrides the host, for testing only. Must be `https`. If it equals one of the two known hosts, it must match `GAMEYE_ENV` or the server refuses to start. Any other URL is labelled `custom` in every tool result. |
-| `GAMEYE_ENABLE_ADMIN_TOOLS` | No | unset | Set to `1` to register the admin tools (create or edit applications, create tokens). They stay off when this is unset. |
 | `GAMEYE_TIMEOUT_MS` | No | `30000` | Per-request timeout in milliseconds, a positive whole number. Log snapshots get at least 60 s and artifact downloads at least 120 s. A request that runs out of time comes back as a tool error: `Request to <host> timed out after <n>s`. |
 
 ## Install
@@ -64,7 +63,7 @@ Most clients (Claude Desktop, Cursor, Windsurf and others) accept an `mcpServers
 
 Restart the client after you change its configuration.
 
-`npx -y gameye-mcp` runs the latest release. To stay on one version, name it: `npx -y gameye-mcp@0.1.2` (or `"args": ["-y", "gameye-mcp@0.1.2"]`).
+`npx -y gameye-mcp` runs the latest release. To stay on one version, name it: `npx -y gameye-mcp@0.2.0` (or `"args": ["-y", "gameye-mcp@0.2.0"]`).
 
 ### Docker
 
@@ -89,10 +88,10 @@ With Claude Code: `claude mcp add gameye --env GAMEYE_API_TOKEN=<your-token> --
 
 - Pass each variable with `-e NAME` (no value), so Docker copies it from the client's environment and the token never appears in the command line.
 - Keep `-i` and never add `-t`: a terminal mangles the JSON-RPC messages on stdout.
-- To stay on one version, use a version tag such as `ghcr.io/gameye/gameye-mcp:0.1.2`.
+- To stay on one version, use a version tag such as `ghcr.io/gameye/gameye-mcp:0.2.0`.
 - Files the server writes stay inside the container, and `--rm` deletes them:
   - `gameye_get_artifacts` saves its download under the temp directory. To keep it, mount a directory and point the temp directory at it: `-v /absolute/dir:/out -e TMPDIR=/out`. The path the tool reports is the container path; the file is in `/absolute/dir` on the host.
-  - `gameye_create_token` (admin tools only) writes to the `outputPath` you give it. Mount a directory the same way and pass an `outputPath` under `/out`.
+  - `gameye_create_token` writes to the `outputPath` you give it. Mount a directory the same way and pass an `outputPath` under `/out`.
   - The server runs as uid 1000, so on Linux the mounted directory must be writable by that user.
 
 ## Token scopes
@@ -103,7 +102,8 @@ Give the server a token with only the scopes it needs.
 |---|---|---|
 | Observer | `session:read` `logs:read` `artifact:read` `regions:read` `region:read` `application:read` | Inspect sessions, logs, artifacts, regions and applications. No changes. |
 | Operator | Observer + `session:start` `session:stop` `session:write` | Also launch and stop sessions and update session state. |
-| Admin tools | Operator + `application:write` `token:write` | Also create or edit applications and create tokens. Requires `GAMEYE_ENABLE_ADMIN_TOOLS=1`. |
+| Deployer | Operator + `application:write` | Also create and edit applications, so the agent can set up a deployment end to end. |
+| Token admin | Deployer + `token:write` | Also create API tokens. |
 
 **Never pass your Gameye API token into a game server's environment.** A game server doesn't need it, and anything inside the container can read it.
 
@@ -113,7 +113,7 @@ Every tool result starts with the environment and host it used, for example `[sa
 
 | Tool | Kind | Description |
 |---|---|---|
-| `gameye_context` | read | Show the environment, host and server version this server targets, whether admin tools are enabled, and the guardrail defaults (session TTL, `launched-by` label, token expiry) |
+| `gameye_context` | read | Show the environment, host and server version this server targets, and the guardrail defaults (session TTL, `launched-by` label, token expiry) |
 | `gameye_launch_session` | write, `dryRun` | Start a containerized game server (billable). Default TTL and agent label applied; see [Guardrails](#guardrails) |
 | `gameye_list_sessions` | read | List running sessions (filterable; `all=true` for every status) |
 | `gameye_describe_session` | read | Get session details, ports and players |
@@ -128,9 +128,9 @@ Every tool result starts with the environment and host it used, for example `[sa
 | `gameye_enable_tag` | write, `dryRun` | Enable an image tag for an application so Gameye preloads it |
 | `gameye_get_logs` | read | Fetch session logs |
 | `gameye_get_artifacts` | read | Download a file or directory from a session container as a tar archive |
-| `gameye_create_application` | admin, `dryRun` | Create an application. Only with `GAMEYE_ENABLE_ADMIN_TOOLS=1` |
-| `gameye_edit_application` | admin, destructive, `dryRun` | Change an application; omitted fields stay unchanged. Only with `GAMEYE_ENABLE_ADMIN_TOOLS=1` |
-| `gameye_create_token` | admin, `dryRun` | Create an API token and write it to a file. Only with `GAMEYE_ENABLE_ADMIN_TOOLS=1` |
+| `gameye_create_application` | write, `dryRun` | Create an application |
+| `gameye_edit_application` | destructive, `dryRun` | Change an application; omitted fields stay unchanged |
+| `gameye_create_token` | write, `dryRun` | Create an API token and write it to a file |
 
 Every tool carries MCP annotations: read tools set `readOnlyHint`, `gameye_stop_session` and `gameye_edit_application` set `destructiveHint`, and every tool that calls the Gameye API sets `openWorldHint`.
 
@@ -140,7 +140,7 @@ The tool set covers every operation in the Gameye client API. `tests/parity.test
 
 These behave the same on sandbox and production, because sandbox runs live matches for self-serve customers.
 
-- **Dry run.** `gameye_launch_session`, `gameye_stop_session`, `gameye_enable_tag` and the admin tools accept `dryRun: true`. The tool returns the exact request (method, host, path and body) with the API token masked, and sends nothing.
+- **Dry run.** `gameye_launch_session`, `gameye_stop_session`, `gameye_enable_tag` and the application and token tools accept `dryRun: true`. The tool returns the exact request (method, host, path and body) with the API token masked, and sends nothing.
 - **Bounded sessions.** A launch without `ttl` gets a `30m` TTL, and the result says the default was applied. Every launch sends the label `launched-by: gameye-mcp`, replacing any `launched-by` value the caller passes, so agent-launched sessions can be found with `gameye_list_sessions` and `filter: { "launched-by": "gameye-mcp" }`. When a warm pool serves the image and region, the Gameye API ignores request labels (and env and args), so warm-pool sessions do not carry this label.
 - **No token in game servers.** A launch is refused, with nothing sent, if any env value or name, arg, or label key or value contains this server's Gameye API token. Env values are never shown in results.
 - **No token in results.** Every tool result, including errors, has this server's API token replaced with `***`, in case log output, labels or an error message echo it.
@@ -150,9 +150,9 @@ These behave the same on sandbox and production, because sandbox runs live match
 
 Every request to the Gameye API sends `User-Agent: gameye-mcp/<version>`, plus the MCP client's name once it has connected, e.g. `gameye-mcp/0.1.0 (claude-code)`, so Gameye can count MCP usage. Only this server's version and the client name are sent, nothing else: no token, env values, paths or other data. There is no other telemetry.
 
-## Admin tools
+## Application and token tools
 
-`gameye_create_application`, `gameye_edit_application` and `gameye_create_token` are registered only when the server starts with `GAMEYE_ENABLE_ADMIN_TOOLS=1`. Without it, they don't appear in the tool list at all. They need a token with `application:write` or `token:write`.
+`gameye_create_application`, `gameye_edit_application` and `gameye_create_token` are always registered. What the agent can actually do is set by the token's scopes: they need `application:write` or `token:write`, and a token without them gets a 403 naming the missing scope. To keep an agent from changing applications or minting tokens, give it a token without those scopes.
 
 `gameye_create_token` never returns the new token. It writes the token to the file you name in `outputPath` and returns only the path, the scopes and the expiry:
 
@@ -185,6 +185,14 @@ npm run build
 
 `spec/client.yaml` is a snapshot of the public sandbox `/openapi.yaml`, and `spec/overrides.yaml` holds the MCP tool name for each operation: the `tools:` map from [gameye-skills](https://github.com/gameye/gameye-skills)' `spec/overrides.yaml`, reduced by `scripts/reduce-overrides.mjs` (gameye-skills keeps the full file, which records where the server differs from the spec). Refresh both with `npm run sync-spec [path-or-url-to-overrides.yaml]`. `npm run check-spec` exits 1 when either snapshot has drifted.
 
+## About Gameye
+
+[Gameye](https://gameye.com/?utm_source=github&utm_medium=readme&utm_campaign=gameye-mcp) is a managed hosting platform for multiplayer game servers. You bring a container image, and Gameye starts a dedicated server for each match through one API.
+
+- Session API docs: [gameye.com/docs/api-v2](https://gameye.com/docs/api-v2/?utm_source=github&utm_medium=readme&utm_campaign=gameye-mcp)
+- Gameye docs: [gameye.com/docs](https://gameye.com/docs/?utm_source=github&utm_medium=readme&utm_campaign=gameye-mcp)
+- Try it free: [trial.gameye.com](https://trial.gameye.com/?utm_source=github&utm_medium=readme&utm_campaign=gameye-mcp)
+
 ## Security
 
 Please report vulnerabilities privately. See [SECURITY.md](SECURITY.md).

package/dist/env.d.ts

@@ -34,9 +34,3 @@ export declare function resultPrefix(config: {
     environment: EnvironmentLabel;
     host: string;
 }): string;
-/**
- * Admin tools (create/edit application, create token) register only when
- * GAMEYE_ENABLE_ADMIN_TOOLS is exactly `1`, so credential- and config-changing
- * tools are invisible unless the operator opts in.
- */
-export declare function adminToolsEnabled(env: Record<string, string | undefined>): boolean;

package/dist/env.js

@@ -112,11 +112,3 @@ export function loadConfigOrExit(env = process.env) {
 export function resultPrefix(config) {
     return `[${config.environment} · ${config.host}]`;
 }
-/**
- * Admin tools (create/edit application, create token) register only when
- * GAMEYE_ENABLE_ADMIN_TOOLS is exactly `1`, so credential- and config-changing
- * tools are invisible unless the operator opts in.
- */
-export function adminToolsEnabled(env) {
-    return env.GAMEYE_ENABLE_ADMIN_TOOLS?.trim() === "1";
-}

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { GameyeClient } from "./client.js";
-import { adminToolsEnabled, loadConfigOrExit } from "./env.js";
+import { loadConfigOrExit } from "./env.js";
 import { registerAllTools } from "./tools/register.js";
 import { createServer } from "./server.js";
 import { BETA_NOTICE } from "./beta.js";
@@ -16,11 +16,10 @@ const ctx = {
     mask: (text) => client.maskToken(text),
 };
 const server = createServer(version);
-const admin = adminToolsEnabled(process.env);
-registerAllTools(server, client, ctx, { admin });
+registerAllTools(server, client, ctx);
 // Attribute API traffic to the MCP client (name only) once it has introduced itself.
 server.server.oninitialized = () => client.setClientName(server.server.getClientVersion()?.name);
 const transport = new StdioServerTransport();
 await server.connect(transport);
-console.error(`Gameye MCP server ${version} running on stdio [${ctx.environment} · ${ctx.host}]${admin ? " with admin tools enabled" : ""}`);
+console.error(`Gameye MCP server ${version} running on stdio [${ctx.environment} · ${ctx.host}]`);
 console.error(BETA_NOTICE);

package/dist/tools/applications.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { GameyeClient } from "../client.js";
-import { type RegisterOptions, type ServerContext } from "./common.js";
-export declare function registerApplicationTools(server: McpServer, client: GameyeClient, ctx: ServerContext, opts: RegisterOptions): void;
+import { type ServerContext } from "./common.js";
+export declare function registerApplicationTools(server: McpServer, client: GameyeClient, ctx: ServerContext): void;

package/dist/tools/applications.js

@@ -49,7 +49,7 @@ function formatApplication(a) {
         `    ports: ${formatPortBindings(a.ports) || "(none)"}`,
     ].join("\n");
 }
-export function registerApplicationTools(server, client, ctx, opts) {
+export function registerApplicationTools(server, client, ctx) {
     // ─── List applications ───────────────────────────────────────────────────────
     defineTool(server, ctx, "gameye_list_applications", {
         title: "List applications",
@@ -97,9 +97,7 @@ export function registerApplicationTools(server, client, ctx, opts) {
         await client.enableTag(name, tag);
         return `Tag ${tag} enabled for ${name}. Preloading can take a while; use gameye_check_tag to confirm it is available in a region.`;
     });
-    if (!opts.admin)
-        return;
-    // ─── Create application (admin) ──────────────────────────────────────────────
+    // ─── Create application ──────────────────────────────────────────────────────
     defineTool(server, ctx, "gameye_create_application", {
         title: "Create application",
         description: "Admin tool. Create a new application (an image Gameye can run). " +
@@ -117,7 +115,7 @@ export function registerApplicationTools(server, client, ctx, opts) {
         await client.createApplication(body);
         return `Application ${body.name} created.`;
     });
-    // ─── Edit application (admin) ────────────────────────────────────────────────
+    // ─── Edit application ────────────────────────────────────────────────────────
     defineTool(server, ctx, "gameye_edit_application", {
         title: "Edit application",
         description: "Admin tool. Change an existing application with PUT /application/{name}. Fields you omit stay unchanged; regions and ports, when given, replace the whole list. " +

package/dist/tools/common.d.ts

@@ -5,11 +5,6 @@ import { GameyeError } from "../client.js";
 import { type EnvironmentLabel } from "../env.js";
 /** Shared `dryRun` input for every tool that sends a write. */
 export declare const dryRunInput: z.ZodOptional<z.ZodBoolean>;
-/** Tool registration options. Admin tools only when GAMEYE_ENABLE_ADMIN_TOOLS=1. */
-export interface RegisterOptions {
-    /** Register admin tools (create/edit application, create token). */
-    admin: boolean;
-}
 /** What every tool needs to know about the server it runs in. Never holds the token. */
 export interface ServerContext {
     environment: EnvironmentLabel;

package/dist/tools/context.d.ts

@@ -1,3 +1,3 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { type RegisterOptions, type ServerContext } from "./common.js";
-export declare function registerContextTool(server: McpServer, ctx: ServerContext, opts: RegisterOptions): void;
+import { type ServerContext } from "./common.js";
+export declare function registerContextTool(server: McpServer, ctx: ServerContext): void;

package/dist/tools/context.js

@@ -1,10 +1,10 @@
 import { AGENT_LABEL_KEY, AGENT_LABEL_VALUE, DEFAULT_SESSION_TTL, DEFAULT_TOKEN_EXPIRY } from "../guards.js";
 import { defineTool } from "./common.js";
 import { BETA_NOTICE } from "../beta.js";
-export function registerContextTool(server, ctx, opts) {
+export function registerContextTool(server, ctx) {
     defineTool(server, ctx, "gameye_context", {
         title: "Server context",
-        description: "Show which Gameye environment and host this server targets, the server version, whether admin tools are enabled, and the guardrail defaults. The environment is fixed when the server starts (GAMEYE_ENV / GAMEYE_API_URL) and cannot be changed by a tool call.",
+        description: "Show which Gameye environment and host this server targets, the server version and the guardrail defaults. The environment is fixed when the server starts (GAMEYE_ENV / GAMEYE_API_URL) and cannot be changed by a tool call.",
         inputSchema: {},
         annotations: { readOnlyHint: true, openWorldHint: false },
     }, async () => [
@@ -13,7 +13,6 @@ export function registerContextTool(server, ctx, opts) {
         `Host:           ${ctx.host}`,
         `Base URL:       ${ctx.baseUrl}`,
         `Server version: gameye-mcp ${ctx.version}`,
-        `Admin tools:    ${opts.admin ? "enabled" : "disabled (set GAMEYE_ENABLE_ADMIN_TOOLS=1 to enable)"}`,
         "",
         "Guardrail defaults:",
         `  Session TTL:   ${DEFAULT_SESSION_TTL} when a launch gives no ttl`,

package/dist/tools/register.d.ts

@@ -1,6 +1,5 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { GameyeClient } from "../client.js";
-import type { RegisterOptions, ServerContext } from "./common.js";
-export type { RegisterOptions };
-/** Register every tool. Admin tools only when `opts.admin` is true. */
-export declare function registerAllTools(server: McpServer, client: GameyeClient, ctx: ServerContext, opts: RegisterOptions): void;
+import type { ServerContext } from "./common.js";
+/** Register every tool. */
+export declare function registerAllTools(server: McpServer, client: GameyeClient, ctx: ServerContext): void;

package/dist/tools/register.js

@@ -8,17 +8,16 @@ import { registerApplicationTools } from "./applications.js";
 import { registerTokenTools } from "./tokens.js";
 import { registerLogTools } from "./logs.js";
 import { registerArtifactTools } from "./artifacts.js";
-/** Register every tool. Admin tools only when `opts.admin` is true. */
-export function registerAllTools(server, client, ctx, opts) {
-    registerContextTool(server, ctx, opts);
+/** Register every tool. */
+export function registerAllTools(server, client, ctx) {
+    registerContextTool(server, ctx);
     registerSessionTools(server, client, ctx);
     registerPlayerTools(server, client, ctx);
     registerLocationTools(server, client, ctx);
     registerRegionTools(server, client, ctx);
     registerTagTools(server, client, ctx);
-    registerApplicationTools(server, client, ctx, opts);
+    registerApplicationTools(server, client, ctx);
     registerLogTools(server, client, ctx);
     registerArtifactTools(server, client, ctx);
-    if (opts.admin)
-        registerTokenTools(server, client, ctx);
+    registerTokenTools(server, client, ctx);
 }

package/dist/tools/tokens.d.ts

@@ -1,5 +1,4 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { GameyeClient } from "../client.js";
 import { type ServerContext } from "./common.js";
-/** Admin tool. Register only when GAMEYE_ENABLE_ADMIN_TOOLS=1. */
 export declare function registerTokenTools(server: McpServer, client: GameyeClient, ctx: ServerContext): void;

package/dist/tools/tokens.js

@@ -2,7 +2,6 @@ import { z } from "zod";
 import { GameyeClient } from "../client.js";
 import { DEFAULT_TOKEN_EXPIRY, GuardError, checkTokenOutputPath, formatDryRun, reserveTokenFile } from "../guards.js";
 import { defineTool } from "./common.js";
-/** Admin tool. Register only when GAMEYE_ENABLE_ADMIN_TOOLS=1. */
 export function registerTokenTools(server, client, ctx) {
     defineTool(server, ctx, "gameye_create_token", {
         title: "Create API token",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gameye-mcp",
-  "version": "0.1.2",
-  "mcpName": "io.github.gameye/gameye-mcp",
+  "version": "0.2.0",
+  "mcpName": "io.github.Gameye/gameye-mcp",
   "description": "MCP server for the Gameye game server orchestration API: launch and inspect sessions, check image tags, fetch logs and artifacts from any MCP client",
   "main": "dist/index.js",
   "bin": {