Impreza Host

impreza-mcp

面向 Impreza Host 的 Model Context Protocol 服务。让 AI 编码工具（Claude Code、Cursor、Codex CLI、Continue、Zed，……）无需离开聊天界面，即可将客户构建的应用部署到由 Impreza 管理的 VPS。

当你对加载了此 MCP 服务的 Claude 说“帮我部署这个”时，Claude 会直接调用 impreza_deploy_custom——打包你的 项目、上传并在你的 Impreza VPS 上构建和运行，然后向你返回 URL。

配对本地 CLI

在 clientarea 的 Impreza API → Connect an AI assistant 中生成一次性代码，并选择助手所需的权限。在运行本地 MCP 服务的机器上执行 npx -y impreza-mcp login --code <code-from-clientarea>。代码 10 分钟后过期，且只能使用一次。

CLI 会通过 POST /v1/mcp/pair 兑换代码，不会发送任何现有 API 凭据。它会将返回的密钥、机密、作用域和过期时间保存到 ~/.impreza/credentials.json；代码和机密绝不会输出。POSIX 系统上的目录权限为 0700，文件权限为 0600。Windows 使用受保护的 ACL，仅允许你的账户访问。当未设置任何一个凭据环境变量时，服务会自动读取此文件。显式设置的 IMPREZA_API_KEY 和 IMPREZA_API_SECRET 会一起优先使用；如果环境变量中只设置了部分凭据，则不会使用已保存的对应凭据。

如需使用其他 API 端点，请在配对前设置 IMPREZA_BASE_URL。必须使用 HTTPS；v3 onion 端点要求设置显式的 SOCKS5 代理 IMPREZA_PROXY，且绝不会回退到直连。端点和代理会与凭据一并保存。使用不同的 API URL 时，已保存的凭据将无法使用。配对时绝不会跟随重定向，也不会自动重试代码。

已有的凭据文件绝不会被覆盖。请先在 clientarea 撤销旧的配对密钥，再删除对应文件并重新配对。如果兑换或写入磁盘失败，代码可能已被使用：请先在 clientarea 检查并撤销新密钥，再生成另一组代码。配对后请重启 AI 客户端。

添加已有服务（0.53.0）

• impreza_add_server 可连接客户已有的服务（任意提供商的 Linux 机器，只要有 root 访问权限且可向外发起 HTTPS 连接），并返回一条安装命令，其中包含一个有效期为 10 分钟的一次性令牌。 每个账户的首台外部服务免费，无需套餐，也无需余额；拥有任意一台有效 Impreza VPS 后，账户即可享受 Bundled 套餐（5 台外部服务）。令牌仅显示一次，系统只保存其哈希值：若令牌丢失或过期，请再次调用此工具。未使用的令牌会在过期前占用免费名额；新服务数量也有每日限制。label 为可选纯文本，最多 120 个字符，按 Unicode 码点计数，与 API 的计数方式相同。对于由 Impreza 管理的 VPS，请使用 impreza_install_agent。需要 deploy 作用域。
• start-from-nothing 技能会首先询问客户是否已有服务，并介绍托管连接器的匿名入口：创建账户并读取公开信息（文档搜索、VPS 报价及费用估算、产品、应用、清单检查、域名可用性和价格）。
• 工具标题和描述遵循当前 API 指南：机密值由账户所有者在门户中输入；除非 Agent 被明确要求，否则 VPS 订单不包含 Agent；对保留的存档和受监视的 Git 引用的描述遵循 API 对它们的适用方式。

非 HTTP 端口的入站访问（0.52.0）

• impreza_get_ingress 会读取应用发布的每个非 HTTP 端口允许访问的地址范围 （数据库、游戏服务器、RustDesk 等）。每次部署默认均为开放状态。响应包含修订版本、状态 （open、pending、enforced、带原因的 not_enforced，或带最低 Agent 版本的 agent_update_required），并说明每个端口是开放还是受限，以及对应的来源。需要读取权限范围。
• impreza_set_ingress 会用完整的目标状态替换允许列表：rules 仅列出受限端口，每个端口包含其 IPv4 或 IPv6 CIDR 来源；rules=[] 会重新开放所有端口。限制访问可能会阻断您自己的访问，因此需要设置 confirm: true；开放端口则不需要。请传入读取到的 base_revision；如果版本已过期，则会以 REVISION_CONFLICT 拒绝请求。Agent 会在约一分钟内应用规则。如果无法应用限制，端口将保持开放，状态会显示带原因的 not_enforced，并在应用上触发警报。需要管理权限范围。
• HTTP 和 HTTPS 不在涵盖范围内：它们会经过代理和 Shield。强制执行需要 Agent 0.6.26 或更高版本。

精确充值金额和 API 路径中的 ID 校验（0.51.0）

• 精确充值金额。 impreza_topup 接受精确的十进制金额字符串（例如 "25.50"），并将其原样发送给 API，不会转换为二进制浮点数。仍接受 JSON 数字。包含指数、符号、空格或超过两位小数的字符串会被拒绝。
• 校验 API 路径中的每个 ID。 0.50.0 中针对 deployment_id 的防护现已覆盖此程序包放入 API URL 路径中的所有标识符：任务、备份、VPS、镜像、发票、命令、读取和运行 ID、Agent ID、onion 客户端名称、按域名路由的工具中的域名，以及用于反向 DNS 的专用 IP。任何会添加或更改路径段的值（.、..、/、\、%、空白字符或控制字符）都会在请求离开进程前被拒绝。有效 ID 仍会像以前一样原样发送。

保护应用、让部署 ID 更安全并默认下单裸 VPS（0.50.0）

• 以引导式提示词保护应用。 prompts/list 新增了 impreza_protect_app。从你正在运行的某个应用开始，它会引导助手在你拥有的另一国家的服务器上建立冷备：与用户一起选择目标、创建冷备（使用 impreza_deploy_catalog_app 并设置 standby: true）、配对并运行首次恢复演练，每一步都需要单独获得用户明确确认。演练验证通过后，它会报告测得的副本时效和演练时长；这些是测量结果，并非对 RPO 或 RTO 的保证。它绝不会购买服务器、提升冷备、切换流量或更改 DNS；目前支持经过审查的故障转移应用（Memos 0.31.0 和 Uptime Kuma 2.5.5）。和所有提示词一样，它不授予任何权限。
• 服务器位置： impreza_list_servers 会在结构化输出中返回每台服务器的 failover_location：country_code、country_basis（verified、operator_verified 或 declared；你为外部服务器声明的国家/地区未经 Impreza 验证）以及 country_notice。
• 部署 ID 不能新增路径段。 如果 deployment_id 会在 API URL 中新增或更改路径段（.、..、/、\、%、空白字符或控制字符），则会在任何请求离开进程前拒绝该 ID。有效 ID 仍会像以前一样原样发送。
• 通过 API 下单的 VPS 默认是裸机。 impreza_order_vps 和 impreza_vps_offer 现在会说明 API 的实际行为：如果不传 app，VPS 创建时会设置 app: "none"（裸操作系统，不含 Agent）。如果客户希望 VPS 可部署应用，请显式传入 app: "@agent"；或者之后在获得客户确认后提供 impreza_install_agent。下单后，轮询 impreza_list_services；impreza_list_servers 只会列出已安装 Agent 的服务器。
• 直接依赖项版本精确固定。 软件包将直接运行时依赖项固定为经过测试的确切版本（参见依赖项版本）。

安装 Agent、在聊天之外输入密钥并保护自定义应用（0.49.0）

• impreza_install_agent 仅在客户明确同意后，才会在尚未安装 Impreza Agent 的受管 VPS 上提供安装服务：首次调用不会安装任何内容，而是返回一个短时有效的 confirm_token；使用相同参数和该令牌再次调用后，才会开始安装。impreza_get_agent_install 会说明 VPS 是否符合安装条件，并跟踪安装进度，直到 Agent 上线。
• 密钥绝不会经过聊天传递。 impreza_prepare_secret_entry 会为现有应用或变量组的密钥变量生成一个有效期为十分钟、只能使用一次的门户链接；账户所有者打开链接、登录并在门户中输入值。impreza_get_secret_entry 只会报告 pending、stored、expired 或 cancelled，绝不会返回密钥值或其哈希。工具现在会拒绝参数中的密钥值（密码、Git 令牌、onion 私钥、构建密钥），并引导用户使用门户；REST API 保持不变。
• 自定义项目的司法辖区故障转移： impreza_deploy_custom 接受 standby: true，可在另一台服务器上创建冷备，使用的来源与主实例相同且已固定（镜像摘要、精确的 Git 提交，或冻结的 Compose 上传）。项目必须声明所有持久化卷；自定义应用对只有在演练验证通过后才会切换。

