星火创作者中心远程 MCP（试用）

作者后台 MCP 与 Editor MCP 是两项独立服务：前者通过 HTTPS 访问创作者中心，不需要打开编辑器项目，也不需要下载或安装后台源码。提供项目配置、开发日志、游戏局脚本日志和内测邀请码工具；配套后台更新后，还可经单独授权预检、创建和编辑测试环境的游戏模式，以及把授权账号加入当前项目内测。其他大厅配置写入、正式环境同步和游戏发布仍由各自流程处理。

日志下载需该环境的作者后台与 AdminServer 均部署对应版本；SDK 文档更新本身不会启用后台接口。下述分页工具需 AdminServer 的 sce-author-backend 0.2.0；连接后以 tools/list 返回的工具为准。

本文新增的项目选择、分阶段授权诊断和测试模式工具也需要配套后台更新。模式能力需先更新作者后台公共脚本及作者脚本，再更新各 AdminServer 副本；缺少工具时先核对部署，文档中的示例不代表服务已经更新。

接入

1. 登录 alpha 创作者中心 或 pd 创作者中心。在相应环境的后台 API 授权页 /api/v1/ai/mcp-grants 为自己的项目生成授权。当前可用的 API 域名分别为 adminapi-alpha.spark.xd.com 和 adminapi-pd.spark.xd.com；若部署地址调整，以创作者中心当前使用的后台 API 地址为准。
2. 授权页会展示所在环境的完整远程 MCP 地址，复制它并在支持 Streamable HTTP MCP 的 AI 客户端中添加远程服务。不要把作者后台源码或本地 stdio 开发工具复制进项目。
3. 从已获权限的项目列表选择项目，再按需要勾选额外权限并生成票据。授权页优先选中入口 URL 的 firm，其次使用后台当前项目；显式指定但无权限的项目不会自动替换为另一个项目。在连接的私有凭据/请求头配置中，将 Authorization 设为 Bearer、一个空格、再接票据。不要将票据写入项目配置文件、聊天或 Git。默认只读项目配置；日志、邀请码、加入自己的内测和测试模式写入分别授权。加入自己的内测与测试模式权限均默认不勾选。

由助手在已登录会话中临时接入

如果作者已经在助手当前的浏览会话里登录创作者中心，助手可以代为完成授权，不必先要求作者另外安装或配置一个 MCP 客户端：

1. 打开该环境的 /api/v1/ai/mcp-grants，选择本次项目，只勾选这次任务真正需要的能力。默认只读项目配置；日志、邀请码、加入自己的内测和测试模式写入分别按需授权。
2. 用生成的票据在本次会话内临时连接。票据只放在私有请求头，不写入聊天、项目文件、URL 或 Git。
3. 任务结束后立即撤销，并确认再次调用被拒绝；撤销失败时保留非敏感授权 ID 重试。

并行 worker 必须使用隔离的浏览器配置或会话，不得复用作者的主登录会话，也不要多个 worker 同时操作同一授权页。助手无法访问已登录会话时，才退回下面的最短配置，请作者在本机完成一次授权。

给外部作者的最短配置

授权成功后，AI 客户端只需要远程 MCP 地址和私有请求头：

{ "url": "授权页显示的远程 MCP 地址", "headers": { "Authorization": "Bearer 授权页刚生成的票据" } }

票据只在授权页显示一次，默认 15 分钟有效。连接失败或过期时，回到授权页重新生成，不要把票据改放到 URL 参数、项目文件或聊天内容中。客户端若不支持为远程 MCP 配置私有 Authorization 请求头，当前版本无法安全接入，应等待后续登录/OAuth 方案。

首次验证建议让 AI 先调用 author_get_project_setup，确认返回的 project_id 和 environment 正确，再调用日志或邀请码工具。这样可以先确认项目授权没有配错。

常见问题：

• 401：票据过期、被撤销，或 Authorization 请求头格式错误。
• 403：票据没有勾选对应能力，或项目不属于当前作者。
• 404：记录 ID 不属于授权项目/环境，或归档日志尚不可用。
• 406：客户端没有同时声明 application/json 和 text/event-stream 的 Accept 类型。
• 503：记录返回的 code、stage、requestId 及 X-Request-ID，交给管理员关联管理服务日志。授权诊断区分 project_list、project_access、grant_write、grant_lookup 和 grant_revoke；仅凭 503 不能判断是哪一项依赖异常。不要将票据或完整认证请求头一并转发。撤销失败时可保留页面上的非敏感授权 ID 重试；游戏局 Host 脚本日志不能替代授权服务日志。

