Gameye

Gameye MCP 服务

一个面向 Gameye 游戏服务器编排 API 的 Model Context Protocol 服务。它让 AI Agent（Claude Code、Claude Desktop、Cursor 或任何 MCP 客户端）能够启动和检查游戏服务器会话、查看镜像标签和区域，以及获取日志和构建产物。你可以用自然语言与它交互，无需离开编辑器。

状态：测试版（0.x）。工具、输入和输出可能会随版本发布而变化，也可能存在 Bug。服务会在启动时以及 gameye_context 中向每个连接的客户端说明这一点。它已发布到 npm，名称为 gameye-mcp；也提供容器镜像 ghcr.io/gameye/gameye-mcp，并以 io.github.Gameye/gameye-mcp 的名称收录在 MCP Registry 中；每个版本的更改内容请参阅变更日志。

快速开始

GAMEYE_API_TOKEN=<your-token> npx -y gameye-mcp

需要 Node.js 22 或更高版本。该服务通过标准输入/输出与 MCP 通信。通常由 MCP 客户端为你启动它（请参阅安装），因此你很少需要手动运行。

环境

Gameye 有两个公开的 API 主机。该服务默认使用 sandbox。

GAMEYE_ENV	主机	适用对象
sandbox（默认）	https://api.sandbox-gameye.gameye.net	自助服务客户。这是你的长期使用环境，可运行实时比赛，而不只是测试。
production	https://api.production-gameye.gameye.net	企业客户。

环境是服务进程的属性。没有任何工具接受环境参数，因此 Agent 无法在对话中途切换到 production。如果你两种环境都需要，请配置两个命名的服务条目（例如 gameye-sandbox 和 gameye-production），并为每个条目使用各自的令牌。

环境变量

变量	必需	默认值	说明
GAMEYE_API_TOKEN	是	—	Gameye API 令牌。请使用所需的最低权限范围（见下文）。
GAMEYE_ENV	否	sandbox	sandbox 或 production。选择 API 主机。
GAMEYE_API_URL	否	—	覆盖主机，仅用于测试。必须使用 https。如果该值与两个已知主机之一相同，则必须与 GAMEYE_ENV 匹配，否则服务将拒绝启动。其他任何 URL 都会在每个工具结果中标记为 custom。
GAMEYE_ENABLE_SKILLS_UPDATE	否	—	设为 1 后，gameye_update_skills 可通过 apply: true 运行技能更新程序。未设置时，该工具只会检查并列出命令。
GAMEYE_MAX_SESSIONS	否	5	此服务允许同时运行的已启动会话数上限。超过上限的启动请求将被拒绝。
GAMEYE_MAX_TTL	否	4h	启动请求可指定的最长 ttl，且至少为 30m。超过此上限的 TTL 或 0 都会被拒绝。
GAMEYE_MAX_LAUNCHES	否	20	每次服务运行期间允许启动的次数。重启服务即可重置。
GAMEYE_STOP_OWN_ONLY	否	—	设为 1 后，gameye_stop_session 只会停止由此服务启动的会话。
GAMEYE_TIMEOUT_MS	否	30000	每个请求的超时时间，单位为毫秒，必须为正整数。日志快照的超时时间至少为 60 s，构建产物下载的超时时间至少为 120 s。请求超时后会返回工具错误：Request to <host> timed out after <n>s。

安装

Claude Code

claude mcp add gameye --env GAMEYE_API_TOKEN=<your-token> -- npx -y gameye-mcp

在 production 环境中，请添加 --env GAMEYE_ENV=production 并使用 production 令牌。

其他 MCP 客户端

大多数客户端（Claude Desktop、Cursor、Windsurf 等）都接受 mcpServers 配置块：

{
  "mcpServers": {
    "gameye": {
      "command": "npx",
      "args": ["-y", "gameye-mcp"],
      "env": {
        "GAMEYE_API_TOKEN": "<your-token>",
        "GAMEYE_ENV": "sandbox"
      }
    }
  }
}

更改配置后，请重启客户端。

npx -y gameye-mcp 会运行最新版本。若要固定版本，请指定版本号：npx -y [email protected]（或使用 "args": ["-y", "[email protected]"]）。

Windows

此服务可在安装了 Node.js 22 或更高版本的 Windows 上运行。我们已在 Windows 11 上通过 Claude Code 和纯 stdio 测试过。如果 Windows 上出现问题，请提交 issue。