部署进度与 Agent 重启

Compose 审核和部署接受 context_id，用于指定一个保留的上传，其中包含本地构建上下文和运行时 env_file、配置或密钥。审核和部署时必须提供相同的上下文。运行时文件需要 agent 0.6.11+ 并支持 compose-source-files-v1。

自定义 Node 服务／静态部署 接受 node_package_manager，例如 [email protected] 或 [email protected]，必须与项目的确切 packageManager 和已提交的锁文件匹配。npm 项目请省略。支持独立版 pnpm 10–12 和 Yarn 4 项目，且不得将此字段与 npm_workspace 一起使用。检查会推断此版本固定信息，并在已保存的计划中保留。支持的输入和限制请参阅部署文档。

从 impreza_list_deployments 读取 last_operation.progress，查看最近报告的步骤和时间戳。Agent 0.6.6+ 会在发送最终结果前保存结果；重启后会重新发送相同的回执，不会重复部署。 Agent 0.6.7+ 可以验证已完成的准备检查点，并在不重放部署的情况下恢复先前配置（recovery=reconciling）。请等待终态失败或确认取消后再重试。 recovery=required 表示无法验证自动协调；请联系支持人员。繁忙的构建、缺失的检查点和替换状态不确定时都会保持阻止状态。长时间运行的构建可在 Agent 退出后继续。进度不是实时百分比，也不能证明当前运行时健康状况。现有 Agent 会在下一次部署前显式更新。请参阅部署进度。

取消部署

使用 impreza_cancel_deployment，并提供部署 ID 和准确的 last_operation.command_id。需要管理权限。排队中的取消会立即生效；正在运行的准备操作需要 agent 0.6.5+。在服务器管理员于受支持的 Ubuntu 24.04 amd64 主机上启用受控构建后，Agent 0.6.12+ 可以中断其拥有的构建。其他准备操作会等待当前步骤完成。只有在确认清理完成且配置已恢复后，才能确认取消。requested 不等于 cancelled。替换／恢复操作不能取消。取消跟踪 Task 是单独的操作。 请阅读取消指南。

运行时健康状况与部署操作

impreza_list_deployments 会分别返回 runtime 和 last_operation。 构建失败后，先前的应用仍可能处于健康状态。请读取运行时状态、观测时间和原因；过时或缺失的读数仍属未知。 没有经过确认的健康检查时，运行中不代表健康。观测功能需要 agent 0.6.4+，且不会验证外部 HTTP/DNS/TLS。现有服务器会显式更新。请参阅运行时健康状况。

已保存的项目计划与安全重试

impreza_plan_project 还支持使用 git_url 和准确的 40 字符 git_commit 代替 context_id。 可选的 git_username 和 git_token 仅用于获取代码。服务 会捕获并保留不可变的归档，计入其上传配额，并在返回归档 SHA256 的同时 返回 source.origin。在准备／应用已保存的配置前，请先检查这些值。仅支持通过 443 端口访问公共网络的 HTTPS；不允许重定向和子模块。检查时不会执行项目代码。 这些选项需要相应的控制平面功能；使用前请更新本地 MCP 软件包。

使用带有保留的 context_id 的 impreza_plan_project 检查归档 清单和选定的配置文件。根据需要选择 project_dir、 dockerfile_path、Python start_command 或 php_document_root。检查分析结果和 analysis.deployment_options。

对于 MCP 0.32.0+，调用 impreza_prepare_project_deployment，并传入 plan_id、从 0 开始的 option_index、应用名称、服务 和运行时设置。此操作会验证并保存生效的配置，但不会创建应用、作业或 DNS 记录。检查返回的配置，然后仅使用 execution_id 和 configuration_digest 调用 impreza_apply_project_deployment。之后表单／请求中的更改无法覆盖该记录。

重复提交同一已保存的部署时，会返回其原始受理回执，即使该回执已过期或应用已被移除也一样。回执、应用和队列作业会一并提交。响应结果不确定时，请使用相同的 ID 和摘要重试，而不要另行准备部署。受理表示任务已加入队列；请检查应用状态、 日志和运行状况。此操作不会重启失败的作业，也不会更新现有应用。

impreza_list_prepared_deployments 会列出最新的 20 个已保存配置，或 检索指定的 execution_id。环境变量值在准备记录中经过加密，不会出现在审核响应中，并会在受理时从该记录中清除； 之后应用会使用常规环境变量存储。审核结果会显示变量名称。 最多可使用 100 个字符串值，且不得覆盖系统／路由变量。

每个账户最多有 20 条待处理记录；记录的有效期不超过源计划的有效期， 且最长为 24 小时。首次应用前会重新检查源、规则、目标可用性／IP 和生效设置。不会预留域名、端口或容量，也不提供依赖项锁定或构建保证。DNS 独立于应用事务处理， 中断的尝试之后 DNS 记录可能仍会保留。过期的待处理记录会在账户下一次准备部署时移除；已受理的回执会保留。

MCP 0.31.0+ 仍可进行源检查。较早的 impreza_deploy_project_plan 会直接根据某个选项创建应用，且不具备幂等性。创建计划需要部署权限范围；列出计划需要读取权限范围； 准备／应用需要部署权限范围。这些账户级工具需要不受资源限制的凭据。仅为使用此流程无需更新 Agent；食谱要求仍然适用。请参阅 项目计划与审核指南。

保留的源代码上传

使用 impreza_upload_context，并提供 dir 和可选的 label，即可上传不可变的源代码版本，而无需部署。响应中包含其 context_id、SHA256、大小和过期时间。使用 impreza_list_contexts 列出或检查版本。

使用 impreza_deploy_custom、mode: "dockerfile" 和 context_id 创建应用（也可以直接部署本地 dir）。使用 impreza_redeploy_deployment 重新构建，也可以选择另一个保留的 context_id。应用身份、域名、主机端口、卷和构建配方保持不变。发生故障或回滚后，所选源代码可能与正在运行的发布版本不同；请检查部署历史记录。

正在使用的源代码会一直保留。未被引用的版本会在上传或上次部署请求 7 天后过期，而不是在取消关联 7 天后过期。默认配额为 10 个未过期或被引用的归档、每个账户 300 MiB、每个归档 100 MiB；被引用的源代码也计入配额。经客户确认后，使用 impreza_delete_context、context_id 和 confirm: true 删除未使用的版本。元数据需要读取权限，上传需要部署权限，删除需要管理权限。资源范围受限的凭据无法管理账户上传内容。

打包器会排除常见的依赖项和 VCS 文件夹、.env 和 .env.*（示例文件、样例文件和模板文件除外）、.npmrc 以及 .pypirc。它不会扫描任意机密，也不会解析 .gitignore/.dockerignore；请检查上传内容。Portal 归档会原样发送。旧版 REST 上传仍为临时上传，除非选择启用 retain=true。较早上传源代码的应用可在重新部署时选择新的保留上下文来迁移。这些 MCP 工具要求版本为 0.22.0+；无需仅为保留源代码而更新 Agent。请参阅源代码上传指南。

Node.js npm 构建

无需仓库 Dockerfile，即可使用 impreza_deploy_custom 部署独立的 npm HTTP 应用，并提供 mode: "dockerfile"、build_strategy: "node_npm"、git_url（或本地 dir）以及 target_port（通常为 3000）。API 会生成 Node 24 配方：执行 npm ci、可选的构建脚本、生产环境精简，并以非 root 用户运行 npm start。所选项目文件夹必须包含 package.json、package-lock.json 和生产环境启动脚本。服务器必须安装 Docker Compose 2.17+ 和 BuildKit。使用 npm_workspace 显式选择 npm 工作区。使用 build_secrets 配置具名凭据，并使用 npmrc 密钥进行私有 npm 安装；这需要 agent 0.6.11+。应用必须监听 0.0.0.0 和配置的端口。运行时 PORT 应与该端口保持一致。

Git 重新部署和预览会重复使用配方快照。保留的上传源代码支持重复使用和选择源代码版本；较早的临时上传只能使用一次。配方会在源代码副本中排除 .git、node_modules、.env、.env.* 和 .npmrc；但这不会扫描任意机密。请勿将凭据放入源代码。HTTP 启动探测会接受 / 路径上低于 500 的响应，但这并非应用功能测试。

