跳至内容

模型上下文协议

Model Context Protocol (MCP) 是一项开放标准,允许人工智能代理与外部服务和数据源进行交互。它使 Claude、Claude Code、Codex 等应用,以及 Zed、Cursor 或 Visual Studio Code 等编辑器能够与 Tuist 互操作。

Tuist 在 https://tuist.dev/mcp 托管服务器端 Model Context Protocol 端点。通过将客户端连接到该端点,代理可以访问你的 Tuist 项目数据,包括测试洞察、不稳定测试分析等。大多数工具为只读,且作用域限定为经过身份验证的 Tuist 项目数据。账户设置工具可以在经过身份验证的用户拥有所需权限时列出账户、创建组织、创建项目,并将现有用户添加到组织中。每个工具都会声明注解,说明其是否为只读、是否可能导致难以撤销的更改,以及是否可以更改公共互联网状态。账户设置工具需要用户身份验证。它们不适用于项目令牌或普通账户令牌。当用户在浏览器中授权客户端或认领 auth.md 注册时,Tuist 仅在该 Model Context Protocol 端点上将该凭据与用户关联,以便设置工具完成请求的工作流。

Tuist 实现了 2026-07-28 protocol。请求是无状态的:客户端在每次请求中发送其协议元数据,并可以直接调用工具而无需初始化。server/discover 返回服务器的身份、能力、支持的版本和说明。不存在会话标识符或独立的事件流。使用 2025-06-18 或 2025-03-26 初始化流的客户端仍然受支持;它们也在没有服务器会话的情况下运行。

模型上下文协议与技能对比#

模型上下文协议工具和 skills 在功能上可能存在重叠。鉴于目前两者之间的重叠,请为每个工作流选择一种方法并一致使用,而不是在同一工作流中混合使用两者。

对于支持插件安装的客户端,请使用 Tuist plugins 同时安装两者。

配置#

将 https://tuist.dev/mcp 添加为客户端中的远程 Model Context Protocol 服务器。服务器的初始化说明和公共服务器卡片以内联方式描述了带有动态客户端注册的 OAuth 2.0 和标准浏览器授权流程,无需代理获取或遵循外部身份验证文档。这些服务器范围的说明保持了工作流指导的通用性:工具身份验证不会对本地命令行工具或构建系统集成进行身份验证,代理应通过相关的 Tuist 工具验证请求的更改。特定于构建系统的设置和身份验证检查记录在集成指南和提示中。Tuist 仍然分别在 https://tuist.dev/auth.md 发布 Open Authorization 发现元数据和当前的 auth.md protocol。

如果你的某个组织实施单点登录,则在浏览器中授权客户端需要通过该组织登录的会话,并且在需要时 Tuist 会先将你重定向到提供商。请参阅 single sign-on。

该端点接受无状态的 2026-07-28 Model Context Protocol 请求生命周期(包括 server/discover),同时也支持较旧的基于会话的生命周期。现有客户端可以继续使用其当前的连接方法。

支持 Model Context Protocol 事件的客户端可以订阅项目事件。有关可用事件和交付要求,请参阅 Events。

已经支持远程浏览器身份验证的客户端可以继续在浏览器中进行身份验证。支持 auth.md 的客户端和代理可以匿名注册、提供受信任的提供商身份断言,或启动服务身份验证的电子邮件认领。注册返回由 Tuist 签名的身份断言,代理在标准令牌端点将其交换为一小时访问令牌。Tuist 发布其公共签名密钥,并支持标准令牌撤销和提供商安全事件交付。

未经身份验证的代理应读取 Model Context Protocol 端点返回的 WWW-Authenticate 标头,获取受保护资源元数据,获取授权服务器元数据,并遵循其 agent_auth.skill URL。Tuist 还在未授权响应正文中返回相同的本地 auth_md URL,以便由语言模型驱动的客户端无需依赖原生客户端集成即可发现该流程。部署本地文档是端点名称、请求正文、认领轮询和断言交换的真实来源。

在代理启动电子邮件认领之前,必须要求用户确认其 Tuist 账户的电子邮件地址。不得从提供商个人资料、Git 配置、环境变量或会话元数据中推断该地址。

该端点使用 mcp 范围组。匿名预认领凭据可以发现能力并阅读公共集成指南,但不被视为已登录用户。在浏览器授权或认领后,凭据具有用户范围,并且每个工具应用与仪表板相同的授权检查。详情请参阅 scope groups documentation。

工具解析为经过身份验证的用户已经可以读取的项目。Xcode 和 Gradle 构建工具接受构建 UUID 或仪表板 URL。UUID 必须唯一标识一个项目;如果它出现在多个项目中,工具将返回未找到,而不是选择另一个项目的报告。项目范围的仪表板和 API 读取仍然可用。报告的行为者标识符是未经验证的标签,不是凭据或额外的访问权限。

构建列表和详情工具提供可选的 tuist_version 元数据:针对 Xcode 和 Cargo 的报告 Tuist CLI、针对 Gradle 的 Tuist Gradle 插件,以及针对 Mix 的 tuist_ex 库。Xcode 还从其关联的项目生成事件中公开 tuist_generation_version,该版本可能与上传所用的 CLI 不同。缺失的观察值为 null,不会从服务器或其他报告中推断。Bazel 使用其现有的 bazel_version;Once 运行详情公开 once_version。这些字段描述报告的版本,而非经过验证的身份或线协议版本。REST 构建端点公开相同的元数据。现有集成和不稳定测试技能不依赖版本字段,无需更改工作流。

Tuist 操作员通过 Tuist 的内部运营工具调查客户账户,该工具会记录每次调用;直接连接到此端点不会获得超出用户自身成员资格的任何访问权限。

Pulse#

Pulse 公开四个只读工具,均通过 account_handle 寻址:

工具 /api/accounts/:account_handle/pulse 下的 REST 等效项
query_pulse GET /:signal
get_pulse_analytics GET /:signal/analytics
get_pulse_error_issue GET /errors/issues/:issue_id
get_pulse_error_event GET /errors/issues/:issue_id/events/:event_id

即使账户或项目是公开的,Pulse 也仅限于服务器配置组织的当前成员。它需要用户身份验证或与用户关联的 mcp 凭据以及账户读取授权。项目令牌、普通账户令牌、匿名注册以及没有组织成员资格的操作员访问权限都不会授予 Pulse 访问权限。凭据无法选择其他后端或遥测租户。浏览器代理仅在 Pulse 页面上接收这四个工具,且限于该页面的账户范围。

