ImageStep

@imagestep/mcp

面向 Agent 的图像处理流水线：以 MCP 工具形式提供预设 + 资源 + 任务。图像不会进入上下文窗口——每个工具都接收并返回资源引用（ID、尺寸、公开 URL）。

工具	功能
generate	提示词 → 图像；返回资源 ID 和 CDN URL。preset 会通过已保存的预设运行该工具；预设中的 subjects 可让一批图像中的角色或产品保持一致（用 slug@version 固定版本）
transform	单个原子操作——GET /api/v1/ops 中除 generate 外的所有操作；在启动时读取（stdio），或按请求读取（托管模式）；无法访问目录时回退到 edit remove_bg upscale restore_face colorize analyze resize convert compress crop pad grayscale rotate flip flop trim flatten adjust mask blur_region overlay caption render_template read_metadata。render_template 不接收图像——parameters: {templateId, items}，每个项目生成一个 PNG。variants（≤ 20）会在一个任务中对每个变体各运行一次操作，一次调用即可生成适用于所有社交平台尺寸的图像。两种模式，由输入决定——见下文
run_preset	运行已保存的版本化预设——由多个步骤组成的列表，可按 slug 或 slug@version 指定（用于串联操作并保持批次一致）
job_status	返回任务中各项目的进度和输出（analyze 任务会返回 analyses）。写入工具的 wait_seconds 等待时间耗尽时，会返回带有 timedOut: true 的任务句柄——这不是错误：任务会继续运行，已完成的部分会计费，因此应轮询此工具，而不是重新提交。默认只读：传入 publish: true 即可发布输出并获取公开 URL。一个响应最多包含 20 个输出（即 search_assets 的一页）；超出后，outputsTruncated / outputsNote 会提示使用 search_assets {job_id, cursor} 继续读取——publish: true 仍会发布所有输出。项目按页返回（由服务分页）：第一页之后，将 itemsCursor 作为 items_cursor 传回以读取下一页；items_status（FAILED：恢复任务时会重新运行的项目）只读取处于一种状态的项目；chain 项目会包含 step / failedStep
search_assets	按集合、关键词、MIME 类型、尺寸查找资源；也可使用 group_by: "collection" 列出你的集合。每次调用返回一页；将响应中的 nextCursor 作为 cursor 传回即可读取下一页
save_preset	将要再次运行的操作链保存为有名称的版本化预设——仅限 L1 op 步骤，且服务会在存储任何内容前进行检查；返回 slug@version，供 run_preset 固定版本运行
send_feedback	免费报告 ImageStep 无法完成的事项（capability_gap · bug · other），无需自行绕过问题

每个工具都会声明一个 outputSchema：列出它可以在 structuredContent 中返回的键，且这些键均为可选项（实际返回哪些键取决于模式——已完成的任务、等待超时、试运行、同步结果或拒绝请求）。

输入可以是 asset_ids、urls（公开的 http(s) URL，由服务获取并导入——此服务绝不会下载这些内容），或者——当服务通过 stdio 在你的机器上运行时——file_paths。所有会产生费用的工具都有 dry_run（返回精确价格，不创建或上传任何内容——asset_ids 按其本身计价，file_paths / urls 按数量计价），并会返回包含 retryable、param 和服务 requestId 的结构化错误（报告故障时请引用该 ID），因此参数错误会在扣除任何额度之前被拒绝。

写入工具（generate · transform · run_preset · save_preset · send_feedback）接受可选的 idempotency_key。MCP 客户端超时时，Agent 会再次调用该工具；如果键和参数均相同，第二次调用会返回第一次调用的响应——例如它创建的任务或保存的预设——而不是再次提交（并再次计费）。相同的键搭配不同参数时会被拒绝，并返回 idempotency_key_reuse。不提供键时，每次调用都会创建新的提交。 每个工具都带有 MCP 注解，这是客户端用来判断哪些操作需要你确认的提示： job_status 和 search_assets 是 readOnlyHint；写入工具不具备幂等性（除非提供密钥），且没有任何工具带有 destructiveHint：每个作业都会写入新资源，绝不会覆盖它读取的资源。

transform 有两种模式，Agent 无法选择

满足以下所有条件时使用同步模式：恰好一个本地文件或 URL、使用确定性操作，且设置了 wait: true。不会在账户中存储任何内容——之后不存在资源 ID，因为没有创建资源。耗时不到一秒，账户也保持整洁。