公开构建变量

必须健康启动：将 require_healthy_start=true、明确的 healthcheck_path 和 build_strategy=node_npm 设为启用状态。在门户中启用「要求健康启动」。Servers 中必须显示 Agent 0.6.3 或更新版本；请明确更新它，并等待下一次心跳。startup_timeout_seconds 接受 30 到 600 之间的整数，默认值为 60。计时预算从容器创建后开始，并包含稳定健康状态的观测；Git 获取、依赖项／镜像构建和恢复各有独立的时限。每个运行中的服务都必须报告 Docker healthy，并且至少有一个容器正在提供服务。HTTP 重定向、身份验证错误和超时均无法通过配置的 2xx 探测。首次安装失败时，其容器会被移除，持久卷则会保留；失败信息中会包含诊断日志。如果可用，失败的替换部署会恢复到已验证健康的上一版本。恢复和手动回滚使用已保存版本的启动策略，因此，健康启动较慢的版本会保留其原始截止时间。失败恢复不会撤销数据库写入或可变数据。控制平面会在创建时拒绝不兼容的 Agent；如果当前轮询不支持 startup-health-v1，则绝不会下发此策略；只有收到匹配的健康确认，才会接受成功结果。预览会继承此策略；重新部署会保留快照。部署读取会公开 startup_health。如需更改已保存的策略，请创建新的部署。省略此选项或将其设为 false 会保留旧行为；启动超时要求启用此选项。此公共选项适用于生成的 Node 构建。此功能不提供零停机切换，也不提供启动后的持续自动回滚。本地 MCP 输入支持需要 0.20.0+。只有客户运行更新程序后，现有 Agent 才会更新。请参阅 https://docs.imprezahost.com/tutorials/agent-apps-panels.html#required-startup

Node 健康检查：使用 build_strategy=node_npm 时，可选设置 healthcheck_path（例如 /health 或 /api/ready），或在门户中填写「健康检查路径」。生成的 Docker 健康检查会在容器内向 127.0.0.1 的 target_port 发送 HTTP GET 请求，并要求状态码为 200-299；它不会跟随重定向，也不会发送凭据。路由必须无需登录即可访问，并且应报告应用处理请求所需的依赖项。使用 / 或长度不超过 200 个 ASCII 字符的路径；各段必须以字母、数字、下划线或连字符开头，之后可包含点或波浪号。允许末尾带斜杠。URL、查询字符串、片段、百分号转义、空格、父级路径段和重复斜杠都会被拒绝。省略该字段（在门户中留空）即可保留接受低于 500 状态码的旧版 / 探测；显式设置 / 则要求 2xx。现有部署快照不会更改。部署读取会返回已保存的 healthcheck_path；新预览会继承该路径，重新部署时也会保留；如需更改，必须创建新的部署。静态网站仍使用其 index.html 探测；自定义 Dockerfile 会定义自己的 HEALTHCHECK。探测每 5 秒运行一次，请求超时时间为 2 秒。禁用必需的启动健康检查时，0.6.2 及更高版本的 Agent 最多会观测启动状态 60 秒：如果存在已验证健康的上一版本，失败的替换部署会恢复到该版本。如果没有可恢复的版本，首次安装仍可能带有启动警告而完成，因此在将其视为就绪之前，请检查健康状态和日志。此默认策略不提供持续回滚、零停机路由或外部运行时间检查。如需强制执行启动截止时间，请启用必需的健康启动，并使用 Agent 0.6.3+。本地 MCP 输入需要 0.19.0+；仅设置 healthcheck_path 时，Agent 不需要更新到高于 0.6.2 的版本。 公共构建设置：生成的 node_npm 和 node_npm_static 配方接受 public_build_vars，这是一个字符串值对象，仅供 npm run build 使用（包括其 prebuild/postbuild 脚本）。例如，{"VITE_API_URL":"https://api.example.com"} 可让 Vite 将公开的 API URL 编译到网站中。名称必须以 VITE_、NEXT_PUBLIC_ 或 PUBLIC_ 开头，只能包含大写字母、数字和下划线，且长度不得超过 128 个字符。限制：最多 20 项，每个值不超过 4096 个 UTF-8 字节，名称和值合计不超过 16384 字节。空字符串会保留；不接受 NUL。值会作为字面数据处理，不进行 shell 或变量展开。门户会将 Public build variables 显示为 KEY=value 行；不要添加成对引号，否则引号会成为值的一部分。这些值是公开的，可能出现在构建包、镜像元数据和日志中：切勿发送密码、令牌或密钥。它们不会传递给 npm ci，也不会自动添加到运行时变量中。运行时变量仍用于配置正在运行的容器，且不会改写已编译的浏览器文件。设置会在创建时保存，在部署读取中公开，由新预览继承，并在重新部署时复用。预览运行时的继承或覆盖不会更改此构建快照；如需使用不同的公共构建值，请创建单独的部署。现有快照默认不含公共构建值。对于受支持的构建凭据，请使用 agent 0.6.11+ 中的 build_secrets；不受支持的构建设置需要使用自定义 Dockerfile。本地 MCP 需要 0.18.0+；除现有构建执行器外，无需更新 Agent。

请参阅构建配置指南。

项目子文件夹中的应用

从子文件夹部署独立的 npm 应用：使用 node_npm 或 node_npm_static 设置 project_dir（默认为 .），或在门户中选择 Project folder。例如，apps/site 必须包含自己的 package.json 和与之匹配的 package-lock.json；static_output_dir 相对于该文件夹。只有所选文件夹会复制到 /app 中，用于 npm 安装和构建。仓库或上传内容仍是 Docker 构建上下文，因此根目录中的 .dockerignore 仍会生效。路径最多可有 120 个字符和五个非隐藏层级；不接受父目录、node_modules 和符号链接路径组件。文件夹不存在或构建失败时，会保留之前正常运行的运行时。project_dir 值会在部署读取中返回，在创建时保存，并由新预览继承；重新部署会复用已保存的配方。现有快照默认使用 .；更改文件夹需要创建新部署。此功能支持在同一仓库中部署独立应用，不支持共享工作区或文件夹外部的依赖；这些情况请使用自定义 Dockerfile。分析器不会发现子文件夹：请提供所选应用的元数据，并自行检查 Project folder。本地 MCP 需要 0.17.0+；除现有构建执行器外，无需升级 Agent。

请参阅项目文件夹指南。

导入 Compose 堆栈

使用 impreza_prepare_compose 和 compose_yaml，然后明确选择 web_service 和整数 target_port。部署前，请使用 impreza_deploy_custom 并设置 mode: "compose"，提供相同的 YAML/服务/端口，并将 compose_review_id 设为返回的 analysis_id。

支持最多包含 12 个服务的自包含公共镜像堆栈、私有桥接网络、本地命名卷和服务依赖项。原有主机端口绑定会被移除；只有选定的 HTTP 服务会加入代理，并获得受管的环回端口。容器和卷的名称会变为部署专用名称。在 YAML 中为每个服务声明 CPU/内存限制。

审查不会拉取镜像、执行代码或预留资源。本地构建上下文和辅助文件在审查和部署时必须使用相同且保留的 context_id。运行时 env_file 仅接受字面赋值，不支持插值或继承裸键。别名、配置文件、主机权限和外部资源不属于此导入范围。请引用大写变量，而不要嵌入机密信息。运行时值必须是单行字符串，长度不超过 4 KiB，且不得包含首尾空白、引号、反斜杠、美元符号或空格后跟 #。变量用于提供明确的引用，而不是提供每个服务的全部环境变量。创建、编辑和重新部署时都会检查必需值。

导入的源会保存为清单。重新部署会复用该清单和命名数据；更改源/拓扑需要新建部署。故障恢复使用现有 Agent 策略，且不会撤销数据库写入。本地 MCP 对公共镜像堆栈的支持需要 0.21.0+。保留的构建/运行时源需要 MCP 0.34.0+ 和 agent 0.6.11+。 请参阅 Compose 导入指南。

准备项目配置

部署前，请使用 impreza_prepare_project，并提供 package_json、dockerfile 和可选的 dockerfile_path。它会返回框架提示、可用的构建和启动命令、最终 Dockerfile 阶段中的显式端口，以及供审查的发现项。每个文件不得超过 32 KiB。发送前请检查文件中是否包含凭据；切勿提交 .env 文件或机密信息。

