modelrun

modelrun

modelrun は Replicate 用の小さなワークベンチです。サービスの構造に沿っており、モデルはオーナーと名前の配下に置かれ、各モデルには独自の入力スキーマを持つバージョンがあり、コレクションには閲覧する価値のあるモデルがまとめられています。予測とは、バージョンまたは公式モデルを、自由形式の入力オブジェクトで実行することです。この構造をもとに、modelrun はモデルの一覧表示と読み取り、コレクションとバージョン履歴の確認、予測の開始、監視、キャンセル、トークンが属するアカウントの報告を行います。1 つのバイナリで、コマンドラインインターフェースと stdio MCP サーバーの両方を提供します。

Replicate API トークンが必要です。REPLICATE_API_TOKEN 環境変数に設定してください。トークンは Authorization: Bearer ヘッダーとして API に送信され、出力には決して表示されません。この変数が設定されていない場合、リクエストを行う前に、その変数名を明記したエラーですべての呼び出しが失敗します。

Replicate は検索エンドポイントを提供していないため、modelrun にもありません。モデルの検出には list_models と list_collections を使い、確認したいモデルを get_model で読み取って絞り込みます。

インストール

npx @reneturcios/modelrun models

または、コンテナイメージを実行します。

docker run -i -e REPLICATE_API_TOKEN ghcr.io/cloudcorprecords/modelrun

コンテナはデフォルトで MCP サーバーとして起動します（下記を参照）。CLI として使うには、CLI 引数を渡してください。

CLI

export REPLICATE_API_TOKEN=<redacted>

modelrun models
modelrun model meta meta-llama-3-70b-instruct
modelrun collections
modelrun collection text-to-image
modelrun versions stability-ai sdxl
modelrun version stability-ai sdxl db21e45d3f7023abc2a46ee38c23973f6dce16bb082a930b0c49861f96d1e5bf
modelrun predict --model meta/meta-llama-3-70b-instruct '{"prompt":"Explain tides in one sentence."}'
modelrun predict --version db21e45d3f7023abc2a46ee38c23973f6dce16bb082a930b0c49861f96d1e5bf '{"prompt":"a lighthouse at dawn"}'
modelrun prediction zt3k9examplepredictionid
modelrun predictions
modelrun cancel zt3k9examplepredictionid
modelrun account

modelrun --version

各コマンドは、上流の JSON ペイロードを出力します。終了コード：成功時は 0、呼び出し失敗時（REPLICATE_API_TOKEN の未設定や API エラーを含む）は 1、使用方法のエラー時は 2 です。

MCP サーバー

1 つのバイナリでどちらの用途にも対応します。mcp サブコマンドを実行すると、stdio MCP サーバーが起動します。

npx -y @reneturcios/modelrun mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "modelrun": {
      "command": "npx",
      "args": ["-y", "@reneturcios/modelrun", "mcp"],
      "env": { "REPLICATE_API_TOKEN": "r8_..." }
    }
  }
}

ツール

ツール	入力	戻り値
list_models	cursor（任意）	モデルの 1 ページ分。
get_model	owner、name（必須）	説明と最新バージョンの概要を含むモデル。
list_collections	（なし）	厳選されたコレクション。
get_collection	slug（必須）	コレクションと、そこに含まれるモデル。
list_model_versions	owner、name（必須）	モデルのバージョン。
get_model_version	owner、name、versionId（必須）	入力／出力スキーマを含むバージョン。
create_prediction	input（必須）、version／model のいずれか一方、webhook（任意）	作成された予測。
get_prediction	predictionId（必須）	ステータスと出力を含む予測。
list_predictions	cursor（任意）	アカウントの予測の 1 ページ分。
cancel_prediction	predictionId（必須）	キャンセルされた予測。
get_account	（なし）	トークンを所有するアカウント。

すべての呼び出しで、https://api.replicate.com/v1 配下の Replicate API を使用します。create_prediction は input オブジェクトを変更せずに渡します。コミュニティモデルには version ID を渡し、公式モデルには model を owner/name の形式で渡します。どちらか一方だけを指定する必要があり、ツールはリクエストを行う前にこれを検証します。

開発

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev     # run the CLI from source via tsx

ライセンス

MIT — LICENSE を参照してください。