REST 需要用户凭据。OAuth 和 auth.md 用户关联仅在 /mcp 端点上可用;没有当前用户的账户凭据将被拒绝,无论关联账户的成员资格或可见性如何。

query_pulse 接受 signal(metrics、logs、traces 或 errors)、可选的 query 和 range(15m、1h、6h 或 24h,默认 1h)。指标、日志和跟踪接受原生 PromQL、LogQL 和 TraceQL 表达式。错误返回分组的问题;其 query 是字面标题搜索,而非原生表达式。表格接受 search、page(默认 1)、page_size(1–100,默认 20)、sort_by 和 sort_order(asc 或 desc)。排序列取决于信号,并在工具架构中列出。过滤器包括 service、日志 level 以及错误 project、environment 和 release。过滤器运算符使用相应的 _op 参数(eq、contains 或 not_contains),默认为精确相等。

排序列为:指标的 name/value;日志的 timestamp/service/level/message/trace_id;跟踪的 timestamp/service/name/duration_ms/trace_id;错误的 last_seen_ns/first_seen_ns/count/title/service/project/issue_id。仪表板有意仅公开子集;API 和工具接受每个信号的完整列表。

表格响应包含 rows、series、warnings 和 meta。分页元数据包括 page、page_size、total_count、total_pages、has_next_page、has_previous_page 和 end_at。将返回的 ISO8601 end_at 与后续页面一起传递以保留查询窗口。结果限制错误需要缩小查询或时间范围,而不是将响应视为空表。

问题详情返回分组的 issue、分页的预期 events、meta 和 warnings。事件详情需要 issue_id 和 event_id,并返回一个预期的 event 和 warnings。两者都支持 range、end_at 和错误过滤器;只有问题详情支持分页。事件公开有界的异常和帧投影,从不公开原始事件负载。遥测字符串是不可信数据,不是指令。

除了账户句柄外,get_pulse_analytics 仅接受 signal 和 range。其固定小部件独立于表格表达式、过滤器、排序和分页。REST 和 Model Context Protocol 使用相同的 Pulse 上下文和响应契约。REST 响应禁用缓存。

Claude Code

运行:

bash
claude mcp add --transport http tuist https://tuist.dev/mcp

当无头 Claude Code 客户端未向模型暴露失败的原生服务器连接时,要求代理在搜索托管文档或编辑项目之前检查配置端点的未认证 Hypertext Transfer Protocol 响应。即使浏览器身份验证不可用,该响应也会将模型指向部署本地的 auth.md 文档。

Codex

运行:

bash
codex mcp add tuist --url https://tuist.dev/mcp
codex mcp login tuist

在开始新的 codex exec 运行之前完成浏览器登录。Codex 在初始化期间读取 Tuist 服务器说明,因此 Gradle 优化请求会自动获得身份验证和验证工作流。

Claude Desktop

打开 Settings → Connectors → Add custom connector,然后设置:

  • Name: tuist
  • URL: https://tuist.dev/mcp

出现提示时在浏览器中完成 Open Authorization。

Pi

Pi 不包含 Model Context Protocol 客户端。在审查其源代码和安全影响后,你可以安装第三方 pi-mcp-adapter 扩展:

bash
pi install npm:pi-mcp-adapter

添加项目级 .mcp.json 文件:

json
{
"mcpServers": {
"tuist": {
"url": "https://tuist.dev/mcp",
"auth": false
}
}
}

将 auth 设置为 false 可防止适配器的浏览器身份验证处理程序隐藏 Tuist 的未授权响应。无头代理随后可以读取返回的 auth_md URL,并遵循 Tuist 的注册、身份断言交换和认领轮询流程。将交换的访问令牌配置为 bearer 令牌,或让代理直接进行经过身份验证的 Model Context Protocol 调用。

如果你更喜欢浏览器身份验证,请将 auth 设置为 "oauth"。对于该流程,在身份验证完成期间,使用 Pi 的 remote procedure call mode 保持一个进程存活:

bash
pi --mode rpc

不要将待处理的浏览器身份验证拆分到单独的 pi --print 调用中,因为拥有回调状态的进程已退出。

OpenCode

将 Tuist Model Context Protocol 服务器添加到 opencode.json:

json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"tuist": {
"type": "remote",
"url": "https://tuist.dev/mcp"
}
}
}

然后对服务器进行身份验证:

bash
opencode mcp auth tuist
Cursor

打开 Cursor Settings → Tools & Integrations → Model Context Protocol Tools 并添加:

  • Name: tuist
  • URL: https://tuist.dev/mcp
Visual Studio Code

使用 Command Palette → MCP: Add Server,然后配置具有以下设置的 Hypertext Transfer Protocol 服务器:

  • Name: tuist
  • URL: https://tuist.dev/mcp
Zed

打开 Agent panel → Settings → Add Custom Server,然后设置:

  • Name: tuist
  • URL: https://tuist.dev/mcp

如果你的代理支持 auth.md,它可以匿名启动而无需打开浏览器。当提供者身份已链接时,受信任的提供者身份也可以在不打开浏览器的情况下完成验证。对于服务认证的电子邮件、匿名认领或首次提供者链接,代理会向你显示一个 Tuist 验证链接和六位代码。打开链接,登录,并在 Tuist 页面上输入代理的代码。切勿将代码发送回代理。Tuist 的授权服务器元数据直接指向部署自身的 /auth.md,其中包含确切的请求和轮询结构。

WebMCP#

在支持 WebMCP 的浏览器中,Tuist 的页面通过 document.modelContext 注册工具,因此内置于浏览器的代理可以在无需额外配置的情况下调用它们。这些调用在 Tuist 服务器上运行。

  • 网站和文档页面注册文档和源代码工具(search_tuist、search_tuist_code、list_tuist_files 和 read_tuist_file)。它们不需要你登录。
  • 当你登录后,账户的仪表板页面会为该账户注册 Tuist 的只读工具。每个页面仅注册其显示内容对应的工具,针对项目的构建系统:Gradle 项目的构建页面获得 Gradle 构建工具,其测试页面获得测试和覆盖率工具,运行器页面获得运行器工具,沙盒页面获得沙盒工具。个人账户 AI 设置页面的“订阅”部分获得 list_ai_subscriptions,它仅回答关于你自己账户的问题。每个页面还会获得文档工具 list_projects 和 get_project。这些工具以登录用户的身份运行,因此它们只能访问你在仪表板中可以读取的数据,且仅限于你正在查看的账户。当你移动到另一个页面或账户时,工具会被替换为该页面的工具。