这是对所提供文本的建议性分析。它不会获取代码仓库、执行代码、生成 Dockerfile 或部署资源。Git 部署默认使用 Dockerfile；受支持的 npm 项目可以选择 Node 配方。分析 ID 标识元数据，而非可执行计划。 需要提供 /v1/platform/deployments/custom/prepare 的 API。

为什么选择这个服务，而不是主流服务商

任何服务商都能运行你的应用。这个服务专为以下场景打造：让 Agent 能够获取并操作不绑定你身份的基础设施，端到端完成操作，无需你打开浏览器：

• 开设账户无需 KYC，也无需电子邮件地址。 账户由生成的客户端 ID 和恢复令牌组成。无需文件、自拍或电话号码。
• 使用加密货币充值。 impreza_topup 接受 BTC、XMR、USDT 和 TRX，impreza_order_vps 会使用该余额购买服务端。Agent 无需银行卡，就能从“我需要一台服务端”开始，直到部署运行。
• 离岸和境内司法管辖区并列提供，按项目选择，而非按账户选择。
• Tor 是部署目标，而非附加功能。 impreza_add_onion 只需一次调用，就能为部署提供 .onion 地址，让 Agent 发布隐藏服务，就像发布普通网站一样。impreza_onion_auth_* 用于管理 Tor v3 限制发现（客户端授权）：私钥绝不会离开客户的 Tor 客户端，除非客户要求服务端生成密钥对——此时私钥只会显示一次，绝不会存储。
• 配置中无需 API 密钥。 托管连接器通过 OAuth 进行身份验证。

如果这些对你的项目都不重要，主流服务商完全是不错的选择，而且通常起步成本更低。这个服务适用于确实需要这些特性的项目：承受压力的研究与新闻报道、规避审查、安全工作，以及任何不应因为一张支持工单就与法定姓名关联起来的项目。

保留版本回滚

源代码树新增了 impreza_rollback_deployment。通过 impreza_api_call 在 /platform/deployments/{id} 读取部署的 release_history，然后选择一个 rollback_supported: true 的 rel_... 条目。

调用工具前，先向客户说明所选版本及可能造成的中断，并传入 deployment_id、target_version 和 confirm: true。 托管连接器则使用双调用的 confirm_token 流程。 此操作需要 manage 范围以及兼容的 API 和 Agent。

历史版本可能已不再保留。Agent 会检查本地镜像，并确认端口、存储和路由未发生变化，然后再替换容器。如果所选版本启动失败，Agent 会保存当前正常运行的环境并尝试恢复。数据库内容和可变数据不会回滚。排队响应不代表已确认恢复；请检查部署历史以查看结果。

此功能从 impreza-mcp 0.12.0 起提供。需要兼容的 API 和 Agent。

静态 npm 站点

静态 npm 站点：选择 build_strategy=node_npm_static，并使用 Git/上下文源（mode=dockerfile）；或在门户中选择 Static site + npm。所选项目文件夹中必须有独立的 npm 包、匹配的 package-lock.json，以及一个能在所选输出文件夹中生成 index.html 的构建脚本。Node 24 会安装依赖并运行构建；非特权 Nginx 仅提供所选输出文件夹中的内容，并支持可配置的 SPA 回退。无需 start 脚本。默认 target_port 为 8080。需要 Compose 2.17+ 和 BuildKit。不支持 SSR 或服务器函数。支持显式设置 npm_workspace 和 build_secrets，但须满足其文档中说明的源和 Agent 要求。运行时变量（包括 VITE_* 和 PORT）不会重写静态包，也不会更改已配置的 Nginx 端口。使用 static_output_dir（默认值为 dist）选择包含 index.html 的相对输出文件夹，并使用 static_spa（布尔值，默认值为 true）选择 SPA 回退，或对未知路由返回 404。门户会显示这两个字段。路径最多 120 个字符、五个层级，且不能包含隐藏目录、父目录或 node_modules；如果输出目录或其父路径中存在符号链接，则会拒绝处理。这些设置在创建时选定、保存在配方快照中、作为 static_options 显示，并沿用至新的预览。重新部署会复用已保存的配方；要更改现有部署的这些设置，必须创建新部署。现有快照会保留原有配方。本地 MCP 选项输入需要 0.16.0+。支持的公共设置请使用 public_build_vars；其他构建时配置需要自定义 Dockerfile。源文件中的 .env/.env.*/.npmrc/.git/node_modules 均会被排除；由于输出文件夹是公开的，请检查所有生成的文件。缺少 index.html 或输出目录中存在符号链接都会导致构建失败。现有预览/重新部署快照会保留原有策略。本地 MCP 需要 0.15.0+；除现有构建执行器外，无需升级 Agent。分析器会返回 static_npm_recipe 和有条件返回的 deployment_options；元数据并不能证明构建是静态且可正常运行的。

状态

软件包版本：0.55.1。 工具目录涵盖应用部署，以及账户和加密货币余额、目录和订购、域名/DNS 和注册、发票、带快照和备份的 VPS 生命周期、专用/裸机服务器、套餐升级，以及 Titan / Google Workspace 邮箱——还提供设置向导，可为 5 种 AI 工具生成可直接粘贴的配置片段。

此外，还涵盖应用运行后所需的一切：备份并恢复至客户自己的 S3 存储桶、为应用设置定时任务并保留其输出、使用出站 Webhook 来替代轮询、读取应用自身的文件，以及运行应用自身的命令行。

本地（npx）服务和托管 OAuth 连接器提供相同的工具目录——本地软件包中有 219 个工具。仍存在已明确声明的单向差异：impreza_get_log_request 仅托管版支持（只有控制平面能够解析裸 request_id；本地可在应用上再次调用 impreza_tail_logs，重复请求会合并）；impreza_list_approvals、impreza_get_approval 和 impreza_get_credential_policy 优先由托管版支持（本地可通过 impreza_api_call 发起相同的 REST 调用）；impreza_upload_context 仅本地版支持（二进制 tarball 流式传输不适用于托管传输）。

0.11.0 中的新内容

运行应用自带的命令行。 WordPress 的 WP-CLI、Nextcloud 的 occ、Gitea 的 gitea admin，以及用于导出数据的数据库客户端——使用 impreza_app_cli 运行，使用 impreza_get_cli_run 收集输出。首次调用 impreza_get_cli_run 时不传入 run_id：它会列出应用提供的命令行、说明各自的用途，并提供一个可用示例。

• 不需要 docker socket，而且这一点有实际验证，不只是口头保证。 命令会在一个独立容器中运行，该容器由应用自身的镜像构建、加入应用自身的网络，并挂载应用的数据——这正是官方 CLI 镜像的设计方式。设置 cap_drop: ALL，不会为机器新增任何权限。
• 参数是列表，绝不是字符串。 每个元素都会通过 execve 成为一个 argv 条目，因此不会发生拆分、通配或替换：你无需操心引号，值中的 $ 或 ; 也只是普通字符。已在运行中的站点上验证——option update blogname 'dollars $HOME and a ; semicolon' 读回的内容与发送的内容完全一致。
• 具有破坏性，因此按此对待。 命令行能执行应用本身能做的任何操作，因此需要 manage 权限范围，并且必须经过确认。参数不受限制，而非采用允许列表：其权限上限与已有的带 purge_data 的 uninstall 相同；而列出一系列 wp 子命令很快就会过时，却无法提供确认机制之外的任何保护。
• CLI 版本与应用保持一致。 如果命令行来自应用自身的镜像，就会从该部署中获取；因此目录版本升级时，命令行也会随之更新——在较新的数据库上运行旧版 Nextcloud 的 occ，正是维护命令导致安装损坏的原因。

此处不支持自定义部署的命令行：镜像由你自行提供，平台无法知道其中包含什么。对于这类部署，请使用类型为 command 的计划任务。

0.10.0 中的新内容

查看应用自身的文件。 impreza_get_logs 会读取 stdout，但它无法回答部署启动异常时真正会遇到的问题：那个变量有没有写入配置文件？现在有两个工具可以做到——使用 impreza_inspect_app 提出查询，再使用 impreza_get_app_read 获取结果。