内测前检查游戏模式

项目发布并取得内测码后，还需在创作者中心的测试环境配置可用的游戏模式。调用 author_get_project_setup，指定 environment="test"，检查返回的 modes 中至少有一个显示开启、生效范围 effect_scope 包含当前项目、房间人数和开局人数与项目玩家槽位匹配的模式。

编辑器中的 GameDataGameMode 和 workflow_create_game_mode 配置项目内玩法；创作者中心的模式决定对战平台的进入入口。两处配置都需要核对。没有可用的后台模式时，即使已有发布包和内测码，测试者也可能无法进入游戏。

缺少模式时，可使用下列已授权工具补充，或在创作者中心“大厅配置”的游戏模式页切到测试环境保存后读回。若授权服务不可用，应明确标记此项尚未检查。配置读回通过后，仍需用对战平台实际进局验证加载和显示。

测试模式 MCP

工具	权限	参数
author_get_test_modes	project_setup.read	environment: "test"
author_preflight_test_mode	project_modes.test.write	environment: "test", mode, mode_id?
author_create_test_mode	project_modes.test.write	environment: "test", mode, expected_version, request_id
author_edit_test_mode	project_modes.test.write	同创建，另需现有 mode_id

先读取当前模式与 version，再预检拟保存的完整 mode。写入使用读取的版本和本次操作唯一的 request_id；创建的模式 ID 由服务端生成，编辑使用读取返回的 mode_id_str 作为 mode_id。项目身份固定为授权项目，effect_scope 只允许包含该项目，所有工具均仅操作 test。

mode 必填 mode_type、mode_name、mode_desc、room_player_count、player_count 和 effect_scope。以下为单人模式预检示例，替换为授权项目 ID：

{
  "name": "author_preflight_test_mode",
  "arguments": {
    "environment": "test",
    "mode": {
      "mode_type": 1,
      "mode_name": "图片验证",
      "mode_desc": "检查发布后的界面图片",
      "room_player_count": 1,
      "player_count": 1,
      "effect_scope": ["p_your_project"],
      "show": true
    }
  }
}

预检通过后，按用户要求调用创建或编辑工具，传入完整 mode、expected_version 和 request_id。expected_version 是整体配置的 SHA-256，不自行计算或拼接；没有测试配置时由读取工具返回 missing。request_id 为 8 到 128 个 ASCII 字母、数字、下划线或短横线。

可选字段为 order、show、mode_key、display_room_list、background_url_enum、create_new_game_on_lobby_enter、has_unlock_condition、unlock_key 和 unlock_desc；实际类型与限制以工具 schema 为准。编辑提交完整模式，可选字段省略时采用默认值：排序 0、显示开启、图片 1、空文本和关闭的布尔开关。不要把局部修改当作补丁提交，以免覆盖原来的可选设置。模式的其他旧字段保留。人数、范围和敏感词检查与后台页面复用业务校验。

• 写后检查 mode、current_mode、version 和 readback_confirmed，再读一次模式列表。mode 是原操作保存的结果，current_mode 是当前结果；后续编辑可能令两者不同。
• 请求超时、MODE_WRITE_UNCONFIRMED 或 MODE_BACKEND_UNCONFIRMED 时，使用完全相同的 request_id、版本和模式参数重试，不能新建请求绕过结果未知。幂等重放不会重新应用已保存的旧模式。
• MODE_MATCHING_REFRESH_UNCONFIRMED 且 persisted=true 表示已经保存，但匹配服务刷新通知未确认；同一请求可重试通知。matching_refresh=published 仅表示通知已发布，不代表对战平台已实际进局。
• 409 表示版本冲突或同一请求 ID 被用于不同参数。先读取当前状态，再决定下一次修改。412 表示项目已达到当前 256 次幂等操作记录上限，需要后台维护，不能通过换 ID 继续。
• MCP 写入后，已打开的后台模式页面应先刷新再编辑，避免页面缓存整份旧配置覆盖新值。正式环境同步仍是独立操作，不随创建或编辑自动执行。

加入自己的项目内测

用户要求“把我加入这个项目的内测”时，可调用 author_join_my_test，省去在对战平台手动输入邀请码。工具使用签发票据的账号和票据绑定的项目；对战平台需登录同一账号并刷新内测列表。