创建、更改或删除数据的工具无法通过 WebMCP 使用,因为浏览器代理会在你未添加它们的情况下接收这些工具,并读取构建和测试生成的内容。连接 MCP 客户端到 /mcp 端点以使用这些工具。

如果组织强制实施单点登录,请使用其提供者登录仪表板以使用其工具。

构建系统集成使用两种凭据#

用于 Model Context Protocol 工具的凭据不会对 Gradle 插件或 Bazel 的远程服务进行身份验证。在代理编辑或验证 Gradle 或 Bazel 集成之前,它应运行:

bash
tuist auth whoami --url https://tuist.dev

如果该命令未经过身份验证,代理必须停止并要求用户运行:

bash
tuist auth login --url https://tuist.dev

对于本地或自托管部署,请替换两个命令以及 tuist.toml 中的 URL。在所有地方保持主机名拼写一致。例如,localhost 和 127.0.0.1 使用单独的存储凭据。

功能#

工具#

以下工具可通过 Tuist Model Context Protocol 服务器使用:

每个工具都会发布人类可读的描述以及明确的输入和输出模式。成功的调用返回符合所宣传输出模式的结构化内容,并为尚未消费结构化内容的客户端提供序列化为文本的相同结果。

接受单个记录标识符的工具,例如 build_run_id、test_run_id、test_case_id、bundle_id、run_id、generation_id 或 cache_run_id,也接受该记录的 Tuist 仪表板 URL。直接从浏览器粘贴 URL,而不是从中提取标识符。

文档和社区搜索#

此只读工具通过驱动文档网站的同一搜索引擎搜索 Tuist 的文档、application programming interface 参考、GitHub 发布、社区论坛和 GitHub issues。发布结果包括产品、版本、发布日期和预发布状态。默认情况下搜索稳定版本,可以通过 include_prereleases 包含预发布版本。该工具仅在位于 https://tuist.dev/mcp 的 Tuist 托管服务器上可用。

工具 描述 必需参数
search_tuist 搜索公开的 Tuist 文档、application programming interface 参考、GitHub 发布、社区讨论和 GitHub issues。可选地限制为一个 source(docs、api_reference、releases、forum、issues)。 query

反馈#

当 Tuist 工具或提示未按预期工作时,代理可以告知 Tuist 团队,例如结果令人困惑、出现错误、数据缺失或缺少功能。代理被要求建议一份报告,并仅在你同意后发送。每份报告都会开启与 Tuist 支持的对话,他们可能会通过电子邮件回复你。报告包括代理的预期、实际发生的情况、可选建议、你的 Tuist 用户 ID、句柄和电子邮件,以及你所属的组织。代理还可以命名问题发生的账户和项目,以便团队知道跟进哪个组织;仅接受你所属的账户。只有以 Tuist 用户身份登录的代理才能发送报告,每个用户每小时最多可以打开 10 份报告。该工具仅在位于 https://tuist.dev/mcp 的 Tuist 托管服务器上可用。

工具 描述 必需参数
report_feedback 报告 Tuist 工具或提示的问题。可选地命名 tool_name、问题发生的 account_handle 和 project_handle,并添加 suggestion。 category, expected, actual

基于源代码的回答#

这些只读工具允许代理使用与托管服务器一起部署的确切公共 Tuist 源代码修订版作为依赖于当前行为的答案的真实来源。它们仅在 https://tuist.dev/mcp 可用。

兼容的客户端在初始化期间接收有关工具源代码修订版、链接和结果限制的事实性描述,以及内联 OAuth 身份验证信息。这些描述不规定回答风格或验证工作流。用户可以直接提问,而无需先调用 ask_tuist 提示;该提示仍可用于显式的基于源代码的工作流。

每个操作都有固定的并发、持续时间、遍历、读取字节数和响应大小限制。搜索和列表结果包括 truncated 和 truncation_reason 字段。当结果被截断时,缩小路径、文件模式或搜索词,而不是将结果视为详尽无遗。

工具 描述 必需参数
search_tuist_code 通过搜索源文件来回答有关当前行为、默认值、配置、功能开关、错误处理或未记录细节的问题。结果包括周围的行、固定修订版的源代码链接以及扫描统计信息。 pattern
list_tuist_files 当相关路径未知时,发现源子系统或附近的测试。列表具有有限的深度和结果数量。 无
read_tuist_file 在找到相关路径后,检查实现文件、调用站点或测试中的特定行范围。截断的响应提供 next_start_line 以继续。 path

项目#

工具 描述 必需参数
list_accounts 列出经过身份验证的用户可用的个人和组织账户句柄,包括每个账户是否可以创建项目。 无
get_organization 获取组织的成员目录。待处理的邀请需要与仪表板相同的管理员权限;永远不会返回邀请接受令牌。 account_handle
create_organization 为经过身份验证的用户创建 Tuist 组织。 handle
create_project 在经过身份验证的用户可以访问的账户下创建 Tuist 项目。 account_handle, project_handle
add_organization_member 将现有的 Tuist 用户添加到组织或更新现有成员的角色。接受 user(默认)、admin 或 viewer,其中查看者可以读取仪表板和运行记录,但不能更改任何内容。 organization_handle, email
invite_organization_member 邀请电子邮件地址加入组织,无论该地址是否属于现有的 Tuist 用户。Tuist 会发送一封包含接受链接的电子邮件,该链接在 14 天后过期;当服务器无法发送电子邮件时,email_sent 为 false,必须从仪表板复制链接。接受 user(默认)、admin 或 viewer。需要组织管理员权限。 organization_handle, email
cancel_organization_invitation 取消待处理的组织邀请,使其链接不再被接受。需要组织管理员权限。 organization_handle, email
list_projects 列出经过身份验证的用户可访问的所有项目。 无
get_project 获取项目的配置和连接的存储库 URL。 account_handle, project_handle
connect_project_repository 将项目链接到账户的 GitHub App 安装可以访问的 GitHub 存储库。项目采用存储库的默认分支。需要项目管理员权限。 account_handle, project_handle, repository_full_handle
disconnect_project_repository 移除项目与其 GitHub 存储库的链接。需要项目管理员权限。 account_handle, project_handle

