gameye-mcp 0.3.1 → 0.4.0

package/README.md

@@ -1,5 +1,7 @@
 # Gameye MCP Server
 
+[![Discord](https://img.shields.io/badge/Discord-join%20chat-5865F2?logo=discord&logoColor=white)](https://discord.com/invite/QvJ3KH5max)
+
 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), 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.
@@ -30,6 +32,11 @@ 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_SKILLS_UPDATE` | No | — | Set to `1` to let `gameye_update_skills` run the skills updaters with `apply: true`. Without it the tool only checks and lists the commands. |
+| `GAMEYE_MAX_SESSIONS` | No | `5` | Most sessions launched by this server that may run at once. A launch past it is refused. |
+| `GAMEYE_MAX_TTL` | No | `4h` | Longest `ttl` a launch may ask for, at least `30m`. A longer TTL, or `0`, is refused. |
+| `GAMEYE_MAX_LAUNCHES` | No | `20` | Launches per server run. Restart the server to reset it. |
+| `GAMEYE_STOP_OWN_ONLY` | No | — | Set to `1` so `gameye_stop_session` only stops sessions this server launched. |
 | `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
@@ -63,7 +70,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.3.1` (or `"args": ["-y", "gameye-mcp@0.3.1"]`).
+`npx -y gameye-mcp` runs the latest release. To stay on one version, name it: `npx -y gameye-mcp@0.4.0` (or `"args": ["-y", "gameye-mcp@0.4.0"]`).
 
 ### Windows
 
@@ -105,7 +112,7 @@ 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.3.1`.
+- To stay on one version, use a version tag such as `ghcr.io/gameye/gameye-mcp:0.4.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` writes to the `outputPath` you give it. Mount a directory the same way and pass an `outputPath` under `/out`.
@@ -162,7 +169,8 @@ These behave the same on sandbox and production, because sandbox runs live match
 - **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.
-- **Explicit stops.** `gameye_stop_session` stops exactly one session by its exact ID. There is no bulk stop, and empty, wildcard or list IDs are refused.
+- **Explicit stops.** `gameye_stop_session` stops exactly one session by its exact ID. There is no bulk stop, and empty, wildcard or list IDs are refused. With `GAMEYE_STOP_OWN_ONLY=1` it also refuses any session this server did not launch.
+- **Session limits.** The Gameye API has no per-token budget, so the server enforces one before it sends a launch. By default an agent can have at most 5 sessions it launched running at once (`GAMEYE_MAX_SESSIONS`), each with a TTL of at most `4h` (`GAMEYE_MAX_TTL`), and at most 20 launches per server run (`GAMEYE_MAX_LAUNCHES`). That caps one run at 20 sessions of 4 hours, 80 session-hours, and 5 at a time. Before each launch the server lists the `launched-by: gameye-mcp` sessions to see which of its own have ended; if that list fails, the launch is refused. Warm-pool sessions carry no label, so they count until their TTL ends. A launch that timed out or got a 5xx may have started, so it counts too. The limits apply to one server process: sessions launched by other agents or tools in your organization don't count, and a restart starts from zero, so set an organization quota in Gameye as well. `gameye_context` shows the limits in force.
 
 ## Keeping the skills current
 
@@ -172,7 +180,7 @@ The [Gameye skills](https://github.com/gameye/gameye-skills) change as the Gamey
 - **skills CLI, this project:** the same, in `skills-lock.json` in the server's working directory.
 - **Claude Code plugin:** `gameye@gameye` in `~/.claude/plugins/installed_plugins.json`.
 
-Without `apply` it only reports. With `apply: true` it runs each outdated install's own updater: `npx -y skills update <the Gameye skills> -g -y` (or `-p -y`), or `claude plugin marketplace update gameye` then `claude plugin update gameye@gameye`. It only updates skills whose lock-file source is `gameye/gameye-skills`, and it never downloads or follows skill text itself. Each command runs with stdin closed and a 90-second limit. On Windows it prints the commands instead of running them. The running agent session keeps the skills it loaded; the next session uses the update. The `gameye` skill tells agents to run the check once per conversation and ask before applying.
+Without `apply` it only reports. With `apply: true`, and only when the server was started with `GAMEYE_ENABLE_SKILLS_UPDATE=1`, it runs each outdated install's own updater: `npx -y skills@1.7.4 update <the Gameye skills> -g -y` (or `-p -y`), or `claude plugin marketplace update gameye` then `claude plugin update gameye@gameye`. Otherwise it lists those commands for you to run. The updaters get a minimal environment: paths, home, temp, locale, proxy and CA settings and npm and Claude config, never `GAMEYE_*` variables or anything named like a token, secret, password or key. It only updates skills whose lock-file source is `gameye/gameye-skills`, and it never downloads or follows skill text itself. Each command runs with stdin closed and a 90-second limit. On Windows it prints the commands instead of running them. The running agent session keeps the skills it loaded; the next session uses the update. The `gameye` skill tells agents to run the check once per conversation and ask before applying.
 
 ## Telemetry/attribution
 

package/dist/env.d.ts

@@ -16,7 +16,22 @@ export interface ResolvedConfig {
     token: string;
     /** Default per-request timeout in milliseconds (GAMEYE_TIMEOUT_MS, default 30s). */
     timeoutMs: number;
+    /** Local launch and stop limits (GAMEYE_MAX_SESSIONS, GAMEYE_MAX_TTL, GAMEYE_MAX_LAUNCHES, GAMEYE_STOP_OWN_ONLY). */
+    limits: SessionLimits;
 }
+/** Limits on what an agent can start through one server process. See limits.ts. */
+export interface SessionLimits {
+    /** Sessions started by this process that may run at once. */
+    maxSessions: number;
+    /** Longest TTL a launch may ask for, as given (e.g. `4h`). */
+    maxTtl: string;
+    maxTtlMs: number;
+    /** Launches per server process. */
+    maxLaunches: number;
+    /** Stop only sessions this process started. */
+    stopOwnOnly: boolean;
+}
+export declare const DEFAULT_LIMITS: SessionLimits;
 /** Per-request timeout used when GAMEYE_TIMEOUT_MS is not set. */
 export declare const DEFAULT_TIMEOUT_MS = 30000;
 export declare class ConfigError extends Error {

package/dist/env.js

@@ -3,10 +3,20 @@
 // The Gameye environment is a property of the server process, never of a
 // single tool call: an agent cannot switch to production mid-conversation.
 // Users who need both environments run two named server entries.
+import { parseDurationMs } from "./limits.js";
 export const KNOWN_HOSTS = {
     sandbox: "https://api.sandbox-gameye.gameye.net",
     production: "https://api.production-gameye.gameye.net",
 };
+export const DEFAULT_LIMITS = {
+    maxSessions: 5,
+    maxTtl: "4h",
+    maxTtlMs: 4 * 3_600_000,
+    maxLaunches: 20,
+    stopOwnOnly: false,
+};
+/** Shortest GAMEYE_MAX_TTL: the default TTL a launch without one gets (DEFAULT_SESSION_TTL). */
+const MIN_MAX_TTL_MS = 30 * 60_000;
 /** Per-request timeout used when GAMEYE_TIMEOUT_MS is not set. */
 export const DEFAULT_TIMEOUT_MS = 30_000;
 export class ConfigError extends Error {
@@ -30,6 +40,35 @@ function parseTimeoutMs(raw) {
     }
     return ms;
 }
+function parsePositiveInt(name, raw, fallback) {
+    const value = nonEmpty(raw);
+    if (value === undefined)
+        return fallback;
+    const n = /^\d+$/.test(value) ? Number(value) : NaN;
+    if (!Number.isSafeInteger(n) || n <= 0) {
+        throw new ConfigError(`${name} must be a positive whole number (got "${value}"). Leave it unset for ${fallback}.`);
+    }
+    return n;
+}
+function parseLimits(env) {
+    const maxSessions = parsePositiveInt("GAMEYE_MAX_SESSIONS", env.GAMEYE_MAX_SESSIONS, DEFAULT_LIMITS.maxSessions);
+    const maxLaunches = parsePositiveInt("GAMEYE_MAX_LAUNCHES", env.GAMEYE_MAX_LAUNCHES, DEFAULT_LIMITS.maxLaunches);
+    let { maxTtl, maxTtlMs } = DEFAULT_LIMITS;
+    const rawTtl = nonEmpty(env.GAMEYE_MAX_TTL);
+    if (rawTtl !== undefined) {
+        const ms = parseDurationMs(rawTtl);
+        if (ms === undefined || ms < MIN_MAX_TTL_MS) {
+            throw new ConfigError(`GAMEYE_MAX_TTL must be a duration of at least 30m, like 2h or 90m (got "${rawTtl}"). Leave it unset for ${DEFAULT_LIMITS.maxTtl}.`);
+        }
+        maxTtl = rawTtl;
+        maxTtlMs = ms;
+    }
+    const rawOwn = nonEmpty(env.GAMEYE_STOP_OWN_ONLY);
+    if (rawOwn !== undefined && rawOwn !== "1" && rawOwn !== "0") {
+        throw new ConfigError(`GAMEYE_STOP_OWN_ONLY must be 1 or 0 (got "${rawOwn}"). Leave it unset to allow stopping any session the token can see.`);
+    }
+    return { maxSessions, maxTtl, maxTtlMs, maxLaunches, stopOwnOnly: rawOwn === "1" };
+}
 /** Lowercase a hostname and drop a trailing root dot (`example.com.` is the same host as `example.com`). */
 function normalizeHostname(hostname) {
     return hostname.toLowerCase().replace(/\.$/, "");
@@ -60,6 +99,7 @@ export function resolveConfig(env) {
             "(default sandbox), or GAMEYE_API_URL for a non-standard https host.");
     }
     const timeoutMs = parseTimeoutMs(env.GAMEYE_TIMEOUT_MS);
+    const limits = parseLimits(env);
     const rawEnv = nonEmpty(env.GAMEYE_ENV);
     let tier = "sandbox";
     if (rawEnv !== undefined) {
@@ -71,7 +111,7 @@ export function resolveConfig(env) {
     const rawUrl = nonEmpty(env.GAMEYE_API_URL);
     if (rawUrl === undefined) {
         const baseUrl = KNOWN_HOSTS[tier];
-        return { environment: tier, baseUrl, host: new URL(baseUrl).host, token, timeoutMs };
+        return { environment: tier, baseUrl, host: new URL(baseUrl).host, token, timeoutMs, limits };
     }
     let url;
     try {
@@ -90,10 +130,10 @@ export function resolveConfig(env) {
                 `Set GAMEYE_ENV=${knownTier} to use ${knownTier}, or remove GAMEYE_API_URL.`);
         }
         const baseUrl = KNOWN_HOSTS[knownTier];
-        return { environment: knownTier, baseUrl, host: new URL(baseUrl).host, token, timeoutMs };
+        return { environment: knownTier, baseUrl, host: new URL(baseUrl).host, token, timeoutMs, limits };
     }
     const baseUrl = `${url.origin}${url.pathname}`.replace(/\/+$/, "");
-    return { environment: "custom", baseUrl, host: url.host, token, timeoutMs };
+    return { environment: "custom", baseUrl, host: url.host, token, timeoutMs, limits };
 }
 /** Resolve from process.env, printing a clear message and exiting 1 on any error. */
 export function loadConfigOrExit(env = process.env) {

package/dist/index.js

@@ -13,6 +13,7 @@ const ctx = {
     host: config.host,
     baseUrl: config.baseUrl,
     version,
+    limits: config.limits,
     mask: (text) => client.maskToken(text),
 };
 const server = createServer(version);

package/dist/limits.d.ts

@@ -0,0 +1,40 @@
+import type { SessionLimits } from "./env.js";
+import type { GameyeClient } from "./client.js";
+/**
+ * Parse a Gameye TTL (Go duration syntax, e.g. `30m`, `1h`, `2.5h`, `4h50m`) to
+ * milliseconds. Returns undefined for anything else. `0` parses to 0.
+ */
+export declare function parseDurationMs(text: string): number | undefined;
+/** A slot held while one launch is in flight. Settle it exactly once. */
+export interface LaunchReservation {
+    /** The launch succeeded with this session ID. */
+    started(id: string): void;
+    /** The launch failed. `maybeStarted` when the outcome is unknown (timeout, network error). */
+    failed(maybeStarted: boolean): void;
+}
+export declare class SessionLimiter {
+    readonly limits: SessionLimits;
+    private readonly client;
+    private readonly now;
+    private inFlight;
+    private launches;
+    private unknownSeq;
+    /** Sessions this process started (or may have started) that may still run: id → expiry time. */
+    private readonly live;
+    /** Every session ID this process started, for GAMEYE_STOP_OWN_ONLY. */
+    private readonly own;
+    constructor(limits: SessionLimits, client: Pick<GameyeClient, "listSessions">, now?: () => number);
+    /** Refuse a TTL above GAMEYE_MAX_TTL, a zero TTL, or one that can't be parsed. Returns it in ms. */
+    checkTtl(ttl: string): number;
+    /**
+     * Hold a launch slot, or refuse with a GuardError. Counts this process's
+     * sessions that are still running, plus launches in flight.
+     */
+    reserve(ttlMs: number): Promise<LaunchReservation>;
+    /** True when this process started the session. */
+    isOwn(id: string): boolean;
+    /** The session was stopped: it no longer counts toward GAMEYE_MAX_SESSIONS. */
+    stopped(id: string): void;
+    /** Number of sessions this process started that may still be running. */
+    private countRunning;
+}

package/dist/limits.js

@@ -0,0 +1,131 @@
+// Local limits on what an agent can start through this server process.
+//
+// The Gameye API has no per-token budget, so these are enforced here, before
+// any request. Together they bound the worst case: at most maxSessions running
+// at once, each living at most maxTtl, and at most maxLaunches per process.
+// Every check fails closed: if the server can't tell how many of its sessions
+// are still running, it refuses the launch.
+import { AGENT_LABEL_KEY, AGENT_LABEL_VALUE, GuardError } from "./guards.js";
+const ENDED = new Set(["exited", "dead"]);
+const UNITS_MS = { h: 3_600_000, m: 60_000, s: 1_000 };
+/**
+ * Parse a Gameye TTL (Go duration syntax, e.g. `30m`, `1h`, `2.5h`, `4h50m`) to
+ * milliseconds. Returns undefined for anything else. `0` parses to 0.
+ */
+export function parseDurationMs(text) {
+    const value = text.trim();
+    if (value === "0")
+        return 0;
+    if (!/^(\d+(\.\d+)?[hms])+$/.test(value))
+        return undefined;
+    let ms = 0;
+    for (const [, num, unit] of value.matchAll(/(\d+(?:\.\d+)?)([hms])/g)) {
+        ms += Number(num) * UNITS_MS[unit];
+    }
+    return ms;
+}
+export class SessionLimiter {
+    limits;
+    client;
+    now;
+    inFlight = 0;
+    launches = 0;
+    unknownSeq = 0;
+    /** Sessions this process started (or may have started) that may still run: id → expiry time. */
+    live = new Map();
+    /** Every session ID this process started, for GAMEYE_STOP_OWN_ONLY. */
+    own = new Set();
+    constructor(limits, client, now = Date.now) {
+        this.limits = limits;
+        this.client = client;
+        this.now = now;
+    }
+    /** Refuse a TTL above GAMEYE_MAX_TTL, a zero TTL, or one that can't be parsed. Returns it in ms. */
+    checkTtl(ttl) {
+        const ms = parseDurationMs(ttl);
+        if (ms === undefined) {
+            throw new GuardError(`Launch refused: ttl "${ttl}" is not a duration like 30m, 1h or 2.5h. No session was started.`);
+        }
+        if (ms === 0 || ms > this.limits.maxTtlMs) {
+            throw new GuardError(`Launch refused: ttl "${ttl}" is above this server's limit of ${this.limits.maxTtl} (GAMEYE_MAX_TTL). ` +
+                `Pass a ttl of ${this.limits.maxTtl} or less. No session was started.`);
+        }
+        return ms;
+    }
+    /**
+     * Hold a launch slot, or refuse with a GuardError. Counts this process's
+     * sessions that are still running, plus launches in flight.
+     */
+    async reserve(ttlMs) {
+        const { maxLaunches, maxSessions } = this.limits;
+        if (this.launches + this.inFlight >= maxLaunches) {
+            throw new GuardError(`Launch refused: this server has already started ${this.launches} session(s), its limit per run (GAMEYE_MAX_LAUNCHES=${maxLaunches}). ` +
+                "Restart the MCP server to reset it, or ask the user to raise the limit. No session was started.");
+        }
+        this.inFlight++;
+        let running;
+        try {
+            running = await this.countRunning();
+        }
+        catch (err) {
+            this.inFlight--;
+            const reason = err instanceof Error ? err.message : String(err);
+            throw new GuardError(`Launch refused: couldn't check how many of this server's sessions are still running (${reason}). ` +
+                "The session limit fails closed. Try again in a moment. No session was started.");
+        }
+        if (running + this.inFlight > maxSessions) {
+            this.inFlight--;
+            throw new GuardError(`Launch refused: ${running} session(s) started by this server are still running, and its limit is ${maxSessions} at once (GAMEYE_MAX_SESSIONS). ` +
+                "Stop one you no longer need with gameye_stop_session, or wait for its TTL. No session was started.");
+        }
+        let settled = false;
+        const settle = () => {
+            if (settled)
+                throw new Error("launch reservation settled twice");
+            settled = true;
+            this.inFlight--;
+        };
+        return {
+            started: (id) => {
+                settle();
+                this.launches++;
+                this.own.add(id);
+                this.live.set(id, this.now() + ttlMs);
+            },
+            failed: (maybeStarted) => {
+                settle();
+                if (!maybeStarted)
+                    return;
+                // The session may exist under an ID we never saw: count it until its TTL ends.
+                this.launches++;
+                this.live.set(`unknown-${++this.unknownSeq}`, this.now() + ttlMs);
+            },
+        };
+    }
+    /** True when this process started the session. */
+    isOwn(id) {
+        return this.own.has(id);
+    }
+    /** The session was stopped: it no longer counts toward GAMEYE_MAX_SESSIONS. */
+    stopped(id) {
+        this.live.delete(id);
+    }
+    /** Number of sessions this process started that may still be running. */
+    async countRunning() {
+        const now = this.now();
+        for (const [id, expiresAt] of this.live) {
+            if (expiresAt <= now)
+                this.live.delete(id);
+        }
+        if (this.live.size === 0)
+            return 0;
+        // Labelled sessions report their status. Warm-pool sessions carry no label, so
+        // they are missing from the list and keep counting until their TTL ends.
+        const { items } = await this.client.listSessions({ all: true, filter: { [AGENT_LABEL_KEY]: AGENT_LABEL_VALUE } });
+        for (const s of items) {
+            if (ENDED.has(s.status))
+                this.live.delete(s.id);
+        }
+        return this.live.size;
+    }
+}

package/dist/skills.d.ts

@@ -1,5 +1,11 @@
 /** Where the `gameye` skill's `Pack version:` line is published. */
 export declare const LATEST_PACK_URL = "https://raw.githubusercontent.com/Gameye/gameye-skills/main/skills/gameye/SKILL.md";
+/** The skills CLI the updater runs, pinned so `npx` never fetches whatever is newest. */
+export declare const SKILLS_CLI = "skills@1.7.4";
+/** Set to 1 to let `gameye_update_skills` run updaters; otherwise apply prints the commands. */
+export declare const ENABLE_UPDATE_ENV = "GAMEYE_ENABLE_SKILLS_UPDATE";
+/** The environment an updater runs with: the allowlist above, no Gameye variables, nothing that looks like a secret. */
+export declare function childEnv(parent: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** How the Gameye skills were installed. Each kind updates differently. */
 export type InstallKind = "skills-cli-global" | "skills-cli-project" | "claude-plugin";
 export interface SkillsInstall {
@@ -14,6 +20,8 @@ export interface SkillsEnv {
     home: string;
     cwd: string;
     platform: NodeJS.Platform;
+    /** The operator set GAMEYE_ENABLE_SKILLS_UPDATE=1: apply may run updaters. */
+    applyEnabled: boolean;
     readText: (path: string) => Promise<string | undefined>;
     fetchText: (url: string) => Promise<string>;
     run: (cmd: string, args: string[], cwd: string) => Promise<string>;

package/dist/skills.js

@@ -8,11 +8,39 @@ const PACK_VERSION_RE = /^Pack version: (\d+\.\d+\.\d+)[ \t]*$/m;
 const SKILLS_SOURCE_RE = /^(https:\/\/github\.com\/|git@github\.com:|github:)?gameye\/gameye-skills(\.git)?\/?$/i;
 // Lock files can come from a cloned project, so a name must look like a skill name, never a CLI option.
 const SKILL_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
+/** The skills CLI the updater runs, pinned so `npx` never fetches whatever is newest. */
+export const SKILLS_CLI = "skills@1.7.4";
+/** Set to 1 to let `gameye_update_skills` run updaters; otherwise apply prints the commands. */
+export const ENABLE_UPDATE_ENV = "GAMEYE_ENABLE_SKILLS_UPDATE";
+// What an updater needs from the parent: where to find programs and home, temp dirs, locale,
+// proxy and CA settings, npm and Claude config. Nothing else is passed, so the Gameye token stays here.
+const CHILD_ENV_NAMES = new Set([
+    "PATH", "Path", "PATHEXT", "HOME", "USERPROFILE", "APPDATA", "LOCALAPPDATA", "HOMEDRIVE", "HOMEPATH",
+    "SystemRoot", "SYSTEMROOT", "ComSpec", "COMSPEC", "WINDIR", "TEMP", "TMP", "TMPDIR",
+    "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL", "TERM",
+    "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY", "http_proxy", "https_proxy", "no_proxy",
+    "NODE_EXTRA_CA_CERTS", "SSL_CERT_FILE", "SSL_CERT_DIR", "CLAUDE_CONFIG_DIR",
+]);
+const CHILD_ENV_PREFIXES = ["XDG_", "npm_config_", "NPM_CONFIG_"];
+// Never passed, even under an allowed prefix: an npm registry token is not the updater's business either.
+const SECRET_NAME_RE = /token|secret|password|passwd|auth|key|credential/i;
+/** The environment an updater runs with: the allowlist above, no Gameye variables, nothing that looks like a secret. */
+export function childEnv(parent) {
+    const env = {};
+    for (const [name, value] of Object.entries(parent)) {
+        if (value === undefined || name.toUpperCase().startsWith("GAMEYE_") || SECRET_NAME_RE.test(name))
+            continue;
+        if (CHILD_ENV_NAMES.has(name) || CHILD_ENV_PREFIXES.some((p) => name.startsWith(p)))
+            env[name] = value;
+    }
+    return { ...env, NO_COLOR: "1", FORCE_COLOR: "0", CI: "1" };
+}
 export function defaultSkillsEnv() {
     return {
         home: homedir(),
         cwd: process.cwd(),
         platform: process.platform,
+        applyEnabled: process.env[ENABLE_UPDATE_ENV] === "1",
         readText: (path) => readFile(path, "utf8").catch(() => undefined),
         fetchText: async (url) => {
             const res = await fetch(url, { signal: AbortSignal.timeout(5_000) });
@@ -21,8 +49,7 @@ export function defaultSkillsEnv() {
             return res.text();
         },
         run: (cmd, args, cwd) => new Promise((resolve, reject) => {
-            const childEnv = { ...process.env, NO_COLOR: "1", FORCE_COLOR: "0", CI: "1" };
-            const options = { cwd, env: childEnv, timeout: 90_000, killSignal: "SIGKILL", maxBuffer: 4 * 1024 * 1024 };
+            const options = { cwd, env: childEnv(process.env), timeout: 90_000, killSignal: "SIGKILL", maxBuffer: 4 * 1024 * 1024 };
             const child = execFile(cmd, args, options, (err, stdout, stderr) => {
                 const out = stripAnsi(`${stdout}${stderr}`).trim();
                 if (err)
@@ -120,9 +147,9 @@ export function isOutdated(install, latest) {
 export function updateCommands(install) {
     switch (install.kind) {
         case "skills-cli-global":
-            return [["npx", "-y", "skills", "update", ...install.skills, "-g", "-y"]];
+            return [["npx", "-y", SKILLS_CLI, "update", ...install.skills, "-g", "-y"]];
         case "skills-cli-project":
-            return [["npx", "-y", "skills", "update", ...install.skills, "-p", "-y"]];
+            return [["npx", "-y", SKILLS_CLI, "update", ...install.skills, "-p", "-y"]];
         case "claude-plugin":
             return [
                 ["claude", "plugin", "marketplace", "update", "gameye"],

package/dist/tools/common.d.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import { GameyeError } from "../client.js";
-import { type EnvironmentLabel } from "../env.js";
+import { type EnvironmentLabel, type SessionLimits } from "../env.js";
 /** Shared `dryRun` input for every tool that sends a write. */
 export declare const dryRunInput: z.ZodOptional<z.ZodBoolean>;
 /** What every tool needs to know about the server it runs in. Never holds the token. */
@@ -11,6 +11,8 @@ export interface ServerContext {
     host: string;
     baseUrl: string;
     version: string;
+    /** Local launch and stop limits, fixed when the server starts. */
+    limits: SessionLimits;
     /** Replace the API token with `***`. Applied to every tool result, success or error. */
     mask: (text: string) => string;
 }

package/dist/tools/context.js

@@ -19,6 +19,12 @@ export function registerContextTool(server, ctx) {
         `  Session label: ${AGENT_LABEL_KEY}=${AGENT_LABEL_VALUE} on every launch`,
         `  Token expiry:  ${DEFAULT_TOKEN_EXPIRY} when gameye_create_token gives no expires_after`,
         "",
+        "Session limits (set when the server starts):",
+        `  Running at once: ${ctx.limits.maxSessions} sessions started by this server (GAMEYE_MAX_SESSIONS)`,
+        `  Longest TTL:     ${ctx.limits.maxTtl} (GAMEYE_MAX_TTL)`,
+        `  Launches:        ${ctx.limits.maxLaunches} per server run (GAMEYE_MAX_LAUNCHES)`,
+        `  Stop:            ${ctx.limits.stopOwnOnly ? "only sessions this server launched (GAMEYE_STOP_OWN_ONLY=1)" : "any session the token can see, by exact ID"}`,
+        "",
         "Token scopes: not introspectable. The Gameye API has no endpoint that reports a token's scopes; a call that needs a missing scope fails with 403 and names the required scope.",
         ctx.environment === "custom"
             ? "This server uses a non-standard GAMEYE_API_URL."

package/dist/tools/sessions.js

@@ -1,18 +1,23 @@
 import { z } from "zod";
-import { GameyeClient } from "../client.js";
-import { AGENT_LABEL_KEY, AGENT_LABEL_VALUE, DEFAULT_SESSION_TTL, applyLaunchDefaults, assertExplicitSessionId, assertNoTokenInLaunch, describeTtl, formatDryRun, } from "../guards.js";
+import { GameyeClient, GameyeError } from "../client.js";
+import { AGENT_LABEL_KEY, AGENT_LABEL_VALUE, DEFAULT_SESSION_TTL, applyLaunchDefaults, assertExplicitSessionId, assertNoTokenInLaunch, describeTtl, formatDryRun, GuardError, } from "../guards.js";
+import { SessionLimiter } from "../limits.js";
 import { defineTool, dryRunInput, formatLabels } from "./common.js";
 function formatPorts(ports) {
     return (ports ?? []).map((p) => `${p.host}:${p.container}/${p.type}`).join(", ");
 }
 export function registerSessionTools(server, client, ctx) {
+    const limiter = new SessionLimiter(ctx.limits, client);
+    const { maxSessions, maxTtl, maxLaunches, stopOwnOnly } = ctx.limits;
     // ─── Launch Session ──────────────────────────────────────────────────────────
     defineTool(server, ctx, "gameye_launch_session", {
         title: "Launch session",
         description: "Start a containerized game server session on the Gameye platform. Returns the session ID, host and ports. Starts a billable session in the environment shown in the result prefix. " +
             `When no ttl is given, a ${DEFAULT_SESSION_TTL} TTL is applied and reported. The label ${AGENT_LABEL_KEY}=${AGENT_LABEL_VALUE} is always sent and replaces any ${AGENT_LABEL_KEY} value you pass; ` +
             "if a warm pool serves the image and region, the server ignores request labels (and env and args), so warm-pool sessions do not carry it. " +
-            "The launch is refused, with nothing sent, if any env value, arg or label contains this server's Gameye API token. Pass dryRun=true to preview the request.",
+            "The launch is refused, with nothing sent, if any env value, arg or label contains this server's Gameye API token. " +
+            `It is also refused if the ttl is above ${maxTtl}, if ${maxSessions} sessions started by this server are already running, or after ${maxLaunches} launches by this server process; ` +
+            "these limits are set by the user when the server starts, and a refusal says which one applied. Pass dryRun=true to preview the request.",
         inputSchema: {
             location: z.string().describe("Region/datacenter to host the session (e.g. 'europe', 'us-east')"),
             image: z.string().describe("Docker image name to run (e.g. 'csgo', 'tf2')"),
@@ -25,18 +30,30 @@ export function registerSessionTools(server, client, ctx) {
             ttl: z
                 .string()
                 .optional()
-                .describe(`Session time-to-live, e.g. '1h', '30m'. Session auto-stops after this duration. Defaults to ${DEFAULT_SESSION_TTL}`),
+                .describe(`Session time-to-live, e.g. '1h', '30m'. Session auto-stops after this duration. Defaults to ${DEFAULT_SESSION_TTL}; at most ${maxTtl}`),
             dryRun: dryRunInput,
         },
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     }, async ({ dryRun, ...input }) => {
         assertNoTokenInLaunch(input, client);
         const { request, defaultTtlApplied } = applyLaunchDefaults(input);
-        const ttlLine = `  TTL:        ${describeTtl(request.ttl ?? DEFAULT_SESSION_TTL, defaultTtlApplied)}`;
+        const ttl = request.ttl ?? DEFAULT_SESSION_TTL;
+        const ttlMs = limiter.checkTtl(ttl);
+        const ttlLine = `  TTL:        ${describeTtl(ttl, defaultTtlApplied)}`;
         if (dryRun) {
             return `${formatDryRun(ctx, GameyeClient.launchSessionRequest(request), client)}\n\n${ttlLine.trim()}`;
         }
-        const result = await client.launchSession(request);
+        const slot = await limiter.reserve(ttlMs);
+        let result;
+        try {
+            result = await client.launchSession(request);
+        }
+        catch (err) {
+            // A 4xx means nothing started. A 5xx, timeout or network error may have started one.
+            slot.failed(!(err instanceof GameyeError && err.statusCode < 500));
+            throw err;
+        }
+        slot.started(result.id);
         const lines = [`Session launched successfully.`, `  Session ID: ${result.id}`, ttlLine];
         if (result.host)
             lines.push(`  Host:       ${result.host}`);
@@ -123,7 +140,9 @@ export function registerSessionTools(server, client, ctx) {
     defineTool(server, ctx, "gameye_stop_session", {
         title: "Stop session",
         description: "Terminate one Gameye session by its exact ID (sends SIGTERM to the container). Any players connected to it are disconnected. The session transitions to 'draining' then 'shuttingdown' then 'exited'. " +
-            "There is no bulk or implicit stop: an empty, wildcard or list ID is refused. Pass dryRun=true to preview the request.",
+            "There is no bulk or implicit stop: an empty, wildcard or list ID is refused. " +
+            (stopOwnOnly ? "This server only stops sessions it launched itself (GAMEYE_STOP_OWN_ONLY=1). " : "") +
+            "Pass dryRun=true to preview the request.",
         inputSchema: {
             id: z.string().min(1).describe("Exact ID of the one session to stop"),
             dryRun: dryRunInput,
@@ -131,9 +150,14 @@ export function registerSessionTools(server, client, ctx) {
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
     }, async ({ id: rawId, dryRun }) => {
         const id = assertExplicitSessionId(rawId);
+        if (stopOwnOnly && !limiter.isOwn(id)) {
+            throw new GuardError(`Stop refused: session ${id} was not launched by this server, and it only stops its own sessions (GAMEYE_STOP_OWN_ONLY=1). ` +
+                "Ask the user to stop it in the Admin Panel or from another tool. No request was sent.");
+        }
         if (dryRun)
             return formatDryRun(ctx, GameyeClient.stopSessionRequest(id), client);
         await client.stopSession(id);
+        limiter.stopped(id);
         return `Session ${id} stop signal sent. The session is now draining.\n\nUse gameye_describe_session to monitor shutdown progress.`;
     });
 }

package/dist/tools/skills.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { defineTool } from "./common.js";
-import { compareVersions, defaultSkillsEnv, describeInstall, fetchLatestPackVersion, findSkillsInstalls, isOutdated, updateCommands, } from "../skills.js";
+import { compareVersions, defaultSkillsEnv, describeInstall, ENABLE_UPDATE_ENV, fetchLatestPackVersion, findSkillsInstalls, isOutdated, updateCommands, } from "../skills.js";
 const RELOAD_NOTE = "The running session keeps the skills it already loaded. Start a new session (in Claude Code, /reload-plugins also works for the plugin) to use the update.";
 export function registerSkillsTools(server, ctx, env = defaultSkillsEnv()) {
     defineTool(server, ctx, "gameye_update_skills", {
@@ -8,7 +8,8 @@ export function registerSkillsTools(server, ctx, env = defaultSkillsEnv()) {
         description: "Compare the installed Gameye agent skills with the latest pack on GitHub, and update them. " +
             "Finds installs made with the skills CLI (user-wide or in this project) and the Claude Code plugin gameye@gameye. " +
             "Without apply it only checks and changes nothing. With apply=true it runs each outdated install's own updater " +
-            "(npx skills update for the Gameye skills only, or claude plugin update); ask the user before applying. " +
+            "(npx skills update for the Gameye skills only, or claude plugin update) when the operator set " +
+            `${ENABLE_UPDATE_ENV}=1; otherwise it lists the commands for the user to run. Ask the user before applying. ` +
             "Updates come only through those package managers; this tool never downloads or follows skill text itself.",
         inputSchema: {
             apply: z
@@ -56,8 +57,15 @@ export function registerSkillsTools(server, ctx, env = defaultSkillsEnv()) {
         if (outdated.length === 0)
             return lines.join("\n");
         const commands = outdated.flatMap(updateCommands);
-        if (!apply || env.platform === "win32") {
-            lines.push("", apply ? "Updating from this server isn't supported on Windows. Run:" : "Call again with apply=true to run:");
+        if (!apply || env.platform === "win32" || !env.applyEnabled) {
+            const why = !apply
+                ? env.applyEnabled
+                    ? "Call again with apply=true to run:"
+                    : "Run:"
+                : env.platform === "win32"
+                    ? "Updating from this server isn't supported on Windows. Run:"
+                    : `Updating from this server is off (set ${ENABLE_UPDATE_ENV}=1 in the server's environment to allow it). Run:`;
+            lines.push("", why);
             for (const cmd of commands)
                 lines.push(`  ${cmd.join(" ")}`);
             return lines.join("\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gameye-mcp",
-  "version": "0.3.1",
+  "version": "0.4.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",
@@ -48,7 +48,7 @@
   },
   "type": "module",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "zod": "^4.3.6"
   },
   "devDependencies": {