gameye-mcp 0.3.2 → 0.5.0

package/dist/index.js

@@ -1,21 +1,25 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { GameyeClient } from "./client.js";
-import { loadConfigOrExit } from "./env.js";
+import { loadConfigOrExit, NO_TOKEN_NOTICE } from "./env.js";
 import { registerAllTools } from "./tools/register.js";
 import { createServer } from "./server.js";
 import { BETA_NOTICE } from "./beta.js";
 import { VERSION as version } from "./version.js";
 const config = loadConfigOrExit(process.env);
-const client = new GameyeClient({ token: config.token, baseUrl: config.baseUrl, timeoutMs: config.timeoutMs });
+// With no token the client gets an empty one so registrars keep their shape;
+// the per-tool token gate stops any request from being built without a token.
+const client = new GameyeClient({ token: config.token ?? "", baseUrl: config.baseUrl, timeoutMs: config.timeoutMs });
 const ctx = {
     environment: config.environment,
     host: config.host,
     baseUrl: config.baseUrl,
     version,
+    hasToken: config.hasToken,
+    limits: config.limits,
     mask: (text) => client.maskToken(text),
 };
-const server = createServer(version);
+const server = createServer(version, { hasToken: config.hasToken });
 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);
@@ -23,3 +27,5 @@ const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error(`Gameye MCP server ${version} running on stdio [${ctx.environment} · ${ctx.host}]`);
 console.error(BETA_NOTICE);
+if (!config.hasToken)
+    console.error(NO_TOKEN_NOTICE);

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/server.d.ts

@@ -1,3 +1,17 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-/** The MCP server, with the beta notice sent to clients as its instructions. */
-export declare function createServer(version: string): McpServer;
+/** What the server knows about its configuration when it builds the instructions. */
+export interface ServerMode {
+    hasToken: boolean;
+}
+/** The engine skills an agent reads after the `gameye` skill, one per supported engine. */
+export declare const ENGINE_SKILLS: readonly string[];
+/** The line, in both modes, naming the tools that read the bundled skills. */
+export declare const BUNDLED_SKILLS_LINE = "This server bundles the Gameye agent skills: list them with gameye_list_skills and read one with gameye_get_skill, starting with the `gameye` skill.";
+/**
+ * The instructions sent at initialize. With no token they lead with what works
+ * now: the first sentence says no token is configured and names the token-free
+ * tools and the first skill to read (R8).
+ */
+export declare function serverInstructions(mode: ServerMode): string;
+/** The MCP server, with instructions for its token mode and the beta notice. */
+export declare function createServer(version: string, mode: ServerMode): McpServer;

package/dist/server.js