• 只有四种操作，没有第五种： 对目录执行 list，读取文件（上限为 256 KB），读取文件末尾的若干行，或使用扩展正则表达式在路径下执行 grep。接口中没有命令字符串，因此也没有 shell。
• 设计上只读。 一次性容器会以只读方式挂载应用的存储——使用与现有备份相同的机制——不需要 docker socket，也没有写入能力。因此，即使应用处于 failed 状态、无法启动时也能使用；而这正是最需要它的时候。
• 仅限应用自身的存储： data，或应用清单中声明的命名卷之一（WordPress 会公开 data 和 wp_db，因此也可以读取其数据库文件）。不传入 read_id 调用 impreza_get_app_read，即可查看指定应用的列表。
• 返回的内容不可信，而且往往包含机密信息——应用的配置文件中就存有数据库密码。内容只会传给你，不会传给其他人：该字段已列入我们的请求日志排除列表，记录会在一天内删除。

自 0.6.1 以来

npm 页面从未介绍过的三个版本，每个版本都带来一项完整功能：

• 0.7.0 — 备份和恢复部署数据，将其备份到帐户自己的 Impreza S3 存储桶中，并在数据旁附上逐块 SHA-256 清单。这样，客户可以使用自己的凭据验证副本，无需联系我们。此外还支持计划任务（默认每天执行，保留 3 份备份），并可将备份恢复到不同的应用中，这也是应用在服务器之间迁移的方式。
• **0.8.0 — 计划任务：**在应用上设置定时器并保留输出，适用于需要计划任务才能正常运行的应用（例如 Nextcloud 的 cron，以及没有访客的网站上的 WordPress wp-cron）。
• **0.9.0 — 出站 Webhook：**订阅部署、备份和 VPS 事件，免去轮询；支持 HMAC 签名投递和投递日志。

0.6.1 新增内容

**tools/list 现在会反映帐户实际拥有的内容。**大约三分之一的工具只有在你拥有对应的机器时才有意义——没有 VPS 时，VPS 电源控制工具只会返回“未找到”——因此，在你拥有机器之前，这些工具不会显示在列表中。典型帐户现在会看到约 70 个工具，而不是 97 个，这意味着在你提出任何问题之前，大约可以少消耗 6,000 个上下文令牌。

关于其行为，有三点值得了解：

• **购买相关工具永远不会被过滤。**一无所有的帐户正是需要购买的帐户，因此下单、充值、发票和目录始终会列出。
• **购买后，列表会在会话期间更新。**服务会在下单的同一响应中发送 notifications/tools/list_changed，因此支持此通知的客户端无需重新连接，就能获取新工具。
• **出现故障时会默认放行。**如果此服务无法连接 API 并发起查询，就会列出所有工具，而不是自行猜测。

隐藏工具并不构成授权边界——对于帐户无权拥有的内容，API 仍会拒绝请求。这只是为了避免列表包含对你而言永远无法使用的工具。

0.6.0 新增内容

专为匿名性打造的主机上才有意义的四项功能：

• 暗网预览——推送一个分支，即可在专属的临时 Tor .onion 地址上查看预览。其他所有平台的预览 URL 都会将分支名称暴露在公共 DNS 中，并写入永久的 Certificate Transparency 日志；而分支名称中可能包含工单 ID、客户名称和未发布的功能。本功能不会留下这两类记录，并会在分支删除或 TTL 到期时销毁密钥。impreza_configure_previews、impreza_list_previews、impreza_retire_preview。
• Agent 子凭据——从你持有的凭据派生权限更窄的凭据，并交给子任务使用：一个部署、一个小时、不能消费。子级在任何权限维度上都不能超出父级；撤销某个凭据时，也会撤销它派生的所有凭据，无论层级有多深。impreza_mint_subcredential、impreza_list_credentials、impreza_revoke_credential、impreza_agent_activity。
• 可供核查的隐私报告——impreza_privacy_report 会返回我们存储的所有帐户字段、字段用途、保留时长及可查看这些字段的其他人员，然后根据实际存留的最早记录，衡量我们自身的数据保留情况。只提供数量和日期范围，绝不提供内容。
• 先询问，再猜测——搜索我们的文档、在部署前验证部署清单（包括检查第三方 CDN、公共 DNS 解析器和泄露的密钥等隐私问题），或在出现问题时运行诊断。impreza_search_docs、impreza_validate_manifest、impreza_doctor。

此外还包括 Tasks 扩展，让长时间运行的操作能够报告完成状态，而不必让你持续轮询；以及三个 MCP Apps 面板——支付卡片、服务器卡片和部署向导——可在支持它们的客户端中渲染。

下表是部分精选内容，并非完整列表——其中列出了大多数人最先会用到的工具。客户端自己的工具列表才是权威来源；未在此处列出的工具，可以通过 impreza_api_search 查找。

工具	封装的接口
应用与部署
impreza_list_servers	GET /v1/platform/servers
impreza_list_apps	GET /v1/platform/apps
impreza_list_deployments	GET /v1/platform/deployments + /custom（合并）
impreza_upload_context	POST /v1/platform/deployments/custom/contexts?retain=true
impreza_list_contexts	GET /v1/platform/deployments/custom/contexts[/{context_id}]
impreza_delete_context	DELETE /v1/platform/deployments/custom/contexts/{context_id}
impreza_deploy_custom	POST /v1/platform/deployments/custom（3 种模式）
impreza_deploy_catalog_app	POST /v1/platform/deployments
impreza_uninstall_deployment	POST .../uninstall
impreza_get_logs	POST .../logs（同步读取末尾日志，最后 N 行）
impreza_restart_deployment	POST .../restart
impreza_redeploy_deployment	POST .../custom/{id}/redeploy（原地重建，域名不变）
impreza_add_onion	POST .../onion/add
impreza_set_onion_profile	POST .../onion/profile（standard / hardened / max 安全强化等级）
impreza_export_onion_key	POST .../onion/export（使用你的 X25519 密钥封装；明文不会传输）
impreza_fetch_onion_key_export	GET .../onion/export/{command_id}（仅读取一次——数据块随后即被销毁）
impreza_rotate_onion_key	POST .../onion/rotate（生成新的 .onion 地址；旧地址失效）
impreza_onion_auth_list	GET .../onion/clients
impreza_onion_auth_add	POST .../onion/clients（使用 pubkey，或使用 generate:true → private_key 仅显示一次）
impreza_onion_auth_revoke	DELETE .../onion/clients/{name}
impreza_change_domain	POST .../domain
impreza_git_webhook_status	GET .../custom/{id}/git-webhook
impreza_git_webhook_connect	POST .../custom/{id}/git-webhook/connect
impreza_git_webhook_disconnect	POST .../custom/{id}/git-webhook/disconnect
账户与余额
impreza_account_info	GET /v1/account
impreza_list_services	GET /v1/account/services
impreza_topup	POST /v1/account/topup — 使用 BTC / XMR / USDT / TRX 充值
impreza_topup_status	GET /v1/account/topup/{invoice_id}
impreza_topup_payment	GET /v1/account/topup/{invoice_id}/payment — 加密货币地址和应付金额
目录与订购
impreza_list_products	GET /v1/products — 产品及定价；VPS 按最小规格列出（configurable: true）
impreza_vps_offer	GET /v1/products/vps — VPS 位置、操作系统、CPU / 内存 / 磁盘范围及价格；提供完整配置时，使用 GET /v1/products/vps/quote 查询其准确价格
impreza_order_vps	POST /v1/orders — 按位置、操作系统和规格订购 VPS（或通过 product_id 订购固定套餐）；从余额扣款；默认预装 Impreza Agent（app: "@agent"；对于可配置 VPS 和固定 VPS 套餐，impreza_vps_offer 都会为同一个应用报价，结果中也会回显为 app_requested）；非文本类型的 app 会在发起任何请求前被拒绝；传入 app: "none" 可选择纯操作系统（客户门户默认保留纯操作系统）；之后可在获得客户确认后，通过 impreza_install_agent 添加 Agent；202 并不表示 Agent 已就绪：请轮询 impreza_list_services，待 Agent 安装并连接后，它才会出现在 impreza_list_servers 中
域名与 DNS
impreza_domain_check	GET /v1/domains/check
impreza_domain_details	GET /v1/domains/{domain}
impreza_list_dns	GET /v1/domains/{domain}/dns
impreza_add_dns_record	POST /v1/domains/{domain}/dns
impreza_update_dns_record	PUT /v1/domains/{domain}/dns
impreza_delete_dns_record	DELETE /v1/domains/{domain}/dns
impreza_set_nameservers	PUT /v1/domains/{domain}/nameservers
VPS 生命周期（Proxmox）
impreza_vps_status	GET /v1/vps/proxmox/{id}/status
impreza_vps_power	POST /v1/vps/proxmox/{id}/{start|shutdown|reboot|stop}
impreza_vps_list_backups	GET /v1/vps/proxmox/{id}/backups
impreza_vps_create_backup	POST /v1/vps/proxmox/{id}/backups
impreza_vps_list_templates	GET /v1/vps/proxmox/{id}/templates
impreza_vps_reinstall	POST /v1/vps/proxmox/{id}/reinstall — 有破坏性（会清除数据）
impreza_vps_resize	POST /v1/services/{id}/resize — 按比例计价，增加 vCPU、内存或磁盘容量（先使用 GET /v1/services/{id}/resize/quote 获取报价）；max_amount 可固定金额上限

