ImageStep

@imagestep/mcp

エージェント向け画像パイプライン：プリセット + アセット + ジョブを、MCP ツールとして提供します。画像がコンテキストウィンドウに入ることはありません。すべてのツールはアセット参照（ID、サイズ、公開 URL）を受け取り、返します。

ツール	機能
generate	プロンプト → 画像。アセット ID と CDN URL を返します。preset を指定すると、保存済みプリセットを通じて実行します。プリセットの subjects により、バッチ全体でキャラクターや製品を同一に保てます（固定するには slug@version を指定します）
transform	1 つのアトミックな操作です。generate を除く GET /api/v1/ops のすべての操作を、起動時（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 を 1 つ生成します。variants（最大 20 個）を指定すると、1 つのジョブ内でバリアントごとに操作を 1 回実行し、1 回の呼び出しであらゆるソーシャルメディア向けサイズを作成します。入力によって選択される 2 つのモード — 以下を参照
run_preset	スラッグ、または 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 の場合は再開時に再実行されるアイテム）は、指定した 1 つの状態のアイテムだけを読み取ります。chain アイテムには step / failedStep が含まれます
search_assets	コレクション、キーワード、MIME タイプ、サイズでアセットを検索します。または group_by: "collection" を指定して、コレクションの一覧を取得できます。1 回の呼び出しで 1 ページを取得します。回答の nextCursor を cursor として渡すと、次のページを取得できます
save_preset	再実行するチェーンを、名前付きのバージョン管理されたプリセットとして保存します。保存前にサービスが L1 の op ステップのみを検証します。run_preset で固定バージョンを実行するための slug@version を回答します
send_feedback	ImageStep でできなかったこと（capability_gap · bug · other）を、回避策を使う代わりに報告します。無料です

すべてのツールは outputSchema を宣言します。これは structuredContent で回答できるキーの一覧で、すべて省略可能です。返されるキーはモードによって異なります（完了したジョブ、タイムアウトした待機、ドライラン、同期結果、拒否）。

入力には asset_ids、urls（公開 http(s)。サービスが取得して取り込みます。このサーバーがダウンロードすることはありません）、または、サーバーを stdio 経由で自分のマシン上で実行している場合は file_paths を使用します。費用が発生するすべてのツールには dry_run があります（正確な料金を提示し、何も作成・アップロードしません。asset_ids はそのまま料金計算され、file_paths / urls は件数に基づいて計算されます）。また、retryable、param、サービスの requestId を含む構造化エラーを返すため、パラメーターの誤りはクレジットが課金される前に拒否されます。失敗を報告する際は requestId を引用してください。

書き込みツール（generate · transform · run_preset · save_preset · send_feedback）には、オプションで idempotency_key を指定できます。タイムアウトした MCP クライアントは、エージェントにツールを再度呼び出させます。同じキーと同じ引数を使った 2 回目の呼び出しでは、別のジョブを送信して課金する代わりに、1 回目の呼び出しで返された内容（作成したジョブ、保存したプリセット）を返します。同じキーを異なる引数で使用すると、idempotency_key_reuse で拒否されます。キーを指定しない場合、呼び出しのたびに新しい送信として扱われます。 すべてのツールには MCP アノテーションが付いており、クライアントはこれを読み取って、何について確認を求める必要があるかを判断します。 job_status と search_assets は readOnlyHint です。書き込みツールは（キーがない場合）べき等ではなく、いずれも destructiveHint ではありません。すべてのジョブは新しいアセットを書き込み、読み取ったアセットを上書きすることはありません。

transform には2つのモードがあり、エージェントはどちらにするか選びません

次の条件をすべて満たす場合は同期処理です。ローカルファイルまたは URL がちょうど1つ、決定論的な op、そして wait: true。アカウントには何も保存されません。アセットが作成されないため、処理後にアセット ID は存在しません。1秒未満で完了し、アカウントはクリーンなままです。

