Yango Tech Retail MCP

Yango Tech Retail MCP

English | Русский

A1 Yango Tech Retail MCP は、AI アプリを Yango Tech Retail の小売業者アカウントに接続します。自然な言葉で店舗、注文、商品、価格、在庫を確認したり、必要に応じて注文を作成したり、アカウントデータを更新したりできます。

このサーバーは、食料品小売およびダークストア向けの小売業者用 B2B API と連携します。マーケットプレイスの出品者向けポータルでも、タクシーサービスでも、Yango Delivery でもありません。

• 16 個のツール。 9 個の読み取り専用ツール、5 個の書き込みツール、2 個の破壊的な操作を伴う可能性のあるツールで、店舗、カタログ、価格設定、在庫、注文、レシートを扱います。
• 安全な読み取り専用の開始。 アカウントの情報を変更する前に、接続済みのデータを確認できます。
• 明確な書き込み範囲。 注文の作成とキャンセル、商品のアップサート、価格変更、割引の作成、在庫更新は、読み取り操作とは分けられています。
• 追加の API 対応。 技術ユーザーは、専用ツールがないメソッドにも raw_request からアクセスできます。

まずは、次のように試してください。

店舗の一覧を表示し、それぞれの店舗にある商品 [product ID] の在庫を教えてください。

サーバーに接続する · ユースケースを見る · 技術ドキュメントを開く

1 分で動作を確認

あなた： 店舗の一覧を表示し、それぞれの店舗にある商品 [product ID] の在庫を教えてください。

アシスタント： 店舗と各店舗の ID、および各店舗にあるこの商品の現在の在庫をお返しします。

あなた： すべての価格リストで、この商品の価格を表示してください。

アシスタント： 価格リストと、それぞれのリストにおける商品の現在価格をお返しします。アカウントデータは変更されません。

あなた： 価格リスト [price-list ID] で、価格を 99.90 に変更してください。

アシスタント： これは実際に顧客に表示される価格を変更します。確認を求める前に、商品、価格リスト、現在の価格、新しい価格を表示します。

あなた： 確認してください。

アシスタント： 価格を更新しました。価格リストを再度読み込み、現在の価格をお返しします。

店舗、商品、価格、在庫、注文の状態には、常に接続先の小売業者アカウントと最新の API レスポンスの情報が反映されます。

目次

• クイックスタート
• 依頼できること
• 小売データの接続方法
• アカウントで変更される内容
• アクセスの取得
• 設定
• データとテレメトリー
• 制限事項とバックグラウンド処理
• 技術ドキュメント
• サポート

クイックスタート

Node.js 20 以降、Yango Tech Retail アカウント、リテーラーの Bearer トークンが必要です。

1. Yango Tech のインテグレーションマネージャーからトークンを取得します。

2. 以下の手順のいずれかを使って、AI アプリにサーバーを追加します。

3. 読み取り専用のリクエストから始めます。

   店舗の一覧を表示し、それぞれの店舗における商品 [product ID] の在庫を表示してください。

codex mcp add yango-retail \
  --env YANGO_RETAIL_TOKEN=your_token \
  -- npx -y mcp-yango-retail@latest

codex mcp list

claude mcp add \
  --env YANGO_RETAIL_TOKEN=your_token \
  --transport stdio \
  --scope user \
  yango-retail \
  -- npx -y mcp-yango-retail@latest

claude mcp list

{
  "mcpServers": {
    "yango-retail": {
      "command": "npx",
      "args": ["-y", "mcp-yango-retail@latest"],
      "env": {
        "YANGO_RETAIL_TOKEN": "your_token"
      }
    }
  }
}

{
  "mcpServers": {
    "yango-retail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yango-retail@latest"],
      "env": {
        "YANGO_RETAIL_TOKEN": "your_token"
      }
    }
  }
}

{
  "servers": {
    "yango-retail": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-yango-retail@latest"],
      "env": {
        "YANGO_RETAIL_TOKEN": "${input:yango_retail_token}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "yango_retail_token",
      "description": "Yango Tech Retail Bearer token",
      "password": true
    }
  ]
}

依頼できること

店舗と商品カタログを確認する

• 店舗の ID、ステータス、場所、住所、および取得可能な場合は名称を一覧表示します。
• カーソルを使って商品を閲覧し、ステータス、カテゴリ、ローカライズされた名称、バーコード、カスタム属性を確認します。
• 1 回のリクエストで最大 100 件の商品を作成または更新します。商品レコードは重複して追加されるのではなく、アップサートされます。

価格を確認・更新する

• 価格表を一覧表示し、1 つ以上の価格表から商品価格を読み取ります。
• 同じ商品を複数の価格表で比較します。
• "150.00" のような小数文字列を使って、1 回のリクエストで最大 100 件の価格を設定します。
• Yango Tech にフィールド構造を確認してから、店舗ごとの割引を最大 100 件作成します。

在庫を確認・更新する

• 商品、数量、棚の種類を含め、店舗間の在庫を読み取ります。
• 1 つの店舗について、在庫明細を最大 1,000 件更新します。
• 初回の在庫登録には initialize を、通常の更新には modify を使います。

注文とレシートを扱う

• 店舗、商品、数量、価格、配送の詳細、支払い方法を収集してから、注文を作成します。
• 注文の詳細を読み取り、複数の注文の現在の状態をまとめて確認します。
• 注文イベントフィードで、新しい注文、状態の変更、発行済みレシートを確認します。
• 注文 ID またはレシート ID を使って、税務レシートを読み取ります。
• 現在の状態とキャンセル理由を確認してから、注文をキャンセルします。