安装与设置

先决条件

• Node ≥ 20
• Impreza Host 账号及 API 密钥和密钥 （clientarea → API Keys；运行此 MCP 服务的机器的 IP 必须列入该密钥的白名单）

通过 npx 一键运行

无需全局安装——运行 npx impreza-mcp 即可。

或进行全局安装

npm install -g impreza-mcp

获取可直接粘贴的配置片段

最快的方法：直接向二进制文件提问。

npx impreza-mcp setup --tool claude-code
# also: cursor | continue | zed | codex-cli

向导会输出要放入 AI 工具 MCP 配置中的 JSON 代码块、确切的文件路径，以及配置后的操作步骤（通常是“完全退出并重新打开 AI 工具”）。它不会写入磁盘——请自行粘贴，以免意外覆盖已有配置中的其他 MCP 服务。

或手动配置

Claude Code — 添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%/Claude/claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "impreza": {
      "command": "npx",
      "args": ["-y", "impreza-mcp"],
      "env": {
        "IMPREZA_API_KEY": "imp_...",
        "IMPREZA_API_SECRET": "..."
      }
    }
  }
}

重启 Claude Code。工具会显示在 MCP 图标下方。

Cursor — 添加到 ~/.cursor/mcp.json（格式同上）。

Continue — 添加到 ~/.continue/config.json：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "impreza-mcp"],
          "env": {
            "IMPREZA_API_KEY": "imp_...",
            "IMPREZA_API_SECRET": "..."
          }
        }
      }
    ]
  }
}

Zed — 添加到设置中：

{
  "context_servers": {
    "impreza": {
      "command": {
        "path": "npx",
        "args": ["-y", "impreza-mcp"],
        "env": {
          "IMPREZA_API_KEY": "imp_...",
          "IMPREZA_API_SECRET": "..."
        }
      }
    }
  }
}

在聊天中使用

设置完成后，可以直接用自然语言向 AI 提出请求：

“列出我的 Impreza 服务。” → 调用 impreza_list_servers

“将此目录部署到我的 Impreza VPS，并通过 .onion 公开访问。” → 将当前工作目录打包为 Dockerfile 模式的自定义部署，上传并以 onion=true 部署，然后报告 .onion 地址。

“我的 Agent 上运行着哪些应用？” → 调用 impreza_list_deployments，并筛选出对应的服务。

身份验证与安全

IMPREZA_API_KEY 和 IMPREZA_API_SECRET 存放在 AI 工具 MCP 配置的环境变量中——不存放在 impreza-mcp 自身拥有的任何磁盘文件中。 MCP 服务仅在内存中保存密钥，并且只将其作为 HTTP 请求标头附加。

运行此 MCP 服务的机器的 IP（几乎总是你的笔记本电脑）必须列入 API 密钥的白名单。请在 Impreza clientarea 中管理白名单。

通过 Tor 使用

MCP 服务可以通过本地 Tor 守护进程路由每个 API 调用，让 API 请求使用已配置的代理。你的网络服务提供商仍然可以观察到 你与 Tor 的连接；此选项不会隐藏你正在使用 Tor 这一事实。

1. 安装并启动 Tor（tor 守护进程或 Tor Browser——两者 通常都会提供 SOCKS5 监听地址：守护进程为 127.0.0.1:9050， Tor Browser 为 127.0.0.1:9150；请检查本地配置）。

2. 将 IMPREZA_PROXY 添加到 MCP 配置环境变量中：

   "env": {
     "IMPREZA_API_KEY": "imp_...",
     "IMPREZA_API_SECRET": "...",
     "IMPREZA_PROXY": "socks5://127.0.0.1:9050"
   }
   

之后，每个 API 请求都会通过 Tor 发出，API 主机名也由 Tor 自行解析（远程 DNS）——本地不会进行任何解析，因此不会发生 DNS 泄漏。传输采用故障关闭策略：如果代理无法访问或拒绝连接，请求就会失败，绝不会悄悄回退到直接连接明网。

也可以将 IMPREZA_BASE_URL 指向 API 的 .onion 镜像——仅当主机为 v3 .onion 时才接受 http://，因为 Tor 会对 onion 连接进行身份验证和加密。明网主机必须使用 https://。onion URL 还必须显式配置 IMPREZA_PROXY；即使 onion URL 使用 HTTPS，客户端也会拒绝直接 DNS 解析和连接。代理请求会拒绝重定向、使用有上限的请求期限，并接受最大 16 MiB 的响应正文。

账号侧还需调整一项设置：Tor 出口 IP 会不断轮换，因此 API 密钥的固定 IP 白名单无法使用。请在 clientarea 中将密钥的 IP 因子设为 tofu 或 keyonly。

PHP 部署

使用 impreza_prepare_project，并提供 composer_json，还可选择提供 php_document_root，以检查 PHP 应用。使用 Git、本地目录或保留的上传内容，通过 impreza_deploy_custom 部署，并设置 mode: "dockerfile" 和 build_strategy: "php_composer"。PHP 8.4/Apache 配方会根据 composer.json 和匹配的 composer.lock 安装生产依赖，不运行 Composer 脚本或插件，并检查实际的平台要求。为应用选择 project_dir，为包含 index.php 的 public 子目录选择 php_document_root（默认为 public）。Apache 以非 root 用户身份在 target_port 上运行（默认为 8080，最小值为 1024）；它会提供 public 文件，并将缺失路径交给 index.php 处理。

健康检查要求 HTTP 返回 2xx，且不发生重定向；检查路径为 / 或你设置的 healthcheck_path。可选的 require_healthy_start 需要显式指定路径，并要求使用 agent 0.6.3+，启动等待时间为 30–600 秒。预览和重新部署会保留已保存的配方。自定义仓库、私有依赖凭据、安装插件、额外扩展、.htaccess 规则、前端构建以及应用设置/迁移都需要自定义 Dockerfile。start_command 和公开构建变量不是 PHP 选项。分析结果仅供参考，且不会检查锁文件或仓库。请参阅 PHP 部署指南。

Python 部署

使用 impreza_prepare_project，并提供 requirements_txt 和明确的 start_command，以检查 Python 应用。使用 Git、本地目录或上传的上下文，通过 impreza_deploy_custom 部署，并设置 mode: "dockerfile" 和 build_strategy: "python_pip"。Python 3.13 配方会从 PyPI 安装扁平的 requirements.txt，并以非 root 用户身份运行；如果应用位于独立目录，请设置 project_dir。在 target_port 上通过 0.0.0.0 启动生产服务器（默认为 8000），例如 exec gunicorn --bind 0.0.0.0:$PORT app:app，并在 requirements 中声明 Flask 和 gunicorn。PORT 和 HOST 是运行时变量。不要将凭据放入已保存的命令中。

默认的 Python 健康探测要求 / 返回 HTTP 2xx；如需检查其他路由，请设置 healthcheck_path。可选的 require_healthy_start 需要显式指定路径，并要求使用 agent 0.6.3+，启动等待时间为 30–600 秒。预览和重新部署会保留已保存的配方。依赖选项、include、URL、本地项目、私有构建凭据、系统包和其他包管理器都需要自定义 Dockerfile。公开构建变量仍仅适用于 npm。分析结果仅供参考；构建会在服务器上解析实际依赖。请参阅 Python 部署指南。

构建

npm install
npm run build
# dist/server.js is the entry point

受监督的准备工作

除非管理员启用 agent 0.6.12+ 受控构建，否则这些旧版工作进程规则仍然适用。受控构建会为新构建增加经过验证的执行器停止与恢复机制。

