Kompressr

@kompressr/mcp-server

MCP エージェント向けの Kompressr ツールです。ファイルのアップロード、処理の完了待ち、非公開リンクの生成、アップロードのページ分割表示、指定したアセット ID の完全削除を行えます。ファイル操作には、別個の @kompressr/sdk パッケージを使用します。アプリケーションでは、MCP を起動せずにこの SDK を直接使用できます。

Node.js 22 以降が必要です。MCPB 拡張機能に対応したデスクトップクライアントをお使いの場合は、GitHub Releases から Kompressr MCP バンドルをダウンロードし、デスクトップへのインストールガイドに従ってください。

セットアップ

Kompressr アカウントを作成し、30 日間の画像アップロードトライアルを開始するか、有料プランを選択します。Dashboard → Projectsでプロジェクトを開き、API Keys を選択します。プロジェクトキー／マスターキーは信頼できるマシンでのみ使用し、個々のアプリケーションやエージェントのランタイムにはスコープ付きキーを使用してください。プロジェクト UUID が必要なのは、アップロード一覧を取得する場合のみです。

MCP クライアントで、このパッケージを実行するよう設定します。

{
  "mcpServers": {
    "kompressr": {
      "command": "npx",
      "args": ["-y", "@kompressr/[email protected]"],
      "env": {
        "KOMPRESSR_API_KEY": "YOUR_PROJECT_OR_SCOPED_KEY",
        "KOMPRESSR_PROJECT_ID": "YOUR_PROJECT_UUID"
      }
    }
  }
}

アップロード一覧の取得には KOMPRESSR_PROJECT_ID が必要です。アップロード、ステータス確認、署名、削除にはキーのみが必要です。ソースからビルドする場合は、CONTRIBUTING.mdに従い、その後 node にこのパッケージのビルド済み dist/index.js の絶対パスを設定してください。

設定と移行

設定	意味
KOMPRESSR_API_KEY	不透明なプロジェクトキー／マスターキー、またはスコープ付きキー。API の権限が引き続き優先されます
KOMPRESSR_PROJECT_ID	プロジェクト UUID。list_assets に必要です
KOMPRESSR_API_URL	管理用オリジン。デフォルトは https://kompressr.com です
KOMPRESSR_UPLOAD_BASE_URL	アップロード本文の送信先オリジンの上書き設定
KOMPRESSR_REMOTE_ALLOWED_HOSTS	プライベート／ローカルのリモートソースアドレスへのアクセスを明示的に許可する、カンマ区切りのホスト名

本番環境では、管理用に https://kompressr.com、アップロード本文用に https://uploads.kompressr.com がデフォルトで使用されます。別のデプロイ先を使用する場合は、プライベートなランタイム設定で KOMPRESSR_API_URL と KOMPRESSR_UPLOAD_BASE_URL を指定してください。カスタムの管理用オリジンでは、上書きしない限り同じアップロード用オリジンが使用されます。オリジンには HTTP(S) を使用し、認証情報、パス、クエリ、フラグメントを含めないでください。

保存済みの設定は引き続き ~/.kompressr/config.json に保存されます。

{
  "api_key": "YOUR_KEY",
  "project_id": "YOUR_PROJECT_UUID",
  "api_url": "https://kompressr.com",
  "upload_url": "https://uploads.kompressr.com"
}

環境変数の設定は、保存済みの値より優先されます。環境変数で別のキーを指定しても、保存済みのプロジェクトやエンドポイントは引き継がれません。これによりアカウントの混在を防ぎます。カスタムオリジンを使用する場合は、これらも明示的に指定してください。管理用オリジンを変更すると、アップロード用オリジンの上書き設定がない限り、アップロード用オリジンも再設定されます。保存済みの古い https://api.kompressr.com の値は、メモリ内で本番環境の値に移行されます。新しい設定を保存する際はアトミック置換が行われ、ディレクトリには 0700、ファイルには 0600 のアクセス権が設定されます。既存のファイルは、読み込みのみでは書き換えられません。キーや設定をソース管理に含めないでください。

