Depot (depot.dev)

depot-mcp：Depot（depot.dev）的 MCP 服务

一个 Model Context Protocol 服务，默认只读，面向 Depot，这项容器构建和 CI 加速服务。它能为编码 Agent 提供 Depot 对“CI 为什么失败了？”和“这次构建为什么失败了？”的答案，以及这些答案背后的运行历史、缓存效果、注册表内容、CI 配置和使用数据。

社区项目，与 Depot 无关联，未获其认可或支持。 源代码可用，采用 Apache 2.0 许可证并附加 Commons Clause；详见许可证。

请勿与以下内容混淆： Home Depot、Chromium 的 depot_tools、Steam depot、Perforce depot 或任何其他“depot”。此服务仅与 api.depot.dev 通信。

目录

• 为何创建此项目
• 状态
• 先决条件
  • 不同令牌的权限
• 安装
• 兼容性
• 获取方式
• 配置
• 工具
• 只读模式与安全性
• 限制
• 架构
• 故障排除
• 开发
• 贡献
• 路线图
• 许可证

为何创建此项目

Depot 已经提供了不错的 Agent 体验，但并非通过 MCP 实现。Depot 提供的方案是 Agent Skills：通过 SKILL.md 文件教 Agent 使用 depot CLI，并提供文档完善的 CI API 和 llms.txt。Depot 发布 Skills 的文章提到了两项限制：技能在实现了 SKILL.md 约定的客户端中效果最佳，而且“有时 Agent 不会自动使用技能”。

此服务弥补了由此留下的空缺：

• 没有 shell 的 Agent。 使用技能需要机器上安装并登录 depot 二进制文件，而调用工具不需要。
• 不会读取 SKILL.md 的客户端。 MCP 与客户端无关。
• 可靠调用。 注册的工具会通过协议被发现，而不是寄希望于它能被检索到。
• 只读边界。 技能无法阻止 Agent 运行 depot ci rerun。此服务可以做到，也确实会阻止；详见只读模式与安全性。

旗舰工具是对 Depot 已有功能的一层精简而谨慎的封装：GetFailureDiagnosis。它在服务端分析失败情况，按根本原因对某次运行中的失败进行归类，并返回诊断结果、建议的修复方法和证据行；结果已控制在适合上下文窗口的范围内。此服务的大部分价值就在于将这项功能提供出来。

与 Depot Agent Skills 的比较

	Depot Agent Skills	depot-mcp
需要安装并登录 depot CLI	是	否
可在不支持 SKILL.md 的客户端中使用	否	是
调用方式	Agent 必须检索技能	工具列在 tools/list 中
能否更改 Depot（重新运行、取消、重置）	可以，CLI 能做的都可以	默认关闭；通过 DEPOT_MCP_ALLOW_WRITES 选择启用写入工具，每项操作前都会先试运行；删除操作还需通过第二个标志启用；不支持重置
输出是否限制在上下文窗口范围内	取决于 CLI 命令	所有工具均有限制
维护方	Depot	社区

截至 2026-09-05，尚无独立的 Depot MCP 服务（无论是官方还是其他来源，都未见于官方注册表、npm 或 PyPI）；而 Depot 对无法访问 shell 的 Agent 的建议，是直接调用 CI API。此服务封装了该 API 调用，专为 Agent 使用而设计。

状态

• 默认只读。 未设置 DEPOT_MCP_ALLOW_WRITES 时，不会注册任何可更改内容的工具。设置后会添加十个写入工具；每项操作都会先试运行，并在执行任何写入前拒绝不安全的请求：取消运行或工作流、取消作业、重试失败的作业、重试单个作业、重新运行工作流、分派工作流（可通过 DEPOT_MCP_DISPATCH_ALLOWLIST 限制）、设置或删除 CI 变量、创建项目、更新项目；详见写入工具。停止或终止沙箱还需要启用 beta 标志；删除项目则还需额外设置 DEPOT_MCP_ALLOW_DESTRUCTIVE；详见破坏性写入。没有重置、写入密钥或生成令牌的工具。
• 根据 Depot 自身文档，Depot CI 仍处于 beta 阶段。 这里最有价值的工具是 CI 工具，同时它们也最可能发生变化。
• 四个 beta 工具需选择启用。 设置 DEPOT_MCP_ENABLE_BETA=1 后，会添加 Depot 沙箱（depot.sandbox.v1）和 Depot 注册表（depot.registry.v1beta1）的只读工具。这些 API 仅以 protos 形式发布，其中一个的名称中带有 beta，因此除非主动启用，否则这些工具会保持隐藏；详见 Beta。
• 已在真实的 Depot 组织中验证。 所有读取工具、提示词和资源都使用组织、用户和项目令牌进行了实时测试；所有写入工具都进行了实时试运行，除两个沙箱工具外，其他写入工具均已于 2026-09-08 在试验组织中实际执行（npm run verify:apply），包括分派、项目更新和项目删除。沙箱停止和终止操作已纳入验证脚本，但仅进行了试运行，因为试验组织中没有可停止的沙箱。
• MCP 协议修订版 2025-11-25。 此服务基于 @modelcontextprotocol/sdk 1.x 系列构建，使用 2025-11-25 版本。当前规范修订版为 2026-07-28，由 v2 包（@modelcontextprotocol/server 2.0.0，发布于 2026-07-28）实现，同时也支持 2025-11-25 客户端。目前所有客户端都会协商使用 2025-11-25，因此现阶段没有任何功能损失。迁移到 v2 已列入计划，范围明确：SDK 在九个文件中导入，传输层接线位于 src/index.ts。

前置条件

• Node.js 20 或更高版本（node --version）。Docker 镜像无需在主机上安装 Node。
• Depot 组织令牌。 在 Depot 控制面板的 Organization Settings → API Tokens 中获取。depot login 使用的用户令牌也可用，但它涵盖你所属的所有组织，因此还需设置 DEPOT_ORG_ID。
• 项目令牌不可用。 根据 Depot 自身的权限范围矩阵，项目令牌无法用于 Depot CI，也无法用于该 API。

哪种令牌能做什么

Depot 有三种令牌，彼此不能互换。已于 2026-09-06 实时验证，包括使用属于组织所有者的用户令牌进行验证：

工具组	组织令牌	用户令牌
depot_whoami	是	是
Depot CI：depot_diagnose_ci_failure、depot_list_ci_runs、depot_get_ci_run、depot_get_ci_job、depot_get_ci_attempt、depot_list_ci_workflows、depot_get_ci_workflow、depot_wait_for_ci_run、depot_get_ci_logs、depot_get_ci_job_summary、depot_get_ci_metrics、depot_list_ci_artifacts、depot_get_ci_artifact_url、depot_compare_ci_runs	是	是
depot_list_ci_secrets、depot_list_ci_variables	是	仅限管理员和所有者
depot_list_images	是	是
depot_list_projects、depot_get_project、depot_audit_trust_policies、depot_list_project_tokens、depot_list_builds、depot_get_build、depot_diagnose_build、depot_get_usage、depot_list_project_usage、depot_get_cache_summary	是	否：无论用户角色如何，Depot 都会返回 401 Invalid token
Beta：depot_list_sandboxes、depot_get_sandbox、depot_list_registry_repositories、depot_get_registry_image	是	尚未测试
项目令牌	无法运行任何工具