结果的去向取决于你使用的是哪个服务，因为两者不共享文件系统：

	返回内容	有效期
stdio（此软件包运行在你的设备上）	path——一个临时文件，文件名采用服务报告的输出名称（convert-<ts>.avif，而非 .bin）	直到服务退出；同一个服务的所有结果都存放在同一个临时目录中
托管服务（https://mcp.imagestep.dev/mcp）	url——带签名的链接，以及 expiresInSeconds	约 5 分钟；请下载文件，或在需要永久 URL 时将任务作为作业运行

两种模式都会返回 mimeType、width 和 height，因此下一个工具不必猜测。托管服务返回 URL，原因显而易见；我们也是遇到一个 bug 后才注意到这一点：你的 Agent 并不运行在服务所在的机器上，因此它无法读取指向该容器 /tmp 的路径。底层使用的是 API 自身的 ?response=url，它会将字节写入一个短期临时对象——仍然不会在资源目录中存储任何内容。

其他情况均作为作业处理：多张图片、asset_ids、任何 AI 操作，或 wait: false。你会获得资源 ID 和公开 URL，还能查看进度、取消作业并使用 Webhook。

哪些操作可以使用第一种模式，通过 GET /api/v1/ops（syncEndpoint）读取，绝不硬编码——API 新增一个确定性操作后，此处便可快速使用，无需更改此软件包。如果无法访问目录，则使用作业模式：慢一点，总比出错好。

两种路径对 urls 输入的判定相同：它必须解析为公开地址，并且会在任何内容离开进程之前于此处遭到拒绝，而不只是由实际抓取它的服务拒绝。无论通过哪种传输方式处理，同一个输入都不会得到不同的结果。

两种模式都不会返回图片字节。 上下文窗口中的图片会消耗 Agent 需要付费的 Token，而且 Agent 无法读取它；返回内容始终是路径、ID 或 URL。

资源

URI	内容
imagestep://ops	原样提供 GET /api/v1/ops 的结果——每个操作及其参数约定（类型、默认值、说明）、提示词和资源要求、默认模型及定价
imagestep://ops/{op}	某个操作的条目（模板；在启动时目录可读取的情况下，会为每个操作列出）
imagestep://models/{mode}	GET /api/v1/ai-models?mode=——ai_image 或 analyze，包含价格
imagestep://usage	GET /api/v1/usage?groupBy=op——账户过去 30 天的支出，按操作统计
imagestep://agent-guidelines	操作约定（如下）

这些目录资源之所以存在，是因为 MCP 专用客户端（Claude Desktop）无法使用 curl 调用 API 或打开控制台；而“绝不臆造参数”这条规则，只有在它能够读取这些资源时才能遵守。 transform 还会为每个操作提供一行摘要：name(type=default)，并附上目录中列出的参数取值、必填参数的含义，以及 AI 操作所用模型自身的 parameters 对象——这些内容根据同一目录生成；如果无法读取目录，则会改用内置摘要并说明这一点。五项资源都会实时读取：如果无法连接服务，读取就会失败，而不会使用副本作答。

imagestep://agent-guidelines 是操作约定——应读取操作目录，而不是随身携带一份列表；支出前先用 dry run 估价；根据 retryable 而不是状态码决定后续处理；批次中统一使用同一个预设；缺少某项能力时应如实说明，而不是绕过限制。它是资源而非工具，因为工具是 Agent 决定调用的东西，而这些规则是它应该事先读过的内容；此外，每次读取都会从服务获取，因此即使这个软件包副本是数月前发布的，提供的仍是今天的约定。

连接

前往 https://imagestep.dev/keys?utm_source=npm&utm_medium=mcp-readme 获取 API key。

Claude Desktop（claude_desktop_config.json）——本地运行，可上传磁盘中的文件：

{
  "mcpServers": {
    "imagestep": {
      "command": "npx",
      "args": ["-y", "@imagestep/mcp"],
      "env": { "IMAGESTEP_API_KEY": "is_sk_…" }
    }
  }
}

Cursor（.cursor/mcp.json）——配置格式相同：

{ "mcpServers": { "imagestep": { "command": "npx", "args": ["-y", "@imagestep/mcp"], "env": { "IMAGESTEP_API_KEY": "is_sk_…" } } } }

Claude Code——本地运行：

claude mcp add imagestep -e IMAGESTEP_API_KEY=is_sk_… -- npx -y @imagestep/mcp

远程（任何支持 Streamable HTTP 的客户端）——无需安装：