ファイルのワークフロー

1. upload_asset を呼び出し、file_path または file_url のどちらか一方だけを指定します。返された数値の asset_id を保存してください。
2. wait_for_asset または get_asset_status を呼び出します。受け付け済みであることや保留中の URL が返されることは、ファイルの準備が完了したことを意味しません。アクティブなアセットについてのみ、現在の処理済みレスポンスを使用してください。
3. 公開処理済み URL を共有するか、アプリで非公開の受信者を認証してから generate_private_url を呼び出し、有効期限付きの新しいリンクを生成します。
4. 待機がタイムアウトした場合は、保存した ID を使って再開してください。ポーリングのタイムアウトから復旧するために、再アップロードしないでください。

30 日間の無料トライアルには、API、SDK、MCP、ダッシュボードで共有される画像アップロード 100 件分が含まれます。この上限は毎月リセットされません。対応フォーマット、サイズ、動画品質、非公開配信は、プラン／プロジェクトによって異なります。SDK は、ストリーミング API の要件に従い、すべてのマルチパートオプションをファイルより先に送信します。

ツール

過去のステータス／一覧レコードにあるファイル名の欠落や空欄は有効なままです。一覧ではレスポンスのメタデータを変更せず、「名前のないファイル」と表示されます。

すべてのファイルツールは、読み取り可能なテキスト、JSON テキストブロック、structuredContent を返します。失敗時は isError が設定されます。数値 ID は正の安全な整数である必要があります（単一 ID を扱うツールでは数値文字列も受け付けます）。

ツール	パラメーターと動作
upload_asset	file_path と file_url のどちらか一方のみを指定します。quality（480p、720p、1080p、4k）、visibility（public／private）、private_url_expires_in（60～604800 秒）、data（スカラー値を最大 5 個。キーは 64 バイト、文字列値は UTF-8 で 512 バイト、エンコード後の multipart JSON は 4096 バイトまで）は省略可能です。受け付けたことと ready を返します。
get_asset_status	asset_id。処理状況、公開範囲、削除状態、バイト単位のサイズ、節約量、準備状況を返します。
wait_for_asset	asset_id、任意の timeout_ms（1～120000、既定値は 120000）。上限付きでポーリングします。タイムアウト／エラー時も ID は保持されます。MCP リクエストのキャンセルで停止するのは待機であり、サーバージョブではありません。非公開アセットを使用可能にするには、新たに署名を取得する必要があります。
list_assets	page（任意、既定値は 1）、limit（任意、1～100、既定値は 20）、visibility、external_id、status（pending、processing、processed、failed、unprocessable）、deletion_status（active、deleting、deleted、legacy_deleted）、文字列の data フィルターは省略可能です。設定済みプロジェクト内のアップロードを一覧表示し、next_page を返します。
generate_private_url	asset_id、任意の expires_in（60～604800 秒、既定値は 3600）、variant（webp／avif、既定値は webp）。アプリケーション側で、最初にアクセスを認可する必要があります。有効期限が切れてもアセットは削除されません。
get_asset_deletion_status	asset_id。処理／削除状況と記録されたストレージクレジットを返します。削除が完了しても、すべてのキャッシュが消去されたことの証明にはなりません。
delete_asset	asset_id。取り消しやキャンセルができない完全削除です。受け付けられると、バックグラウンドでのクリーンアップが開始されます。削除権限が必要です。
bulk_delete_assets	asset_ids（明示的に指定した数値 ID を 1～100 個）。項目ごとの結果と件数を返します。HTTP リクエストが成功しても、一部の項目が失敗している場合があります。すべてを削除する選択機能はありません。
register	email、password（8 文字以上）。アカウントを作成し、確認メールを送信します。ランタイムが設定済みの場合は拒否されます。
verify_email	token。メールアドレスを確認し、発行済みの場合は認証情報を保存します。ランタイムが設定済みの場合は拒否され、ツール出力で生のキーが返されることはありません。トライアルまたは有料プランの制限は引き続き適用されます。