agent 0.6.8+：受支持的 Linux/systemd 部署会在单独的受监督进程中运行镜像拉取和构建。如果 agent 重启，它会等待确切的工作进程回执，不会重复执行这些工作。只有持久化的成功回执才允许继续执行现有的准备工作协调流程：重新验证操作/阶段和容器是否未变更、恢复先前的配置，并以失败状态结束或确认先前请求的取消。recovery=reconciling 可能包括等待原始工作进程。缺失/无效的回执、工作进程失败或超时、收到回执前主机重启、旧版未受监督的工作、替换状态不确定、数据所有权以及 onion 准备工作仍需人工审查。进程或服务消失绝不能作为工作已完成的证明。客户必须等待最终结果后再重试；不会增加自动重试部署、立即终止构建、数据回滚或运行时健康保证。

许可证

MIT — 参见 LICENSE。

受监督的替换

Agent 0.6.9+：新的受支持 Linux/systemd 部署会在一个受监督的工作进程中完成获授权的容器替换、启动检查、生命周期钩子、路由和正常启动恢复。如果 Agent 重启，recovery=reconciling 且 step=reconciling_replacement 时会等待原工作进程。该工作进程经过验证的持久化最终回执会被交付，不会重复执行容器操作或钩子；即使部署失败且已恢复到先前版本，也会如此。缺少回执或回执无效、工作进程丢失或超时、完成前主机重启、旧式无监督操作、数据所有权变更以及 onion 配置仍需支持；请保留私有日志，不要通过重试来解除队列阻塞。这不会增加自动部署重试、数据库回滚或零停机流量切换。请在下次部署前显式更新 Agent。

Python 部署可以选择 [email protected]，并使用 python_pip、pyproject.toml 和 uv.lock。在 Python 3.13 上，安装会锁定依赖，仅安装生产环境依赖，且采用非可编辑模式；仅支持公共 PyPI 源。自定义 uv 工作区或索引需要 Dockerfile。需要使用 MCP 0.34.0+，并确保控制平面支持此方案。

PostgreSQL 应用连接

impreza_prepare_service_binding 会审核同一项目环境和服务器中镜像应用所用的专用 PostgreSQL 连接。impreza_prepare_service_binding_removal 会审核移除操作或待清理重试，需使用确切的 deployment_id 和 binding_id。使用 impreza_get_service_binding_plan 读取已保存的计划；只有在明确确认后，才能使用 impreza_apply_service_binding_plan、确切的摘要值和 confirm: true 应用计划。移除操作会保留数据库数据，并且仅在不再使用该连接的替代版本健康后禁用专用登录。接受仅表示已排入队列，不代表已验证完成。需要 Agent 0.6.13+ 和兼容的控制平面。

impreza_prepare_service_binding_rotation 会审核现有连接的凭据轮换，需提供 deployment_id、binding_id 和 mode（rotate 或 abandon）。轮换会将专用登录替换为一个不同的新登录，并且仅在使用轮换后 DATABASE_URL 的替代版本健康后禁用之前的登录；数据库及其数据始终保留。若启动失败，当前凭据仍用于提供服务的先前应用版本，并且需要重新审核后重试；如果无法确认之前的登录已禁用，轮换会保持待清理状态，新的 rotate 审核将重试该操作。abandon 会丢弃未使用的候选凭据并保留当前凭据；如果只剩清理操作，则会拒绝此请求。按上述方式，使用 impreza_apply_service_binding_plan 应用返回的审核结果；准备操作不会将任务排入队列，也不会返回凭据。轮换需要声明支持 postgres-service-binding-rotation-v1 的 Agent：较旧的 Agent 会拒绝派发，失败的任务会提示客户显式更新 Agent，同时保留其身份、配置和应用。轮换需要使用 v2 协议连接；不会接管旧式第一协议连接。

公共 HTTPS 诊断

impreza_probe_deployment 接收 deployment_id，并通过控制平面检查已保存的公共主机名。它会报告公共 DNS 解析、TLS 验证和 HTTPS HEAD 状态，不会跟随重定向或发送应用凭据。它不会读取响应正文，也不会验证依赖项。每个账户每 30 秒可尝试一次；无需更新 Agent。

镜像推广和环境

impreza_prepare_image_promotion、impreza_get_image_promotion 和 impreza_apply_image_promotion 会针对现有目标配置审核确切的注册表摘要。应用推广需要使用审核返回的摘要并进行明确确认。目标变量和数据仅保留在该应用中。

项目／环境工具通过明确的组件关联来整理现有应用。它们不会复制变量、创建网络连接或部署工作负载。请参阅项目环境指南。

经审核的部署工作流

0.38.0 版新增了环境配置比较、准备／读取／应用流量切换，以及可选择密码保护的显式分支预览。比较操作只返回变量名，不返回变量值。流量切换需要经审核的摘要和确认，会保持源端运行；如果无法验证恢复状态，则需要操作员进行协调。受保护的预览凭据仅显示一次。流量切换和受保护的预览需要 0.6.16 或更高版本的 Agent。只有在客户提出请求时，才会更新现有服务器。辅助数据库恢复采用 REST 工作流。请参阅项目环境和部署安全。

基本 Cloud VPS 管理

基本 Cloud VPS 支持通过 impreza_api_call 查看状态和已分配资源，并通过 impreza_cloud_power 启动、正常关机和重启。请使用 impreza_list_services 返回的 WHMCS 服务 ID。高级 Cloud 基础设施工具已不再提供；已退役的调用会返回 FEATURE_NOT_AVAILABLE。如需进行其他基础设施更改，请联系 Impreza 支持。订购和取消仍使用原有的账户工作流。通过已注册 Agent 进行的应用管理是独立功能。

配置、指标和恢复（0.39.0）

使用导出／准备／获取／应用工具审核应用配置；检查每个应用的指标和告警规则；下载备份分片，并审核／应用 PostgreSQL 恢复，将数据恢复到新数据库。应用审核结果需要提供其摘要并进行明确确认；接受操作表示工作已排队，并不代表已确认完成。自定义部署和准备工具也支持 static_files 和 go_build。指标和 MariaDB 绑定需要 0.6.17 或更高版本的 Agent。有关权限、示例和限制，请参阅配置、指标和恢复。不会自动更新服务器。

通过 Tor 隔离运行时（0.42.0）

自定义镜像和源代码部署可通过 impreza_deploy_custom 和已保存的部署准备，以 tor_egress: true 启用此选项。此选项需要声明支持 tor-egress-v1 的 Agent、Docker Engine 28+，以及支持 SOCKS5h 的应用。运行时没有直接出站回退路径。源代码下载、镜像拉取和构建仍使用服务器的常规网络连接。不支持目录安装、导入的清单和外部服务绑定。有关可用性和验证方法，请参阅 Tor 运行时指南。此选项不同于使用 Tor 连接 MCP 客户端本身，也不同于发布入站 onion 地址。

法域故障转移与更安全的读取（0.48.0）

经审核的冷故障转移。 14 个工具可将应用迁移到你拥有的另一台服务器上的冷备用实例，该服务器位于不同国家/地区，并且需要经过你确认的审核流程。已审核的应用包括目录中的 Memos 0.31.0，以及从 0.48.1 起支持的 Uptime Kuma 2.5.5。使用 impreza_deploy_catalog_app 创建备用实例并设置 standby: true，不配置域名或 onion；该实例启动时没有公开路由。然后配对并读取它（impreza_pair_failover_standby、impreza_get_failover_standby）。对于外部服务器，请先使用 impreza_declare_external_failover_country 声明其所在国家/地区（由你声明，而非 Impreza 验证；托管服务器会报告其所在国家/地区）。确认确切的备份/恢复/重新部署流程（impreza_confirm_failover_sync），然后准备、读取并应用审核（impreza_prepare_failover、impreza_get_failover、impreza_apply_failover；如果目标激活需要重试，则使用 impreza_retry_failover_activation）。

故障转移通过验证后，impreza_prepare_failback、impreza_get_failback 和 impreza_apply_failback 会释放旧主机并反转配对关系：旧主实例变为冷备用实例，且不会迁移流量。要将流量迁回，需执行常规备份、恢复、同步确认和经审核的故障转移。impreza_set_failover_drill_policy、impreza_run_failover_drill 和 impreza_get_failover_drill 可按需或每隔 60 到 10080 分钟通过平台运行的冷拷贝刷新备用实例，并记录每个步骤的耗时。

