agenthand

agenthand

人々の販売を支援するAIエージェント向けのMCPサーバーです。

販売者がagenthandを開くことはありません。販売者のエージェントが呼び出します。販売者が雑然とした商品写真をエージェントに渡すと、agenthandは出品にすぐ使える素材へと変換します。出品を作成する順序に沿って、3つのツールを使います。

ツール	機能
draw	実物の商品をピクセル単位で変更せず、生成したシーン（荘厳な部屋に置かれた椅子、清潔なテーブルに並べられたゲーム一式など）に配置し、合成画像と忠実度レシートを返します。
cut_out	写真から商品を切り抜き、アセットハンドルで参照できる透明PNGを返します。コンセプトは任意です。指定しない場合、プランニング工程が内部で実行されます。
identify	一連の処理におけるプランニング工程です。写真を読み取って切り抜き方法を計画し、構造化された説明と、cut_outが使用するセグメンテーション対応の名詞句コンセプト（別案を含む）を返します。

忠実度ロック

drawは商品を再生成しません。この不変条件はコードで強制されています。

1. セグメンテーションによって、実物の商品前景とそのマスクを抽出します。
2. 商品レイヤーは変更せずに保存し、元画像、前景、マスクについて、ファイルバイトのハッシュと、それぞれをデコードしたピクセルのハッシュの両方を記録します。
3. 画像モデルが生成するのは背景シーンのプレートのみです。そのインターフェースが受け取るのはプロンプトと寸法だけで、商品ピクセルを受け取ることはありません。
4. 決定論的なコードで、元の商品レイヤーをそのプレートに合成します。プレートは商品の寸法に合わせてリサイズおよびクロップされ、商品レイヤーは一切拡大縮小されません。
5. drawは、元の商品写真まで遡れるforeground_pngアセット以外は拒否し、ピクセルが1つでも移動する前に保存済みのハッシュを検証します。
6. 結果には忠実度レシートが付属します。元画像、前景、マスクのハッシュ、納品ファイル自体のハッシュ、適用した変換、変更された不透明な前景ピクセルの測定数、実行したモデル呼び出しとそのコストが記録されます。また、カウントから除外したものも公開します。エッジバンドのピクセル数と最大幅、マスクの不透明部分の割合、許容誤差0での変更ピクセル判定条件、元写真と合成画像のカラープロファイル識別情報です（ICCプロファイルが欠落または変更されると、ピクセル値が同一でも商品の色が変わるため、記録したうえで忠実度の失敗としてカウントします）。

主張は明確です。保存された抽出済み前景が変更されずに合成画像へ反映され、そのハッシュによって対象のレイヤーが厳密に特定されています。部分的に透明なエッジバンドのピクセルは合成時にプレートとブレンドされるため、レシートでは過大な主張を避け、別個にカウントします。カウントは納品ファイル上で測定し、ストアから再デコードして算出するため、独立して再検証できます。 composite.verify_receipt_from_diskは保存されたファイルから再カウントし、レシート自体のハッシュとレシートに記載されたアセットのハッシュを照合します。変更ピクセルが厳密に0で、実際に対象領域が含まれる場合にのみ合格します。スタンドアロンのagenthand-verify SOURCE FINAL MASKチェッカーは、ストアを使わずにエクスポート済みファイルを検証し、マスクが何も選択していない場合も同様に拒否します。取り込み時にはHEICを含むスマートフォンで使われる形式に対応し、各写真に埋め込まれたカラープロファイルを最後まで保持します。

cut_outには、上限付きのマスク復旧ループを設けています。マスクの品質をチェックし、品質が低い場合はプランニング工程で得た別のコンセプト句を使って、ツールが1回だけ再試行します。すべての試行はレシートに記録されます。

アセットハンドル

ツール間で画像バイト列をやり取りすることはありません。各画像はローカルに 保存され（アセットごとのサイドカーレコードもアトミックに書き込まれます）、 asset://<id> で参照されます。ハンドルはツール間で引き継がれます。identify は ハンドルを読み取り、cut_out は新しいハンドルを返し、draw はそれを使用します。