docs/tokens.md 中列出了完整矩阵，按工具和 Depot 服务分类，并说明了如何获取每种令牌。depot_whoami 会报告其持有的令牌类型，并列出无法使用的工具。

为此服务创建专用令牌，以便单独撤销。Depot 没有只读令牌作用域；请先阅读安全性部分，再将令牌粘贴到任何地方。

安装

下面的每种客户端都会通过 stdio 运行相同的命令。唯一不同的是配置文件所在位置，以及客户端如何让你避免将令牌保存在文件中。

以下通用配置可直接用于 Claude Desktop、Cursor、Windsurf、Cline、JetBrains 和大多数其他客户端：

{
  "mcpServers": {
    "depot": {
      "command": "npx",
      "args": ["-y", "depot-mcp"],
      "env": {
        "DEPOT_TOKEN": "YOUR_DEPOT_TOKEN"
      }
    }
  }
}

如果你的令牌可以访问多个组织，请在 env 中添加 "DEPOT_ORG_ID": "..."。每个工具都以 depot_ 为前缀，工具名称在各版本之间保持稳定。

Claude Code

claude mcp add depot --scope user --env DEPOT_TOKEN=YOUR_DEPOT_TOKEN -- npx -y depot-mcp

你也可以在仓库根目录提交 .mcp.json，供整个团队使用。Claude Code 会在 command、args、env、url 和 headers 中展开 ${VAR} 和 ${VAR:-default}，因此令牌会保留在每位开发者的 shell 环境中，而不会进入 git。复制 .mcp.json.example：

{
  "mcpServers": {
    "depot": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "depot-mcp"],
      "env": {
        "DEPOT_TOKEN": "${DEPOT_TOKEN}",
        "DEPOT_ORG_ID": "${DEPOT_ORG_ID:-}"
      }
    }
  }
}

无论 readOnlyHint 的值是什么，Claude Code 每次调用 MCP 工具时都会提示确认。若不想再收到提示，请在 .claude/settings.json 中允许只读工具："permissions": { "allow": ["mcp__depot__*"] }。

Claude Desktop

有两种方式。

扩展包（一键安装）。 从发布页面下载 depot-mcp.mcpb，用 Claude Desktop 打开（或依次选择 Settings、Extensions、Advanced settings、Install extension），然后在设置表单中粘贴令牌。manifest.json 中的令牌字段标记为敏感信息，因此 Claude Desktop 会将其存储在操作系统密钥链中，而不是 JSON 文件中。

手动配置 JSON。 在 macOS 上编辑 ~/Library/Application Support/Claude/claude_desktop_config.json，或在 Windows 上编辑 %APPDATA%\Claude\claude_desktop_config.json，并添加上面的通用配置。

Cursor

此按钮会预填服务；Cursor 显示配置时，填写 DEPOT_TOKEN。你也可以编辑 ~/.cursor/mcp.json（适用于所有项目）或 .cursor/mcp.json（适用于单个项目）。Cursor 会在 command、args、env、url 和 headers 中解析 ${env:NAME}，因此已提交的项目文件可以从环境中读取令牌：

{
  "mcpServers": {
    "depot": {
      "command": "npx",
      "args": ["-y", "depot-mcp"],
      "env": {
        "DEPOT_TOKEN": "${env:DEPOT_TOKEN}"
      }
    }
  }
}

VS Code 和 GitHub Copilot

这些按钮会注册服务并提示输入一次令牌，然后将其保存为 VS Code 密钥。等效的 .vscode/mcp.json（可安全提交：令牌是输入项，而不是值）：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "depot-token",
      "description": "Depot Organization token",
      "password": true
    }
  ],
  "servers": {
    "depot": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "depot-mcp"],
      "env": {
        "DEPOT_TOKEN": "${input:depot-token}"
      }
    }
  }
}

也可以在终端中运行：code --add-mcp '{"name":"depot","command":"npx","args":["-y","depot-mcp"],"env":{"DEPOT_TOKEN":"YOUR_DEPOT_TOKEN"}}'。VS Code 中的 Copilot Chat 会使用 mcp.json 中的配置；用户级配置文件可通过“MCP: Open User Configuration”打开。

GitHub Copilot 编码 Agent

Repository Settings，Copilot，Coding agent，MCP configuration。密钥必须是名称以 COPILOT_MCP_ 开头的 Copilot 环境密钥：

{
  "mcpServers": {
    "depot": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "depot-mcp"],
      "env": {
        "DEPOT_TOKEN": "$COPILOT_MCP_DEPOT_TOKEN"
      },
      "tools": ["*"]
    }
  }
}

OpenAI Codex CLI

codex mcp add depot --env DEPOT_TOKEN=YOUR_DEPOT_TOKEN -- npx -y depot-mcp

也可以在 ~/.codex/config.toml 中配置。env_vars 会从 shell 转发指定变量，因此无需将令牌写入文件：

[mcp_servers.depot]
command = "npx"
args = ["-y", "depot-mcp"]
env_vars = ["DEPOT_TOKEN", "DEPOT_ORG_ID"]

Gemini CLI

gemini mcp add -e DEPOT_TOKEN=YOUR_DEPOT_TOKEN depot npx -y depot-mcp

也可以在 ~/.gemini/settings.json 中配置。Gemini CLI 会展开 env 中的 $VAR 和 ${VAR}：

{
  "mcpServers": {
    "depot": {
      "command": "npx",
      "args": ["-y", "depot-mcp"],
      "env": {
        "DEPOT_TOKEN": "$DEPOT_TOKEN"
      }
    }
  }
}

Windsurf

使用 ~/.codeium/windsurf/mcp_config.json，或前往 Windsurf Settings，Cascade，MCP Servers，Manage。使用上面的通用配置。

Zed

settings.json：

{
  "context_servers": {
    "depot": {
      "command": "npx",
      "args": ["-y", "depot-mcp"],
      "env": {
        "DEPOT_TOKEN": "YOUR_DEPOT_TOKEN"
      }
    }
  }
}

Cline

打开 Cline 面板，选择 MCP Servers，Configure（CLI 可使用 ~/.cline/mcp.json）。通用配置可用；Cline 还支持在每个服务中设置 "disabled": false 和 "autoApprove": ["depot_whoami", "depot_diagnose_ci_failure"]。

JetBrains AI Assistant

依次打开 Settings，Tools，AI Assistant，Model Context Protocol (MCP)，Add，然后粘贴通用配置的 JSON。如果已配置 Claude Desktop，可选择“Import from Claude”导入配置。

Docker

主机上无需安装 Node.js。该镜像使用 stdio，因此必须使用 -i，且不能使用 -t。请从环境传入令牌，而不要在命令行中传入：

