gameye-mcp 0.2.0 → 0.3.1

package/README.md

@@ -63,7 +63,24 @@ 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.2.0` (or `"args": ["-y", "gameye-mcp@0.2.0"]`).
+`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"]`).
+
+### Windows
+
+The server runs on Windows with Node.js 22 or newer. We've tested it on Windows 11, through Claude Code and over plain stdio. If something breaks on Windows, please [open an issue](https://github.com/Gameye/gameye-mcp/issues).
+
+- Many Windows MCP clients can't start `npx` directly, because it's a `.cmd` script. Start it through `cmd /c` instead:
+
+  ```json
+  "command": "cmd",
+  "args": ["/c", "npx", "-y", "gameye-mcp"]
+  ```
+
+  With Claude Code: `claude mcp add gameye --env GAMEYE_API_TOKEN=<your-token> -- cmd /c npx -y gameye-mcp`. Claude Code 2.1.296 and later also start plain `npx`.
+- In PowerShell, type `npx.cmd` instead of `npx` when you run the server by hand. A new Windows install blocks the `npx` PowerShell script with "running scripts is disabled on this system".
+- The first start downloads the package and can take 10 to 40 seconds. Later starts take about a second.
+- `gameye_update_skills` reports outdated skills on Windows but doesn't run the update. It prints the commands for you to run.
+- `gameye_create_token` writes the token file with owner-only permissions on macOS and Linux. On Windows those permissions don't apply, and the file gets the access rules of its folder. Write it inside your user profile.
 
 ### Docker
 
@@ -88,7 +105,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.2.0`.
+- To stay on one version, use a version tag such as `ghcr.io/gameye/gameye-mcp:0.3.1`.
 - 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`.
@@ -131,6 +148,7 @@ Every tool result starts with the environment and host it used, for example `[sa
 | `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 |