画像の取り込みは ingest を通じて行われます。ツールの画像引数には、既存の ハンドル、http(s) URL、または base64 データ URI を指定できます。取り込み時には バイト数とピクセル数の上限が適用され、EXIF の向きが反映されて、8-bit RGBA PNG に 正規化されます。画像の出力方法は 2 つあります。draw は結果とともに画像の プレビューを返し、すべてのアセットはクライアントがそれぞれの asset://<id> URI の MCP リソースとして読み取れます。

コスト明細と支出上限

請求対象となるすべての呼び出しは、1 つの集中処理箇所 （src/agenthand/meta_client.py）を経由し、予約後に精算する方式で管理されます。 ファイルロックのもとで、予測される最悪ケースのコストを台帳と照合し、保留中の 明細として予約します。呼び出し後、プロバイダーの使用量カウントをもとに算出した 実際のコストを精算明細に記録します。請求された可能性がある状態で呼び出しが 失敗した場合、予約はカウントされたままになります。プロバイダーの応答に有効な 使用量情報がない場合、呼び出しは $0 ではなく、予約時の予測額で精算されます。 使用量情報が欠けていても、支出が取り消されることはありません。明細は、ツール、 モデル、トークン数と画像数、米ドルの推定額、使用した料金表のバージョンとともに、 ローカルの JSONL 台帳に記録されます。料金は 1 つのモジュール （src/agenthand/pricing.py）に集約されているため、料金変更はバージョンを更新して 1 行を編集するだけで済みます。料金未設定のモデルは、$0 と推定するのではなく エラーになります。支出が発生する経路はすべて、この 1 つの台帳を共有します。 ドライランのゲートも例外ではありません（アセットストアは一時ディレクトリに 分離されますが、台帳は分離されません）。

サーバーは支出に関してフェイルクローズ方式です。通常の上限はデフォルトで $120.00 です。設定によって上げ下げできますが、ハッカソンのクレジット額である $150.00 のハード上限を超えることはできず、どのような設定でもこの上限を 超過できません。台帳の記録に破損、負の値、または有限でない値がある場合は、 すべての支出が拒否されます。支出状況が不明な場合は、支出を許可しません。

ステータス

ハッカソン向けビルドです（Meta Global AI Developer Hackathon、2026 年 10 月 26 日～11 月 4 日）。3 つすべてのツールが、支出上限の請求集中処理箇所を通じて実際の Meta Model API に接続されています。identify は muse-spark-1.3、cut_out は sam-3.1、draw は muse-image-1.0 を使用しており、一連の処理を実際に最初から最後まで実行しています。2026-10-26 の検証済み実行（identify $0.007544、cut_out $0.0025、draw $0.01。透明度のないピクセル 580,613 個を確認し、変更は 0 個）の結果は、忠実度の明細とともにプロジェクトサイトで公開されています。同じ検証はブラウザー上で、その実行に使われたファイルを用いて再実行できます。プレースホルダーのプレートは、オフラインテスト用の明示的な開発フラグがある場合にのみ使用されます。現在、サーバーはローカルで stdio 経由で動作します。ホスト型エンドポイントは後日提供予定です。

サーバーには、単一バイナリの Rust ビルドもあります。上記の検証済み実行の固定ファイルを使った同等性ゲートに合格し、その実行のカウントと出力ピクセルのハッシュを再現しました。また、Rust バイナリによる実際の実行結果は Python の検証ツールで照合済みです。Python 実装は引き続きリファレンスであり、Rust ビルドは同じサーバーの 2 つ目の実装です。両者の結果は一致しています。

実行方法

任意の MCP クライアントに agenthand を登録してください。主な方法では uv を使用します。事前のインストールは不要で、uv が公開済みのパッケージを取得して実行します。

{
  "mcpServers": {
    "agenthand": {
      "command": "uvx",
      "args": ["agenthand"],
      "env": { "META_API_KEY": "…" }
    }
  }
}

または、pip でパッケージをインストールし、クライアントにインストール済みのコマンドを指定します。

pip install agenthand

{
  "mcpServers": {
    "agenthand": {
      "command": "agenthand",
      "env": { "META_API_KEY": "…" }
    }
  }
}

サーバーはキーがなくても起動してツール一覧を表示します。キーが必要になるのは、ツールがモデルを呼び出すときだけです。設定は環境変数で行います。.env.example を参照してください。

ソースから実行（開発用）

git clone https://github.com/AUsernameForYou/agenthand
cd agenthand
python3.12 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/agenthand          # stdio transport
.venv/bin/pytest             # unit tests