游隙接入文档
接入文档

开发者文档 · v1

MCP 接入

配置本地客户端，授权正式平台，管理多个独立连接。

Markdown 原文 ↗

正式平台为 https://scalia.ltd。使用运行在你电脑上的 轻量 stdio MCP 客户端，通过 HTTPS 访问平台管理 API。独立安装包已包含运行依赖，无需平台源码、pnpm、本地数据库或 Web 服务。当前没有可直接填写 URL 的远程 MCP 服务。

安装客户端

需要 Node.js 24.x 或 26.x。支持 Node.js 26.5.0；游戏项目的 Node、pnpm 版本与客户端独立，游戏仍在自己的环境完成构建。

推荐使用 Node 自带的 npm，在任意目录安装：

npm install --global https://scalia.ltd/downloads/scalia-mcp-client-0.1.0.tgz
scalia-mcp --version
scalia-mcp --print-config

已有 pnpm 的站主也可使用（支持 pnpm 11.17.0）：

pnpm add --global https://scalia.ltd/downloads/scalia-mcp-client-0.1.0.tgz
scalia-mcp --print-config

若 pnpm 提示未配置全局 bin 目录，先运行 pnpm setup，重新打开终端后安装；也可直接使用 npm。不要在游戏项目中安装客户端依赖，也无需更换游戏项目的工具版本。

这是站点直接分发的标准 npm 格式安装包，尚未发布到公共 npm registry，请保留完整下载 URL。下载安装包、SHA-256、版本清单。

没有全局安装权限时，可下载后解压直接运行，安装包无需再安装依赖。例如 macOS/Linux：

mkdir scalia-client
cd scalia-client
curl --fail --location --output scalia-mcp-client-0.1.0.tgz https://scalia.ltd/downloads/scalia-mcp-client-0.1.0.tgz
tar -xzf scalia-mcp-client-0.1.0.tgz
node "$PWD/package/dist/cli.mjs" --print-config

解压后保留该目录；宿主会直接从这里启动客户端。

MCP 客户端配置

scalia-mcp --print-config 会输出使用当前 Node 与已安装客户端绝对路径的 Codex TOML。把输出合并到用户级 ~/.codex/config.toml 的 MCP 配置中；已存在 [mcp_servers.scalia] 时更新该段，避免重复。此命令只打印配置，不自动改写文件。结果类似下方，实际路径以命令输出为准：

[mcp_servers.scalia]
command = "/ABSOLUTE/PATH/TO/node"
args = ["/ABSOLUTE/PATH/TO/scalia-mcp-client/dist/cli.mjs"]
startup_timeout_sec = 20
tool_timeout_sec = 180

[mcp_servers.scalia.env]
YOUXI_PLATFORM_ORIGIN = "https://scalia.ltd"
YOUXI_MCP_CREDENTIALS = "/ABSOLUTE/PATH/TO/USER/.scalia/mcp/connection.json"

其他支持 stdio 的宿主使用相同 command、args 和 env。需要 JSON 的宿主可按以下结构填写：

{
  "mcpServers": {
    "scalia": {
      "command": "/ABSOLUTE/PATH/TO/node",
      "args": ["/ABSOLUTE/PATH/TO/scalia-mcp-client/dist/cli.mjs"],
      "env": {
        "YOUXI_PLATFORM_ORIGIN": "https://scalia.ltd",
        "YOUXI_MCP_CREDENTIALS": "/ABSOLUTE/PATH/TO/USER/.scalia/mcp/connection.json"
      }
    }
  }
}

无需 cwd。默认来源为 https://scalia.ltd，默认凭据为 ~/.scalia/mcp/connection.json；正式来源末尾不加斜杠，自定义凭据使用绝对路径。每个独立客户端进程应使用不同凭据文件，例如 connection-agent-a.json 和 connection-agent-b.json。

配置完成后，让宿主重新加载 MCP。工具总数当前为 30；可先调用 platform_status，尚未授权时显示 connected: false 与 LOGIN_REQUIRED。

首次授权

  1. 调用 platform_login，提供易于识别的客户端名称和所需权限。
  2. 在运行客户端的同一台电脑上打开返回的 authorizationUrl，以已验证的站主账号登录。
  3. 检查客户端名称和权限，明确同意。回调使用本机 127.0.0.1 的临时端口，授权有效窗口为 10 分钟；期间保持 MCP 进程运行。
  4. 浏览器提示连接已授权后，再调用 platform_status，确认 connected: true。
{
  "label": "游戏上传 Agent A",
  "scopes": ["manage:read", "manage:draft", "manage:publish"]
}