先更新作者后台脚本并让目标后台加载，再更新授权服务，最后重新生成勾选“加入我的内测”的票据。独立权限为 test_invite.join_self；原只读、读取邀请码或创建邀请码权限均不包含它。连接后以 tools/list 是否提供该工具为准；本功能不要求更新编辑器或手机客户端。

调用无业务参数，可省略 arguments 或传空对象：

{"name": "author_join_my_test", "arguments": {}}

工具拒绝 user_id、project_id、firm、code 和 environment 等额外字段，不提供替其他账号加入的能力。前提是授权项目已有且启用的内测邀请码；创建邀请码、发布项目和配置游戏模式分别使用各自流程。

成功结果包含 project_id、joined: true、status、already_joined、readback_confirmed: true 和 message。status 为 joined 或 already_joined，后者表示该账号已经在内测列表。服务必须读回列表后才报告成功；返回中不包含邀请码或账号 ID。通过本工具及配套后台按钮重复加入时，同一账号、项目和邀请码复用持久记录标识，避免重试重复追加。

• JOIN_TEST_UNCONFIRMED 或 JOIN_TEST_BACKEND_UNCONFIRMED：加入结果未知，写入可能已经发生。保持同一账号、项目和有效授权，重试同一工具；持续未确认时停止自动重试，检查平台列表或交由管理员排查。后台操作约 15 秒截止，外层 MCP 最多等待 20 秒；截止不会回滚已受理的写入。
• JOIN_TEST_BUSY：前一次请求仍在处理，稍后重试；过期请求会释放占用，晚到结果不会覆盖新请求。
• JOIN_TEST_INVITE_MISSING / JOIN_TEST_INVITE_DISABLED：先核对邀请码配置；工具不会自动创建或启用邀请码。JOIN_TEST_INVITE_CHANGED 表示处理期间邀请码已轮换，核对后重新调用。
• JOIN_TEST_ACCESS_DENIED：当前账号失去项目权限，应停止操作。票据过期或撤销返回 HTTP 401，缺少对应权限返回 HTTP 403；业务失败以 MCP result.isError=true 返回错误码及 readback_confirmed: false，不能将 HTTP 200 当作加入成功。

加入列表与实际进局、游戏模式可用性是不同的检查。成功后仍需在目标平台刷新并实际进局验收。本工具不会自动同步正式配置；撤销票据阻止后续调用，不会取消已受理的操作或撤回已加入的内测。

日志文件

分析报错时优先使用文本分页工具：先列出实际记录，再读取末尾或定位关键词；需要交付完整文件时再分块下载。旧整包工具返回的 512 KiB 超限提示不代表日志无法读取，改用下述分页工具即可。

• 客户端上传日志：先调用 author_list_log_records 获取项目内的记录 ID，再调用 author_list_client_log_files 列出 ZIP 中的文件。选择返回的 entry_index，用 author_read_log_text 直接读取日志文本。压缩包可以超过 512 KiB，AI 客户端不需要另外发 HTTP 请求或取出连接中的私有票据。
• 服务端脚本日志：调用 author_list_game_sessions 获取开局 session ID，再用 author_read_log_text，指定 kind="session"。2.0 优先读取 script.log，旧项目回退 lua.log；在线 LogProvider 不可用时，会在已核对项目与游戏局的 OSS 归档路径下寻找相应脚本日志。
• 客户端原始附件、游戏局脚本日志总量、ZIP 内单个文件解压后大小均限制为 16 MiB。ZIP 列表最多处理 4096 个条目，列表按 next_offset 分页。不展开目录到服务器磁盘，也不递归解压嵌套压缩包。

记录列表默认查询过去 24 小时，可用 Unix 秒 since / until 查询最近七天内的时间段。列表为空时，先核对项目和 test / formal 环境，再扩大查询时间；仍为空则需要近期上传的客户端日志或近期游戏局作为样本。空列表只表示该查询范围内没有记录，不表示已读取或分析日志正文。

直接在 MCP 中分析文本

以下是 tools/call 的 name 和 arguments 示例，id 要替换为实际列表返回的字符串 ID：

{
  "name": "author_list_client_log_files",
  "arguments": {"environment": "test", "id": "270902"}
}

列表返回包内文件名、entry_index、文件大小、加密标记和原始附件 sha256。entry_index 是文件条目标识，允许重复文件名；以本次列表的实际返回值为准。