2つのサーバーはファイルシステムを共有していないため、結果の出力先は接続先のサーバーによって異なります。

	応答	有効期間
stdio（お使いのマシン上のこのパッケージ）	path — サービスが生成したとするファイル名の一時ファイル（.bin ではなく convert-<ts>.avif）	サーバーの終了まで。1つのサーバーが生成した結果はすべて、1つの一時ディレクトリに保存されます
ホスト型（https://mcp.imagestep.dev/mcp）	url — 署名付きリンクと expiresInSeconds	約5分。ダウンロードするか、永続的な URL が必要な場合はジョブとして実行してください

どちらの応答にも mimeType、width、height が含まれるため、次のツールが推測する必要はありません。ホスト型の応答が URL であるのには明白な理由がありますが、それに気づくにはバグが必要でした。エージェントはサーバーが実行されているマシン上にはいないため、そのコンテナー内の /tmp へのパスを返されても読み取れません。内部では API 自身の ?response=url を使っており、バイト列は短期間だけ保持される一時オブジェクトに書き込まれます。アセットカタログには何も追加されません。

それ以外はすべてジョブとして実行されます。画像が複数ある場合、asset_ids を指定する場合、AI op を使う場合、または wait: false の場合が該当します。アセット ID と公開 URL に加え、進行状況、キャンセル、Webhook を利用できます。

どの op が同期処理の対象になるかは、ハードコードされるのではなく、GET /api/v1/ops の syncEndpoint から読み取られます。API に決定論的な op が追加されても、このパッケージを変更することなく、ここでは高速に処理できます。カタログに接続できない場合はジョブの経路が使われます。誤った結果を返すより、遅いほうがよいからです。

urls 入力はどちらの経路でも同じように判定されます。パブリックアドレスに解決される必要があり、サービスが取得する段階だけでなく、プロセス外に何も送信される前にここで拒否されます。同じ入力に対して、どのトランスポートで運ばれたかによって応答が2つ返ることはありません。

どちらのモードでも、画像のバイト列が返されることはありません。 コンテキストウィンドウ内の画像は、エージェントが費やすトークンになるうえ、読み取ることもできません。応答は常にパス、ID、または URL です。

リソース

URI	内容
imagestep://ops	GET /api/v1/ops の内容そのまま — すべての op と、そのパラメーターの仕様（型、デフォルト値、説明）、プロンプトとアセットの要件、デフォルトモデル、料金
imagestep://ops/{op}	1 つの op のエントリー（テンプレート。起動時にカタログを読み取れた場合、op ごとに一覧表示）
imagestep://models/{mode}	GET /api/v1/ai-models?mode= — ai_image または analyze と、その料金
imagestep://usage	GET /api/v1/usage?groupBy=op — 過去 30 日間にアカウントが op ごとに使った金額
imagestep://agent-guidelines	運用ルール（以下を参照）

カタログのリソースがあるのは、MCP のみを使うクライアント（Claude Desktop）では API を curl したりコンソールを開いたりできず、「パラメーターを決して捏造しない」というルールを守るには、クライアントがカタログを読み取れる必要があるためです。 transform には op ごとの 1 行の概要も含まれます。これは name(type=default) に加えて、カタログに記載されている場合はパラメーターが取りうる値、必須パラメーターの意味、AI op ではモデル独自の parameters オブジェクトを含みます。同じカタログから生成されます。カタログを読み取れなかった場合は、組み込みの概要にフォールバックし、その旨を明記します。5 つすべてが ライブで読み取られます。サービスに接続できない読み取りは、コピーから回答するのではなく失敗します。

imagestep://agent-guidelines は運用ルールです。リストを持ち歩くのではなく op カタログを読み、支出する前にドライランで料金を確認し、ステータスコードではなく retryable に応じて処理を分岐し、バッチ内ではプリセットを統一し、機能が不足している場合は回避策を講じずにその旨を報告します。エージェントが呼び出すかどうかを決めるのがツールであり、ルールはあらかじめ読んでおくべきものなので、これはツールではなくリソースです。また、読み取るたびにサービスから取得するため、このパッケージがリリースされてから数か月経っていても、今日のルールが提供されます。

