upload-files

ファイルをアップロードする

アップロードは DAM（https://imagekit.io/mcp/dam）経由で行います。

ファイルのバイト列を会話やツール引数に含めないでください。 Base64、データ URI、バッファー、ストリームは使わないでください。トークンを大量に消費し、大きなファイルでは失敗します。

アップロードの仕組み

アップロードは、短時間有効で一度だけ使える署名によって認証される、ImageKit のアップロードエンドポイントへの multipart/form-data POST です。DAM サーバーが行うのは署名だけです。ファイルは、存在する場所から ImageKit に直接送られます。ローカルファイルならユーザーのマシンから、公開 URL なら ImageKit が取得します。各ファイルの署名を取得し、ファイルがある場所で POST が実行されるようにするのがあなたの役目です。

使用するツール

状況	呼び出し
ユーザーの環境でシェルコマンドを実行できる（1 個または複数のファイル、ローカルパスまたは公開 URL）	create_upload_signatures_in_bulk を呼び出してから、返された uploadCommand を実行します。
シェルを使えず、ユーザーが自分のコンピューター上のファイルを選択したい（クライアントで MCP Apps を表示できる）	パラメーターなしで upload_file を呼び出します。ファイル選択画面が開きます（ファイル名、フォルダー、タグ、カスタムメタデータ）。
ユーザーが別の場所で自分でアップロードを実行するため、署名済みフォームフィールドが必要	create_upload_signature を呼び出します。各ファイルを formFields とともに POST します。

シェルを使える場合は、ファイルが 1 つだけでも、可能な限り create_upload_signatures_in_bulk を優先してください。署名済みトークンが会話に含まれることはなく、1 つのコマンドですべてをアップロードし、ファイルごとにステータス行を表示します。

create_upload_signatures_in_bulk

• 1 回の呼び出しで 1～1,000 件のエントリーに署名します。各エントリーは、ローカルディレクトリ内に直接あるファイル、または公開 URL のいずれかで、それぞれに独自の fileName、folder、アップロードフィールドがあります。
• トークンは返されません。expire（60～3,600 秒、デフォルトは 600）まで、manifestUrl の背後にあるサーバー上に保持されます。ローカルファイルの場所をコマンドに伝えるため、localDirectory を指定します。
• 返された uploadCommand をユーザーのシェルで実行します。コマンドはローカルディレクトリに移動し、マニフェストを取得して、一度に最大 16 個のファイルをアップロードします。
• ファイルごとに 1 行出力されます：<status> <name>。200 はアップロード済みを意味します。SKIP <name> はファイル名がローカルで拒否されたことを意味します（空、/ または " を含む、あるいは . で始まる）。
• 有効期限前に同じコマンドを再実行すると、失敗したファイルを再試行します。アップロード済みのファイルは拒否され、重複しません。有効期限後は manifest unavailable と表示され、アップロードは行われません。署名を再取得してください。
• マニフェスト URL は認証情報として扱ってください。URL を知っている人は、有効期限まで署名済みのファイルをアップロードできます。コマンド以外の場所に貼り付けないでください。

create_upload_signature

ユーザーが自分で（自作のスクリプトまたは別のマシンで）アップロードを実行する場合に使用します。結果には署名済みトークンが含まれます。

• 1 回の呼び出しで複数のファイルに署名できます。ファイルごとに fileName を指定したエントリーを 1 つ送り、必要に応じて folder、tags、customMetadata、その他のアップロードフィールドを指定します。expire はすべてのファイルに適用されます。
• 結果には uploadUrl と、ファイルごとの formFields が含まれます。formFields には token を含む、その署名が紐付けられた正確なフィールドが含まれます。
• 各ファイルは、file=@<LOCAL_FILE_PATH> として、または ImageKit に取得させる場合は file=<PUBLIC_URL> として、返されたとおりのそのファイルの formFields を添えて uploadUrl に POST します。フィールドを追加、削除、または再シリアライズすると、署名チェックに失敗します。
• トークンは短時間有効で一度だけ使用できます。アップロードの直前に署名を取得してください。

手順

1. フォルダー、ファイル名、タグ、カスタムメタデータを確認します。フィールドは事前に作成しておく必要があります（list_custom_metadata_fields）。
2. 上の表にあるツールを呼び出します。
3. search_media_library、アップロード応答、または一括コマンドのステータス行で、ファイルが正常にアップロードされたことを確認します。

注意事項

• フォルダーは / で始まるメディアライブラリのパスであり、ローカルパスではありません。必要に応じて、ネストされたフォルダーが作成されます。
• 無料プランの上限は、画像が25MB、動画が100MBです。1ファイルあたりの最大バージョン数は100です。
• 移行したアセットの元の作成日時を保持するには、予約済みのカスタムメタデータキー _internal_original_created_datetime に ISO 8601 形式の文字列を設定します。このキーは、元の作成日時の設定を有効にしたアカウントにのみ存在します。list_custom_metadata_fields で確認してください（reserved: true）。