docker build -t depot-mcp .
export DEPOT_TOKEN=YOUR_DEPOT_TOKEN
docker run -i --rm -e DEPOT_TOKEN -e DEPOT_ORG_ID depot-mcp

镜像的客户端配置：

{
  "mcpServers": {
    "depot": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "DEPOT_TOKEN", "depot-mcp"],
      "env": {
        "DEPOT_TOKEN": "YOUR_DEPOT_TOKEN"
      }
    }
  }
}

计划发布镜像 ghcr.io/akshayjain3450/depot-mcp 和 Docker MCP Catalog 条目；请参阅获取方式。

从克隆版本运行

npm 发布之前即可使用：

git clone https://github.com/akshayjain3450/depot-mcp.git
cd depot-mcp
npm install
npm run build

然后将上面任意配置块中的 "command": "npx", "args": ["-y", "depot-mcp"] 替换为 "command": "node", "args": ["/absolute/path/to/depot-mcp/dist/index.js"]。Claude Code 配置：

claude mcp add depot --env DEPOT_TOKEN=YOUR_DEPOT_TOKEN -- node /absolute/path/to/depot-mcp/dist/index.js

验证是否正常工作

npx @modelcontextprotocol/inspector npx -y depot-mcp      # or: node dist/index.js

然后，在你的 Agent 中让它调用 depot_whoami。这会确认令牌，报告它可以访问哪些组织和项目，并提醒你注意 Configuration 中所述的组织歧义。

无需令牌，二进制文件也能响应以下两个标志：

npx depot-mcp --version   # prints the version from package.json
npx depot-mcp --help      # usage, environment variables, exit codes

导入软件包（import { createServer } from 'depot-mcp'）会提供服务工厂，但不会启动任何内容；只有 depot-mcp 二进制文件会打开 stdio。

兼容性

该服务仅支持 stdio。任何可以启动本地进程并使用 MCP 2025-11-25 通信（或协商降级至该版本）的客户端都可以使用。“已测试”表示维护者使用真实令牌进行了端到端测试；“已验证”表示已根据供应商在 2026-09-05 发布的文档检查配置格式，但未实际运行。

客户端	传输方式	状态	备注
MCP Inspector	stdio	已测试	npm run inspect
CI stdio 冒烟测试（initialize + tools/list）	stdio	已测试	每次提交都会运行，使用 Node 20 和 22
Claude Code	stdio	已验证	.mcp.json 中的 ${VAR} 展开；除非加入允许列表，否则每次调用都会提示
Claude Desktop	stdio、.mcpb	已验证	自动批准时会遵循 readOnlyHint
Cursor	stdio	已验证	${env:VAR}；一键深层链接
VS Code / Copilot Chat	stdio	已验证	inputs 可避免将令牌写入文件；一键链接
GitHub Copilot 编码 Agent	stdio（type: local）	已验证	密钥必须使用 COPILOT_MCP_ 前缀
OpenAI Codex CLI	stdio	已验证	env_vars 会从 Shell 转发变量
Gemini CLI	stdio	已验证	env 中的 $VAR 展开
Windsurf	stdio	已验证	通用配置
Zed	stdio	已验证	context_servers 键
Cline	stdio	已验证	可为每个工具设置 autoApprove
JetBrains AI Assistant	stdio	已验证	可以导入 Claude Desktop 配置
Docker（任意客户端）	通过 docker run -i 使用 stdio	已验证	镜像在 CI 中构建；运行时使用 distroless
Streamable HTTP / 远程	不提供		令牌会离开本机；请参阅 Security

如果你在未列出的环境中运行它，请提交 issue，并注明客户端名称和可用的配置。

获取方式

按实用性排序的计划发布渠道。标记为待处理的项目需要先发布到 npm。

渠道	标识符	状态
npm	depot-mcp	待处理（release.yml 会在 v* 标签上发布并附带来源证明）
Official MCP Registry	io.github.akshayjain3450/depot-mcp (server.json)	待处理；npm 发布后运行 mcp-publisher publish
Claude Desktop 扩展	GitHub releases 上的 depot-mcp.mcpb（manifest.json）	待处理
Docker MCP Catalog	向 docker/mcp-registry 提交 PR，添加指向此仓库 Dockerfile 的 server.yaml	待处理
GitHub Container Registry	ghcr.io/akshayjain3450/depot-mcp	待处理
Smithery	仅收录；Smithery 于 2025 年 9 月停止托管 stdio 服务，而本服务按设计仅支持 stdio	待处理
Glama、PulseMCP、awesome-mcp-servers	目录收录	待处理