• 许多 Windows MCP 客户端无法直接启动 npx，因为它是 .cmd 脚本。请通过 cmd /c 启动：

  "command": "cmd",
  "args": ["/c", "npx", "-y", "gameye-mcp"]
  

  使用 Claude Code：claude mcp add gameye --env GAMEYE_API_TOKEN=<your-token> -- cmd /c npx -y gameye-mcp。Claude Code 2.1.296 及更高版本也可以启动普通的 npx。

• 在 PowerShell 中手动运行服务时，请输入 npx.cmd，而不是 npx。新安装的 Windows 会阻止 npx PowerShell 脚本，并提示“此系统上已禁用脚本运行”。

• 首次启动时会下载软件包，可能需要 10 到 40 秒。之后启动大约只需一秒。

• gameye_update_skills 会在 Windows 上报告过时的技能，但不会执行更新，而是打印供你运行的命令。

• gameye_create_token 会在 macOS 和 Linux 上以仅所有者可访问的权限写入令牌文件。在 Windows 上，这些权限不适用，文件会继承所在文件夹的访问规则。请将文件写入你的用户配置文件目录。

Docker

机器上没有 Node.js？可以改为运行已发布的镜像。该镜像支持 amd64 和 arm64：

{
  "mcpServers": {
    "gameye": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GAMEYE_API_TOKEN", "-e", "GAMEYE_ENV", "ghcr.io/gameye/gameye-mcp"],
      "env": {
        "GAMEYE_API_TOKEN": "<your-token>",
        "GAMEYE_ENV": "sandbox"
      }
    }
  }
}

使用 Claude Code：claude mcp add gameye --env GAMEYE_API_TOKEN=<your-token> -- docker run -i --rm -e GAMEYE_API_TOKEN ghcr.io/gameye/gameye-mcp。

• 使用 -e NAME（不带值）传递每个变量，以便 Docker 从客户端环境中复制变量，令牌也不会出现在命令行中。
• 保留 -i，切勿添加 -t：终端会破坏 stdout 上的 JSON-RPC 消息。
• 若要固定使用某个版本，请使用版本标签，例如 ghcr.io/gameye/gameye-mcp:0.4.0。
• 服务写入的文件会留在容器内，并会被 --rm 删除：
  • gameye_get_artifacts 会将下载内容保存到临时目录。若要保留文件，请挂载一个目录，并将临时目录指向该目录：-v /absolute/dir:/out -e TMPDIR=/out。工具报告的路径是容器内的路径；文件在主机上的 /absolute/dir 中。
  • gameye_create_token 会写入你提供的 outputPath。同样挂载一个目录，并将 outputPath 设为 /out 下的路径。
  • 服务以 uid 1000 运行，因此在 Linux 上，挂载的目录必须允许该用户写入。

令牌作用域

为服务提供的令牌只应包含其所需的作用域。

方案	作用域	Agent 可以执行的操作
观察者	session:read logs:read artifact:read regions:read region:read application:read	检查会话、日志、制品、区域和应用。无法进行更改。
操作员	观察者 + session:start session:stop session:write	还可以启动和停止会话，以及更新会话状态。
部署者	操作员 + application:write	还可以创建和编辑应用，使 Agent 能够端到端地完成部署设置。
令牌管理员	部署者 + token:write	还可以创建 API 令牌。

切勿将 Gameye API 令牌传入游戏服务器的环境变量中。 游戏服务器不需要该令牌，而且容器内的任何内容都可以读取它。

可用工具

每个工具结果都会显示它使用的环境和主机，例如 [sandbox · api.sandbox-gameye.gameye.net]。

工具	类型	描述
gameye_context	读取	显示此服务面向的环境、主机和服务版本，以及防护栏默认值（会话 TTL、launched-by 标签、令牌有效期）
gameye_launch_session	写入，dryRun	启动容器化游戏服务（计费）。应用默认 TTL 和 Agent 标签；请参阅防护栏
gameye_list_sessions	读取	列出运行中的会话（可筛选；all=true 表示列出所有状态）
gameye_describe_session	读取	获取会话详情、端口和玩家信息
gameye_stop_session	破坏性操作，dryRun	根据确切 ID 停止一个会话
gameye_player_join	写入	将一个或多个玩家登记为已加入
gameye_player_leave	写入	将一个或多个玩家从会话中移除
gameye_get_locations	读取	列出当前可托管映像的位置
gameye_list_regions	读取	列出组织可用的区域
gameye_check_tag	读取	检查某个映像标签在某个区域是否可用
gameye_list_applications	读取	列出你的应用及其注册表、资源、区域和端口
gameye_list_registry_tags	读取	列出应用在其上游注册表中的标签（分页）
gameye_enable_tag	写入，dryRun	为应用启用映像标签，以便 Gameye 预加载该映像
gameye_get_logs	读取	获取会话日志
gameye_get_artifacts	读取	从会话容器下载文件或目录，并将其保存为 tar 归档
gameye_create_application	写入，dryRun	创建应用
gameye_edit_application	破坏性操作，dryRun	修改应用；未指定的字段保持不变
gameye_create_token	写入，dryRun	创建 API 令牌并将其写入文件
gameye_update_skills	读取，或使用 apply 写入	将已安装的 Gameye 技能包与最新技能包进行比较，并使用 apply: true 更新。请参阅保持技能包为最新