{
  "name": "author_read_log_text",
  "arguments": {
    "environment": "test", "id": "270902",
    "kind": "client", "entry_index": 0, "tail": true
  }
}

游戏局日志使用同一个工具，将 kind 改为 "session" 并省略 entry_index。文本默认每页 16 KiB，limit_bytes 可设为 4 至 32768，按返回文本的 UTF-8 字节数计。返回的 encoding 表示源文件编码；默认 UTF-8，也可自动识别 UTF-16 BOM，旧中文日志可显式指定 encoding="gb18030"。如果日志只有少量非 UTF-8 字节导致严格解码失败，服务会自动改用宽松解码并返回 text_lossy: true；替换字符只代表这些少量字节，不代表整份文件可当作无损文本。真正包含二进制控制字符的文件仍会拒绝，请改用分块获取。

• 读取末尾：tail=true，适合先查看加载失败或退出前的日志；不能同时传 offset 或 query。
• 顺序分页：省略 tail，从 offset=0 开始，将返回的 next_offset 原样作为下一次的 offset。next_offset=null 表示到达末尾。文本 offset 按解码后 UTF-16 code units 计，不是字节位置或行号；超长单行也能继续读取，Unicode 字符不会在页边界被拆开。
• 关键词定位：设置 query="地图加载失败"，按大小写敏感的字面子串匹配，从 offset 开始找到下一处并返回从命中位置起的一页文本及 match_offset。保留相同 query，用 next_offset 继续寻找后续页面中的命中；无命中时 match_offset=null。不是正则表达式，也不是整份日志的完整搜索结果。
• 内容一致性：续读时带上上一页或文件列表返回的 sha256。它校验原始附件或游戏局日志，而非某个文本分页。若内容变化，服务会提示重新开始；持续写入的实时日志可重新读取末尾，并将每次结果视为独立快照。

获取原始文件

author_get_client_log 和 author_get_game_session_log 保留完整文件 Base64 返回方式，上限仍为 512 KiB；超过时会提示使用分页工具。需要完整文件时可用 author_read_log_chunk，传入 environment、字符串 id 和 kind，按 next_offset 获取后续块：

{
  "name": "author_read_log_chunk",
  "arguments": {
    "environment": "test", "id": "270902", "kind": "client",
    "offset": 0, "limit_bytes": 32768
  }
}

分块结果的 data 是 Base64，offset/next_offset 按字节计。每页解码后按顺序拼接，核对 size_bytes；完整原始附件还可核对返回的 sha256。客户端省略 entry_index 时获取整个原始 ZIP/7Z/DUMP；指定时获取 ZIP 内单文件的原始字节，sha256 仍对应外层附件。ZIP 当前支持未加密的 Store/Deflate 条目。7Z、DUMP 和其它二进制内容可分块获取，但自动解压 7Z、解析 DUMP 需要 AI 客户端具有相应本地工具，服务不会把它们当作文本。没有文件处理能力的客户端应明确报告此能力边界；超过 512 KiB 的 ZIP 文本日志可以直接使用前述文本工具。

已有带授权的 HTTP 下载接口仍可使用：后台 API 下的 /api/v1/ai/mcp/client-log 或 /api/v1/ai/mcp/game-session-log，查询参数为 environment 与 id，返回完整原始文件。它们需要同一私有 Bearer 请求头，票据不能拼入 URL。MCP 文本分析流程无需调用这两个接口。

客户端上传日志目前仅允许从后台当前环境的 sce-maps-环境名.oss-cn-shanghai.aliyuncs.com 桶下对应项目的 logs/游戏ID/哈希.压缩包 路径读取。其它域名或项目路径会安全拒绝，需要先核对实际部署配置后再扩展，不能让用户填写任意下载地址。

票据仅绑定一个项目，15 分钟后失效，也可在授权页撤销；过期后需重新签发并更新连接凭据。当前是手动短期授权，尚不支持 AI 客户端自动浏览器登录或 OAuth 刷新。若 AI 客户端不支持安全配置 Bearer 请求头，请勿改用项目文件保存票据，等后续登录方案接入。创建邀请码的工具还要求用户明确提出创建请求；邀请码本身是可分享给测试者的代码，授权票据不是。

远程工具调用仍由后台再次校验作者身份、项目归属与票据范围。该入口不提供访问其它项目、后台管理员权限或发布权限。