账户令牌#

工具 描述 必需参数
list_account_tokens 列出账户令牌元数据,而不暴露令牌值。 account_handle
get_account_token 获取账户令牌元数据,而不暴露其值。 account_handle, token_id
list_project_tokens 列出项目令牌元数据,而不暴露令牌值。 account_handle, project_handle

AI 订阅#

这些工具管理经过身份验证的用户自己的 Claude 和 ChatGPT 订阅,用于线程等 AI 功能。它们需要用户身份验证和对 AI 功能的访问权限,并且仅返回连接元数据,从不返回凭据。断开连接会删除保存的凭据,但不会撤销提供商处的授权。

工具 描述 必需参数
list_ai_subscriptions 列出每个订阅是否已连接以及服务器是否可以连接它。 无
connect_claude_subscription 保存 claude setup-token 打印的订阅令牌。该令牌是一个秘密,会通过客户端和模型传递,因此请明确提供;将其粘贴到仪表板的 AI 设置中可使其不出现在对话中。 token
start_chatgpt_subscription_login 启动 OpenAI 设备登录并返回用户在那里输入的验证 URL 和代码,以及一个 login_id。15 分钟后过期。 无
poll_chatgpt_subscription_login 检查待处理的登录:在用户批准代码之前为 pending,之后变为 connected。 login_id
cancel_chatgpt_subscription_login 取消待处理的登录。已连接的订阅保持连接状态。 login_id
disconnect_ai_subscription 删除订阅的保存凭据和任何待处理的登录。 provider

通知规则#

这些工具管理经过身份验证的用户自己的通知规则:当规则中的项目(或未列出任何项目时,你可被通知的任何项目)发生事件(例如新预览)并满足其条件时,执行其操作,例如向你的 Tuist 应用设备发送推送通知。没有规则你就收不到通知。它们需要用户身份验证,仅作用于你自己的规则,并且仅接受你所属账户的项目。它们不提供用于仪表板页面,因为规则跨越你所有的账户。

工具 描述 必需参数
list_notification_events 列出规则可以订阅的事件类型,每个类型都带有其条件的 JSON Schema。 无
list_notification_condition_options 建议项目中事件的条件值,例如其最近预览的轨道和分支。 event, account_handle, project_handle
list_notification_rules 列出你的规则。 无
create_notification_rule 从事件、可选项目和条件以及至少一个操作创建规则。 event, actions
update_notification_rule 更改规则的启用状态、项目、条件或操作。 rule_id
delete_notification_rule 删除规则。 rule_id

持续集成运行器#

工具 描述 必需参数
list_runner_jobs 列出账户的持续集成运行器作业。 account_handle
get_runner_job 获取持续集成运行器作业。 account_handle, workflow_job_id
list_runner_job_steps 列出为持续集成运行器作业记录的步骤。 account_handle, workflow_job_id
list_runner_job_metrics 列出为持续集成运行器作业记录的机器指标。 account_handle, workflow_job_id
list_runner_job_logs 列出持续集成运行器作业最多 500 条捕获的日志行。 account_handle, workflow_job_id
list_runner_workflows 列出账户的持续集成工作流汇总。 account_handle
list_runner_profiles 列出账户的持续集成运行器配置文件,以及每个配置文件的 runs-on 标签。 account_handle
get_runner_catalog 列出运行器配置文件可以使用的机器规格和 Xcode 版本。 account_handle
create_runner_profile 创建具有平台、机器规格以及在 macOS 上的 Xcode 版本的运行器配置文件。可选择设置哪些分支保存其缓存卷。需要账户管理权限或 account:runners:write 范围。 account_handle, name, platform, vcpus, memory_gb
update_runner_profile 更改运行器配置文件的机器规格、Xcode 版本或哪些分支保存其自定义缓存卷更改。省略的字段保留其值。需要账户管理权限或 account:runners:write 范围。 account_handle, profile_name
delete_runner_profile 经用户确认后删除运行器配置文件。默认配置文件无法删除。需要账户管理权限或 account:runners:write 范围。 account_handle, profile_name

运行器卷工具公开与卷仪表板相同的数据。读取工具需要运行器访问权限;清除需要账户管理权限或 account:runners:write 范围,以及用户确认。

工具 描述 必需参数
list_runner_volumes 按名称和存储库过滤,对卷进行排序和分页。 account_handle
get_runner_volume 存储库、平台、容量、已用空间和最后使用时间。 account_handle, volume_id
list_runner_volume_jobs 分页的作业和工作流引用、缓存状态、命中结果和挂载时间。 account_handle, volume_id
list_runner_job_volumes 作业挂载的卷。 account_handle, workflow_job_id
get_runner_volume_analytics 存储序列、作业运行、命中率和趋势。可选 volume_id、start 和 end(ISO 8601);默认为七天,最长 90 天。 account_handle
delete_runner_volume 删除卷及其保存的内容。正在运行的作业保留其私有副本但无法保存;后续使用相同密钥的作业将从空状态开始。 account_handle, volume_id

列表接受 page 和 page_size(最多 100)。卷清单还接受 name 和 repository(精确匹配,以 AND 组合)、sort_by(volume、repository、used_space、capacity、last_used)以及 sort_order(asc、desc)。未知的测量值和命中结果保持为 null。缓存状态描述卷更改是否已保存,而非作业成功与否。

沙盒#

沙盒工具公开与沙盒仪表板相同的数据和操作。沙盒运行任意命令,因此每个工具(包括只读工具)都需要账户管理权限,且账户需启用沙盒功能。仪表板的沙盒页面注册了只读工具。

工具 描述 必需参数
list_sandboxes 对沙盒进行分页,显示其状态、规格和时间戳。可选 search(沙盒中的文本、Amp Orb 或 Anthropic 会话 ID)、status、vcpus、sort_by(created、last_active、identifier)和 sort_order。 account_handle
get_sandbox 沙盒的状态、规格、节点、归档和时间戳。 account_handle, sandbox_id
get_sandbox_analytics vCPU 小时数、创建的沙盒数量、会话、设置和启动耗时,以及相对于账户限制的峰值 vCPU、内存和磁盘使用情况,并附带趋势。可选 start 和 end(ISO 8601);默认为 30 天,最长 90 天。 account_handle
create_sandbox 启动一个空白沙盒并在其运行后返回。可选 platform(linux 或 darwin)、template、带 memory_mb 的 vcpus(Linux:2x4096、4x8192 或 8x16384,默认 2x4096;macOS:8x8192、8x16384 或 8x24576,默认 8x8192)以及 workspace_gb。 account_handle
pause_sandbox 将正在运行的沙盒快照保存到其节点的磁盘。 account_handle, sandbox_id
resume_sandbox 恢复已暂停或归档的沙盒。 account_handle, sandbox_id
archive_sandbox 将已暂停沙盒的磁盘排队移动到对象存储。 account_handle, sandbox_id
delete_sandbox 经用户确认后删除沙盒及其磁盘。 account_handle, sandbox_id