追加の API メソッドを使用する

raw_request は、専用ツールのない /b2b/v1/* メソッドをカバーします。注文の更新、VAT データ、価格表リンク、ピッキング、物流、3PL 配送の操作などが対象です。実際のアカウントデータを変更する可能性があるため、上流 API を理解している技術ユーザー向けです。

完全なスキーマ、レスポンスフィールド、API の不足情報は、ツールリファレンスで確認できます。

小売データの連携方法

フィードではカーソルページネーションを使用します。指定した上限より項目数が少ないページが返された場合、現在の商品、価格表、または在庫のフィードは終了しています。注文イベントフィードは継続的に更新されます。最後のカーソルを保持し、後で次のページをリクエストしてください。

アカウントに対する変更

サーバーは、読み取り専用、書き込み、破壊的な操作について MCP アノテーションを公開します。確認を求めるタイミングや方法は、AI クライアントが決定します。

書き込みを行う前に、対象の店舗、商品 ID、価格表、数量、現在の値、変更後の値をアシスタントに表示するよう依頼してください。書き込みのレスポンスは上流で完全にはドキュメント化されていないため、価格または在庫の更新に成功すると、サーバーは該当データを再度読み取り、現在の値を表示できます。

アクセスの取得

Yango Tech は、インテグレーションマネージャーを通じて小売事業者アカウント用の Bearer トークンを発行します。このリポジトリでは、セルフサービスのトークンポータルについて説明していません。

1. Yango Tech のインテグレーションマネージャーに連絡し、小売事業者用の Bearer トークンを依頼します。
2. YANGO_RETAIL_TOKEN として AI クライアントに追加します。
3. Git には含めず、AI クライアントのシークレットまたは環境変数の設定を通じてのみ共有してください。

本番環境の API ホストは https://api.retailtech.yango.com です。読み取り操作を含め、すべての API 呼び出しは /b2b/v1/* 配下への JSON ボディを含む POST です。

トークンは AI クライアントのローカル設定に保存されます。パスワードと同様に扱い、実際のトークンを含む設定を決してコミットしないでください。

設定

データとテレメトリ

Yango Tech Retail へのリクエスト

サーバーはお使いのマシン上で動作し、設定された Yango Tech Retail API ホストに小売業者のデータを直接送信します。Bearer トークンは、そのホストに解決されるリクエストにのみ付加されます。raw_request でも相対パスのみを受け付け、別のオリジンに解決されるパスは拒否します。

匿名テレメトリー

デフォルトでは、サーバーは usage.gistrec.cloud に技術イベントを送信します。イベントには、サーバーの起動、呼び出されたツール名、起動に失敗した場合の固定の理由コードが含まれます。

イベントには、ランダムなインストール ID、パッケージのバージョン、AI クライアント名とバージョン、Node.js のバージョン、オペレーティングシステムが含まれます。Bearer トークン、小売業者のデータ、ツールの引数、プロンプトが読み取られたり送信されたりすることはありません。 テレメトリーのタイムアウトは 2 秒で、ツールの呼び出しを妨げることはありません。

テレメトリーを無効にするには、次を追加します。

ASKADS_TELEMETRY=0

実装は src/telemetry.ts にあります。

制限とバックグラウンド処理

• 公開 API のクォータは文書化されていません。 公式 Python クライアントは、1 つのトークンとエンドポイントにつき毎秒 5 リクエストに制限しています。これは公開された API の制限ではなく、運用上の目安として使用してください。このサーバーはすべての呼び出しを事前にスロットリングするわけではありません。
• 429 応答は再試行されます。 サーバーは Retry-After がある場合はその値に従い、YANGO_RETAIL_MAX_RETRIES で許可される回数を超えて再試行することはありません。
• 不確実な失敗の後に書き込みを再実行することはありません。 ネットワークエラーおよび 5xx エラーに対する再試行は、副作用のない読み取りにのみ適用されます。不確実な書き込みの後は、再試行する前に現在の注文、価格、在庫を読み取ってください。
• バッチ上限が適用されます。 商品、価格、割引は、1 リクエストにつき最大 100 件まで受け付けます。在庫の更新は最大 1,000 行まで受け付けます。
• バックグラウンドでの監視はありません。 サーバーは AI アプリから呼び出された場合にのみ動作します。アプリがスケジュールタスクに対応している場合は、注文の状態や在庫を定期的に確認できます。
• 自動ロールバックはありません。 更新が成功すると、小売業者のアカウントに即時反映されます。
• 削除は上流 API によって制限されています。 商品と価格はアップサートされます。商品、価格、割引を削除する既知のメソッドはありません。
• 上流の割引サポートは不完全です。 販促期間と割引額に使用する正確なキーは文書化されておらず、割引の一覧表示や削除を行う既知のメソッドもありません。使用前に Yango Tech にペイロードを確認してください。

技術ドキュメント

• MCP 機能カタログ — 各ツールのタスク別ページです。
• すべてのツール — 入力スキーマ、レスポンス、ページネーション、API の不足事項、バッチ上限です。
• 開発 — ローカル環境のセットアップとプロジェクトのチェックです。
• 公開 — パッケージのリリースと MCP カタログへの掲載です。
• npm パッケージ — 公開済みの mcp-yango-retail パッケージです。
• 公式 Yango Tech Python クライアント — この API で利用可能な上流の仕様です。

サポート

バグを見つけた場合や、必要なユースケースが不足している場合は、issue を作成するか、Telegram でご連絡ください。

最後までお読みいただき、ありがとうございます！