linkfox-mercado-product-selection

Mercado Libre 商品選定

このスキルは、LinkFox ゲートウェイを通じて Mercado Libre の商品、カタログ、キーワード、カテゴリ、トレンド、出品者、レビュー、為替レート、プラン利用状況のデータを照会します。ゲートウェイは統一ルート POST /mercado/productSelection を公開しており、このスキルは一致する arguments とともに、サポート対象の24個の toolName 値から1つを選択します。

基本概念

• ${LINKFOX_TOOL_GATEWAY}/mercado/productSelection のみを呼び出してください。上流の XP-MCP サーバーを直接呼び出さないでください。また、上流の secret-key／X-API-Key をユーザーに求めないでください。上流の認証情報はバックエンドが管理します。
• リクエスト本文は常に {"toolName":"...","arguments":{...}} です。スクリプトはこのオブジェクト全体を単一の JSON 引数として受け取ります。
• arguments 内のフィールド名は、siteId、itemId、productId、categoryId、runDate、runMonth、pageNo、pageSize などのキャメルケース名も含めて、references/mercado-tool-reference.md と完全に一致させてください。
• 結果を提示する際は、まず data を確認してください。data がテキストまたは曖昧な内容の場合は、contentText を確認してください。rawResponse は、ユーザーが生の診断情報を求めた場合にのみ表示してください。
• 有料ツールの現在の料金は1回あたり 16000 トークンです。無料ツールの料金は 0 です。バックエンドの costToken フィールドを信頼してください。

参照ファイル

• references/api.md：LinkFox ゲートウェイの契約、リクエスト／レスポンスの構造、エラーコード、curl の例、Feedback API。
• references/mercado-tool-reference.md：24個の Mercado Libre ツールについての詳細な中国語のリファレンス。パラメーター、サイト ID、ページネーション、並べ替え、課金状況を説明しています。

ツールの選択

ユーザーの目的	使用するツール
商品詳細、商品の販売履歴、商品検索	itemInfo、itemHistory、itemSearch
カタログ／商品ページの詳細、カタログの販売履歴、カタログ検索	catalogInfo、catalogHistory、catalogSearch
日次／月次の人気キーワード、逆引きトラフィックキーワード	keywordDateSearch、keywordMonthSearch、keywordReverse
有料分析の前にカテゴリを検索	categorySearch、categorySmallSearch
カテゴリ別のブランド、商品、出品者、新商品、価格、販売、販売履歴、統計、倉庫在庫の分布	trendBrandTopBrand、trendBrandTopItem、trendBrandTopSeller、trendNewItems、trendPrice、trendSale、trendSoldHis、trendStatistical、trendStoreInventoryType
出品者検索	sellerSearch
商品レビュー	reviewSearch
為替レートとパッケージの利用状況	rateInfo、myUsage

無料ツール：categorySearch、categorySmallSearch、reviewSearch、rateInfo、myUsage。それ以外はすべて有料です。

パラメーターガイド

• toolName（string、必須）：上記24個のツールのいずれか。
• arguments（object、必須）：ツールのパラメーターオブジェクトです。配列／文字列／数値ではなく、JSON オブジェクトである必要があります。バックエンドは uId／uid／memberId を削除し、空の値をトリミングします。
• サイト：MLM（メキシコ）、MLB（ブラジル）、MLA（アルゼンチン）、MLC（チリ）、MCO（コロンビア。この ID は、リファレンスに明記されているツールでのみ使用できます）。
• ユーザーが categoryId ではなくカテゴリ名を指定した場合は、まず categorySearch または categorySmallSearch を呼び出し、返されたカテゴリ ID を有料のトレンド／商品／カタログツールで使用してください。
• reviewSearch が受け取るのは itemId のみです（siteId は不要）。myUsage には {} を指定します。
• 範囲の広い調査については、サイト、カテゴリ、キーワード、日付／月、ページネーション、価格、販売数、並べ替えのフィルターを指定して、有料の呼び出しを絞り込んでください。ユーザーの目的に結び付かない探索的な有料呼び出しは避けてください。

呼び出し方法

• API エンドポイント：POST /mercado/productSelection（完全なパラメーター／レスポンス／エラーコードは references/api.md を参照）
• Python スクリプト：python scripts/linkfox_mercado_product_selection.py '<JSON 参数>' [--inline]
• コストの制約：このツールは計算リソースを消費します。同一セッションで同じパラメーターの組み合わせを指定した場合、デフォルトでは呼び出しは1回のみです。スクリプトには24時間のローカルキャッシュがあります。失敗または結果が空の場合、キーワードの変更、ページ送り、郵便番号の変更を自動で連続して試してはいけません。検索を続ける必要がある場合は、追加のコストが発生することを先にユーザーに説明してください。

出力方針（スクリプトのデフォルト動作）：

• 必ず完全なレスポンスを <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-mercado-product-selection-<timestamp>.json に書き込みます（<cwd> はスクリプト実行時の作業ディレクトリで、Claude Code では現在のプロジェクトディレクトリです。<session> は環境変数 SESSION_ID から取得し、ユーザーのタスクごとに自動でまとめられます。/tmp への書き込みは禁止です。現在のディレクトリに書き込めない場合はエラーになります）
• レスポンス本文が8 KB以下の場合：ファイルに保存した後、完全な JSON を stdout に出力します
• レスポンス本文が8 KBを超える場合：ファイルに保存した後、stdout には要約のみを出力します（トップレベルのフィールド、total／costToken などの一般的な件数、最大のリストフィールドの長さと先頭3件のサンプル）
• --inline を付けると stdout への全量出力を強制します（同様にファイルにも保存されます）