Webhook#

Webhook 工具使用与仪表板相同的仅限管理员权限。交付尝试包含为端点记录的请求和响应数据,但不包含端点签名密钥。

工具 描述 必需参数
list_webhook_endpoints 列出账户的 Webhook 端点。 account_handle
get_webhook_endpoint 获取 Webhook 端点。 account_handle, webhook_endpoint_id
list_webhook_delivery_attempts 列出端点的交付尝试。 account_handle, webhook_endpoint_id
get_webhook_delivery_attempt 获取交付尝试。 account_handle, webhook_endpoint_id, delivery_attempt_id

Xcode 构建#

用于 Xcode、Gradle、Bazel、Mix 和 Cargo 的构建详情工具公开现有的 custom_metadata: {tags, values} 结构,包括报告的基础设施观测数据。值保持为字符串,不熟悉的键会被保留。例如,tuist.cpu.available_processors 描述运行时可用的逻辑处理器,而 tuist.gradle.max_workers 是 Gradle 工作器限制,tuist.jvm.max_heap_bytes 是 JVM 堆限制,而非主机内存。这些是不可信的客户端观测数据,而非经过验证的运行器身份。缺失的观测数据保持缺失;导入的日志和较旧的客户端可能没有基础设施元数据。元数据更新有待协调的客户端/协议更新。

工具 描述 必需参数
list_xcode_builds 列出项目的 Xcode 构建运行。 account_handle, project_handle
get_xcode_build 获取特定 Xcode 构建运行的详细信息,包括保存原始 .xcactivitylog 的归档文件的临时下载 URL。 build_run_id
list_xcode_build_targets 列出特定 Xcode 构建运行的构建目标。 build_run_id
list_xcode_build_files 列出特定 Xcode 构建运行的编译文件。 build_run_id
list_xcode_build_steps 列出记录的构建步骤,包含时间和结果,不含日志文本。 build_run_id
get_xcode_build_step 获取一个记录的构建步骤,包括其日志和截断标志。 build_run_id, step_id
list_xcode_build_issues 列出特定构建运行的构建问题(警告和错误)。 build_run_id
list_xcode_build_cache_tasks 列出特定 Xcode 构建运行的可缓存任务(缓存命中/未命中)。 build_run_id
list_xcode_build_cas_outputs 列出特定 Xcode 构建运行的 内容寻址存储 输出。 build_run_id

list_xcode_build_steps 默认返回每页 20 个步骤(通过 page_size 最多 100 个),并提供 page 和 pagination_metadata 用于导航。使用 search 匹配标题、项目或目标,或过滤精确的 project、target、category(例如 swiftCompilation)和 status(success 或 failure)。按 duration_ms 排序以最慢优先(默认),或按 start_ms 按时间顺序排序。步骤 ID 用于打破平局,并以十进制字符串形式返回以保留完整的 64 位精度。ID 限定于单个构建,不应跨构建匹配。

可选的 start_ms 和 end_ms 选择与从构建开始起以毫秒为单位的时间范围重叠的步骤;结束时间是独占的。两个工具都接受构建 UUID 或仪表板 URL 作为 build_run_id。将返回的步骤 id 原样作为 step_id 传递以检索其日志。每个步骤的日志最多保留 64 KiB,log_truncated 表示省略的输出。

处理 Xcode 构建时,默认会收集步骤。记录的步骤数据保留 90 天。列表响应包含 availability:当存在记录的步骤时(即使过滤器未匹配任何项)为 available;当构建仍在处理且尚无步骤时为 processing;或者当步骤未被记录或已过期时为 unavailable。

HTTP API 在 GET /api/projects/{account_handle}/{project_handle}/xcode/builds/{build_id}/steps 和 GET /api/projects/{account_handle}/{project_handle}/xcode/builds/{build_id}/steps/{step_id} 提供相同的操作,具有相同的过滤器和分页功能。两者都需要对构建所属项目的读取权限。

Gradle 构建#

工具 描述 必需参数
get_gradle_integration_guide 返回完整的身份验证、项目设置、Gradle 插件、缓存策略以及两次构建验证工作流。代理在编辑现有的 Android 或 Gradle 项目之前应调用此方法。 无
list_gradle_builds 列出项目的 Gradle 构建运行,包括自定义元数据。使用可选的 tag 参数按自定义标签进行过滤。 account_handle, project_handle
get_gradle_build 获取构建元数据和任务/缓存计数。 build_run_id
list_gradle_build_tasks 列出任务结果、复合构建标识、可缓存性和增量状态。 build_run_id
list_gradle_build_steps 列出定时任务、配置和转换,支持搜索、元数据和重叠时间过滤器。 build_run_id
get_gradle_build_step 通过不透明 ID 检查记录的步骤元数据;不提供每个步骤的日志。 build_run_id, step_id

Gradle 和 Bazel 步骤列表默认返回 20 个结果(最多 100 个),支持 search、精确的 project、target、category 和 status、重叠的 start_ms / end_ms 过滤器(结束时间独占),以及按 duration_ms 或 start_ms 排序。原样传递返回的 ID;它们限定于其所属的构建。列表公开 time_origin 和 coverage。较旧的 Gradle 报告使用 first_recorded_timestamp,因为未上传构建开始时间。Bazel 配置文件通过 trace_profile 覆盖范围和以 profile_start 为时间原点来公开所有记录的间隔。较旧的构建回退到保留的 BEP 摘要。源记录在 90 天后过期。Bazel 详细信息在发布时包括经过清理的操作日志;Gradle 详细信息 log 为空。compare_builds 提示利用此覆盖范围来区分完整的 Bazel 跟踪与保留的摘要,并引导代理在检查更广泛的调用输出之前,先查看步骤详细信息以获取操作结果和日志。