每个工具都带有 MCP 注解：读取工具设置 readOnlyHint，gameye_stop_session 和 gameye_edit_application 设置 destructiveHint，而每个调用 Gameye API 的工具都会设置 openWorldHint。

这组工具涵盖了 Gameye 客户端 API 中的所有操作。tests/parity.test.ts 会将其与 spec/ 中随项目提供的规范进行核对。

防护措施

这些防护措施在沙盒和生产环境中的行为相同，因为沙盒会为自助客户运行实时匹配。

• 试运行。 gameye_launch_session、gameye_stop_session、gameye_enable_tag 以及应用和令牌工具支持 dryRun: true。工具会返回确切请求（方法、主机、路径和请求体），并将 API 令牌遮盖，不会发送任何内容。
• 有界会话。 启动会话时若未指定 ttl，则默认使用 30m TTL，结果中会说明已应用默认值。每次启动都会发送标签 launched-by: gameye-mcp，并替换调用方传入的任何 launched-by 值，因此可以通过 gameye_list_sessions 和 filter: { "launched-by": "gameye-mcp" } 查找由 Agent 启动的会话。如果热池提供了镜像和区域，Gameye API 会忽略请求中的标签（以及 env 和 args），因此热池会话不会带有此标签。
• 游戏服务器中不含令牌。 如果任何 env 值或名称、arg，或标签键或值包含此服务的 Gameye API 令牌，启动请求会被拒绝，且不会发送任何内容。结果中绝不会显示 env 值。
• 结果中不含令牌。 每个工具结果（包括错误）都会将此服务的 API 令牌替换为 ***，以防日志输出、标签或错误消息中回显该令牌。
• 明确停止。 gameye_stop_session 只会根据精确 ID 停止一个会话。不支持批量停止，并会拒绝空 ID、通配符 ID 或列表 ID。设置 GAMEYE_STOP_OWN_ONLY=1 后，还会拒绝停止并非由此服务启动的会话。
• 会话限制。 Gameye API 没有按令牌设置的额度，因此服务会在发送启动请求前自行执行限制。默认情况下，一个 Agent 同时最多可有 5 个由其启动且正在运行的会话（GAMEYE_MAX_SESSIONS），每个会话的 TTL 最长为 4h（GAMEYE_MAX_TTL），每次服务运行最多可启动 20 个会话（GAMEYE_MAX_LAUNCHES）。因此，单次运行最多可启动 20 个时长为 4 小时的会话，共计 80 个会话小时，且同时最多运行 5 个会话。每次启动前，服务都会列出 launched-by: gameye-mcp 会话，以检查其中哪些会话已结束；如果列表请求失败，启动会被拒绝。热池会话没有标签，因此会一直计入限制，直到 TTL 到期。启动请求超时或返回 5xx 时，会话可能已启动，因此也会计入限制。这些限制仅适用于单个服务进程：由组织内其他 Agent 或工具启动的会话不会计入，重启后计数也会归零，因此也应在 Gameye 中设置组织额度。gameye_context 会显示当前生效的限制。

保持 skills 为最新

Gameye skills 会随着 Gameye API 的变化而更新。gameye_update_skills 会从 GitHub 上的 gameye skill 获取最新的包版本（main 分支中 skills/gameye/SKILL.md 的 Pack version:），并与已安装的版本进行比较：

• skills CLI，用户范围： ~/.agents/.skill-lock.json 中记录的 skills，来源为 gameye/gameye-skills。
• skills CLI，此项目： 同上，记录在服务工作目录中的 skills-lock.json。
• Claude Code 插件： ~/.claude/plugins/installed_plugins.json 中的 gameye@gameye。