迁移内容：托管区域中的主机名，或通过密封导出流程迁移的公开 onion 地址。不支持自定义域名、私有 onion 服务、数据库绑定和专用服务器。应用操作会停止源实例，并可能中断流量或丢失恢复的备份之后写入的数据：请与用户一起审核源实例、目标实例和备份时间，然后传入准确的 cutover_id（或 failback_id）、review_digest 和 confirm: true。接受操作为异步执行：持续读取审核，直至审核通过验证或报告可采取行动的故障。如果 API 未启用故障转移，这些工具会返回 API 的 404。托管连接器需要使用未受限的账户凭据。指南：法域故障转移。

0.48.0 中的其他更新：

• impreza_vps_resize_recommendation：根据 Agent 报告的持续负载，判断可配置 VPS 是否需要更多 CPU、内存或磁盘空间。
• 除非传入 include_ssh_fingerprints: true，否则 impreza_get_host_inventory 不会返回 SSH 主机密钥指纹。
• API 错误会以包含 code 和 next_steps 的 structuredContent 返回。
• npx -y impreza-mcp login --code <code> 可使用客户端区域提供的一次性代码，将本地服务器与其配对（参见配对本地 CLI）。
• 发布操作手册会使用 impreza_doctor 和 impreza_get_logs 诊断部署失败。

账户概览、操作手册与更安全的操作（0.47.0）

新增 12 个工具和 5 个提示词：

• 账户概览： impreza_get_account_overview 通过一次只读调用，帮助助手了解账户情况：服务器、应用和环境、域名、未处理的警报、近期部署失败情况以及建议的后续操作。仅限访问部分资源的凭据看到的每个部分都会相应过滤。
• 以提示词形式提供操作手册： prompts/list 提供五种引导式流程： impreza_publish_git、impreza_change_domain、 impreza_diagnose_deployment、impreza_restore_backup 和 impreza_update_agent。它们不会授予任何权限；每一步仍需通过工具执行并获得确认。
• 暂停和恢复服务器的 Agent： impreza_pause_agent 会停止派发新命令，并暂停仅限该服务器使用的凭据； impreza_resume_agent 会恢复这些凭据。已派发的任务可能会继续完成。 两者都需要具备管理范围且不受资源限制的凭据，并设置 confirm: true。
• 需人工审批的主机计划： impreza_host_permissions、 impreza_prepare_host_plan、impreza_get_host_plan 和 impreza_apply_host_plan 用于准备 VPS 重装计划。计划运行前，必须由人员在仪表板中审批（确切的服务器、模板、摘要和截止时间）。AI 不能审批自己的计划。
• 零停机重新部署： impreza_get_zero_downtime 会说明应用是否符合条件，以及不符合的所有原因；impreza_set_zero_downtime 会为自定义应用启用此功能并设置就绪检查。需要使用 0.6.27 或更高版本的 Agent。
• 读取： impreza_get_shield（Shield 策略和过去 24 小时的 WAF 检测结果，不包含访客身份）、impreza_privileged_audit（账户特权操作的准入审计）以及 impreza_get_host_inventory（允许列表中的主机信息；需要 0.6.28 版本的 Agent，该版本尚未发布，工具会说明这一点）。
• 结构化输出： 读取工具会声明 outputSchema 并返回 structuredContent；一次性密钥仍保留在文本中，不会出现在结构化结果中。

本地版与托管版功能一致（0.46.0）

本地包现已包含此前只有托管连接器提供的 16 个工具：

• 项目和环境：impreza_rename_project、impreza_delete_project、 impreza_rename_environment 和 impreza_delete_environment；
• 变量组：impreza_get_variable_group 和 impreza_set_variable_group；
• 配置提升：impreza_prepare_config_promotion、 impreza_get_config_promotion 和 impreza_apply_config_promotion；
• 按顺序部署环境：impreza_deploy_environment、 impreza_get_environment_deploy 和 impreza_list_environment_deploys；
• Agent 更新：impreza_get_update_policy、impreza_set_update_policy 和 impreza_request_agent_update；
• Shield：impreza_set_shield。

工具注解（只读、破坏性、幂等）现已与托管连接器保持一致。调用破坏性工具时，如果未提供 confirm 或其值为 false，系统会在发送任何请求前拒绝调用。

PostgreSQL 时间点恢复（0.45.0）

六个工具涵盖状态、配置、恢复演练，以及经审核的 UTC 恢复点的准备、查询和应用：impreza_get_pitr、impreza_configure_pitr、 impreza_drill_pitr、impreza_prepare_pitr_restore、 impreza_get_pitr_restore 和 impreza_apply_pitr_restore。状态查询使用读取范围；更改操作使用部署范围。由于物理 PostgreSQL 恢复可能涉及同一服务提供商上的多个绑定，托管连接器要求凭据不受资源限制。

WAL 和基础备份会占用账户的存储空间。连续失败六次后，自动任务会暂停，直到问题修复并再次保存配置。禁用功能会停止保护，但会保留已存储的对象。恢复操作需要审核摘要和 confirm: true，会创建一个新数据库，绝不会重定向正在运行的应用。请轮询审核结果，直到回执显示 verified 或 failed；仅仅受理并不代表恢复成功。

定时任务（0.45.0）

impreza_create_task 用于在应用上创建定时任务，impreza_update_task 用于修改现有任务（任何未填写的字段都会保留当前值，因此可以通过设置 enabled=false 暂停任务，而不会丢失其计划或历史记录），与托管连接器中的行为一致。它们取代了已移除的 impreza_schedule_task：请更新仍在调用该工具的客户端或提示词。impreza_list_tasks、 impreza_run_task 和 impreza_delete_task 保持不变。

VPS 扩容（0.44.0）

impreza_vps_resize 可为可配置 VPS 增加 vCPU、内存或磁盘容量。请先通过 impreza_api_call 调用 /services/{id}/resize/quote 并将新规格作为 query 传入，以获取报价：它会返回今日应付的按比例计费金额（由计费系统计算）、VPS 续费时的价格，以及余额是否足够。然后使用相同规格调用 impreza_vps_resize，并将 max_amount 设为该 due_today 值，以便在价格期间发生变动时拒绝操作，而不是照常收费。 规格只能增大。磁盘会立即扩容；新的 vCPU 数量和内存将在使用 impreza_vps_power 并设置 action=reboot 重启 VPS 后生效（从服务器内部重启仍会保留旧规格）。请参阅 VPS 扩容。

可配置 VPS（0.43.0）

VPS 是一种可配置产品：可选择位置、操作系统、vCPU、内存和 SSD 磁盘容量。impreza_vps_offer 会按各个计费周期列出所有选项及其单价，价格以账户币种显示；传入完整配置（billing_cycle、location、os、cpu_cores、memory_gb、 disk_gb）后，它会返回确切价格、余额是否足够，以及该位置当前是否有余量。impreza_order_vps 可下单购买该配置，此时不填写 product_id；Tor Hosting 等固定套餐仍通过 product_id 下单。实际收取的价格就是报价。请参阅 订购 VPS。

私有 onion 预览和保留的身份密钥（0.42.0）

创建预览时可设置 private: true；也可以选择提供一个或多个 onion_clients。 提供的审核者需使用名称和 X25519 公钥。如果未提供客户端，则会生成一个审核者密钥对，并且私钥只会显示一次。此模式要求 Agent 0.6.20 及其 onion-private-preview-v1 功能；在首次发布 onion 之前会安装审核者授权。 后续重复部署会保留之后的撤销操作。 请勿将此选项与受密码保护的 HTTPS 预览同时使用。

impreza_purge_onion_key 要求提供确切的旧 onion 地址并明确确认。任务已排队并不能证明删除已完成：请检查其完成后的结果。活动地址会被拒绝。清除操作会移除此服务器上保留的副本；其他位置的导出文件和备份仍会保留。释放未安装应用的预留不会删除密钥材料。

有关权限、客户更新步骤和支持限制，请参阅 onion 指南。

依赖项版本

软件包清单将每个直接运行时依赖项固定为精确版本：@modelcontextprotocol/sdk 1.29.0、 tar 7.5.22 和 zod 3.25.76。源代码构建使用 package-lock.json 锁定经过测试的依赖项树。全新安装到使用方环境时，传递依赖仍可能发生变化；依赖项更新需要重新构建软件包、通过干净安装测试，并在发布前审查已安装的依赖项树。