单步工具 get_gradle_build_step 和 get_bazel_build_step 通过 ID 检索步骤,不接受时间过滤器;请使用相应的列表工具按时间范围过滤步骤。

如果在列出步骤和获取步骤之间收到了完整的配置文件,则从保留的摘要中返回的 Bazel 步骤 ID 仍然可读。如果索引配置文件的步骤数据已过期,则会报告为不可用。Gradle 步骤列表包括持续时间为零的缓存和跳过操作。

Bazel 调用#

工具 描述 必需参数
get_bazel_integration_guide 返回身份验证、项目设置、Bazel 配置和验证工作流。 无
list_bazel_invocations 列出已完成的 Bazel 构建事件协议 调用,包括构建指标、有界的执行时间线、关键路径诊断以及项目的相关远程缓存总数。 account_handle, project_handle
get_bazel_invocation 获取一个已完成的 Bazel 调用,包括构建指标、有界的执行时间线、关键路径诊断以及相关的远程缓存总数。 account_handle, project_handle, invocation_id
list_bazel_build_steps 列出记录的 Bazel 配置文件间隔,带有过滤器和明确的覆盖范围。 account_handle, project_handle, invocation_id
get_bazel_build_step 检查记录的 Bazel 步骤及其发布的操作结果和经过清理的日志。 account_handle, project_handle, invocation_id, step_id
list_bazel_invocation_logs 按执行顺序列出为 Bazel 调用捕获的经过清理的测试日志。 account_handle, project_handle, invocation_id
get_bazel_invocation_log 获取为 Bazel 调用捕获的一个经过清理的测试日志。 account_handle, project_handle, invocation_id, invocation_log_id
list_bazel_cache_events 列出原始的 Bazel 远程缓存观察结果,包括其操作、端点和观察时间,可选择缩小到特定调用、结果或操作。 account_handle, project_handle
get_bazel_cache_event 获取一个原始的 Bazel 远程缓存观察结果。 account_handle, project_handle, cache_event_id

Cargo 构建#

工具 描述 必需参数
list_cargo_builds 列出项目的 Cargo 构建,最新的排在前面。按 git_branch、status、is_ci 或 command 过滤。Cargo 测试执行结果可通过测试工具获取,而非此构建列表。 account_handle, project_handle
get_cargo_build 获取构建元数据、聚合缓存计数器,以及最多 500 个带有诊断信息的已记录编译器作业。compilations_truncated 表示省略的作业;诊断信息仅涵盖返回的作业。 account_handle, project_handle, build_id

在 get_cargo_build 上设置 include_cache_inspection: true 以检索经过验证的任务决策和 CAS 操作,限制为 4 MB。默认情况下,以及当记录缺失或无效时,cache_inspection 为空。请尊重其部分捕获的 truncated 标志;传输不会确定每个任务命中的本地/远程来源。HTTP 详细端点接受相同的查询参数。

Mix 构建#

工具 描述 必需参数
list_mix_builds 列出项目的 Mix (Elixir) 编译构建,最新的排在前面,包括自定义元数据。按 git_branch、status、is_ci 或 mix_env 过滤。 account_handle, project_handle
get_mix_build 获取构建元数据、诊断计数以及依赖缓存摘要。 account_handle, project_handle, build_id

构建跟踪#

工具 描述 必需参数
get_build_trace 获取 Xcode、Gradle、Bazel 或 Mix 构建时间线的下载链接,格式为可在 Perfetto 中打开的跟踪文件。 account_handle, project_handle, build_id

build_id 是构建运行 ID(Bazel 的调用 ID)或构建的仪表板 URL。返回的 trace_url 提供 Chrome Trace Event JSON 文件。任何持有该链接的人都可以在调用后一小时内(直到 expires_at)无需其他凭据即可下载该构建的跟踪文件。代理可以使用 curl 下载它,交给你在 Perfetto 中打开,或使用 Perfetto 的 trace_processor 进行查询。跟踪文件包含按并行性打包到通道中的记录步骤、跨越整个构建的轨道,以及在构建记录机器指标时的 CPU 和内存计数器。它包含与上述步骤工具相同的数据,但不包含日志。仪表板从每个构建的“时间线”选项卡提供相同的文件。

Once 运行#

工具 描述 必需参数
list_once_runs 列出项目的 Once 运行,最新的排在前面。按 kind(build、test 或 generic)、status、is_ci 或 git_branch 过滤。未完成的运行状态为 in_progress。 account_handle, project_handle
get_once_run 获取运行及其操作总数、缓存摘要,对于测试运行还包括测试总数。 account_handle, project_handle, run_id

Cargo 构建、Mix 构建和 Once 运行 ID 在项目内是唯一的。通过 HTTP API 在 GET /api/projects/{account_handle}/{project_handle}/cargo/builds、.../mix/builds 和 .../once/runs 上可提供相同的读取操作,每个都有一个针对单个 ID 的详细端点。

任务、操作、模块和文件#

这些项目范围的工具检查跨运行的持久构建身份。首先使用 list_build_entities,然后将返回的稳定 id 与相同的 kind 一起传递给 get_build_entity 或 list_build_entity_history,同时提供 account_handle 和 project_handle。不需要构建或调用标识符。

工具 描述 必需参数
list_build_entities 列出在项目构建中看到的某一类任务、模块、操作或文件。 account_handle, project_handle, kind
get_build_entity 获取一个构建实体,包括其原生身份和所选周期的分析数据。 account_handle, project_handle, kind, id
list_build_entity_history 列出一个构建实体的记录执行、编译或缓存事件,最新的排在前面。 account_handle, project_handle, kind, id
kind 工具链 历史列表
bazel_actions Bazel 操作 BEP 报告的操作执行
gradle_tasks Gradle 任务 任务执行
xcode_modules Xcode 模块 编译和模块缓存事件
once_actions Once 操作 执行
mix_files Mix 编译文件 编译
mix_modules Mix 编译模块 编译
cargo_crates Cargo crate 记录的 rustc 调用

这些工具正在逐步推出,仅返回已启用它们的项目的数据;对于其他项目,它们会返回错误而不是空结果。只有使用其构建工具链的项目才可以使用某种类型。这些工具接受有界的 start_at/end_at 过滤器、environment(any、ci 或 local)以及精确的 branch。list_build_entities 接受 q;list_build_entity_history 支持不透明的 after/before 游标。未知的时间或缓存观测值保持不可用,而不是变为零或缺失。历史记录引用记录的父级和原生执行,以便使用现有的运行工具进行下钻分析。