+| `gameye_update_skills` | read, or write with `apply` | Compare the installed [Gameye skills](https://github.com/gameye/gameye-skills) with the latest pack, and update them with `apply: true`. See [Keeping the skills current](#keeping-the-skills-current) |
 
 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`.
 
@@ -146,6 +164,16 @@ These behave the same on sandbox and production, because sandbox runs live match
 - **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.
 
+## Keeping the skills current
+
+The [Gameye skills](https://github.com/gameye/gameye-skills) change as the Gameye API does. `gameye_update_skills` reads the latest pack version from the `gameye` skill on GitHub (`Pack version:` in `skills/gameye/SKILL.md` on `main`) and compares it with what is installed:
+
+- **skills CLI, user-wide:** skills recorded in `~/.agents/.skill-lock.json` with source `gameye/gameye-skills`.
+- **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.
+
 ## Telemetry/attribution
 
 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.

package/dist/skills.d.ts

@@ -0,0 +1,32 @@
+/** 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";
+/** How the Gameye skills were installed. Each kind updates differently. */
+export type InstallKind = "skills-cli-global" | "skills-cli-project" | "claude-plugin";
+export interface SkillsInstall {
+    kind: InstallKind;
+    /** Pack version read from the installed `gameye` skill, if it could be read. */
+    version?: string;
+    /** Skill names installed from gameye-skills (skills CLI installs only). */
+    skills: string[];
+}
+/** Everything the check touches outside this module, so tests can replace it. */
+export interface SkillsEnv {
+    home: string;
+    cwd: string;
+    platform: NodeJS.Platform;
+    readText: (path: string) => Promise<string | undefined>;
+    fetchText: (url: string) => Promise<string>;
+    run: (cmd: string, args: string[], cwd: string) => Promise<string>;
+}
+export declare function defaultSkillsEnv(): SkillsEnv;
+export declare function stripAnsi(text: string): string;
+export declare function parsePackVersion(skillText: string | undefined): string | undefined;
+/** -1, 0 or 1 for two X.Y.Z versions. */
+export declare function compareVersions(a: string, b: string): number;
+/** Find every install of the Gameye skills this server can see: user-wide, this project, and the Claude Code plugin. */
+export declare function findSkillsInstalls(env: SkillsEnv): Promise<SkillsInstall[]>;
+export declare function fetchLatestPackVersion(env: SkillsEnv): Promise<string>;
+export declare function isOutdated(install: SkillsInstall, latest: string): boolean;
+/** The commands that update an install, as argv lists. The skills CLI updates only the named Gameye skills. */
+export declare function updateCommands(install: SkillsInstall): string[][];
+export declare function describeInstall(install: SkillsInstall): string;

package/dist/skills.js

@@ -0,0 +1,140 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Where the `gameye` skill's `Pack version:` line is published. */
+export const LATEST_PACK_URL = "https://raw.githubusercontent.com/Gameye/gameye-skills/main/skills/gameye/SKILL.md";
+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;
+export function defaultSkillsEnv() {
+    return {
+        home: homedir(),
+        cwd: process.cwd(),
+        platform: process.platform,
+        readText: (path) => readFile(path, "utf8").catch(() => undefined),
+        fetchText: async (url) => {
+            const res = await fetch(url, { signal: AbortSignal.timeout(5_000) });
+            if (!res.ok)
+                throw new Error(`GET ${url} returned ${res.status}`);
+            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 child = execFile(cmd, args, options, (err, stdout, stderr) => {
+                const out = stripAnsi(`${stdout}${stderr}`).trim();
+                if (err)
+                    reject(new Error(`${cmd} ${args.join(" ")} failed: ${err.message}\n${out}`));
+                else
+                    resolve(out);
+            });
+            // Closed stdin makes a prompting CLI fail at once instead of waiting for the timeout.
+            child.stdin?.end();
+        }),
+    };
+}
+// Terminal colour and cursor codes and carriage returns, which some CLIs print even when asked not to.
+const ANSI_RE = /\x1b\[[0-9;?]*[A-Za-z]|\r/g;
+export function stripAnsi(text) {
+    return text.replace(ANSI_RE, "");
+}
+export function parsePackVersion(skillText) {
+    return skillText ? PACK_VERSION_RE.exec(skillText)?.[1] : undefined;
+}
+/** -1, 0 or 1 for two X.Y.Z versions. */
+export function compareVersions(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if (pa[i] !== pb[i])
+            return pa[i] < pb[i] ? -1 : 1;
+    }
+    return 0;
+}
+function parseJson(text) {
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Skill names a skills CLI lock file records as coming from gameye-skills. */
+function gameyeSkillsInLock(lockText) {
+    const lock = parseJson(lockText);
+    return Object.entries(lock?.skills ?? {})
+        .filter(([name, s]) => SKILL_NAME_RE.test(name) && (SKILLS_SOURCE_RE.test(s.source ?? "") || SKILLS_SOURCE_RE.test(s.sourceUrl ?? "")))
+        .map(([name]) => name)
+        .sort();
+}
+// The skills CLI keeps one copy in .agents/skills when it installs for several agents,
+// and copies straight into the agent's own folder when it installs for one.
+const SKILL_DIRS = [".agents/skills", ".claude/skills", ".codex/skills", ".cursor/skills", ".config/opencode/skills"];
+/** The oldest pack version among the copies found, so one stale copy still counts as outdated. */
+async function readInstalledPackVersion(env, root) {
+    const versions = [];
+    for (const dir of SKILL_DIRS) {
+        const version = parsePackVersion(await env.readText(join(root, dir, "gameye", "SKILL.md")));
+        if (version)
+            versions.push(version);
+    }
+    return versions.sort(compareVersions)[0];
+}
+async function skillsCliInstall(env, kind, lockPath, root) {
+    const skills = gameyeSkillsInLock(await env.readText(lockPath));
+    if (skills.length === 0)
+        return undefined;
+    return { kind, version: await readInstalledPackVersion(env, root), skills };
+}
+async function claudePluginInstall(env) {
+    const registry = parseJson(await env.readText(join(env.home, ".claude", "plugins", "installed_plugins.json")));
+    const entry = Object.entries(registry?.plugins ?? {}).find(([id]) => id === "gameye@gameye")?.[1]?.[0];
+    if (!entry?.installPath)
+        return undefined;
+    const version = parsePackVersion(await env.readText(join(entry.installPath, "skills", "gameye", "SKILL.md")));
+    return { kind: "claude-plugin", version, skills: [] };
+}
+/** Find every install of the Gameye skills this server can see: user-wide, this project, and the Claude Code plugin. */
+export async function findSkillsInstalls(env) {
+    const found = await Promise.all([
+        skillsCliInstall(env, "skills-cli-global", join(env.home, ".agents", ".skill-lock.json"), env.home),
+        skillsCliInstall(env, "skills-cli-project", join(env.cwd, "skills-lock.json"), env.cwd),
+        claudePluginInstall(env),
+    ]);
+    return found.filter((i) => i !== undefined);
+}
+export async function fetchLatestPackVersion(env) {
+    const version = parsePackVersion(await env.fetchText(LATEST_PACK_URL));
+    if (!version)
+        throw new Error(`No "Pack version: X.Y.Z" line in ${LATEST_PACK_URL}`);
+    return version;
+}
+export function isOutdated(install, latest) {
+    return !install.version || compareVersions(install.version, latest) < 0;
+}
+/** The commands that update an install, as argv lists. The skills CLI updates only the named Gameye skills. */
+export function updateCommands(install) {
+    switch (install.kind) {
+        case "skills-cli-global":
+            return [["npx", "-y", "skills", "update", ...install.skills, "-g", "-y"]];
+        case "skills-cli-project":
+            return [["npx", "-y", "skills", "update", ...install.skills, "-p", "-y"]];
+        case "claude-plugin":
+            return [
+                ["claude", "plugin", "marketplace", "update", "gameye"],
+                ["claude", "plugin", "update", "gameye@gameye"],
+            ];
+    }
+}
+export function describeInstall(install) {
+    const where = {
+        "skills-cli-global": "skills CLI, user-wide",
+        "skills-cli-project": "skills CLI, this project",
+        "claude-plugin": "Claude Code plugin gameye@gameye",
+    }[install.kind];
+    return `${where}: pack ${install.version ?? "version unknown"}`;
+}

package/dist/tools/register.js

@@ -8,6 +8,7 @@ import { registerApplicationTools } from "./applications.js";
 import { registerTokenTools } from "./tokens.js";
 import { registerLogTools } from "./logs.js";
 import { registerArtifactTools } from "./artifacts.js";
+import { registerSkillsTools } from "./skills.js";
 /** Register every tool. */
 export function registerAllTools(server, client, ctx) {
     registerContextTool(server, ctx);
@@ -20,4 +21,5 @@ export function registerAllTools(server, client, ctx) {
     registerLogTools(server, client, ctx);
     registerArtifactTools(server, client, ctx);
     registerTokenTools(server, client, ctx);
+    registerSkillsTools(server, ctx);
 }

package/dist/tools/skills.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ServerContext } from "./common.js";
+import { type SkillsEnv } from "../skills.js";
+export declare function registerSkillsTools(server: McpServer, ctx: ServerContext, env?: SkillsEnv): void;

package/dist/tools/skills.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { defineTool } from "./common.js";
+import { compareVersions, defaultSkillsEnv, describeInstall, 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", {
+        title: "Check and update the Gameye skills",
+        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. " +
+            "Updates come only through those package managers; this tool never downloads or follows skill text itself.",
+        inputSchema: {
+            apply: z
+                .boolean()
+                .optional()
+                .describe("Run the updates for outdated installs. Omit or false to only check."),
+            installedVersion: z
+                .string()
+                .regex(/^\d+\.\d+\.\d+$/)
+                .optional()
+                .describe("The `Pack version:` from the gameye skill you have loaded, used when no install is found on disk"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ apply, installedVersion }) => {
+        const installs = await findSkillsInstalls(env);
+        let latest;
+        try {
+            latest = await fetchLatestPackVersion(env);
+        }
+        catch (err) {
+            const lines = [
+                `Could not read the latest Gameye skills pack version from GitHub: ${err instanceof Error ? err.message : String(err)}`,
+                "Nothing was updated.",
+            ];
+            for (const install of installs)
+                lines.push(`• ${describeInstall(install)}`);
+            return { text: lines.join("\n"), isError: true };
+        }
+        const lines = [`Latest Gameye skills pack: ${latest}`];
+        if (installs.length === 0) {
+            lines.push("No skills CLI or Claude Code plugin install of the Gameye skills was found.");
+            if (installedVersion) {
+                lines.push(`The loaded gameye skill reports pack ${installedVersion}.`);
+                if (compareVersions(installedVersion, latest) < 0) {
+                    lines.push("To update, reinstall the way they were installed: `npx skills add gameye/gameye-skills --skill \"*\"` (add -g for user-wide), " +
+                        "`/plugin marketplace update gameye` for the Claude Code plugin, or copy the skills directories again.");
+                }
+            }
+            return lines.join("\n");
+        }
+        const outdated = installs.filter((i) => isOutdated(i, latest));
+        for (const install of installs) {
+            lines.push(`• ${describeInstall(install)}${outdated.includes(install) ? " (update available)" : " (up to date)"}`);
+        }
+        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:");
+            for (const cmd of commands)
+                lines.push(`  ${cmd.join(" ")}`);
+            return lines.join("\n");
+        }
+        let failed = false;
+        lines.push("");
+        for (const install of outdated) {
+            for (const cmd of updateCommands(install)) {
+                try {
+                    const out = await env.run(cmd[0], cmd.slice(1), env.cwd);
+                    lines.push(`Ran: ${cmd.join(" ")}`, ...(out ? [indentTail(out)] : []));
+                }
+                catch (err) {
+                    failed = true;
+                    lines.push(`Failed: ${err instanceof Error ? err.message : String(err)}`);
+                    break;
+                }
+            }
+        }
+        const after = await findSkillsInstalls(env);
+        lines.push("", "After updating:");
+        for (const install of after) {
+            const behind = isOutdated(install, latest);
+            failed ||= behind;
+            lines.push(`• ${describeInstall(install)}${behind ? " (still behind)" : ""}`);
+        }
+        lines.push("", RELOAD_NOTE);
+        return { text: lines.join("\n"), isError: failed };
+    });
+}
+/** The last lines of a command's output, indented, so a long install log doesn't flood the result. */
+function indentTail(out, max = 15) {
+    const all = out.split("\n");
+    const tail = all.slice(-max).map((l) => `    ${l}`);
+    return (all.length > max ? ["    …", ...tail] : tail).join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gameye-mcp",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",