処理状況と削除状況は別々です。完全削除ではファイルが後から削除されます。キャッシュ、ダウンロード済みのコピー、オフラインのコピーは残る場合があります。同じ古い ID で再試行しても、新しい ID を持つ置き換え後のファイルは削除されません。一括削除では部分的な失敗が保持され、選択範囲が自動的に拡張されたり、再試行されたりすることはありません。storage_credited_mb は MB 単位で記録されたストレージクレジットであり、現金での返金ではありません。その他のサイズ項目の単位はバイトです。

読み取りツールには読み取り専用のアノテーションが付与され、削除ツールには破壊的操作のアノテーションが付与されます。アノテーションは動作を説明するものです。アクセスの制御は、サーバーの認可と MCP クライアントの承認制御によって行われます。

キー、エラー、リモートファイル

1つの顧客／エージェント実行環境には、スコープを限定したキーを使用してください。サーバーは、ID、許可されるファイルの種類／公開範囲、アクションのスコープを適用します。デフォルトのスコープでは delete は除外されており、使用するにはプロビジョニング時に明示的に含める必要があります。スコープを限定したキーでは、プラットフォームの管理操作や URL Prepend／ソース最適化を呼び出せません。信頼できるバックエンドから、SDK の client.platform グループまたは既存のプラットフォーム API を使って、ID とキーをプロビジョニングしてください。MCP にマスターキー管理ツールは追加されません。

安全な GET リクエストでは、ネットワークエラー／429／502／503／504 が発生した場合、30秒のリクエスト期限内で最大2回再試行し、Retry-After を尊重します。アップロードのデフォルト期限は10分で、書き込みは自動的に再実行されません。構造化エラーには、code、kind、HTTP ステータスが保持され、該当する場合は assetId／mayHaveSucceeded も含まれます。ディスパッチ済みの書き込みが中断された場合や、不正な JSON／データを返した場合、処理が成功している可能性があります。再実行する前に結果を確認してください。任意のエラーやゲートウェイの生のレスポンス本文は公開されません。

file_url は MCP マシンでダウンロードしてから、ローカルの一時ファイルをアップロードします。stdin の EOF を含む MCP のキャンセル／切断が発生すると転送は中止され、アップロード開始前にも再確認されます。ディスパッチ前であればアセットは作成されませんが、ディスパッチ後は、サーバーが受理したアップロードをクライアント側のキャンセルでロールバックできません。ディスクへのストリーミングには2 GiBの転送上限があり、ダウンロード期限は5分、リダイレクトは最大5回です。HTTPS から HTTP へのダウングレードは許可されません。数値形式の CIDR チェックでは、一般的なグローバル IPv6 ユニキャストアドレスを許可し、圧縮形式を含め、IETF プロトコル、移行、ドキュメント用の範囲を保守的に除外します。各宛先は、接続に使用される許可済みアドレスに解決されます。プライベート／ローカル宛先には、KOMPRESSR_REMOTE_ALLOWED_HOSTS に完全一致するホスト名が必要です。リダイレクト先も再確認されます。ソースには Kompressr の認証情報は使用されません。一時ファイルへのアクセスは制限され、成功時／失敗時に削除されます。転送上限は、ご利用プランやディスク容量の制限を上書きするものではありません。リモートからのダウンロードとアップロードには、それぞれ別の期限があります。サーバー側の URL インポートは、この SDK／MCP 統合には含まれません。

CHANGELOG.md とコントリビューションガイドを参照してください。ローカルの HTTP／プロトコルチェックでは、デプロイ済みの認証、処理、CDN の動作は保証されません。ソース検証コマンドはローカルのフィクスチャを使用し、パッケージを公開しません。