# MCP 接入

正式平台为 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，在任意目录安装：

```sh
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）：

```sh
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。[下载安装包](/downloads/scalia-mcp-client-0.1.0.tgz)、[SHA-256](/downloads/scalia-mcp-client-0.1.0.tgz.sha256)、[版本清单](/downloads/scalia-mcp-client.json)。

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

```sh
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]` 时更新该段，避免重复。此命令只打印配置，不自动改写文件。结果类似下方，实际路径以命令输出为准：

```toml
[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 的宿主可按以下结构填写：

```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`。

```json
{
  "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 权限保存凭据。

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

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

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

## 工具调用格式

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

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

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

工具分组、每个动作的 input JSON Schema、权限和 HTTP 对应关系见[平台 API](/docs/api)及 [OpenAPI JSON](/docs/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` 版本。普通站主按本文安装独立客户端即可。