get_build_entity 指标包括 duration_samples,即具有记录时间的观测值数量:真正的零持续时间计入计数,缺少时间数据的不计入。此计数可能低于观测值总数;不可用的持续时间统计信息保持为 null。

Xcode 模块的持续时间来自构建日志中测量的目标编译。模块缓存解析和没有编译工作的目标不提供持续时间样本。编译观测值引用 Xcode 构建;缓存事件引用生成或缓存命令。

Bazel 操作通过目标标签、助记符和配置的主要输出来标识,在不依赖输入相关缓存摘要的情况下保持不同的操作和配置相互独立。历史记录 BEP 报告的执行,而不是缓存查找或跟踪配置文件阶段。完整的执行覆盖需要 --build_event_publish_all_actions;构件交付是尽力而为的,因此缺失的观测值并不能证明没有工作运行。较旧的没有稳定身份或执行开始的 Kura 负载仍然被接受但不建立索引。缺少结束时间测量值保持不可用,真正的零持续时间计入计数。

Mix 模块的持续时间测量包含文件的编译,而不是独立测量的模块工作。当客户端报告目标映射时,Once 操作使用声明的目标/能力/索引槽位;仅诊断标签不是稳定的身份。现有客户端和运行级别工具保持不变地得到支持。

Cargo crate 按精确记录的 crate 根目录、名称和类型分组。检出路径更改可能会拆分历史记录,并且不区分构建配置文件、功能和目标三元组。历史记录测量 rustc 调用,而不是每个文件的工作或缓存命中;缺失的作业不能确定删除或完整的工作区清单。

分析读取具有有限的内存和执行时间。如果查询超过这些限制,工具将返回错误而不是虚构一个空结果。

新观测值在部署后建立索引;此功能不会回填现有的运行遥测数据。在 数据保留策略 下,身份元数据的寿命长于单个观测值。

测试#

工具 描述 必需参数
list_test_runs 列出项目的测试运行。query 字段为 git_branch、scheme 和 status:field:"value" 精确匹配,field~"value" 匹配不区分大小写的子字符串,前导 - 否定任一运算符。例如,-git_branch~"gh-readonly-queue" 排除合并队列分支。空格分隔的查询过滤器和显式参数以 AND 语义组合。 account_handle, project_handle
get_test_run 获取测试运行的详细指标,包括其结果包 (.xcresult) 和会话归档的临时下载 URL。 test_run_id
list_test_module_runs 列出特定测试运行的测试模块运行。 test_run_id
list_test_suite_runs 列出特定测试运行的测试套件运行,可选按模块过滤。 test_run_id
list_test_cases 列出项目的测试用例(支持如 flaky 等过滤器)。 account_handle, project_handle
get_test_case 获取测试用例的详细指标,包括可靠性率、不稳定率和运行次数。 test_case_id 或 identifier + account_handle + project_handle
list_test_case_runs 列出测试用例运行,可选按测试用例或测试运行过滤。 account_handle, project_handle
get_test_case_run 获取特定测试用例运行的失败详情和重复情况。 test_case_run_id
list_test_case_run_attachments 列出测试用例运行的附件。每个附件都包含一个临时下载 URL。 test_case_run_id
list_test_case_events 列出测试用例的状态更改,例如将其静音或跳过。 test_case_id
update_test_case 更新测试用例的状态或不稳定分类。更改可以将事件分派到配置的 webhook 端点,包括外部服务。 test_case_id 或 identifier + account_handle + project_handle
list_xcode_test_targets 列出测试运行的选择性测试目标结果。 test_run_id
get_coverage 获取项目的代码覆盖率及其目标,在某个提交处或分支的最新完整提交处。如果没有 git_commit_sha 或 branch,则读取默认分支。 account_handle, project_handle
list_coverage_files 列出某个提交的代码覆盖率测量的文件及其行覆盖率,在某个提交处或分支的最新完整提交处。支持 search、排序和分页。 account_handle, project_handle
get_coverage_file 获取文件的代码覆盖率及其函数,在某个提交处或分支的最新完整提交处。设置 include_lines 以获取每行的执行计数。 account_handle, project_handle, path

代码覆盖率工具可供启用了代码覆盖率的账户使用。

Bundle#

工具 描述 必需参数
list_bundles 列出项目的 bundle(应用二进制文件)。可选按 git_branch 和 tags 过滤(所有标签必须精确匹配)。 account_handle, project_handle
get_bundle 获取特定 bundle 的详细信息,包括自定义标签。 bundle_id
get_bundle_artifact_tree 获取 bundle 的完整构件树,作为按路径排序的平面列表。 bundle_id

list_bundles 接受 tags: ["paid", "production"] 以区分构建变体或环境。标签是区分大小写的标签,包含字母、数字、连字符或下划线,最多 10 个标签,每个标签最多 50 个字符。列表和详细结果包括 custom_metadata.tags。分页计数和分支过滤器应用于带标签的结果;省略 tags 保留未过滤的行为。无效的标签过滤器返回错误而不是扩大查询范围。

生成#

工具 描述 必需参数
list_generations 列出项目的生成运行。 account_handle, project_handle
get_generation 获取特定生成运行的详细信息。 generation_id

缓存运行#

工具 描述 必需参数
list_cache_runs 列出项目的缓存运行。 account_handle, project_handle
get_cache_run 获取特定缓存运行的详细信息。 cache_run_id
list_xcode_module_cache_targets 列出生成或缓存运行的模块缓存目标,显示每个目标的缓存命中/未命中状态和诊断组件哈希值,包括额外的哈希输入。 run_id

预览#

工具 描述 必需参数
list_previews 列出项目的可共享应用预览。 account_handle, project_handle
get_preview 获取预览及其构建的临时下载 URL。 preview_id
get_latest_preview 查找正在运行的应用二进制文件的最新预览。 account_handle, project_handle, binary_id, build_version

自动化#

工具 描述 必需参数
list_automation_alerts 列出项目的自动化警报。 account_handle, project_handle
get_automation_alert 获取自动化警报。 alert_id
list_automation_alert_revisions 列出自动化警报的修订历史。操作凭据已脱敏。 alert_id
list_project_notification_alerts 列出项目通知警报规则。需要与仪表板设置页面相同的管理员权限。Webhook 地址已脱敏。 account_handle, project_handle