@@ -1,6 +1,37 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { BETA_NOTICE } from "./beta.js";
-/** The MCP server, with the beta notice sent to clients as its instructions. */
-export function createServer(version) {
-    return new McpServer({ name: "gameye", version }, { instructions: BETA_NOTICE });
+import { NO_PASTE_RULE, RESTART_RULE, TOKEN_FREE_TOOLS, TOKEN_SIGNUP_STEPS } from "./tokenless.js";
+/** The engine skills an agent reads after the `gameye` skill, one per supported engine. */
+export const ENGINE_SKILLS = [
+    "gameye-unity-server",
+    "gameye-unreal-server",
+    "gameye-godot-server",
+    "gameye-web-server",
+];
+function orList(items, word) {
+    return items.length < 2 ? items.join("") : `${items.slice(0, -1).join(", ")} ${word} ${items[items.length - 1]}`;
+}
+/** The line, in both modes, naming the tools that read the bundled skills. */
+export const BUNDLED_SKILLS_LINE = "This server bundles the Gameye agent skills: list them with gameye_list_skills and read one with gameye_get_skill, starting with the `gameye` skill.";
+/**
+ * The instructions sent at initialize. With no token they lead with what works
+ * now: the first sentence says no token is configured and names the token-free
+ * tools and the first skill to read (R8).
+ */
+export function serverInstructions(mode) {
+    if (mode.hasToken)
+        return `${BETA_NOTICE}\n${BUNDLED_SKILLS_LINE}`;
+    return [
+        `No Gameye API token is configured, so only the token-free tools work: ${orList(TOKEN_FREE_TOOLS, "and")}; ` +
+            `read the \`gameye\` skill first with gameye_get_skill, then the skill for the game's engine (${orList(ENGINE_SKILLS, "or")}).`,
+        "Every other tool needs a token: without one it returns setup steps and sends nothing to the Gameye API, dry runs included.",
+        TOKEN_SIGNUP_STEPS,
+        RESTART_RULE,
+        NO_PASTE_RULE,
+        BETA_NOTICE,
+    ].join("\n");
+}
+/** The MCP server, with instructions for its token mode and the beta notice. */
+export function createServer(version, mode) {
+    return new McpServer({ name: "gameye", version }, { instructions: serverInstructions(mode) });
 }

package/dist/tokenless.d.ts

@@ -0,0 +1,36 @@
+/** The first line of every no-token refusal. Stable: agents and tests match on it. */
+export declare const TOKEN_REQUIRED_MARKER = "Token required: no GAMEYE_API_TOKEN is configured for this server.";
+/**
+ * Tools that work without a token. Every other tool needs one: `defineTool`
+ * gates any tool that does not set `requiresToken: false`.
+ */
+export declare const TOKEN_FREE_TOOLS: readonly string[];
+/** Every token-free tool description opens with this sentence. */
+export declare const TOKEN_FREE_LEAD = "Works without a Gameye account or token.";
+/** Every account tool description ends with this sentence. */
+export declare const ACCOUNT_TOOL_TAIL = "Needs GAMEYE_API_TOKEN; without one, returns setup steps and sends nothing.";
+/** A tool description with the sentence that says whether it needs a token. */
+export declare function describeTokenNeed(description: string, requiresToken: boolean): string;
+export type ScopeRecipeName = "Observer" | "Operator" | "Deployer" | "Token admin";
+export interface ScopeRecipe {
+    name: ScopeRecipeName;
+    /** Every scope the recipe grants, including the recipes it builds on. */
+    scopes: readonly string[];
+    /** What a token with this recipe lets the agent do. */
+    summary: string;
+}
+/** The README "Token scopes" recipes, narrowest first. */
+export declare const SCOPE_RECIPES: readonly ScopeRecipe[];
+/** The narrowest recipe for each account tool, from the scope each API operation requires. */
+export declare const TOOL_SCOPE_RECIPE: Readonly<Record<string, ScopeRecipeName>>;
+/** Where a self-serve developer gets a token (sandbox host, this server's default). */
+export declare const TOKEN_SIGNUP_STEPS: string;
+export declare const RESTART_RULE = "The server reads GAMEYE_API_TOKEN once when it starts: after setting or changing it, restart or reconnect the MCP server.";
+export declare const NO_PASTE_RULE = "Do not paste the token into this chat. The user sets it in the server configuration themselves.";
+export declare const TOKEN_FREE_LINE: string;
+/**
+ * The refusal an account tool returns when no token is configured. Order per
+ * R6: marker; nothing sent; where to get a token; scopes; how to set it per
+ * install path; restart; do not paste; what works now.
+ */
+export declare function tokenRequiredMessage(tool: string): string;

package/dist/tokenless.js

@@ -0,0 +1,97 @@
+// No-token mode: which tools work without GAMEYE_API_TOKEN, the scope recipe
+// each account tool needs, and the refusal an account tool returns when no
+// token is configured. The refusal never asks for the token: credentials stay
+// in the server's environment, read once at start.
+/** The first line of every no-token refusal. Stable: agents and tests match on it. */
+export const TOKEN_REQUIRED_MARKER = "Token required: no GAMEYE_API_TOKEN is configured for this server.";
+/**
+ * Tools that work without a token. Every other tool needs one: `defineTool`
+ * gates any tool that does not set `requiresToken: false`.
+ */
+export const TOKEN_FREE_TOOLS = [
+    "gameye_context",
+    "gameye_update_skills",
+    "gameye_list_skills",
+    "gameye_get_skill",
+    "gameye_get_template",
+    "gameye_check_dockerfile",
+];
+/** Every token-free tool description opens with this sentence. */
+export const TOKEN_FREE_LEAD = "Works without a Gameye account or token.";
+/** Every account tool description ends with this sentence. */
+export const ACCOUNT_TOOL_TAIL = "Needs GAMEYE_API_TOKEN; without one, returns setup steps and sends nothing.";
+/** A tool description with the sentence that says whether it needs a token. */
+export function describeTokenNeed(description, requiresToken) {
+    return requiresToken ? `${description} ${ACCOUNT_TOOL_TAIL}` : `${TOKEN_FREE_LEAD} ${description}`;
+}
+const OBSERVER = ["session:read", "logs:read", "artifact:read", "regions:read", "region:read", "application:read"];
+const OPERATOR = [...OBSERVER, "session:start", "session:stop", "session:write"];
+const DEPLOYER = [...OPERATOR, "application:write"];
+const TOKEN_ADMIN = [...DEPLOYER, "token:write"];
+/** The README "Token scopes" recipes, narrowest first. */
+export const SCOPE_RECIPES = [
+    { name: "Observer", scopes: OBSERVER, summary: "Inspect sessions, logs, artifacts, regions and applications. No changes." },
+    { name: "Operator", scopes: OPERATOR, summary: "Also launch and stop sessions and update session state." },
+    { name: "Deployer", scopes: DEPLOYER, summary: "Also create and edit applications, so the agent can set up a deployment end to end." },
+    { name: "Token admin", scopes: TOKEN_ADMIN, summary: "Also create API tokens." },
+];
+/** The narrowest recipe for each account tool, from the scope each API operation requires. */
+export const TOOL_SCOPE_RECIPE = {
+    gameye_list_sessions: "Observer",
+    gameye_describe_session: "Observer",
+    gameye_get_logs: "Observer",
+    gameye_get_artifacts: "Observer",
+    gameye_list_regions: "Observer",
+    gameye_get_locations: "Observer",
+    gameye_check_tag: "Observer",
+    gameye_list_applications: "Observer",
+    gameye_list_registry_tags: "Observer",
+    gameye_launch_session: "Operator",
+    gameye_stop_session: "Operator",
+    gameye_player_join: "Operator",
+    gameye_player_leave: "Operator",
+    gameye_enable_tag: "Deployer",
+    gameye_create_application: "Deployer",
+    gameye_edit_application: "Deployer",
+    gameye_create_token: "Token admin",
+};
+/** Where a self-serve developer gets a token (sandbox host, this server's default). */
+export const TOKEN_SIGNUP_STEPS = "Get a token: sign up at https://trial.gameye.com, then in the Gameye Admin Panel open Users → API tokens and create one. " +
+    "Self-serve accounts use the sandbox host, which is this server's default (GAMEYE_ENV=sandbox).";
+export const RESTART_RULE = "The server reads GAMEYE_API_TOKEN once when it starts: after setting or changing it, restart or reconnect the MCP server.";
+export const NO_PASTE_RULE = "Do not paste the token into this chat. The user sets it in the server configuration themselves.";
+export const TOKEN_FREE_LINE = `Works now without a token: ${TOKEN_FREE_TOOLS.join(", ")}.`;
+function scopeLine(tool) {
+    const name = TOOL_SCOPE_RECIPE[tool];
+    const recipe = SCOPE_RECIPES.find((r) => r.name === name);
+    if (!recipe) {
+        return `Narrowest token scopes for ${tool}: see the Token scopes section of the gameye-mcp README.`;
+    }
+    return `Narrowest token scopes for ${tool}: ${recipe.name} (${recipe.scopes.join(" ")}). ${recipe.summary}`;
+}
+/**
+ * The refusal an account tool returns when no token is configured. Order per
+ * R6: marker; nothing sent; where to get a token; scopes; how to set it per
+ * install path; restart; do not paste; what works now.
+ */
+export function tokenRequiredMessage(tool) {
+    return [
+        TOKEN_REQUIRED_MARKER,
+        "Nothing was sent to the Gameye API, and retrying this call will not help until a token is configured.",
+        "",
+        TOKEN_SIGNUP_STEPS,
+        "",
+        scopeLine(tool),
+        "",
+        "Set the token where this server is configured:",
+        "• Claude Code plugin: enter it in the gameye plugin's API token setting.",
+        "• Claude Code CLI: re-add the server in your own terminal, passing the token with the -e GAMEYE_API_TOKEN option of `claude mcp add`.",
+        "• Other MCP clients: add GAMEYE_API_TOKEN to the env block of the server's mcpServers entry.",
+        "• Docker: keep `-e GAMEYE_API_TOKEN` (no value) in the docker run arguments and set the value in the client's env block, so it never appears on the command line.",
+        "",
+        RESTART_RULE,
+        NO_PASTE_RULE,
+        "",
+        TOKEN_FREE_LINE,
+    ].join("\n");
+}

package/dist/tools/bundled-skills.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ServerContext } from "./common.js";
+/** The first line of every bundled-skill result. */
+export declare const BUNDLED_PACK_LINE: string;
+export declare const INSTALLED_WINS_LINE = "If an installed copy of the Gameye skills is newer, it wins.";
+export declare const BUNDLED_HEADER: string;
+export declare function registerBundledSkillsTools(server: McpServer, ctx: ServerContext): void;