接続

https://imagestep.dev/keys?utm_source=npm&utm_medium=mcp-readme で API キーを取得してください。

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 ヘッダー（Bearer または ApiKey）の API キーに紐づいた新しいサーバーで処理されます。file_paths は無効です。urls または asset_ids を渡してください。リクエストごとに、JSON-RPC メソッド、tools/call のツール名、initialize が報告する clientInfo、キーのプレフィックス（コンソールに表示される 12 文字。キーそのものは決して記録されません）、キーの有効性、HTTP ステータス、所要時間を 1 行の JSON として標準出力に記録します。ツールの引数やプロンプトは記録しません。有効性は API への別リクエスト（タイムアウト 3 秒、キーの使用回数には含まれません）で確認され、その回答は有効・無効にかかわらず 5 分間有効です。ハンドシェイクはその確認を待ちません。API キーを使って API を呼び出せるリクエスト（ツールの呼び出し、リソースの読み取り）は、サーバーがそのキーをまだ確認していない場合にキーの有効性を確認します。そのため、誤ったキーはその時点で拒否され、API と同じ unauthorized エラーが返され、API には到達しません。1 分間に無効と判定されたキーが 20 回あったアドレスからは、その 1 分が経過するまで、サーバーがまだ確認していないキーに対するリクエストはすべて Retry-After 付きの HTTP 429 になります。すでに有効だと確認されているキーは引き続き使えます。

リモートサーバーがツールの呼び出しを待つ時間は最大 90 秒です（これを超える wait_seconds は上限値に丸められます。デフォルトも 90 です）。各呼び出しには 1 つの JSON ボディで応答するため、ツールが戻るまでクライアントには何も届きません。また、Cloudflare のエッジは、応答が 100 秒以内に開始されないと接続を切断します。その場合、ジョブ ID を含まない HTML の 524 が返されますが、ジョブ自体は実行され続けます。90 秒を超えると、代わりに timedOut: true とともにジョブハンドルが返されます。その後は job_status をポーリングしてください。stdio 経由では、指定した時間だけ待機します（デフォルトは 180 秒、最大 600 秒）。

試してみる

./product.jpg をアップロードし、背景を削除して、2×にアップスケールし、URL を教えてください。

エージェントは transform（remove_bg、file_paths）を呼び出し、続けて transform（upscale、asset_ids = 前の出力、parameters: {"scaleFactor": 2}）を呼び出し、最後の結果から publicUrl を読み取ります。3 回の呼び出しで、コンテキストに画像のバイトデータは入りません。

自分で実行する

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 秒で、ホストされたポッドの 30 秒の猶予時間内です。ジョブの完了を待っている呼び出しには、待機がタイムアウトした場合と同様、ジョブハンドルと timedOut: true をただちに返します。再送信せず、job_status をポーリングしてください。その場合、ホスト版サーバーではサービスが送信を最大 15 秒間保持してから読み取りを続けます。イメージノードは tini の下で実行され、シグナルを無視してしまう PID 1 としては実行されません。

エージェントは適切なツールを選べるでしょうか？

eval/ で測定できます。このサーバー独自の tools/list を使う最小限のエージェントループを、偽アカウントで実行します（画像は生成せず、モデルのトークンだけを消費します）。ドキュメントやレシピをもとにしたタスクのうち、5 分の 1 は ImageStep では実行できない内容で、その場合の適切な呼び出しは send_feedback です。モデルごとのツール選択、引数の妥当性、ステップ数を、支出上限を設けて評価します。

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

これはツールの説明、アノテーション、エラーメッセージに対する回帰シグナルです。また費用もかかるため、習慣的にではなく、意図的に実行します。テストではなく、CI にも含まれません。実行するタイミング、費用、変更を段階的に測定する方法、タスクの読み書き、これまでの数値については、eval/README.md を参照してください。