事件#

使用无状态 2026-07-28 Model Context Protocol 生命周期的客户端可以调用 events/list 来发现事件及其负载架构:

事件 发送时机 订阅过滤器
test_case.marked_flaky 测试用例从非不稳定变为不稳定。 account_handle, project_handle
build.failed 本地或持续集成的 Xcode、Gradle 或 Bazel 构建以失败结束。 account_handle, project_handle
test_run.failed 本地或持续集成测试运行以失败结束,包括合并的分片运行或已放弃的运行。 account_handle, project_handle
ci_job.failed Tuist runner 作业以失败完成。 account_handle

要订阅,客户端调用 events/subscribe,传入事件名称、上面列在 arguments 中的句柄,以及包含 https:// 回调 URL 和 whsec_ 签名密钥的 webhook 交付。项目事件需要账户成员资格以及对相应测试或构建数据的读取权限;runner 作业事件需要账户成员资格和 runner 读取权限。已声明的 auth.md 访问令牌、已声明的账户令牌和浏览器授权授予可以创建订阅;当相关凭据不再有效时,交付停止。每个用户最多可以保留 25 个活跃订阅。Tuist 在保存订阅之前向回调发送验证质询。回调必须返回包含相同 challenge 值的对象。订阅默认持续七天,可以通过再次订阅来刷新,并在用户的访问权限或凭据被移除时停止交付。可选的 ttlMs 限制在一小时到 30 天之间。Tuist 会重试超时的回调,并在至少三次连续超时(跨越五分钟)后取消订阅;恢复回调后请重新订阅。

当事件发生时,Tuist 将其资源标识符和仪表板 URL 发送到回调。构建和测试运行失败还包括 is_ci 和 git_branch,因此客户端可以忽略本地失败或按分支过滤。构建事件包括 build_system;runner 作业事件包括 workflow_job_id 和 workflow_run_id。请求包含订阅标识符和 Standard Webhooks 签名标头,以便客户端验证其来源。Tuist 会重试失败的交付,因此客户端应使用稳定的 eventId 来丢弃重复项。负载省略了测试名称、日志和失败消息;客户端可以通过上述工具获取这些详细信息,并决定是否通知团队或开始调试。客户端可以使用 events/unsubscribe 停止交付。

提示#

提示 描述
fix_flaky_test 引导你通过分析失败模式、识别根本原因并应用针对性修复来解决不稳定测试。
compare_builds 引导你对比构建以识别性能回归、缓存变化和构建问题。针对 Xcode、Gradle、Bazel 和 Cargo 项目使用原生工具。Cargo 对比保留部分编译器覆盖范围,并区分估算的编译器工作量与实际节省的时间。
compare_test_runs 引导你对比两次测试运行以识别回归、新失败和不稳定测试。
compare_bundles 引导你对比两个包以识别整个构件树中的大小变化。
compare_test_case 引导你对比测试用例在两个分支或时间段内的行为。
compare_generations 引导你对比两次生成运行以识别性能回归和模块缓存变化。
compare_cache_runs 引导你对比两次缓存运行以识别缓存有效性变化和目标级回归。
integrate_gradle_project 引导你将 Tuist 集成到现有的 Gradle 项目中。包括独立的工具和 Gradle 身份验证、账户发现、项目创建、远程缓存策略、构建洞察以及回读验证。
integrate_bazel_project 引导你创建或选择 Bazel 项目、对命令行进行身份验证、配置远程缓存和构建洞察,并通过 Tuist 构建数据验证集成。
integrate_xcode_project 引导你将 Tuist 集成到现有的 Xcode 项目中。支持 Xcode 缓存、构建洞察、测试洞察和测试分片。
ask_tuist 使用公开材料作为上下文,并以聚焦的实现和测试证据作为当前行为的真实来源来回答 Tuist 相关问题。它需要 question 并引用修订版固定的证据。

项目数据提示接受 account_handle 和 project_handle 以将调查范围限定到特定项目。比较提示还接受 base 和 head 参数以指定要比较的两个项目(通过 ID、仪表板 URL 或分支名称)。ask_tuist 接受 question 而非项目参数。integrate_gradle_project 还接受 features,即要应用的 Gradle 集成的逗号分隔列表:remote_cache、build_insights、test_insights、flaky_tests 和 test_sharding。integrate_bazel_project 接受可选的 server_url 用于自托管或本地安装。integrate_xcode_project 接受包含 xcode_cache、build_insights、test_insights 和 test_sharding 的 features。

Gradle 集成提示功能#

integrate_gradle_project 提示和 get_gradle_integration_guide 工具记录了完整的设置工作流。服务器的初始化说明中也引用了该工具,这使得不枚举提示的代理也能发现它。

功能 代理配置的内容
remote_cache 启用 Gradle 的构建缓存,配置 Tuist 远程缓存上传策略,并建议仅从具有本地只读使用权的持续集成 runner 进行上传。
build_insights 应用 Tuist Gradle 插件,并在需要时配置构建分析上传行为。
test_insights 应用 Tuist Gradle 插件,以便自动上传 Gradle Test 任务结果。
flaky_tests 引导设置不稳定测试检测、可选的 Gradle Test Retry 插件用法以及测试隔离配置。
test_sharding 添加用于 tuistPrepareTestShards、分片矩阵生成和基于 TUIST_SHARD_INDEX 的测试执行的持续集成工作流。

当省略 features 时,提示会要求代理澄清用户想要哪些集成,或在编辑 Gradle 项目之前从请求中推断出最小的有用集合。

Xcode 集成提示功能#

integrate_xcode_project 提示记录了 Tuist 支持的每种 Xcode 集成:

功能 代理配置的内容
xcode_cache 配置 tuist setup cache、生成项目的缓存设置、手动 Xcode 缓存构建设置,以及仅限于持续集成 runner 的上传策略。
build_insights 通过 tuist setup insights 配置 tuist inspect build、tuist xcodebuild、-resultBundlePath 以及可选的机器指标。
test_insights 配置 tuist inspect test、方案测试后操作以及持续集成测试运行的结果包生成。
test_sharding 添加带有 TUIST_SHARD_INDEX 的 Xcode 或生成项目的分片规划和分片执行工作流。

当省略 features 时,提示会要求代理澄清用户想要哪些集成,或在编辑 Xcode 项目之前从请求中推断出最小的有用集合。