切勿在 @depot/* 或 dev.depot/* 下查找；这些命名空间属于 Depot，而本项目并非由他们开发。

配置

每项设置都是环境变量，在客户端的配置中设置。

变量	必需	默认值	用途
DEPOT_TOKEN	是		Depot API 令牌。必须是单行可打印 ASCII；如果从自动换行的终端复制时带有换行符，启动时会拒绝该令牌，且不会回显其值。没有该令牌，服务将拒绝启动（退出代码为 78）。
DEPOT_ORG_ID	否		作为 x-depot-org 发送。如果你的令牌可以访问多个组织，请设置此项（见下文）。
DEPOT_PROJECT_ID	否		默认的容器构建项目，因此调用构建工具时可以不指定项目。
DEPOT_API_URL	否	https://api.depot.dev	覆盖 API 端点。必须使用 https://；仅在 localhost 上允许使用普通的 http://，用于连接存根服务。
DEPOT_MCP_MAX_LOG_PAGES	否	20	每次工具调用获取的日志／步骤页面上限，避免单次调用遍历数 GB 的日志。
DEPOT_MCP_OUTPUT_BUDGET	否	24000	任意单个工具结果的字符数硬上限。
DEPOT_MCP_ENABLE_BETA	否	0	同时注册用于 Depot 沙盒和 Depot 注册表的四个只读测试版工具。默认关闭，因为 Depot API 可能会在不另行通知的情况下发生变化。depot_whoami 会报告该功能是否启用。
DEPOT_MCP_ALLOW_WRITES	否	0	为未来版本预留；目前不起作用。 该开关为将来添加修改型工具预留，届时无需重新调整注册逻辑。v1 中未定义此类工具，因此设置此项不会有任何变化；depot_whoami 会说明这一点。
DEPOT_MCP_ALLOW_WRITES	否	0	设置为 1，以注册五个 Depot CI 写入工具。未设置时，这些工具根本不会注册，因此 tools/list 不会显示它们。所有写入操作默认使用 dryRun: true；depot_whoami 会报告已注册的写入工具。
DEPOT_MCP_ALLOW_WRITES	否	0	设置为 1，以注册写入工具。所有工具默认使用 dryRun: true；未启用此标志的客户端不会看到这些工具。stderr 上的启动行和 depot_whoami 都会说明写入功能是否已启用。
DEPOT_MCP_DISPATCH_ALLOWLIST	否		以逗号分隔的 owner/name:workflow.yml 条目，指定 depot_dispatch_ci_workflow 可以启动的工作流，例如 acme/api:deploy.yml,acme/api:nightly.yml。设置此项后，任何不在列表中的工作流分发都会在发出请求前被拒绝；未设置时，令牌可访问的任何仓库都可以分发。仓库名称不区分大小写，工作流文件名则必须完全匹配。条目格式不正确时，服务会在启动时停止。
DEPOT_MCP_ALLOW_DESTRUCTIVE	否	0	与 DEPOT_MCP_ALLOW_WRITES 一同设置为 1，以同时注册不可逆写入操作（depot_delete_project）。单独设置此项不起作用：关闭写入功能的服务绝不会删除内容。每个破坏性工具还需要一个用于指定目标的确认参数。启动行和 depot_whoami 会说明此开关是否已启用。

每次 Depot API 调用的总时限约为 40 秒，并会对 unavailable、deadline_exceeded、aborted 和 429 响应进行次数有限的重试（指数退避）。invalid_argument、not_found、permission_denied 和 failed_precondition 永远不会重试。会进行多次调用的工具（例如日志分页、构建诊断）可能因此耗时超过单次时限；如果后续页面超时，工具会报告部分结果，而不会直接失败。

组织相关陷阱

这是 Depot 最容易让人困惑的故障模式，Depot 自己的 Agent Skill 也特别指出了这一点。用户令牌涵盖你所属的所有组织。如果令牌可以访问多个组织，而未设置 DEPOT_ORG_ID，请求会解析到其中一个组织；其他组织中的所有内容都会显示为空，而不是报错。如果列表看起来异常为空，请调用 depot_whoami；它会准确检测到这种情况，并告知你需要设置什么。

工具

所有 28 个常驻工具均以 depot_ 为前缀，命名格式为 depot_<verb>_<noun>，并标注 readOnlyHint: true 和 destructiveHint: false。另有 4 个只读工具由 DEPOT_MCP_ENABLE_BETA 控制（参见 Beta）；10 个可撤销写入工具由 DEPOT_MCP_ALLOW_WRITES 控制（参见 Write tools）；2 个沙盒写入工具须同时启用该标志和 Beta 标志；此外，还有 1 个不可撤销写入工具，须在此基础上启用 DEPOT_MCP_ALLOW_DESTRUCTIVE（参见 Destructive writes）。写入工具会携带 readOnlyHint: false，以及如实设置的 destructiveHint 和 idempotentHint 值。名称保持稳定：重命名或移除都属于破坏性变更，并会按破坏性变更进行版本管理。

诊断（从这里开始）

工具	能解答的问题
depot_diagnose_ci_failure	为什么这次 CI 运行/工作流/作业/尝试失败了？ 汇总聚类后的根本原因、AI 诊断、建议的修复方法和证据行。
depot_diagnose_build	为什么这次容器构建失败了？ 定位失败步骤，返回其错误和日志末尾内容，以及缓存效果。如果步骤输出超过页面上限，则报告 logPageCapHit 和 logNextPageToken。
depot_whoami	我的令牌有效吗？它能查看哪些内容？诊断上述组织不明确的问题，并在 DEPOT_ORG_ID 指向令牌无法查看的组织时发出警告。

Depot CI

工具	用途
depot_list_ci_runs	最近有哪些运行，哪些运行失败？可按状态、仓库、SHA、触发方式和 PR 筛选。
depot_get_ci_run	此次运行的工作流、作业和尝试树是什么，哪个节点出错？
depot_get_ci_job	此作业在多次重试中的情况如何？状态、结论、记录的错误、运行器标签、时间，以及每次尝试的信息（包括其沙盒 ID），按最新优先排列。
depot_get_ci_attempt	某次尝试的记录：状态、结论、错误、沙盒和会话 ID、时间，以及是否为当前尝试。
depot_list_ci_workflows	最近运行了哪些工作流，哪些失败？可按名称、状态、仓库、SHA、触发方式和 PR 筛选；显示每个工作流的作业数量。
depot_get_ci_workflow	某个工作流的执行历史（重新运行和重试）及其作业 → 尝试树。
depot_wait_for_ci_run	完成了吗？轮询 GetRunStatus 以检查 runId，或轮询 GetWorkflow 以检查 workflowId（重新运行或重试后应监视的对象；它们会启动新的执行，而不是新的运行），最长等待 timeoutSeconds（默认值为 120，最大值为 300），直到运行、工作流的最新执行或由 untilJobKey 指定的某个作业进入终止状态；然后报告结果、经过的时间、轮询次数，以及状态发生变化的所有节点。仅进行有界轮询；超时会返回 timedOut: true，Agent 可再次调用。绝不流式传输。
depot_get_ci_logs	获取某次尝试的有界原始日志：默认读取尾部，支持 grep、步骤和流筛选器，以及使用精确游标向前分页。筛选器由此服务在获取日志后执行，因此 grep 仍会读取最多 DEPOT_MCP_MAX_LOG_PAGES 页。达到页面上限而停止遍历时，结果会说明日志仍有后续内容，并提供 pageCapHit 和 nextPageToken 以便继续；绝不会将日志中间部分标记为尾部。每行正文最长为 2000 个字符（bodyTruncated）。
depot_get_ci_job_summary	作业发布了哪些自述信息（相当于 $GITHUB_STEP_SUMMARY）？
depot_get_ci_metrics	是 OOM 终止还是 CPU 资源不足？获取运行、作业或尝试的 CPU／内存数据。
depot_list_ci_artifacts	此次运行上传了哪些内容，其签名下载 URL 是什么？接受 pageToken。
depot_get_ci_artifact_url	根据 ID 获取某个制品的签名下载 URL，并在 URL 包含有效期时返回该信息。此 URL 是短时有效的持有者凭据；结果会说明这一点，且此工具绝不会获取该 URL 的内容。
depot_compare_ci_runs	两次运行之间发生了什么变化？提供按作业键索引的作业矩阵，列出 A 与 B 的状态、耗时和峰值内存变化（来自 GetRunMetrics；Depot 没有样本时留空）、仅在某次运行中出现的作业，以及 B 中新增与已解决的失败错误消息（来自 Depot 的失败分析，仅在运行失败的一侧获取）。可用于比较两个提交之间的回归，并判断失败是偶发还是确定性的。
depot_list_ci_secrets	存在哪些 CI 密钥，它们适用于哪些范围？仅返回名称和适用范围；Depot 绝不会返回密钥值。
depot_list_ci_variables	存在哪些 CI 变量，其值和适用范围是什么？类似凭据的值会被隐藏（见下文）。

容器构建、项目、镜像仓库、用量

工具	可回答的问题
depot_list_builds	最近的容器构建，包括持续时间和缓存命中率。
depot_get_build	单次构建的状态、时间、缓存计数器和命中率，以及 terminal 和 failure 标记。构建失败时会指向 depot_diagnose_build；开销足够低，可用于轮询正在运行的构建。
depot_list_projects	存在哪些构建项目、所在区域、使用的硬件和缓存策略？接受 pageToken。
depot_get_project	单个项目的完整配置及其 OIDC 信任策略。
depot_audit_trust_policies	哪些外部 CI 身份（GitHub 仓库、Buildkite 流水线、CircleCI 或 GitLab 项目）可以在组织范围内构建到哪些项目？传入一个 projectId 可指定单个项目，否则返回前 50 个。没有策略也是正常结果。
depot_list_project_tokens	项目有哪些项目令牌：ID、描述，以及 Depot 提供的时间戳。绝不会返回密钥；Depot 只会在创建时显示一次，而且此服务不会创建令牌。
depot_list_images	此项目的镜像仓库中有哪些内容，包括摘要和大小？
depot_get_usage	哪些因素影响了费用？构建分钟数、缓存节省的分钟数、GitHub Actions 运行器分钟数、存储和沙盒。日期采用 UTC；仅包含日期的 endAt 会包含当天的全部时间。
depot_list_project_usage	某个时间段内每个项目的构建次数、构建时间和层缓存大小，按缓存从大到小排列，并解析项目名称。接受 pageToken。
depot_get_cache_summary	此项目的缓存是否正常工作？包括当前大小对应的保留策略、近期构建的命中率、节省的分钟数，以及相关观察（接近大小上限、命中率低、构建频率低于保留期限）。Depot 无法列出缓存条目，且此服务绝不会重置缓存；该工具会说明这两点。

Beta（选择启用）

仅在设置 DEPOT_MCP_ENABLE_BETA=1 时注册。与其他工具一样，它们均为只读工具，但依赖的 Depot API 仅以 proto 形式发布（depot.sandbox.v1、depot.registry.v1beta1，名称中带有 beta），因此字段名称、状态和分页方式可能会发生变化，且 Depot 不会发布变更日志说明。每个工具的描述都对此有所说明。已于 2026-09-06 使用 Organization 令牌进行在线验证：每个 RPC 均返回了 JSON 绑定结果（试用组织返回空列表，未知 ID 则由 Depot 返回 not_found）。

工具	可回答的问题
depot_list_sandboxes	Depot 中有哪些沙盒、它们处于什么状态、使用什么镜像和资源？可按状态和创建时间筛选；支持令牌分页。环境变量仅返回名称。
depot_get_sandbox	单个沙盒的生命周期时间、退出代码、错误消息、计量的 CPU 和网络用量，以及环境变量名称。绝不返回变量值。
depot_list_registry_repositories	组织的镜像仓库中有哪些仓库、各自大小、最近推送时间，以及是否设有保留策略？按编号分页（page、hasMore）。
depot_get_registry_image	此仓库标签或摘要指向什么？包括摘要、大小、标签、推送时间，以及清单摘要：多平台索引的平台信息，或单个镜像的层数和配置摘要。

有意不提供的功能：创建沙盒、执行命令或更改超时；列出或创建镜像仓库令牌；任何删除操作。停止或终止沙盒属于写入操作，因此只有同时设置 DEPOT_MCP_ALLOW_WRITES 时才会提供 depot_stop_sandbox 和 depot_kill_sandbox；请参阅写入工具（选择启用）。路线图中的第五个 Beta 工具 depot_list_test_results 需要使用 depot CLI，因此尚未构建。

写入工具（选择启用）

仅在设置 DEPOT_MCP_ALLOW_WRITES=1 时注册。不设置此标记时，客户端无法察觉这些工具的存在：它们不会出现在 tools/list 中，调用时会因工具未知而失败。depot_whoami 会报告这些工具是否已注册，并列出其名称。

所有写入工具的工作方式都相同：

1. dryRun 默认为 true。 调用会使用 Depot 的读取 RPC 读取当前状态，并返回变更预览，以及可再次发送的准确参数。
2. 用户确认后，使用 dryRun: false 再次发送。工具会重新读取状态，针对最新状态应用拒绝规则，然后才调用唯一的变更 RPC。Depot 返回的 412 会转换成易读的消息。

每次写入操作都会向 stderr 记录一行：[depot-mcp write] <tool> <ids> <time>，方便操作人员查看 Agent 做了哪些更改。其中不会出现令牌。

工具	Depot RPC	拒绝条件
depot_cancel_ci_run	CancelRun；如果提供了 workflowId，则使用 CancelWorkflow	已处于终态的运行或工作流；不属于指定运行的 workflowId
depot_cancel_ci_job	CancelJob	已处于终态的作业；不属于指定 runId 的作业
depot_retry_ci_failed_jobs	RetryFailedJobs	仍在运行的工作流；没有失败或已取消作业的工作流；包含多个工作流的 runId（请传入 workflowId）；任何重试次数达到 3 次或以上的失败作业，除非 force: true
depot_retry_ci_job	RetryJob	状态不是失败或已取消的作业；重试次数达到 3 次或以上的作业，除非 force: true
depot_rerun_ci_workflow	RerunWorkflow	仍在运行的工作流；包含失败作业的工作流，除非 allowFullRerun: true，因为只重试失败作业更省成本
depot_dispatch_ci_workflow	DispatchWorkflow	设置了 DEPOT_MCP_DISPATCH_ALLOWLIST 时，不在该列表中的仓库和工作流文件；不是 owner/name 格式的 repo；路径而非文件基本名称的 workflow；空 ref；超过 20 个 inputs，或任何值超过 1000 个字符。预览会显示该工作流最近一次运行，并明确提示新运行可能会触发部署或消耗数分钟
depot_set_ci_variable	SetVariableVariant	根据脱敏规则被判定为凭据的值（请使用 Depot secret）；已属于 secret 的名称
depot_delete_ci_variable	DeleteVariableVariant；如果 allVariants: true，则使用 DeleteVariable	选择器匹配到零个或多个变体；未指定 allVariants 时删除整个变量
depot_create_project	CreateProject	重复的项目名称，除非 allowDuplicateName: true；不是 us-east-1 或 eu-central-1 的区域
depot_update_project	UpdateProject	未作任何更改的调用（每个值都等于当前值）；不同于项目自身区域的 regionId，因为 Depot 不会迁移项目；小于 1 的 cacheKeepGb 或 cacheKeepDays。预览会显示差异，并在缓存缩小时警告可能发生驱逐，在硬件变更时警告可能增加成本；同时发送两个缓存数值，因为 Depot 会将省略的数值读取为零
depot_stop_sandbox（还需要 DEPOT_MCP_ENABLE_BETA）	StopSandbox，beta depot.sandbox.v1	已完成、已取消或已失败的沙盒；对于相同情况，Depot 返回的 412 也会转换
depot_kill_sandbox（还需要 DEPOT_MCP_ENABLE_BETA）	KillSandbox，beta depot.sandbox.v1	与停止相同；kill 是强制版本，会使沙盒进入 cancelled 状态

注解：全部十二个工具均设置 readOnlyHint: false；取消操作、变量删除和沙盒 kill 设置 destructiveHint: true；重试、重新运行、调度和项目创建会创建新的尝试、运行或项目，因此设置 idempotentHint: false。 已在线验证的内容。 每个写入工具都已针对真实的 Depot 组织进行过空运行，因此预览流程、所依赖的读取 RPC，以及所有拒绝规则都已测试。除停止和终止沙箱外，所有写入工具的应用流程也都已测试；试用组织没有可供测试的沙箱。npm run verify:apply 会执行这项测试，记录见 docs/verification/apply-0.2.1.md。CI 写入操作的请求字段名称由 Depot 文档说明；变量和项目写入操作的请求字段名称则来自 Depot 开源 CLI 中随附的 v3beta2 绑定以及 depot/proto，因此首次实际应用每项操作时，都应将其视为验证步骤。

破坏性写入（第二道关卡）

有些写入操作无法撤销，而且空运行也无法让误删的内容恢复。这些操作受第二个标志 DEPOT_MCP_ALLOW_DESTRUCTIVE 控制，只有同时设置了 DEPOT_MCP_ALLOW_WRITES 时，该标志才会生效。启用写入但未启用第二个标志时，tools/list 不会显示这些操作，depot_whoami 也会说明破坏性操作关卡已关闭。每项操作还需要一个确认参数，明确指出将被销毁的对象；该参数必须由用户输入，而不能从列表中复制。

工具	Depot RPC	确认方式	拒绝条件
depot_delete_project	DeleteProject	confirmProjectName 必须与项目当前名称完全一致	名称不匹配时，在执行任何变更调用前拒绝；如果项目在过去 24 小时内有过构建，除非设置 force: true，否则拒绝。预览会显示项目、构建次数以及最近一次构建的时间，让用户清楚看到将被删除的内容

注解：destructiveHint: true、idempotentHint: true。删除操作会移除：项目、其层缓存、构建历史、注册表镜像、信任策略和项目令牌。

提示词

七个提示词将工具串联成工作流，否则 Agent 只能逐步自行摸索。每个参数都会被限制为其类型允许包含的字符（仓库限制为 owner/name，ID 限制为字母、数字、.、_、-），并在插入指令前进行 JSON 引号转义，因此恶意参数无法改写指令。

提示词	参数	功能
diagnose-latest-failure	repo?	查找最近一次失败的运行，进行诊断并提出修复建议。
explain-build-slowness	projectId?	结合构建与用量数据，判断原因是缓存未命中还是工作量增加。
triage-failures-today	repo?、hours?（默认 24）	列出时间范围内失败和已取消的运行，按仓库、工作流和失败作业分组；诊断最多 5 个不同分组；生成表格，标明每个分组是重复出现还是新出现，并指出哪些看起来可以安全重试。它绝不会要求 Agent 重试任何内容；此服务无法执行重试。
compare-ci-runs	runA、runB	获取两次运行的树状结构和指标，诊断失败的一侧；报告状态差异、每个作业的耗时和峰值内存变化，以及只出现在其中一次运行中的失败分组。
cache-audit	projectId?	列出项目及其缓存策略、每个项目最近 20 次构建和 30 天的用量；标记命中率低于 50%、冷构建以及保留时间过短的情况。明确说明不提供重置项目缓存的操作。
debug-missing-secret	name、repo、branch?、workflow?	使用范围筛选条件调用 depot_list_ci_secrets 和 depot_list_ci_variables；解释哪种配置适用于该作业，以及它可能无法看到该配置的原因。
watch-run	runId	轮询 depot_get_ci_run，直到运行结束（最多轮询 20 次），然后在失败时进行诊断，或在成功时列出其构件。

资源

四个只读资源通过 URI 暴露相同的数据，适用于通过 @ 提及或资源选择器附加上下文，而非调用工具的客户端。每个资源都会调用相同的 Depot RPC 和解析器，返回 text/plain，遵守 DEPOT_MCP_OUTPUT_BUDGET，并将 Depot 错误转换为易读的 JSON-RPC 错误。这些模板不带列表回调，也没有任何订阅：每次读取都会发起新的请求。

URI	内容
depot://ci/run/{runId}	运行的工作流、作业和尝试树，呈现方式与 depot_get_ci_run 相同（仅来自 GetRunStatus）。
depot://ci/runs/failed	最近失败的 20 次 CI 运行，按时间从新到旧排列。
depot://project/{projectId}/builds	该项目最近的 20 次容器构建及其缓存命中率。
depot://projects	每个项目的区域、硬件和缓存策略。

输出始终有上限

每个工具都会限制自身的输出，并在发生截断时告知 Agent：

• 日志工具会将日志分页读入环形缓冲区并返回末尾部分，因为 GetJobAttemptLogs 按从旧到新的顺序分页，且没有用于获取末尾部分的参数。
• depot_diagnose_ci_failure 会将 Depot 自身的 bounds 对象转换为通俗易懂的说明，并区分Depot 丢弃的内容和此服务丢弃的内容，以免部分诊断被误认为完整诊断。
• 每个结果都遵守 DEPOT_MCP_OUTPUT_BUDGET。

只读模型和安全性

请仔细阅读第一点。

• Depot 没有只读令牌范围。 能调用 ListRuns 的组织令牌也能调用 CancelRun、RerunWorkflow 和 DeleteProject。交给此服务的凭据并不会让它变得安全。此服务的工具注册就是完整的安全边界：默认情况下它是只读的，因为除非设置了 DEPOT_MCP_ALLOW_WRITES，否则不会注册任何会修改数据的工具，而不是因为令牌受到限制。设置该标志后，写入工具 才会启用；每个工具都会先进行试运行，并在调用 Depot 前由服务端拒绝不符合条件的请求，但 dryRun: false 调用确实会更改 Depot。depot_dispatch_ci_workflow 可以启动工作流；如果设置了 DEPOT_MCP_DISPATCH_ALLOWLIST，则会受其限制。仍然没有任何工具可以重置项目、删除映像或密钥，或创建令牌。应将 readOnlyHint 视为给客户端的提示，而非强制措施。
• 不可逆写入还需要通过第二道关卡。 只有同时设置了 DEPOT_MCP_ALLOW_WRITES，DEPOT_MCP_ALLOW_DESTRUCTIVE 才会启用 depot_delete_project；并且只有当 confirmProjectName 与项目当前名称匹配时，该工具才会执行。关闭写入功能也会同时关闭删除功能；参见破坏性写入。
• 某些操作永远不在支持范围内，而非仅仅暂缓支持：ProjectService/ResetProject（会删除所有缓存数据；这种听起来似乎合理的“修复”会造成不可逆、不可见且代价高昂的影响）、CIService/Run（会在你的基础设施上执行任意工作流内容）、令牌和密钥写入（CreateToken 会返回密钥，并将其写入对话记录）、映像和标签删除，以及 ShareBuild（会创建公开 URL，以读取之名暴露数据）。
• 令牌绝不会被记录、回显或写入磁盘。 令牌只从环境变量读取，绝不会输出在错误消息或 depot_whoami 中。传输层和 Depot 自身错误信封中的错误消息在传给模型之前都会清除令牌，以防配置错误的端点回显请求标头。此服务不会读取 ~/.config/depot/depot.yaml，因此不会获取你无意交给它的环境凭据。
• CI 变量值会经过脱敏。 Depot 会在服务端隐藏机密的值，但会原样返回变量值，而变量常被误用作机密存储。名称或内容看起来像凭据的值会被替换为占位符，结果还会报告触发了哪条规则，因此你仍然知道该变量存在。
• 为此服务创建专用的组织令牌，以便可以单独撤销。
• 仅使用 stdio，不开放监听端口。 除了通过 TLS 连接 api.depot.dev 外，令牌不会跨越其他网络边界。
• CI 日志是不可信文本。 日志行、步骤摘要、构件名称、变量值和 Depot 的 AI 诊断均源自仓库内容，因此任何能向 Depot CI 运行的仓库推送内容的人，都可以在其中写入任意文字。此服务只会返回这些内容，不会根据它们采取行动，但你的 Agent 可能会。摘要会用 --- begin untrusted CI content --- 和 --- end untrusted CI content --- 标出这些文本，并将 Depot 的诊断和建议修复标记为未经验证，同时在结构化输出中附带 contentWarning 字段。服务指令会告诉模型将其视为数据，而非命令。
• Depot 会以明文形式存储 CLI 凭据（模式为 0600），不会使用操作系统钥匙串：macOS 上为 ~/Library/Application Support/depot/depot.yaml，Linux 上为 ~/.config/depot/depot.yaml。如果你从这些位置复制令牌，请留意这一点。请注意，CLI 会优先使用已存储的登录信息，而非 DEPOT_TOKEN，因此 CLI 和此服务可能使用的是不同的组织。

不同客户端对这些注解的处理方式有所不同：Claude Desktop 使用 readOnlyHint 进行自动批准；Claude Code 除非工具已加入允许列表，否则每次调用都会提示；Cursor 则使用自己的运行模式。请按照 SECURITY.md 中的说明报告安全问题。

限制

• 任何人都无法通过 Depot 的 API 启动容器构建。 运行构建需要获取 mTLS BuildKit 端点并传输本地构建上下文；depot CLI 内嵌了一个 BuildKit 分支来完成这些操作。这里的构建功能仅用于观测。构建由人工运行 depot build，或由 CI 运行。
• 容器构建步骤通过 Connect 的二进制 protobuf 编码读取，而非 JSON。 Depot 对 GetBuildSteps 的 JSON 绑定在 Depot 端会失败（服务器无法编码自己的响应），因此此服务包含一个小型、无依赖的 protobuf 编解码器，用于处理两个构建步骤 RPC，该编解码器基于 Depot 发布的 build.proto 构建。截至 2026-09-06，GetBuildStepLogs 使用这两种编码时都会返回服务器端 internal error，因此 depot_diagnose_build 会报告失败步骤及其记录的错误，但通常无法提供该步骤的日志行；结果会明确说明这一点，而不会因此失败。
• depot.ci.v1 有参考文档，但没有已发布的 schema。 它既不在 depot/proto 中，也不在 Buf Schema Registry 中。没有可用于生成类型的内容，也无从检查破坏性变更。我们不会声称存在无人发布的契约，而是通过宽容的访问器读取响应，支持 camelCase 或 snake_case，处理 protobuf 将 int64 编码为字符串的情况，并去除枚举名称前缀。字段缺失时会回退为“unknown”，而不是导致崩溃。
• depot_get_ci_metrics 会返回 Depot 的原始文档以及它能识别的字段，因为 Depot 的文档明确说明，这些 RPC 会返回 CPU 和内存摘要，但未公布其字段名称。
• depot.ci.v3beta2 的名称中带有 beta。 密钥和变量工具最容易发生故障。其列表筛选条件没有文档说明，因此筛选在此服务中进行，发送给 Depot 的请求为空。
• 不支持日志流式传输。 Depot 会按令牌和组织限制并发日志流数量；不谨慎的流式传输工具可能耗尽整个组织的额度，包括实际 CI 使用的额度。此服务改为轮询一元 GetJobAttemptLogs，Depot 的文档明确认可这种方式。
• 有意不提供 wait_for_run_to_finish 工具。 长轮询不适合放在工具调用超时范围内。请再次查询状态；Agent 可以跨轮次轮询。

架构

flowchart LR
    Client["MCP client<br/>(Claude Code, Cursor, VS Code, Codex, ...)"]
    Server["depot-mcp<br/>node dist/index.js"]
    API["api.depot.dev<br/>Connect JSON over HTTPS"]

    Client -- "JSON-RPC over stdio<br/>tools, prompts, resources" --> Server
    Server -- "POST /depot.ci.v1.CIService/GetFailureDiagnosis<br/>Authorization: Bearer DEPOT_TOKEN<br/>x-depot-org: DEPOT_ORG_ID" --> API
    API -- "JSON, read through tolerant accessors" --> Server
    Server -- "text summary + structuredContent,<br/>capped by DEPOT_MCP_OUTPUT_BUDGET" --> Client

单个进程、单个凭据、无监听端口、无 protobuf 工具链。Depot 的 Connect 绑定是通过 HTTP POST 传输的纯 JSON，因此客户端是一个带重试机制的 fetch 封装。工具各自位于 src/tools/ 下的模块中；共享辅助模块（budget、redact、resolve、ci-target）让工具保持精简，并使其输出可预测。设计说明、Depot API 调研和既有方案审查见 docs/ 和 research/。

故障排除

症状	原因和解决方法
claude mcp list 显示 Failed to connect，日志中显示 sh: depot-mcp: command not found	你在 depot-mcp 仓库本身内启动了 Claude Code：npx 检测到同名项目后会跳过安装。请从其他目录启动 claude，或将注册项指向 node <clone>/dist/index.js。
服务立即以代码 78 退出	DEPOT_TOKEN 未设置或为空。通常是客户端的 env 块中遗漏了它。
项目、构建或用量工具显示 unauthenticated，而 CI 工具可以正常工作	你使用的是用户令牌。这些服务只接受 Organization 令牌；请参阅哪种令牌可以做什么。
所有列表都是空的，但令牌有效	使用了未设置 DEPOT_ORG_ID 的多组织令牌。调用 depot_whoami，查看它能访问哪些组织。
permission_denied 或 unauthenticated	使用了项目令牌（不受支持）、已撤销的令牌，或错误的组织。depot_whoami 可以区分这些情况。
depot_diagnose_ci_failure 返回 state: empty	此运行没有 Depot 可用于聚类的失败项，或者该 ID 对应的并非失败运行。使用 status: ["failed"] 调用 depot_list_ci_runs 即可找到失败运行。
state: over_limit	目标范围过广。结果会列出 narrowerTargets；请使用工作流或作业 ID 重新调用。
结果显示 truncated: true	这是预期情况。使用结果中的 hint（缩小筛选范围、使用 grep 或 pageToken），或提高 DEPOT_MCP_OUTPUT_BUDGET。
depot_list_sandboxes 或注册表仓库工具未出现在工具列表中	这些工具处于 beta 阶段，默认关闭。请在服务的 env 中设置 DEPOT_MCP_ENABLE_BETA=1；调用 depot_whoami 可确认是否已启用。
客户端显示“response was interrupted”或上下文错误	这是客户端自身的 MCP 输出上限。优先使用诊断工具而非原始日志，减少 tailLines，或使用 grep。
首次运行时 npx 一直卡住	它正在下载软件包。在终端中运行一次 npx -y depot-mcp，然后重启客户端。
客户端中没有任何内容，但 Inspector 可以正常工作	stdout 必须只传输 JSON-RPC。如果你添加了日志，请将其发送到 stderr。
429 resource_exhausted	已达到 Depot 的令牌级或组织级限制。请等待；服务会自动退避并重试。
大约 40 秒后出现 deadline_exceeded	Depot 未能在单次调用的截止时间内响应。请重试；如果问题持续，请缩小请求范围（减少页数，或使用作业而不是运行）。
DEPOT_API_URL must be an https URL	只接受 https:// 端点，但本地 stub 可使用 http://localhost。
写入工具未出现在工具列表中	未设置 DEPOT_MCP_ALLOW_WRITES。这是默认设置；请在客户端的 env 块中将其设为 1，然后重启服务。depot_stop_sandbox 和 depot_kill_sandbox 还需要设置 DEPOT_MCP_ENABLE_BETA=1。
depot_dispatch_ci_workflow 表示工作流不在允许列表中	已设置 DEPOT_MCP_DISPATCH_ALLOWLIST，但其中未列出该 owner/name:workflow.yml。请将其添加到列表中，或取消设置该变量，以允许访问令牌可见的任意仓库。
写入工具未出现在工具列表中	未设置 DEPOT_MCP_ALLOW_WRITES。这是默认设置；请在客户端的 env 块中将其设为 1，然后重启服务。
已启用写入，但仍缺少 depot_delete_project	未设置 DEPOT_MCP_ALLOW_DESTRUCTIVE。该工具需要同时启用两个标志；depot_whoami 会报告破坏性操作开关处于关闭状态。
depot_delete_project 返回 confirmProjectName ... is not this project's current name	确认名称不匹配。请从试运行预览或 depot_get_project 中读取名称，并让用户确认；此检查要求完全匹配。
写入工具返回 Refused ... before calling Depot	对最新读取结果进行前置条件检查时未通过（目标已处于终态、工作流仍在运行、没有失败项或已达到尝试次数上限）。消息会指出具体规则；dryRun: true 可显示当前状态。
服务器启动时会向 stderr 写入一行内容（depot-mcp 0.1.0 ready on stdio ...）；大多数客户端会在其 MCP 日志中显示 stderr。

开发

npm install
npm run typecheck   # tsc --noEmit, strict
npm run lint        # eslint with type-aware rules
npm test            # vitest, no network or Depot account needed
npm run build       # emit dist/
npm run inspect     # build, then open the MCP Inspector
npm run smoke:stdio # handshake + tools/list against dist/, no token needed
DEPOT_MCP_ENABLE_BETA=1 npm run smoke:stdio   # the same with the four beta tools registered

测试通过 SDK 的 InMemoryTransport，让真实的 Client 与真实的 McpServer 通信，并将 fetch 替换为返回 test/fixtures/ 中记录的测试数据。测试会断言完整的往返流程：输入验证、输出架构符合性、注释、字符数限制和错误转换。测试数据涵盖 GetFailureDiagnosis 的全部四种状态（focused_failure、grouped_failures、over_limit、empty）、空结果和 Connect 错误信封。

对自己的 Depot 组织进行实时检查

DEPOT_TOKEN=YOUR_DEPOT_TOKEN npm run smoke

此操作只会执行只读调用，打印找到的内容，并报告哪些检查已通过、失败或跳过。如果你的组织没有失败的运行，它会跳过故障诊断检查；没有此类运行，就无法测试核心工具。

发布前，npm run verify 会使用 .env 中的每种令牌类型运行所有工具、提示词和资源，并打印跨令牌矩阵；docs/verification.md 说明了该矩阵、选择加入的应用运行，以及每个版本发布时由人工执行一次的 Claude Code 会话测试。

目录结构

src/
  index.ts          entrypoint: config, stdio transport
  server.ts         McpServer construction and instructions
  config.ts         environment resolution, fail-fast validation
  prompts.ts        the two chained workflows
  depot/
    client.ts       fetch against Depot's Connect JSON binding, with retry
    api.ts          typed RPC surface
    errors.ts       Connect error codes -> actionable messages
    shape.ts        tolerant accessors for an unpublished schema
  lib/
    tool.ts         registration, validation, error translation in one place
    write.ts        the write pattern: dryRun default, preview, refusal, audit line
    budget.ts       character budgets and truncation
    diagnosis.ts    parsing and shaping the GetFailureDiagnosis document
    ci-tree.ts      run -> workflow -> job -> attempt parsing
    ci-detail.ts    GetJob and GetWorkflow parsing, terminal states, attempt counts
    ci-target.ts    loose identifier resolution
    redact.ts       credential scrubbing
    write.ts        the dryRun / preview / refuse / apply shape of every write tool
    build.ts  project.ts  resolve.ts  time.ts
  tools/            one module per tool group; index.ts holds the write and beta gates
                    (beta.ts lists sandboxes.ts and registry-beta.ts)
  tools/            one module per tool group; index.ts holds the write and destructive gates,
                    writes.ts the gated lists, ci-writes.ts the five CI write tools,
                    projects-admin.ts the project update and delete
test/               vitest: unit, tool round-trips over InMemoryTransport, fixtures
docs/               design notes and distribution details
research/           the API and design research this was built from
.github/            CI, release, smoke and metadata scripts, templates
server.json         MCP Registry entry      manifest.json   Claude Desktop .mcpb manifest
Dockerfile          distroless stdio image  .mcp.json.example  Claude Code project config

research/ 记录了 Depot API、MCP 设计决策以及本实现所遵循的前人成果调查。在进行任何不明显的更改前，建议先阅读。

贡献

请先阅读 CONTRIBUTING.md。简而言之：默认保持只读，所有写入操作都必须经过门控并先执行试运行；不要在任何地方泄露令牌；限制输出大小；通过 MCP 客户端测试框架进行测试；并为提交签署声明（git commit -s）。错误报告和功能请求均有模板；安全问题请通过 SECURITY.md 提交，而不要在问题跟踪器中报告。

许可证

Apache License 2.0，附带 Commons Clause License Condition v1.0。请参阅 LICENSE 和 NOTICE。

简而言之，你可以：

• 在家中或工作场所使用它，包括在商业 CI 流水线和使用 Depot 的付费产品中；
• 修改、分叉和重新分发它，只要同时附上 LICENSE 和 NOTICE 文件；
• 根据相同条款贡献更改。

你不得：

• 出售它、收费提供托管服务，或提供其价值完全或实质上来自此服务功能的付费产品或服务。

由于 Commons Clause，根据 OSI 的定义，这属于可获取源码，而非开源。Apache 2.0 中的其他所有条款（专利授权、无担保、署名）均保持不变。

Depot 是其所有者的商标。本项目与 Depot Technologies Inc. 无关联。