不带 apply 时，它只会报告结果。设置 apply: true 后，且仅当服务以 GAMEYE_ENABLE_SKILLS_UPDATE=1 启动时，它才会运行每个过期安装项各自的更新程序：npx -y [email protected] update <the Gameye skills> -g -y（或 -p -y），或者先运行 claude plugin marketplace update gameye，再运行 claude plugin update gameye@gameye。否则，它会列出供你运行的命令。更新程序只能访问最小化环境：路径、主目录、临时目录、区域设置、代理和 CA 设置，以及 npm 和 Claude 配置；绝不会接触 GAMEYE_* 变量，或任何名称中包含 token、secret、password 或 key 的变量。它只会更新锁文件来源为 gameye/gameye-skills 的 skills，并且绝不会自行下载或读取 skill 文本。每条命令都会关闭 stdin，并设有 90 秒时限。在 Windows 上，它只会打印命令，不会运行命令。正在运行的 Agent 会话会继续使用已加载的 skills；下一个会话才会使用更新后的版本。gameye skill 会指示 Agent 每次对话检查一次，并在应用更新前征求同意。

遥测/归因

每个发往 Gameye API 的请求都会发送 User-Agent: gameye-mcp/<version>，客户端连接后还会附带 MCP 客户端名称，例如 gameye-mcp/0.1.0 (claude-code)，以便 Gameye 统计 MCP 使用情况。只会发送本服务的版本和客户端名称，不会发送其他内容：没有 token、环境值、路径或其他数据。除此之外没有其他遥测。

应用和 token 工具

gameye_create_application、gameye_edit_application 和 gameye_create_token 始终会注册。Agent 实际能够执行的操作由 token 的作用域决定：这些操作需要 application:write 或 token:write，缺少相应作用域的 token 会收到指出缺失作用域的 403 错误。若要阻止 Agent 修改应用或创建 token，请提供不含这些作用域的 token。

gameye_create_token 绝不会返回新 token。它会将 token 写入你在 outputPath 中指定的文件，并且只返回路径、作用域和有效期：

• outputPath 必须是 git 工作树之外的绝对路径，以免 token 意外提交。
• 除非传入 overwrite: true，否则已有文件会被拒绝。符号链接始终会被拒绝。
• 文件会以 0600 权限独占创建，且不会跟随符号链接。创建 token 前会先预留文件，因此错误路径不会创建 token。
• expires_after 默认为 24h。请求的作用域必须是服务 token 自身作用域的子集。
• 如果 token 创建后文件无法写入（例如磁盘已满），不会留下不完整文件，工具会返回一条指出该 token 名称的错误，说明 token 已创建但密钥已丢失，以便你撤销它。

gameye_edit_application 只会发送你提供的字段。提供 regions 和 ports 时，会替换整个列表。

TLS 端口

tls: true 的端口由 Gameye 在主机上终止 TLS。请使用 gameye_create_application 设置该选项：gameye_edit_application 不会应用 tls，并且通过 edit 发送的任何 ports 都会以 tls=false 保存，因此编辑使用 TLS 的应用时请省略 ports。

Agent skills

若要教会 Agent 如何集成 Gameye（会话生命周期、匹配、webhook 等），请安装姊妹项目 gameye-skills。这些 skills 会在可用时使用这些 MCP 工具，否则会回退到普通 HTTP。

开发

参见 CONTRIBUTING.md。

npm ci
npm test
npx tsc --noEmit -p tsconfig.test.json
npm run build

spec/client.yaml 是公共沙盒 /openapi.yaml 的快照，spec/overrides.yaml 保存每个操作对应的 MCP 工具名称：它取自 gameye-skills 的 spec/overrides.yaml 中的 tools: 映射，并由 scripts/reduce-overrides.mjs 精简而成（gameye-skills 保留完整文件，其中记录了服务与规范不一致之处）。运行 npm run sync-spec [path-or-url-to-overrides.yaml] 可刷新这两个文件。任一快照存在偏差时，npm run check-spec 会以代码 1 退出。

关于 Gameye

Gameye 是一个面向多人游戏服务器的托管平台。你只需提供容器映像，Gameye 就会通过一个 API 为每场比赛启动专用服务器。

• 会话 API 文档：gameye.com/docs/api-v2
• Gameye 文档：gameye.com/docs
• 免费试用：trial.gameye.com

安全

请私下报告漏洞。参见 SECURITY.md。

许可证

MIT © Gameye B.V.