上面是 platform_login 的参数。普通注册玩家没有管理权限，需要当前站主完成授权。无需把网站密码、短信验证码或 SMTP 授权码交给 agent。

站主账号、权限与多个连接

权限能力
manage:read概览、游戏、站点与操作记录
manage:draft创建或修改工作稿、上传文件、查询上传状态、创建候选
manage:publish正式发布、上下架和历史回退
manage:accounts查询与停用账号、查看与撤销连接

platform_login 未传 scopes 时默认申请四类权限。仅查看信息的 agent 可以只申请 manage:read。完整上传发布通常需要读取、草稿和发布三类权限。

平台支持多个独立连接，每个连接都由站主分别授权，可分别限制权限、单独撤销。每个 agent/客户端进程应使用独立凭据文件，例如 production-agent-a.json 与 production-agent-b.json；不要让多个进程并发共享同一文件。客户端会以 0600 权限保存凭据。

平台支持多个站主账号。主管理员在后台账号管理查询已注册且验证邮箱的账号，确认“添加为站主”。各站主可管理全站游戏和站点内容，并用自己的账号授权 MCP。只有主管理员可以添加、移除或停用其他站主；添加和移除必须在网页后台完成，MCP 不提供这两个工具，manage:accounts 也不能授予这项权限。

移除站主后，旧网页会话、MCP 连接和私有预览立即失效；重新添加不会恢复旧授权。停用账号也使旧授权失效，恢复后需要重新登录并重新授权。账号管理中的 MCP 列表只展示当前账号自己的连接。修改同一游戏时仍需使用最新修订号，遇到冲突先重新读取，不覆盖另一连接的新改动。网页退出不撤销 MCP；重置账号密码会使旧连接失效。站主可在后台账号管理中撤销连接，或由有账号权限的连接使用 list_connections / revoke_connection。

访问令牌约 10 分钟有效，客户端自动轮换刷新；管理连接绝对有效期最长 30 天，到期后重新授权。不要分发凭据文件或将其提交到代码仓库。

工具调用格式

管理工具使用统一包装：input 为业务参数，写操作建议明确传入稳定 idempotencyKey。例如调用 get_game：

{
  "input": {"gameId": "11111111-1111-4111-8111-111111111111"}
}

platform_login、platform_status 和 submit_game_files 直接接受各自参数，不套 input。上传工具的示例见上传与发布。只读管理动作直接返回数据；写动作的业务结果放在 data 内。MCP 将结果序列化为文本 JSON，失败时设置 isError。

工具分组、每个动作的 input JSON Schema、权限和 HTTP 对应关系见平台 API及 OpenAPI JSON。

常见问题

状态或错误处理
客户端提示 Node 版本不支持使用 Node.js 24.x 或 26.x，并重新生成配置中的 Node 路径
全局安装权限不足或找不到命令使用上方解压运行方式，或配置自己的全局安装目录
LOCAL_CONFIGURATION_REQUIRED检查正式来源无尾斜杠、凭据为绝对路径
LOGIN_REQUIRED凭据不存在、过期、权限不正确或与来源不匹配，重新授权
REAUTHORIZE_REQUIRED连接失效，重新运行 platform_login
INSUFFICIENT_SCOPE当前连接未获对应权限，重新申请并由站主确认
REVISION_CONFLICT重新读取工作稿和状态，确认差异后使用最新修订
授权回调打不开检查是否在运行 MCP 的同一电脑打开、进程是否存活及授权是否超时

若要区分不同故障，请使用平台 API 返回的 code 和可用的 requestId；不要在日志中打印 Authorization 请求头或凭据文件。

平台源码开发者

仅开发客户端本身时需要完整项目源码、项目使用的 Node.js 24.22.0 与 pnpm 10.30.3。在源码根目录执行 pnpm install --frozen-lockfile --strict-peer-dependencies，然后用 Node 加载 tsx 运行 apps/mcp/src/server.mts。源码模式使用相同 YOUXI_PLATFORM_ORIGIN 和 YOUXI_MCP_CREDENTIALS，仍不需要启动本地平台服务来连接正式站。

pnpm mcp:package 从锁定依赖打包独立客户端并生成下载文件、校验摘要和第三方许可。已分发版本不能原地换包，后续更新需提升 apps/mcp/package.json 版本。普通站主按本文安装独立客户端即可。