claude mcp add --transport http imagestep https://mcp.imagestep.dev/mcp --header "Authorization: Bearer is_sk_…"

远程服务是无状态的：每个请求都由一个新服务处理，并根据 Authorization 标头中的 API key（Bearer 或 ApiKey）进行绑定。此处已禁用 file_paths；请传入 urls 或 asset_ids。服务会为每个请求在 stdout 输出一行 JSON 日志，其中包含 JSON-RPC 方法、tools/call 的工具名称、initialize 报告的 clientInfo、你的 key 前缀（控制台显示的 12 个字符——绝不会记录 key 本身）、key 是否有效、HTTP 状态码和耗时。绝不会记录工具参数或你的提示词。有效性通过向 API 发出的旁路请求确定（超时为 3 秒，不计为一次 key 使用），结果无论有效与否，都会保留 5 分钟。握手不会等待该请求。能够使用你的 key 调用 API 的请求（工具调用、资源读取）会在服务尚未见过该 key 时进行验证；因此，错误的 key 会在那里被拒绝，并返回与 API 相同的 unauthorized 错误，不会到达 API。若某个地址的 key 在 1 分钟内有 20 次被判定为无效，那么对于服务尚未见过的任何 key，服务都会返回 HTTP 429 和 Retry-After，直到该分钟结束；已确认有效的 key 则不受影响。

远程服务等待每次工具调用的时间最多为 90 秒（高于此值的 wait_seconds 会被截断；默认值也是 90）。每次调用都会作为一个 JSON 响应体返回，因此在工具返回前，你的客户端不会收到任何内容；而如果响应尚未开始，Cloudflare 边缘节点会在 100 秒后断开连接——此时你会收到不含 job id 的 HTML 524 响应，但任务仍会继续运行。超过 90 秒时，会改为返回 job 句柄，并将 timedOut: true 设为 true；请轮询 job_status。通过 stdio 调用时，等待时长由你设定（默认 180 秒，最长 600 秒）。

试用

上传 ./product.jpg，移除背景，将其放大 2×，并给我 URL。

Agent 调用 transform（remove_bg、file_paths），然后调用 transform（upscale， asset_ids = 上一次的输出，parameters: {"scaleFactor": 2}），并从 最后的结果中读取 publicUrl。三次调用，上下文中没有图像字节。

自己运行

IMAGESTEP_API_KEY=is_sk_… npx -y @imagestep/mcp            # stdio
npx -y @imagestep/mcp --http --port 8787                   # HTTP on /mcp, key per request

IMAGESTEP_BASE_URL 用于将服务指向其他 API 主机。

--http 会监听 127.0.0.1，并且只响应 Host: localhost:<port> / 127.0.0.1:<port> / [::1]:<port> — 其他任何主机都会在检查密钥之前收到 403，因此，重新绑定其自身主机名到你的机器的网页无法驱动它。--host 0.0.0.0 会将其开放到网络（托管版图像就是这样做的）；添加 --allowed-hosts mcp.example.com,…，将其限制为你提供服务时使用的主机名。

收到 SIGTERM / SIGINT 后，--http 会停止接受连接，让正在执行的调用完成，并以 0 退出 — 最多等待 25 s，低于托管 Pod 的 30 s 宽限时间。如果调用仍在等待其作业，则会立即返回作业句柄和 timedOut: true，与等待超时的行为相同 — 轮询 job_status，不要重新提交；为此，托管服务会让服务在继续读取之前最多等待提交 15 s。在图像中，节点由 tini 运行，而不是作为 PID 1 运行；作为 PID 1 时会忽略该信号。

Agent 会选择正确的工具吗？

eval/ 会对此进行测量：针对这个服务自身的 tools/list，运行一个最简 Agent 循环，并使用一个虚拟账户 （不会生成图像，只会消耗模型令牌），任务取自文档和配方 — 其中五分之一 是 ImageStep 无法完成的任务，正确的调用方式是 send_feedback。它会测量每个模型的工具选择、参数有效性和 调用步数，并设有开销上限：

OPENROUTER_API_KEY=… pnpm --filter @imagestep/mcp eval --runs 3 --budget 3

这是工具描述、注释或错误消息的回归信号，而且会产生费用，因此会有意运行，而不是养成习惯后随手运行。这不是测试，也不会在 CI 中运行。关于何时运行、费用、如何逐步衡量更改、如何读取和编写任务，以及目前的数据： eval/README.md。