package/dist/tools/bundled-skills.js

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { defineTool } from "./common.js";
+import { BUNDLED_SKILLS, BUNDLED_SKILLS_COMMIT, BUNDLED_SKILLS_PACK_VERSION, BUNDLED_SKILLS_TAG, } from "../generated/skills.js";
+/** The first line of every bundled-skill result. */
+export const BUNDLED_PACK_LINE = `Bundled Gameye skills pack: ${BUNDLED_SKILLS_PACK_VERSION} (gameye-skills ${BUNDLED_SKILLS_TAG}, commit ${BUNDLED_SKILLS_COMMIT.slice(0, 7)}).`;
+export const INSTALLED_WINS_LINE = "If an installed copy of the Gameye skills is newer, it wins.";
+export const BUNDLED_HEADER = `${BUNDLED_PACK_LINE}\n${INSTALLED_WINS_LINE}`;
+const SKILL_FILE = "SKILL.md";
+/** Looks like a path escape, an absolute path or a URL rather than a file inside one skill. */
+function unsafeReason(value) {
+    if (/^[a-z]:/i.test(value) || (value.startsWith("/") && !value.startsWith("//")) || value.startsWith("\\"))
+        return "an absolute path";
+    if (/^[a-z][a-z0-9+.-]*:/i.test(value) || value.startsWith("//"))
+        return "a URL";
+    if (value.split(/[\\/]/).includes(".."))
+        return "a parent-directory path";
+    return undefined;
+}
+function skillNames() {
+    return BUNDLED_SKILLS.map((s) => s.name).join(", ");
+}
+function refuse(text) {
+    return { text: `${BUNDLED_HEADER}\n\n${text}`, isError: true };
+}
+function filesOf(skill) {
+    return Object.keys(skill.files);
+}
+export function registerBundledSkillsTools(server, ctx) {
+    defineTool(server, ctx, "gameye_list_skills", {
+        title: "List the bundled Gameye skills",
+        description: "List the Gameye agent skills bundled with this server: each skill's name, description, version and files, and the bundled pack version. " +
+            "Works offline. Read one with gameye_get_skill. If an installed copy of the Gameye skills is newer, it wins.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        requiresToken: false,
+    }, async () => {
+        const lines = [BUNDLED_HEADER, ""];
+        for (const skill of BUNDLED_SKILLS) {
+            lines.push(`• ${skill.name} (skill ${skill.version}): ${skill.description}`);
+            lines.push(`  files: ${filesOf(skill).join(", ")}`);
+        }
+        return lines.join("\n");
+    });
+    defineTool(server, ctx, "gameye_get_skill", {
+        title: "Read a bundled Gameye skill",
+        description: "Read a Gameye agent skill bundled with this server: its SKILL.md, or one of its reference files. " +
+            "Works offline and serves only the bundled copy (list names and files with gameye_list_skills). " +
+            "If an installed copy of the Gameye skills is newer, it wins.",
+        inputSchema: {
+            name: z.string().describe("Skill name, e.g. gameye or gameye-containerize"),
+            file: z
+                .string()
+                .optional()
+                .describe("File inside the skill, e.g. references/routing.md. Defaults to SKILL.md"),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        requiresToken: false,
+    }, async ({ name, file }) => {
+        const nameProblem = unsafeReason(name) ?? (/[\\/]/.test(name) ? "a path" : undefined);
+        if (nameProblem)
+            return refuse(`Refused: the skill name is ${nameProblem}. Use one of: ${skillNames()}.`);
+        const skill = BUNDLED_SKILLS.find((s) => s.name === name);
+        // Never echo the supplied name or file: it is user text and may be a pasted token.
+        if (!skill)
+            return refuse(`No bundled skill has that name. Bundled skills: ${skillNames()}.`);
+        const rel = file ?? SKILL_FILE;
+        const fileProblem = unsafeReason(rel);
+        if (fileProblem) {
+            return refuse(`Refused: the file is ${fileProblem}. Files in ${skill.name}: ${filesOf(skill).join(", ")}.`);
+        }
+        if (!Object.hasOwn(skill.files, rel)) {
+            return refuse(`The bundled ${skill.name} skill has no such file. Files: ${filesOf(skill).join(", ")}.`);
+        }
+        return [BUNDLED_HEADER, `Skill: ${skill.name} ${skill.version} · ${rel}`, "", skill.files[rel]].join("\n");
+    });
+}

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,10 @@ export interface ServerContext {
     host: string;
     baseUrl: string;
     version: string;
+    /** Whether an API token is configured. The context never holds the token itself. */
+    hasToken: boolean;
+    /** 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;
 }
@@ -26,13 +30,21 @@ export interface ToolDefinition<Shape extends z.ZodRawShape> {
     annotations: ToolAnnotations;
     /** Extra hint appended to the error text for a GameyeError, e.g. for a 404. */
     errorHint?: (err: GameyeError) => string | undefined;
+    /**
+     * Whether the tool needs GAMEYE_API_TOKEN. Defaults to true, so a new tool
+     * fails closed: with no token it refuses before its handler runs.
+     */
+    requiresToken?: boolean;
 }
 /**
  * Register a tool so that every result starts with the environment and host,
  * has the API token masked (log output, labels and error messages can echo
  * it), and every failure comes back as `isError: true` with the server's details
  * and trace ID instead of being thrown. A GuardError (a refusal before any
- * request) comes back as `isError: true` with its message.
+ * request) comes back as `isError: true` with its message. With no token
+ * configured, a tool that requires one is refused before its handler runs, so
+ * no request (and no dry run or limit check) happens. The description gains
+ * the sentence that says whether the tool works without a token.
  */
 export declare function defineTool<Shape extends z.ZodRawShape>(server: McpServer, ctx: ServerContext, name: string, def: ToolDefinition<Shape>, handler: (args: z.infer<z.ZodObject<Shape>>) => Promise<ToolOutput>): void;
 /** Format labels for display, never showing the value of the `env` label. */

package/dist/tools/common.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { GameyeError, GameyeTimeoutError, redactLabels } from "../client.js";
 import { resultPrefix } from "../env.js";
 import { GuardError } from "../guards.js";
+import { describeTokenNeed, tokenRequiredMessage } from "../tokenless.js";
 /** Shared `dryRun` input for every tool that sends a write. */
 export const dryRunInput = z
     .boolean()
@@ -12,9 +13,13 @@ export const dryRunInput = z
  * has the API token masked (log output, labels and error messages can echo
  * it), and every failure comes back as `isError: true` with the server's details
  * and trace ID instead of being thrown. A GuardError (a refusal before any
- * request) comes back as `isError: true` with its message.
+ * request) comes back as `isError: true` with its message. With no token
+ * configured, a tool that requires one is refused before its handler runs, so
+ * no request (and no dry run or limit check) happens. The description gains
+ * the sentence that says whether the tool works without a token.
  */
 export function defineTool(server, ctx, name, def, handler) {
+    const requiresToken = def.requiresToken !== false;
     const prefix = resultPrefix(ctx);
     const wrap = (text, isError) => ({
         content: [{ type: "text", text: ctx.mask(`${prefix}\n${text}`) }],
@@ -22,6 +27,8 @@ export function defineTool(server, ctx, name, def, handler) {
     });
     const callback = async (args) => {
         try {
+            if (requiresToken && !ctx.hasToken)
+                throw new GuardError(tokenRequiredMessage(name));
             const out = await handler(args);
             return typeof out === "string" ? wrap(out) : wrap(out.text, out.isError);
         }
@@ -38,7 +45,7 @@ export function defineTool(server, ctx, name, def, handler) {
     };
     server.registerTool(name, {
         title: def.title,
-        description: def.description,
+        description: describeTokenNeed(def.description, requiresToken),
         inputSchema: def.inputSchema,
         annotations: def.annotations,
     }, callback);

package/dist/tools/context.js

@@ -1,25 +1,39 @@
 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";
+import { RESTART_RULE, TOKEN_FREE_LINE, TOKEN_SIGNUP_STEPS } from "../tokenless.js";
 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 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 },
+        requiresToken: false,
     }, async () => [
         BETA_NOTICE,
         `Environment:    ${ctx.environment}`,
         `Host:           ${ctx.host}`,
         `Base URL:       ${ctx.baseUrl}`,
         `Server version: gameye-mcp ${ctx.version}`,
+        `Token: ${ctx.hasToken ? "configured" : "not configured"}`,
         "",
         "Guardrail defaults:",
         `  Session TTL:   ${DEFAULT_SESSION_TTL} when a launch gives no ttl`,
         `  Session label: ${AGENT_LABEL_KEY}=${AGENT_LABEL_VALUE} on every launch`,
         `  Token expiry:  ${DEFAULT_TOKEN_EXPIRY} when gameye_create_token gives no expires_after`,
         "",
-        "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.",
+        "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"}`,
+        "",
+        ...(ctx.hasToken
+            ? [
+                "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.",
+            ]
+            : ["No API token: account tools refuse and send nothing until a token is set.", TOKEN_FREE_LINE, TOKEN_SIGNUP_STEPS]),
+        RESTART_RULE,
         ctx.environment === "custom"
             ? "This server uses a non-standard GAMEYE_API_URL."
             : "To target the other environment, configure a second server entry with a different GAMEYE_ENV.",

package/dist/tools/dockerfile-check.d.ts

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

package/dist/tools/dockerfile-check.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+import { checkDockerfile, formatDockerfileReport } from "../dockerfile-check.js";
+import { defineTool } from "./common.js";
+const MAX_DOCKERFILE_CHARS = 200_000;
+export function registerDockerfileCheckTool(server, ctx) {
+    defineTool(server, ctx, "gameye_check_dockerfile", {
+        title: "Check Dockerfile",
+        description: "Check game server Dockerfile text against the gameye-containerize container contract, offline: linux/amd64 base, exposed ports and protocols, exec-form launch without npm/yarn start, no loopback bind, non-root user, and no API token or credential in ENV/ARG. Returns findings with severity, rule code, line, message and fix, plus what the check cannot know. Pass the Dockerfile text itself; this tool reads no files and sends nothing.",
+        inputSchema: {
+            dockerfile: z
+                .string()
+                .min(1)
+                .max(MAX_DOCKERFILE_CHARS)
+                .describe("The full Dockerfile text (not a path)"),
+            ports: z
+                .array(z.object({
+                port: z.number().int().min(1).max(65535).describe("Container port the server binds"),
+                protocol: z.enum(["tcp", "udp"]).describe("Protocol the server binds on that port"),
+            }))
+                .max(64)
+                .optional()
+                .describe("Optional: the ports and protocols the server binds, to check against EXPOSE"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        requiresToken: false,
+    }, async ({ dockerfile, ports }) => formatDockerfileReport(checkDockerfile(dockerfile, { ports })));
+}