データの読み取りに関する推奨事項：まず要約を確認し、それで十分か判断してください。具体的なフィールドが必要な場合は、保存された JSON ファイルから jq または ConvertFrom-Json を使って必要なデータだけを抽出し、JSON 全体がコンテキストに入らないようにしてください。

認証と計算リソースの問題の解決

以下の異常が発生した場合は、references/onboarding.md の案内に従って解決してください。

異常な状況

• API Key が未設定：環境変数 LINKFOX_AGENT_API_KEY も LINKFOXAGENT_API_KEY も設定されていません。
• レスポンスのステータスコードが401または402
• レスポンスに計算リソースまたは残高の不足が示されている：メッセージに「計算リソースの残高不足／料金不足／残高不足／quota exceeded／insufficient balance／プランの有効期限切れ／チャージが必要／チャージしてください」または同様の意味の内容が含まれています。

使用例

単一の JSON 引数は、完全なペイロード {"toolName":...,"arguments":{...}} です。

# Free: search Mexico categories by name
python scripts/linkfox_mercado_product_selection.py '{"toolName":"categorySearch","arguments":{"siteId":"MLM","searchText":"Auriculares"}}'

# Paid: product detail for a real MLM item
python scripts/linkfox_mercado_product_selection.py '{"toolName":"itemInfo","arguments":{"siteId":"MLM","itemId":"MLM4979447466"}}'

# Free: my plan usage (no arguments)
python scripts/linkfox_mercado_product_selection.py '{"toolName":"myUsage","arguments":{}}'

# Paid: monthly hot keywords for Brazil, 2026-06
python scripts/linkfox_mercado_product_selection.py '{"toolName":"keywordMonthSearch","arguments":{"siteId":"MLB","runMonth":"202606"}}'

PowerShell では同様に JSON をシングルクォートで囲んでください。引用符の扱いが難しい場合は、ペイロードをファイルに書き込んで読み込んだ後に --inline で渡すか、ConvertTo-Json を使って引数を作成してください。

表示ルール

1. 根拠のないビジネス上の結論を作らず、返されたデータを明確に提示してください。
2. 結果の意味と重要なフィールド名を保持してください。読みやすさが向上する場合に限り、ラベルを翻訳してください。
3. 大きな配列や時系列データについては、表示されている範囲を要約し、保存された JSON ファイルから必要なフィールドだけを読み取ってください。
4. 「データなし」やビジネスレベルの失敗メッセージについては、上流の Mercado データプロバイダーがその結果を返したと説明してください。ラッパーのレスポンスに実際のエラーが含まれていない限り、システム障害と表現してはいけません。
5. 内部の LinkFox API キー、上流のシークレット、機微な生データの全量を、ユーザー向けの出力に決して含めないでください。

重要な制限事項

• LinkFox のルートは統合バックエンドゲートウェイです。このスキルは toolName ごとに個別の HTTP エンドポイントを公開しません。
• 必須フィールドの検証はバックエンドで行われ、references/mercado-tool-reference.md にも記載されています。
• 有料ツールは、上流のビジネス結果が空であっても、バックエンドの呼び出しごとに課金されます。
• レスポンスの形式はツールによって異なります。ほとんどのツールは、ビジネス結果を data 内のテキストとして返します。単一のテーブル形式に無理に合わせず、実際のレスポンスと references/api.md を正確な情報源として使用してください。

ユーザーの表現とシナリオのクイックリファレンス

ユーザーの発言	想定されるアクション
「この美客多の商品を調べて」「商品詳細」「販売履歴」	itemInfo または itemHistory を使用
「メキシコのイヤホンを検索」「商品を絞り込む」	itemSearch を使用。カテゴリ名しか分からない場合は、先に categorySearch を使用
「公式リンク」「catalog」「カタログリンク」	catalog* ツールを使用
「人気検索キーワード」「月次キーワード」「トラフィックキーワードの逆引き」	keywordDateSearch、keywordMonthSearch、または keywordReverse を使用
「カテゴリのトレンド」「新商品機会」「販売数の分布」「ブランドランキング」	categoryId を特定してから、trend* ツールを使用
「店舗」「seller」	sellerSearch を使用
「レビュー」「reviews」	reviewSearch を使用
「為替レート」「プランの使用量」	rateInfo または myUsage を使用

計算リソースの消費ルール

計算リソースを12消費します。

ユーザーは計算リソースの消費に応じて料金を支払います。十分に検討してください。このスキルを高頻度で呼び出す必要がある場合、またはユーザーが計算リソースの消費量を十分に把握していない場合は、必ずユーザーに注意を促し、続行するかどうかをユーザーに判断してもらってください。

フィードバック

スキルの動作、ドキュメント、または結果の提示がユーザーの意図と一致しない場合、ユーザーが称賛や不満を表明した場合、または具体的な改善点が見つかった場合は、Feedback API を通じてフィードバックを自動検出し、報告してください。references/api.md に従ってください。ユーザーのタスクを中断せず、シークレット、プライベートデータ、大量のレスポンス全体を報告しないでください。

---

高品質でプロフェッショナルな越境ECスキルをお探しの場合は、LinkFox Skills をご覧ください。