Shiplight Cloud 用于在本地仓库与 Shiplight 云之间同步 YAML 测试用例、模板和 TypeScript 函数，主要用途是把本地测试推送到云端（也可从云端拉回），使其能够按计划运行、与团队共享并集成 CI。此外，它还通过 REST API 管理测试运行、环境、文件夹、测试套件、标签、测试账号、测试数据与转发邮件配置。
主要能力
MCP 工具（需设置 SHIPLIGHT_API_TOKEN 后可用）：上传类包括 save_test_case、save_test_account、save_template、save_function；下载类包括 get_test_case、get_template、get_function；账号类 save_test_account 可创建或更新测试账号，并可通过可选的 storage_state_path 将本地浏览器会话上传到云端。建议优先使用 file_path 而非直接传内容以节省 token，get_test_case 始终使用 output_format: 'yaml'。
ID 追踪：上传后应将返回的云端 ID 写回本地文件，以便后续保存执行更新而非重复创建。测试用例（.test.yaml）使用顶层 YAML 字段 test_case_id: 123；模板（templates/.yaml）使用顶层字段 template_id: 45；函数（helpers/*.ts）使用每个导出上的 JSDoc 标签 @function_id 67。
REST API：基础地址为 https://api.shiplight.ai，所有调用需携带 Authorization: Bearer $SHIPLIGHT_API_TOKEN。覆盖测试用例（列表、获取、软删除、批量移动到文件夹）、测试数据（列表、获取、下载文件）、测试运行（列表、详情、触发）、测试用例结果、环境、变量、测试账号、转发邮件配置、文件夹、测试套件和标签等资源。
使用方式
设置：需要 Shiplight 云订阅和 SHIPLIGHT_API_TOKEN。若工具列表中缺少云端 MCP 工具（save_test_case、get_test_case 等），说明令牌缺失。此时应提示用户：云端工具不可用，请从 https://app.shiplight.ai/settings/api-tokens 获取 API 令牌，在项目的 .env 文件中设置 SHIPLIGHT_API_TOKEN，然后重新连接 MCP（/mcp）。若用户提供了令牌，将其追加到项目的 .env 文件（如不存在则创建），并告知：已保存到 <project>/.env，请确保 .env 在 .gitignore 中，重新连接 MCP（/mcp）以激活云端工具。
错误处理：401 Unauthorized 表示令牌无效或过期，请用户检查 .env 中的 SHIPLIGHT_API_TOKEN；403 Forbidden 表示权限不足，告知用户；404 Not Found 表示资源未找到，向用户报告；422 Validation 向用户展示校验信息；工具未找到表示令牌缺失，按上述设置流程引导用户。
适用场景
适合需要将本地 YAML 测试用例、模板和 TypeScript 函数同步到云端，以便按计划运行、团队共享和 CI 集成的团队；也适合通过 REST API 自动化管理测试运行、环境、文件夹、套件、标签、账号、测试数据和邮件转发配置的场景。
限制
需要 Shiplight 云订阅和有效的 SHIPLIGHT_API_TOKEN；缺少令牌时云端 MCP 工具不可用。部分端点有特殊约定：测试运行详情和测试用例结果端点没有 /v1/ 前缀；获取套件时始终使用 ?fields= 选择所需列，否则会返回完整测试用例实体，开销过大。测试用例删除为软删除，记录保留但从查询中隐藏。