alza-mcp について
alza-mcpはAlza.cz向けの非公式MCPサーバーで、AIエージェントによる商品検索やアカウント・注文操作に利用できます。ツールセットで機能を段階的に有効化し、注文送信には一度限りの確認トークンを求めます。
主な機能
- 01商品の検索、詳細、レビューの表示
- 02商品の比較と受取場所の検索
- 03ツールセット単位でカート・アカウント機能を有効化
- 04注文送信に一度限りのトークンを要求
活用シーン
- 01キーワード、価格、在庫で商品を絞り込む
- 02候補商品の価格と仕様を比較
- 03近くのAlzaBoxや店舗を探す
- 04確認後にチェックアウトを完了
MCP 対応
MCPサーバーとして、カタログのスクレイピングとAlzaのモバイル・Web APIを通じて商品、アカウント、チェックアウトのツールを公開します。ツールセットで機能を有効化し、カタログと認証関連のツールが標準で利用できます。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
ツール
18掲載時のツール一覧 · 2 週間前に更新
| パラメーター | 型 | 必須 | 説明 |
|---|---|---|---|
| page | integer | いいえ | 1 始まりの結果ページ（1～50）（Alza がレンダリングしたページネーションに従います）。Alza が実際にレンダリングするページのみアクセスできます。レンダリングされた範囲を超えるページでは、1 ページ目を繰り返すのではなく、結果が返りません。この方法でページを移動しても、スイープがスキャンするページは変わりません（並べ替えでは引き続き 1 ページ目からスキャンします）。 |
| sort | enum | いいえ | 並べ替え順。デフォルトは 'relevance' です。Alza の検索ページはサーバー側の並べ替えパラメーターを無視するため、価格（昇順／降順）および評価順では、最大 3 ページ（約 72 件、Alza の関連度ランキング上位）の結果から候補を収集し、クライアント側で並べ替えます。レスポンスの `candidatesScanned` はスキャンした候補数を示します。'newest' はベストエフォートです（Alza の新着順はクライアント側の JavaScript で実装されているため、関連度順の結果が返されます）。絶対的な価格下限を指定する場合は、`max_price` も渡すか、`category_id` の範囲を絞り込んでください。relevance | price-asc | price-desc | rating | newest |
| limit | integer | いいえ | 返す結果の最大数。デフォルトは 20、最大は 50 です。 |
| query | string | はい | 検索キーワード。必須。例：'iPhone 15 Pro'、'PlayStation 5'、'gaming mouse Logitech'。 |
| filters | array | いいえ | `list_category_filters` の属性フィルター選択項目（`filterable: true` のグループのみ。IDを推測しないでください）。`category_id` が必要です。`producer_ids` と併用できます。形式は2種類です。Checkbox グループ（`filterMode: "value"`）では `{param_id, value_id}`、Slider グループ（`filterMode: "range"`）では `{param_id, min?, max?}` を指定します（画面サイズ、リフレッシュレート、輝度、重量、ポート数など。少なくとも一方の境界値が必要です。単位はグループの `values[].value` を使用します。2026-10-06 にライブ検証済み）。Alza が実際に適用した範囲は `appliedRanges` に返されます。Alza がフィルターを適用できない場合、フィルターなしの結果を返すのではなく、呼び出しはエラーになります。 |
| in_stock | boolean | いいえ | true の場合、現在購入可能な商品だけを残します（商品カードに購入 CTA 'Do košíku'/'Vybrat variantu'（alza.sk：'Do košíka'/'Vybrať variant'）が表示される商品。通知ボタン 'Hlídat'/'Strážiť' が表示されるカードは除外されます）。検索カードの CTA に基づいて判定します。実際の配送日については `get_product` を使用してください。 |
| max_price | number | いいえ | ロケールの通貨での最高価格です。価格を読み取れなかった商品は除外されます。`min_price` 未満にはできません。スキャン済み候補（上位最大約 72 件、3 ページ分。`candidatesScanned` を参照）にクライアント側で適用され、カタログ全体には適用されません。 |
| min_price | number | いいえ | ロケールの通貨での最低価格です。価格を読み取れなかった商品は除外されます。`max_price` を超える値にはできません。スキャン済み候補（上位最大約 72 件、3 ページ分。`candidatesScanned` を参照）にクライアント側で適用され、カタログ全体には適用されません。 |
| category_id | integer | いいえ | 検索対象を特定のカテゴリ ID に限定します。ID の確認には list_categories を使用してください。 |
| producer_ids | array | いいえ | ブランド ID を1つ指定して絞り込みます（配列は最大1件。Alza には複数ブランドのカテゴリ URL がないため、ブランドを比較する場合はブランドごとに呼び出してください）。実際の ID は `list_category_filters` の `brands` から取得してください。`category_id` が必要です。すべてのカテゴリで使用できます。 |
| max_screen_inches | number | いいえ | 画面対角線の最大値（インチ）。サーバー側フィルターと名前ベースのフォールバックの使い分けについては `min_screen_inches` を参照してください。 |
| min_screen_inches | number | いいえ | ディスプレイ製品（モニター、テレビ、ノート PC）の画面対角線の最小値（インチ）。`category_id` が指定され、カテゴリに対角線スライダーがある場合、Alza 独自のサーバー側対角線フィルターを使用します（2026-10-06 にライブ検証済み）。スライダーの実際のサイズに丸められ、結果は `appliedRanges` に報告されます。`filters` と同様、カテゴリ閲覧ページに切り替わるため、`query` は適用されません。`category_id` がない場合は、商品名の先頭にあるサイズを解析する方法にフォールバックします（例：'40" MSI MAG401QR' → 40）。名前がサイズで始まらない商品は除外されます。 |
詳細
alza-mcp-community
AI エージェントに Alza.cz で買い物をさせましょう — 中央ヨーロッパ最大の E コマースストアです。
非公式のコミュニティ開発プロジェクトです。Alza.cz a.s. が作成、推奨、サポートしているものではありません。
alza-mcp-community は、ブラウザーでの商品カタログのスクレイピングと、リバースエンジニアリングしたモバイル／Web API を通じて、Claude（または MCP 対応のエージェント）に Alza へのインターフェースを提供する、非公式の Model Context Protocol サーバーです。商品の検索、詳細情報の取得、レビューの閲覧、匿名データやアカウントデータの利用、カートの管理、配送や AlzaBox での受け取りの選択、チェックアウト内容の確認を行えます。注文の送信は、明示的に発行したワンタイム確認トークンがある場合に限られます。
実際のセッション、カタログツールセットのみ、アカウントなし。再録画：docs/demo-recording.md。静止版：docs/demo.svg。
次のように尋ねてください：「600 Kč 未満で、プロ仕様の最高のホイールクリーナーを探して、プラハで受け取れる場所を教えてください。」 エージェントは search_products → get_product → find_pickup_points を呼び出し、実際の価格と住所を含む正確な回答を返します。
重要
このプロジェクトは非公式であり、Alza.cz a.s. と提携、推奨、後援関係にありません。個人利用／研究利用を目的としたコミュニティ製ラッパーです。デプロイや広範な共有の前に、免責事項をお読みください。
クイックインストール
メモ
alza-mcpから名前が変更されました。 Alza の要請により、Alza の公式製品ではないことが明確になるよう、プロジェクト名はalza-mcp-communityになりました。旧パッケージをインストールした場合は、MCP 設定でalza-mcpをalza-mcp-communityに置き換えてください。~/.alza-mcp/に保存されたログイン情報は引き続き使用できます。
ワンクリックインストール
どちらのボタンも、以下の手動設定と同じ内容をインストールします：npx -y alza-mcp-community。環境変数やシークレットは不要です。npx／npm ではインストール時に postinstall ステップが実行され、Playwright のヘッドレス Chromium（約 92 MB）がダウンロードされ、オプションの curl_cffi 仮想環境がセットアップされます。そのため、初回のインストールには時間がかかりますが、以降の起動は数秒です。.mcpb バンドルと --ignore-scripts を指定したインストールでは postinstall がスキップされます。その場合、Chromium はブラウザーを使う最初の呼び出し時にダウンロードされ（約 30 秒）、仮想環境は作成されません（インストール方法を参照）。Claude Desktop の場合は、最新リリースからワンクリック版の alza-mcp-community-<version>.mcpb バンドルをダウンロードして開くか、以下の JSON 設定を使用してください。
Claude Code
claude mcp add alza --scope user -- npx -y alza-mcp-community
以上です。Claude Code を再起動し、/mcp と入力して確認したら、質問を始めてください。インストール時に postinstall 経由で Playwright のヘッドレス Chromium ブラウザー（約 92 MB）がダウンロードされます。スキップされた場合は、ブラウザーを使う最初の呼び出し時にダウンロードされます（約 30 秒）。
Claude Desktop
~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）に追加します。
{
"mcpServers": {
"alza": {
"command": "npx",
"args": ["-y", "alza-mcp-community"]
}
}
}
アプリを再起動してください。インストール時のダウンロードは同じです。
Cursor / Continue / その他の MCP クライアント
形式は同じです。command: "npx"、args: ["-y", "alza-mcp-community"] を指定します。Stdio トランスポートを使い、どこでも標準の MCP に対応しています。
質問できること
テスト中に記録した実際のセッションです。
あなた： Alza で、500 Kč 前後のプロ仕様のホイールクリーナーを探してください。ディテーラー向けのブランドが希望です。
Claude： （
search_productsで「čistič disků kol」を検索し、sort=rating を指定。その後、有力候補に対してget_productを呼び出す）ライブカタログから選んだトップ 3：
# 商品 ブランド 容量 価格 ★ 1 Sonax Xtreme Full Effect Sonax 🇩🇪 750 ml 559 Kč 4.8 2 Kenotek Wheel Cleaner Ultra Kenotek 🇧🇪 1 L 455 Kč 4.8 3 Auto Finesse Reactive 1L Auto Finesse 🇬🇧 1 L 599 Kč 4.4 おすすめは Sonax Xtreme Full Effect 750 ml です。ディテーラーの定番として広く推奨されています。鉄粉に反応し、ブレーキダストの粒子に触れると紫色に変わるため、効果を目で確認できます。Sonax はドイツの整備工場で定番のブランドで、在庫もあります。
これは、エージェントが 2 件の並列検索を通じて 4 つの MCP ツールを呼び出し、Alza の実データをまとめた例です。SKU を捏造していません。
できること
ドメインツールは 63 個あり（list_toolsets、set_toolset、report_issue を含めると 66 個です）、すべての tools/list 呼び出しで全ツールを列挙すると、その会話で使わない可能性のある数十個のツールがエージェントのコンテキストを最初から圧迫します。そこで、ツールはツールセットにまとめられており、デフォルトでは 2 つだけが有効になっています。これにより、ドメインツール 15 個に加え、2 つのツールセット制御ツールと report_issue が公開されます。
| ツールセット | デフォルトで有効？ | 対応内容 |
|---|---|---|
catalog | ✅ | 検索、商品詳細、並べて比較、レビュー、カテゴリ、受取場所の検索 |
auth | ✅ | OAuth ハンドシェイク、アカウントの状態、ミューテーション用トークンの発行 |
basket_and_checkout | — | カート、配送／受取方法の選択、チェックアウト、注文とキャンセル |
account_management | — | プロフィール、連絡先、住所、登録、認証情報／ID の変更 |
orders_and_payments | — | 注文履歴、支払い方法、注文後の支払い、クレーム、書類 |
reviews_and_subscriptions | — | レビュー、苦情、AlzaSubscription、添付ファイル、EAN 検索 |
watchdogs | — | Alza 標準の値下がり／再入荷監視（一覧表示、設定、削除） |
chat | — | Alza のアプリ内チャットボット |
pc_builder | — | 互換性を確認した PC パーツリスト：pc_build_check、pc_build_suggest |
advanced_raw | — | 型指定のない抜け道である mobile_read |
list_toolsets を呼び出すとすべてのグループを確認でき、set_toolset({id, enabled: true}) を呼び出すと、そのツールセットを有効にしてツールを使えるようになります。たとえば、カートに商品を追加する前に basket_and_checkout を有効にします。これは標準的な MCP の段階的開示です（RegisteredTool.enable()／.disable() により、通常の tools/list_changed 通知が送信されます）。機能が削除されているわけではなく、一度にすべてが表示されないだけです。
問題の報告。 report_issue は、どのツールセットが有効でも常に利用できます。ツールが予期せず失敗したり、明らかに誤ったデータを返したり、Alza の変更によって動作しなくなったりすると、サーバーの指示とエラーメッセージ自体がエージェントにこのツールを案内します。ツールは、バージョン、Node、プラットフォーム、ストアフロント、トランスポート、このセッションで最近発生したツールエラーを含む、機密情報を伏せた下書きと、重複を確認するための gh issue list コマンド、すぐに実行できる gh issue create --repo lukabudik/alza-mcp-community … コマンド、シェルを使えないエージェント向けの、新しい Issue を事前入力したリンクを返します。サーバーが自分で Issue を作成することはありません。エージェントが下書きをあなたに提示し、あなたが同意した場合にのみ、あなたの GitHub アカウントから Issue を作成します。認証情報（Cookie や API キーを含む）、メールアドレス、電話番号、UUID、URL のクエリ値、アカウント ID、ホームディレクトリのパスは自動的に伏せられ、最近のエラーにはルートとステータスだけが残ります。引数が無効な場合や、製品が不明な場合には、この案内は表示されません。
カタログツール：
| ツール | 用途 |
|---|---|
search_products | キーワード検索、価格／在庫／画面サイズのフィルター、範囲が限定されたクライアント側での並べ替え（価格フィルターと並べ替えは上位約72件の候補に適用されます。pageSizeは実際のページあたりの商品カード数で、hasMore／nextPageを使ってページを切り替えます。価格範囲が逆になっている場合や、クエリが空の場合は拒否されます）。ブランド／属性フィルターではカテゴリページが使われ、queryは無視されます |
get_product | 1商品の詳細情報（価格、在庫状況、ブランド、画像、URL） |
compare_products | 2～6商品を並べて比較します。価格、在庫状況、評価、すべての仕様項目を1つの表にまとめます。クライアントが対応している場合は、MCP サンプリングによる判定を summarize: trueで任意に取得できます |
get_product_reviews | レビューAPIから取得した総合評価、レビュー数、個々のレビュー（投稿者、日付、評価、本文、長所／短所）を新しい順に返します。レビューの一覧は総レビュー数より長い場合があります（他のストアのレビューも含まれているようです） |
recommend_alternatives | 商品より安い商品、評価の高い商品、または同じブランドの商品を代替候補として提案します（Alza独自の代替商品リストを使用し、利用できない場合は同じカテゴリ内で検索します） |
find_pickup_points | 5桁の郵便番号をもとに、最寄りのAlzaBoxロッカーとAlzaShopショールームを距離順にまとめて返します。営業時間も含まれ、カートは不要です。郵便番号は公開されているOpenStreetMap Nominatimサービス（nominatim.openstreetmap.org）でジオコーディングされるため、正規化された郵便番号と国がAlzaではなく第三者に送信されます。結果は1週間キャッシュされます。特定の商品がAlzaBoxに入るかどうかは判定できません。その場合はdelivery_optionsを使用してください |
list_category_filters | カテゴリのブランド（brands[].valueId）と、最新のID／件数を含む属性ファセットを返します。category_idとともにproducer_idsまたはfiltersを使用してください（チェックボックス式ファセットには{param_id, value_id}、画面サイズやリフレッシュレートなどのスライダー範囲には{param_id, min?, max?}を指定します）。サポートされていないURLフィルターはエラーになります（チェックボックスの値が使用できるのは、Alzaがその値のランディングページを公開している場合のみです。HDMIは対応していますが、モニターのパネルタイプと解像度は対応していません） |
get_deals | alza.czおよびalza.skの割引商品を返します。現在購入できる価格（Alza dniの「コードを使って購入」のようなプロモーションコード価格も含み、promoCode／promoPercentで示されます）、通常価格と以前の取り消し線付き価格、バッジ（SUPER CENA、ZĽAVNENÉ -N %、CENOVÁ BOMBA、NOVINKA）、割引額、月々の分割払い、AlzaPlus+会員／非会員価格、および取得した価格から算出した割引率が含まれます。priceCheckは、コード適用後の価格が通常価格×（1 − 割引率）と一致しないカードにフラグを付けます。ストアフロントのcategory_idまたは任意の一覧ページのurl（例：/monitory-23-a-24/alza-dni/18848792-e39.htm）をスキャンし、新しい商品が見つからなくなるまでページリンクをたどります（最大5ページ）。指定がない場合は人気カテゴリをスキャンします。Cloudflareがヘッドレスブラウザーにチャレンジを表示する場合は、ALZA_CDP_URLを設定して独自のChromeを使用してください |
list_categories | 最上位カテゴリ、またはparent_idが指定された場合は実際のサブカテゴリを返します。返されたIDをsearch_productsに渡してください |
autocomplete | プレーンHTTPで検索ボックスの候補を取得します（ページのレンダリングはありません）。ID／コード付きのフレーズ、カテゴリ、ブランド、商品が含まれます。search_productsの前に、曖昧なチェコ語のクエリを絞り込むために使用してください |
product_by_ean | バーコード／EANでカタログ商品を検索します（アプリのカメラによるバーコードスキャンAPI、AT3を使用。読み取り専用で、アカウントは不要です。reviews_and_subscriptionsを有効にしてください） |
PCビルダーのツール（pc_builderを有効にしてください）：
| ツール | 用途 |
|---|---|
pc_build_check | パーツ一覧（Alzaコード）をチェックします。ソケット、RAMの世代／スロット、PSUのワット数と余裕、GPUの長さ、クーラーの高さ／ラジエーターとケースの適合性、フォームファクター、ディスプレイ出力を確認します。価格、合計金額、在庫状況、および各ルールで使用した仕様値と判定を返します |
pc_build_suggest | Alzaの実際のコンポーネントカテゴリから、CZK予算内で互換性のある構成を提案します（ゲーミング／ワークステーション／オフィス、固定するfixed_parts、上限付きの詳細情報取得） |
アカウントおよびチェックアウトのツール：
| ツール | 目的 |
|---|---|
auth_start | モバイル API の OAuth PKCE 認証 URL を作成します |
auth_exchange | 返された認証コードをモバイル API のトークンと交換します |
auth_discovery | identity.alza.cz から最新の OIDC メタデータを読み取ります |
mobile_read | APK で確認されたカタログ、ナビゲーション、アカウント、注文履歴、リスト、支店、代替商品、バスケット、費用見積もり、ウェブの支払い後ダイアログ、ウェブの郵便番号（WCF の GetZipCodes に相当）、チャットボットナビゲーションの機能を読み取ります |
prepare_mutation | リクエストを送信せずに、固定されたソース確認済みの変更用のワンタイムトークンを作成します。このトークンはアクションと正確な呼び出し引数（payload）に紐付けられ、有効期限は 5 分です |
mutate_list | トークンを使用して、検証済みの APK 確認済み低リスク変更（リスト、クーポン、バスケット、国／ISIC、ギフト、ウォッチドッグ、フィードバック、ディスカッション）を実行します |
account_status | モバイル API のアクセストークンが読み込まれているか確認します |
cart | 現在のカートと合計金額を読み取ります |
add_to_cart | Alza コードで商品をカートに追加します |
delivery_options | APK の getDeliveryPaymentGroups エンドポイントから、配送と AlzaBox／受け取りオプションを読み取ります |
select_pickup_point | 名前とは異なり、getDeliveryAssociations から配送と支払いの対応関係（各配送に利用できる支払い方法と、それぞれの配送料）を返します。受け取り場所は選択しません。2026-10-06 に認証済みカートで再テスト済みです。AlzaBox を選ぶには、web_pickup_places → web_place_order の順に使用し、parcel_shop_id を指定してください。 |
checkout_preview | チェックアウトをプレビューし、ワンタイム確認トークンを返します |
cancel_order | キャンセルフォーム、理由、ワンタイムの prepare_mutation トークンを使用して、注文の一部をキャンセルします |
place_order | プレビュートークンと必須の API ペイロードが指定された場合にのみ、モバイル API の注文シーケンスを実行します |
web_pickup_places | ウェブチェックアウトで配送先を選択するため、ウェブの受け取り場所ファミリー（AlzaBox／支店／24 時間利用可能状況、場所のリスト、場所の詳細）を読み取ります（読み取り専用） |
web_add_to_cart | 商品をウェブの最新 HATEOAS バスケット（basket/v1/items、訪問者キーで識別）に追加し、抽出したバスケット ID を返します |
web_cart | web_add_to_cart で取得したバスケット ID の、ウェブチェックアウトの最新カート状態と商品リストを読み取ります（読み取り専用） |
chat_navigation | 最新のチャットボット HATEOAS ナビゲーション（chatbotapi.alza.cz、サーバー提供のチャットアクション）を読み取ります（読み取り専用） |
chat_send | ページコンテキストを使用してチャットボットセッションを開始または継続します（セッション単位、訪問者キーで識別。{configuration, showChat} を返します） |
ユーザー管理、支払い、注文、購入後のツール：
| ツール | 目的 |
|---|---|
profile | 認証済みのプロフィールとアドレス帳を読み取ります（APK getUserData） |
contacts | アカウントの連絡先リストを読み取ります |
register | 新しいAlzaアカウントを登録します（認証情報を伴う、ワンタイムトークン） |
address_upsert | サーバー提供の住所フォームを使って配送先住所を作成・編集します |
address_delete | 住所ごとのアクションを使って配送先住所を削除します |
address_search | 検証済みのgetZipCodes検索、または提供されている場合はプロフィールのaddressSearchActionを使って郵便番号・市区町村を検索します（読み取り専用） |
payment_methods | APKの配送・決済グループエンドポイントから決済方法を一覧表示します |
after_order_payments | 注文の一部に対する注文後の決済オプションを一覧表示します |
pay_after_order | 注文後の決済を実行します（APK AfterOrderRequestBody、ワンタイムトークン） |
web_place_order | ライブ検証済みの従来型Web WCFパイプライン（SaveOrder2→3、113ゲートの再試行、CheckOrder4、SendOrder4、ワンタイムトークン）を使って注文します。モバイルのsendOrder3が500を返す間、動作する注文送信経路です |
web_pay_after_order | ライブ検証済みのWCF CreateAfterPaymentを使ってWeb上の注文後決済を実行します（ワンタイムトークン） |
order | 数値のuser_idとorder_idを使ってユーザーの注文を読み取ります（任意で一部の詳細、マイルストーン、請求書参照を指定可能） |
review_submit | サーバー提供のレビューフォームを使って商品レビューを送信します |
complaint_claims | user_idを使って有効またはアーカイブ済みの保証請求を一覧表示します（K1、読み取り専用） |
subscription_overview | user_idを使ってアカウントのサブスクリプションセクションを読み取ります（ナビゲーションのuserSubscriptionリンク）（S1、レスポンス形式はまだライブ検証されていません） |
subscription_activate | AlzaSubscriptionを有効化します（ワンタイムトークン） |
subscription_update_installment | 分割払いプランを変更します（ワンタイムトークン） |
upload_attachment | サーバー提供のマルチパートアクションを使って画像添付ファイルをアップロードします（ワンタイムトークン） |
order_search | 検索語を使ってアカウントの注文を検索します（OR6、読み取り専用） |
order_archive | アカウントのアーカイブ済み注文を読み取ります（OR7、読み取り専用、「Skrýt zrušené」キャンセル済み注文の表示・非表示切り替え） |
order_document | サーバー提供のhrefから注文の請求書・書類をダウンロードします（OR10、Alzaホストファミリーにオリジンを検証。本文はstructuredContentのみで返されます） |
gdpr_info | GDPRセクションとエクスポートダイアログを読み取ります（A17、読み取り専用 — データエクスポートの送信先を確認できます） |
claim_detail | detailActionリンクから1件の保証請求の詳細を読み取ります（K2、読み取り専用、保証請求ルートに固定） |
change_password | アカウントのパスワードを変更します（A14、ワンタイムトークン、すべてのデバイスからユーザーをログアウトさせます） |
two_factor_set | SMSによる2要素認証を有効化・無効化します（A15、ワンタイムトークン） |
phone_change | 連絡先電話番号を変更します（A16、ワンタイムトークン） |
email_change | 連絡先メールアドレスを変更します（A16の関連機能、ワンタイムトークン） |
delete_account | アカウントを削除します（A18、ワンタイムトークン、取り消し不可 — 使い捨てアカウントのみ） |
watchdog_list | アカウントのAlzaウォッチドッグを一覧表示します。価格下落と在庫復活のアラートが対象です（B9a、読み取り専用、出力にメールアドレスは含まれません） |
watchdog_set | 商品にウォッチドッグを設定します（max_priceおよび／またはtrack_stock）。条件を満たすとAlzaからアカウントにメールが届きます（B9、ワンタイムトークン） |
watchdog_delete | watchdog_idまたはcommodity_idを使ってウォッチドッグを削除します（B9b、ワンタイムトークン） |
影響の大きい変更操作にはワンタイム確認トークンが必要です（モバイルのplace_orderにはcheckout_preview、その他の保護対象の変更操作にはprepare_mutation）。ルートの全一覧、公開範囲の判断、検証ラベルはdocs/mobile-endpoint-coverage.mdに記載されています。
OAuth サインインは MCP の外部で行われます。auth_exchange は返されたコードを交換し、サーバーはアクセストークンとリフレッシュトークンをメモリに保持するか、設定されたトークンファイルから読み込みます。有効期限が切れたアクセストークン（または JWT の exp まで 60 秒以内のトークン）は、次のアカウント呼び出しの前に更新され、並列呼び出しでは更新処理が共有されます。account_status は expiresAt／expired を報告します。トークンがトークンファイルから読み込まれた場合、更新後のトークンはそのファイルに書き戻されます（アトミックに、モード 0600）。これにより、再起動後に古いトークンで開始することを防げます。プロセス内で auth_exchange したトークンはメモリに保持されます。
サインイン後に「Při přihlášení došlo k chybě.」と表示されますか？ サインイン自体は通常成功しています。Alza は
alza://identity?code=…&state=…にリダイレクトしますが、デスクトップブラウザーでは開けないため、ページが停止し、Alza のログインページで 40 秒のタイマーがこのメッセージを表示します。サインインする前に DevTools を開き、Network → Preserve log を有効にします。サインイン後、リダイレクトのLocationヘッダー、またはalza://の起動失敗に関する Console エラーから、alza://identity?code=…URL をコピーします。URL 全体をcodeとしてauth_exchangeに渡します。コードはすぐに期限切れになるため、直ちに交換してください。登録ツールと認証情報変更ツールでは、パスワードや確認コードを引数として受け付けますが、ワンタイム確認トークンで保護されています。アカウント／カート／注文ツールは API リクエストを送信し、チャレンジがあった場合はブラウザー経由のリクエストにフォールバックできます。チェックアウトフォームの自動操作は行いません。
チェックアウトの経路： web_place_order は、add_to_cart で追加したカートを送信します。その前に delivery_options と、カート単位の web_pickup_places の検索を行います。web_add_to_cart → web_cart の HATEOAS バスケットは別のものです。記録されたライブテストでは、モバイルの place_order 経路はサーバー側の HTTP 500 によりブロックされました。従来の WCF 経路はライブ環境で検証済みです。日付付きの根拠については、既知の制限事項を参照してください。
モバイル API の環境変数：
| 環境変数 | 用途 |
|---|---|
ALZA_API_BASE_URL | モバイル API のベース URL。デフォルトは https://www.alza.cz |
ALZA_VISITOR_ID | 任意の匿名ビジター UUID。指定しない場合はプロセスごとに生成されます |
ALZA_OAUTH_CLIENT_ID | auth_start、auth_exchange、トークン更新で使用する OAuth クライアント ID。デフォルトは alza_Android。ALZA_OAUTH_CLIENT_SECRET と合わせて変更してください |
ALZA_OAUTH_REDIRECT_URI | OAuth リダイレクト URI。デフォルトは alza://identity |
ALZA_COUNTRY / ALZA_CULTURE | OAuth 認可 URL で送信する countryCode / culture。デフォルトは ALZA_BASE_URL のストアフロントの値（alza.cz では CZ / cs-CZ、alza.sk では SK / sk-SK） |
ALZA_OAUTH_AUTHORITY | OAuth オーソリティ。デフォルトは https://identity.alza.cz |
ALZA_OAUTH_CLIENT_SECRET | alza_Android OAuth クライアントは機密クライアントです。トークンリクエストには APK に埋め込まれたシークレットが必要です（デフォルトはソースで確認済みの値です。パブリッククライアントの場合は "" を設定して省略してください）。auth_exchange とトークン更新で使用します |
ALZA_CLIENT_SECRET | PKCE 交換スクリプト（scripts/e2e-order-payment.browser.mjs exchange、scripts/alza-auth-exchange.mjs）で使用する同じシークレット |
ALZA_TOKEN_FILE | scripts/alza-auth-login* / scripts/alza_auth_login.py が書き込む JSON トークンストア（デフォルトは ~/.alza-mcp/tokens.json。自動読み込みを無効にするには none を設定してください）。サーバーは、このファイルから読み込んだトークンを更新した後、ファイルをアトミックに書き換えます（0600）。none の場合、読み込みも書き込みも行いません |
さらに：
- 📦 リソース —
alza://product/{code}を使うと、エージェントは URI として商品を読み取れます。 - 💬 プロンプト —
/find-productは、ガイド付きのショッピングを支援します。 - 🌍 複数ロケール対応 — カタログのロケール設定は、
ALZA_BASE_URLを介してalza.cz、.sk、.hu、.at、.de、.co.ukに対応します。API 呼び出し（オートコンプリート、個別のレビュー、代替商品、ナビゲーション、チャットボット、アカウントの読み取り）では、そのストアフロントのcountryとAccept-Languageが送信されます。webapi.alza.czとchatbotapi.alza.czはすべてのストアフロントに対応し、countryに基づいて振り分けます（alza.sk で 2026-10-12 にライブ検証済み）。アカウント／チェックアウトの検証は CZ のみを対象としており、アカウントへの書き込み（2FA、電話番号、メール、アカウント削除、ウォッチドッグ、バスケットのロック解除）では、引き続きcountry=CZが送信されます。
設定
すべて任意です。alza-mcp-community は設定不要ですぐに動作します。
| 環境変数 | デフォルト | 用途 |
|---|---|---|
ALZA_BASE_URL | https://www.alza.cz | ロケールを切り替えます：https://www.alza.cz、.sk、.hu、.at、.de、.co.uk |
ALZA_CDP_URL | 未設定 | 管理対象の Chromium を起動する代わりに、CDP を介してすでに実行中の Chrome に接続します。既存のブラウザーセッションを再利用します。インストール時のダウンロードをスキップするには、別途 ALZA_MCP_SKIP_INSTALL=1 を設定してください。Chrome を --remote-debugging-port=9222 で起動し、ALZA_CDP_URL=http://localhost:9222 を設定してください。 |
ALZA_TOOLSETS | 未設定 | デフォルトの catalog + auth に加えて、起動時に有効にするツールセットをカンマ区切りで指定します（basket_and_checkout,orders_and_payments または all）。set_toolset の後にツールリストを再読み込みしない MCP クライアント（notifications/tools/list_changed を無視するクライアント）向けです。これにより、最初の tools/list からバスケット、注文、アカウントのツールが表示されます。ID：list_toolsets を参照してください。不明な ID を指定すると、サーバーは起動時に停止します。 |
ALZA_HEADLESS | true | false に設定すると、スクレイピングと API フォールバックに使用するブラウザーを表示します。OAuth／MFA／決済の操作は引き続きユーザーが制御します。 |
ALZA_IDLE_TTL_MS | 180000 | ツール呼び出しがない状態がこのミリ秒数続くと、ヘッドレス Chromium を終了します。メモリに制約のあるマシンでは値を小さくしてください。短時間に多くの呼び出しを行い、再起動の遅延を避けたい場合は、値を大きくするか、非常に大きな値を設定して無効にしてください。 |
ALZA_PROXY_URL | 未設定 | HTTP(S) または SOCKS5 プロキシ（http://user:pass@host:port、socks5://host:port）を介して Alza のトラフィックをルーティングします。たとえば、このマシンの IP が Cloudflare のチャレンジを受ける場合に（データセンターや CI の IP では発生します）、住宅用プロキシを指定します。管理対象の Chromium と curl_cffi サイドカーで使用されます。設定されている間、アカウントスタックはプロキシを経由しない通常の fetch にフォールバックせず、管理対象のブラウザーのみを使用します。また、サイドカーが無効（ALZA_CF_TRANSPORT=0）の場合、OAuth、AppAction、ドキュメントのリクエストは直接送信せずに拒否されるため、プロキシ障害は迂回されずに報告されます。無効な値を設定すると、サーバーは起動時に1行のエラーを出して停止します。プロキシ経由にならないもの：ALZA_CDP_URL のブラウザーとマルチパートアップロード（upload_attachment）。サイドカーでは処理できません。 |
ALZA_DEBUG | false | 詳細な stderr ログを有効にします（ALZA_LOG_LEVEL=debug と同等です）。 |
ALZA_LOG_LEVEL | info | stderr に出力する最小ログレベル：debug、info、warn、error |
ALZA_CF_TRANSPORT | 有効 | 0 に設定すると、Chrome フィンガープリントを使用する curl_cffi サイドカーを無効にします（その場合、アカウントスタックは通常の fetch とブラウザーを使用します）。 |
ALZA_CF_PYTHON | 自動 | curl_cffi がインストールされている Python インタープリターを指定します。デフォルトの検索順序：この変数、パッケージ内の .venv-cf（Windows では bin/python、または Scripts\python.exe）、次に python3（Windows では python／py） |
インストール方法と curl_cffi の venv
Chrome フィンガープリント用サイドカーには、curl_cffi（テスト済みの範囲である >=0.16,<0.17 に固定）を含む Python venv が必要です。各インストール方法で実行される内容は次のとおりです。
| インストール方法 | Chromium headless-shell | curl_cffi venv |
|---|---|---|
npx -y alza-mcp-community / npm i alza-mcp-community（Linux、macOS、WSL、MSYS bash） | postinstall によってダウンロードされます | bash と python3（venv を含む）があれば postinstall によって作成されます。作成に失敗すると、途中まで作成された venv は削除されます |
ALZA_MCP_SKIP_INSTALL=1 または PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 | スキップされます（必要に応じて実行時にダウンロードされます） | 引き続き作成されます |
ALZA_MCP_SKIP_VENV=1 | ダウンロードされます | スキップされます |
--ignore-scripts、または .mcpb バンドル | 必要に応じて実行時にダウンロードされます | 作成されません。--ignore-scripts の場合は、npx -y alza-mcp-community --setup-cf（クロスプラットフォーム対応で、bash は不要）を実行するか、パッケージディレクトリで bash scripts/ensure-cf-venv.sh を実行してください。.mcpb バンドルの場合は、--setup-cf を一度実行し、curl_cffi がインストールされている任意のインタープリターを ALZA_CF_PYTHON に指定してください |
このリポジトリを自分でチェックアウトした場合（npm ci） | スキップされます | スキップされます。npm run setup:cf と npx playwright install chromium --only-shell を自分で実行してください |
venv がなくてもサーバーは動作します。アカウントスタックはプレーンな fetch にフォールバックし、Cloudflare からチャレンジを受ける頻度が高くなります。Windows の場合、インタープリターの検索では .venv-cf\Scripts\python.exe、python、py も試されます。また、bash スクリプトは通常の Windows では実行されません。代わりに npx -y alza-mcp-community --setup-cf を使用してください。これは Node で実装されており、py -3／python／python3 を検索し、パッケージディレクトリに python -m venv .venv-cf を実行して、curl_cffi>=0.16,<0.17 をインストールし、インポートを検証して、成功または失敗を出力し、終了コード 0／1 で終了します。冪等性があり、pip が失敗した場合は途中まで作成された venv を削除し、ALZA_MCP_SKIP_VENV=1 を尊重します。また、自動的には実行されません（サーバーは実行時にパッケージをインストールしません。サイドカーを利用できない場合は、実行するよう促すヒントを一行だけログに記録します）。venv はコマンドを実行したパッケージのコピー内に作成されます（npx の場合はキャッシュディレクトリです。新しいバージョンの取得時または npm キャッシュの消去時に置き換えられるため、その場合は --setup-cf を再実行してください）。そのため、独自のディレクトリを持つ .mcpb バンドルからは利用できません。実行後、バンドルの環境で ALZA_CF_PYTHON に、出力されたインタープリター（または curl_cffi がインストールされている任意のインタープリター）を設定してください。Windows パス（Scripts\python.exe、py -3）は、モックプロセスのみで単体テストされており、実際の Windows マシンでは未検証です（実機テストは未実施です）。
HTTP での実行（Streamable HTTP）
デフォルトは stdio で、上記のインストール例でも stdio を使用します。たとえば URL のみを受け付けるクライアント向けに、代わりに同じサーバーを MCP Streamable HTTP で提供するには、次のようにします。
npx -y alza-mcp-community --http --port 3000 # or: ALZA_TRANSPORT=http ALZA_HTTP_PORT=3000 npx -y alza-mcp-community
# → MCP endpoint http://127.0.0.1:3000/mcp, health check http://127.0.0.1:3000/healthz
claude mcp add --transport http alza http://127.0.0.1:3000/mcp
HTTP では、ネットワークエンドポイントには複数のクライアントからアクセスできるため、サーバーは stdio よりも厳格です。
- デフォルトではカタログのみです。 読み取り専用の匿名ツールセットのみ使用できます。
catalog（有効）とpc_builder（set_toolsetで有効化）です。それ以外のすべてのツールセット（auth、basket/checkout、account、orders/payments、reviews/subscriptions、chat、advanced_raw）はロックされています。list_toolsetsはロックされている理由とともに表示し、set_toolsetは有効化を拒否します。これらのツールは実際の Alza アカウントにサインインして操作するもの（注文、支払い、認証情報）なので、共有エンドポイントで誤って提供してはいけません。有効にするにはALZA_HTTP_ENABLE_ACCOUNT=1を設定してください。 - MCP セッションごとにサーバーは 1 つです。 各
Mcp-Session-Idには、独自のツールセット状態、OAuth トークン、一度限りの確認トークンを持つ専用のサーバーインスタンスが割り当てられます。ALZA_HTTP_ENABLE_ACCOUNT=1の場合、Alza の Cookie を保持するため、各セッションには専用のブラウザーコンテキストと Chrome フィンガープリントのサイドカーも割り当てられます。セッションは 30 分間操作がないと期限切れになります。 - トークンファイルは使用しません。
ALZA_TOKEN_FILE（~/.alza-mcp/tokens.json）には 1 人分のログイン情報が保存されるため、HTTP モードでは読み込みません。各セッションはauth_start→auth_exchangeでサインインします。単一ユーザーのローカルホスト環境では、ALZA_HTTP_ENABLE_ACCOUNT=1と併せてALZA_HTTP_ALLOW_TOKEN_FILE=1を設定できます。この場合、すべてのセッションがそのアカウントでサインインした状態で開始されるため、共有ホストでは絶対に使用しないでください。すべてのセッションは同じリフレッシュトークンから開始します。Alza はリフレッシュ時にトークンをローテーションする場合があります（2026-09-10 に報告あり。2026-10-07 の実行では同じリフレッシュトークンが 6 回返されたため、ローテーションは保証されませんが発生する可能性があるものとして扱ってください）。その場合、最初にリフレッシュしたセッションによって、他のセッションが保持するコピーは無効になります（そのセッションではauth_start→auth_exchangeが必要になります）。各セッションはリフレッシュ後のトークンをトークンファイルに書き戻すため、再起動すると最新のトークンが読み込まれます。このモードでは、同時にアクティブにするセッションは 1 つにしてください。 - デフォルトではローカルホストのみです。
127.0.0.1にバインドし、HostまたはOriginがループバック名でないリクエストは拒否します（DNS リバインディング対策）。認証機能や TLS は組み込まれていません。別のアドレスにバインドする場合（--host 0.0.0.0）、両方に対応するリバースプロキシの背後に配置し、ALZA_HTTP_ALLOWED_HOSTSを設定してください。
| 環境変数／フラグ | デフォルト | 用途 |
|---|---|---|
--http、ALZA_TRANSPORT=http | stdio | Streamable HTTP 経由で提供します |
--help、--version（-h、-v） | 使用方法またはバージョンを表示して終了します | |
--port N、ALZA_HTTP_PORT（または PORT） | 3000 | リッスンするポート（0 を指定すると空きポートが選ばれます） |
--host H、ALZA_HTTP_HOST | 127.0.0.1 | バインドアドレス |
ALZA_HTTP_ALLOWED_HOSTS | ループバックにバインドする場合はループバック名、それ以外はチェックなし | Host／Origin で許可するホスト名（カンマ区切り） |
ALZA_HTTP_ENABLE_ACCOUNT | オフ | 認証／アカウント／チェックアウト／注文／支払いのツールセットをロック解除します（セッションごとにログイン） |
ALZA_HTTP_ALLOW_TOKEN_FILE | オフ | ALZA_TOKEN_FILE もすべてのセッションに読み込みます（単一ユーザー専用。ALZA_HTTP_ENABLE_ACCOUNT が必要） |
ALZA_HTTP_MAX_SESSIONS | 50 | 同時セッション数の上限（超過すると HTTP 503） |
ALZA_HTTP_SESSION_IDLE_MS | 1800000 | リクエストがない状態がこの時間続くとセッションを終了します（GET／SSE ストリームを開いたままのセッションは終了しません） |
ALZA_HTTP_REQUEST_TIMEOUT_MS | 30000 | クライアントがリクエスト全体を送信するまでの時間（ヘッダーはその半分）。超過すると HTTP 408 になります。ツール呼び出しや GET／SSE ストリームを含むレスポンスには制限がありません |
ALZA_HTTP_MAX_CONNECTIONS | 256 | 開いている TCP 接続の上限（SSE ストリームも含む）。上限を超える接続は切断されます |
ホスティングはまだサポートされていません。 ホスト型エンドポイント（Vercel mcp-handler、Fly、Railway、…）は今後の対応事項です。主な障害はトランスポートではなく Cloudflare です。Alza は Cloudflare Bot Management の背後にあり、ヘッドレスブラウザーと curl_cffi サイドカーはどちらも住宅用 IP からは通過できます（実環境で検証済み）が、データセンターの IP からはチャレンジを受ける可能性が大幅に高くなります。ホスト型インスタンスでは、おそらく住宅用プロキシ（ALZA_PROXY_URL）か、ブラウザー・アズ・ア・サービス（たとえば ALZA_CDP_URL 経由の Browserbase）が必要になります。毎日のカナリアテストで実行される GitHub ホスト型のジョブを見ると、この問題が分かります。Cloudflare の対話型チャレンジが表示されます。ホスト側で必要なその他の要件は、イメージ内の Chromium と curl_cffi を含む Python、アカウントセッションごとに 1 つのブラウザーを実行できる十分なメモリ、スティッキーなルーティング（セッションは 1 つのプロセスのメモリ内に保持されます）、エンドポイント前段での認証です。マルチユーザー環境でアカウントのツールセットを有効にする場合は、ロックされた状態を維持してください。 |
Pi エージェントとの統合
ローカルビルドを pi のグローバル MCP 設定（~/.pi/agent/mcp.json）に登録します。
{
"alza": {
"command": "node",
"args": ["/absolute/path/to/alza-mcp-community/dist/index.js"]
}
}
/reload を実行します（または mcp connect alza を実行します。ゲートウェイが stdio プロセスを再起動するため、新しくビルドした dist/ は /reload なしで反映されます）。ゲートウェイは alza_ プレフィックス付きでツール（ドメインツールに加えて list_toolsets／set_toolset／report_issue を含みます。set_toolset を呼び出すまでは catalog と auth のツールセットのみが有効です）を公開します（alza_search_products、alza_get_product、alza_cart、…）。認証情報は ~/.alza-mcp/tokens.json から自動的に読み込まれます。両方のモードで検証済みです。（a）ゲートウェイ経由のセッション内実行では、検索／フィルター／詳細表示、認証済みの商品追加、不正なクーポンを使った往復処理で、サーバー側の err:1 エンベロープが返されます（docs/live-evidence/pi-integration-2026-09-10.md）。（b）ヘッドレス（pi -p による単発プロンプト）では、エージェントが alza_* ツールを検出し、適切な引数で search_products を呼び出して、在庫のある最安商品を正しく報告します（docs/live-evidence/headless-pi-2026-09-12.json）。2026-09-13 の再実行では、カタログ検索での価格昇順ソート、認証済みアカウントの一連の処理（account_status と cart）、一度限りの変更トークンのフロー（prepare_mutation）という、さらに 3 つのヘッドレスシナリオが追加されています。すべて docs/live-evidence/headless-pi-2026-09-13.json に記録されています。
仕組み
Alza には一般消費者向けの公開 API がありません。このプロジェクトでは、Android アプリの REST 機能（APK から復元したルート名と DTO）と、ウェブサイト独自のチェックアウト処理をリバースエンジニアリングしています。どちらもサポート対象でも、ドキュメント化されたインターフェースでもないため、予告なく変更されたり、動作しなくなったりする可能性があります。
Cloudflare Bot Management。 Alza はその背後にあり、通常の HTTP クライアントには HTTP 403 を返します。このサーバーは、ヘッドレス Chromium（カタログのスクレイピング）と、Chrome のフィンガープリントを使う HTTP サイドカー（scripts/cf-transport.py。curl_cffi を使って Chrome の TLS／HTTP2 フィンガープリントを偽装）という 2 つの方法でこれを回避します。これはボット対策措置の回避にあたり、Alza の利用規約で禁止されている可能性があります。サイドカーとセットアップスクリプトは npm パッケージに含まれており、postinstall では curl_cffi の仮想環境のセットアップが試みられます。これは引き続き任意です。Python または curl_cffi がない場合、アカウント関連のスタック（OAuth サインインを含む）は通常の fetch にフォールバックし、同一オリジンの API 呼び出しではブラウザーも使用します。状態を変更するリクエスト（POST/PUT/PATCH/DELETE）は、サイドカーが送信していない場合に限り、別の方法で再送されます。サイドカーが送信後に失敗した場合（タイムアウト、接続エラー）、注文、支払い、アカウント変更を二重に送信するのではなく、結果が不明であることをツールが報告します。使用する前に、免責事項とSECURITY.mdを参照してください。
リンクのアトリビューション。 カタログツールが返す商品、カテゴリ、おすすめのリンク（search_products、get_product、compare_products、recommend_alternatives、get_deals、autocomplete、list_categories、pc_build_*、watchdog_list、および alza://product/{code} リソース）には、Alza の要望により utm_source=alza-mcp-community&utm_medium=mcp が付与されます。これにより、Alza はこのサーバー経由の訪問を把握できます。パラメーターが追加されるのは、ユーザーに表示される Alza ストアフロントへのリンクのみです。サーバーから Alza へのリクエスト、サインイン、支払い、API、PDF、画像の URL、およびアカウントとチェックアウトのツールの生のレスポンスにはタグが付与されません。ほかのデータは追加されません。
任意のルートを指定できる汎用ツールは公開されていません。対象範囲は次のとおりです。
- 対象外：管理者ログインルート、テレメトリ／監査ルート、デバイストークンおよび匿名アクティビティのルート、外部決済サービスへの引き継ぎ（Klarna、Google Pay）、およびクイック注文の支払い関連ルート（対象範囲のマトリックスでは
blockedと記載）。 - 対象：ワンタイムトークンを使用する注文の確定とキャンセル、アカウント登録、認証情報／本人情報の変更（パスワード、2FA、電話番号、メールアドレス、アカウント削除 —
delete_accountは取り消せません）。 - サーバー駆動のアクション URL は、確認済みのレスポンスで返された場合に限り、オリジン検証済みの
AppActionExecutorを介して実行されます（GET/POST、パスの許可リスト、ツールごとのルートファミリーとメソッド、認証情報／支払い／注文ルートおよび GET による書き込みルートの拒否リスト、機密フィールドのブロックリスト、ワンタイム確認トークンを適用）。任意の MCP URL として受け付けることはありません。
メソッド、DTO、前提条件、副作用、公開範囲、検証状況を含む、全 12 ファミリーのルート一覧はdocs/mobile-endpoint-coverage.mdで管理されています。
従来のカタログとの互換性には、引き続き元のページアダプターを使用します。
- 検索では
/search.htm?exps=...に移動し、.browsingitemカードをスクレイピングします。 - 商品の詳細は、ページの JSON-LD から取得します。
- レビューには JSON-LD の集計評価を使用します。
- 受け取り場所では、支店データとジオコーディングを組み合わせます。
- プロセスごとのキャッシュは引き続き有効です。
画像、フォント、アナリティクスのリクエストは、ルートレベルでブロックされます。カタログページではスクリプトが読み込まれ、並べ替えた検索では複数の結果ページが取得される場合があります。一般的な所要時間：検索は約 2 秒、商品詳細はキャッシュが温まった状態で約 5 秒です。
┌────────────────────────────────────────────┐
│ stdio transport (npx alza-mcp-community) │
├────────────────────────────────────────────┤
│ MCP tools / resources / prompts │
│ grouped into toolsets (toolsets.ts) │
├────────────────────────────────────────────┤
│ Domain: catalog · reviews · pickup · │
│ mobile-account (cart/checkout/…) │
├────────────────────────────────────────────┤
│ Infra: │
│ • browser (Playwright, CDP) │
│ • impersonate-transport (curl_cffi │
│ Chrome-fingerprint sidecar) │
│ • mobile-api (APK-derived REST client) │
│ • jsonld (schema.org parser) │
│ • cache (LRU + TTL) │
│ • locale (multi-country) │
└────────────────────────────────────────────┘
HTTP／okhttp の手順を同梱しない理由など、アーキテクチャに関する詳しい説明はARCHITECTURE.mdを参照してください。
開発
git clone https://github.com/lukabudik/alza-mcp-community.git
cd alza-mcp-community
npm install # dev checkout: postinstall is skipped on purpose
npm run setup:cf # optional curl_cffi venv (needs bash + python3)
npx playwright install chromium --only-shell # browser for live runs
npm test # unit tests, no network
npm run typecheck
npm run build # → dist/
npm run eval # agent-driven MCP eval harness (6 scenarios) → docs/live-evidence/
npm run validate:api # hits real Alza — runs every tool end-to-end
npm run pentest:app-action # Node AppAction transport comparison
npm run live:endpoint-matrix # bounded read-only APK route matrix; requires ALZA_API_BASE_URL
npm run live:user-journeys # catalog, delivery/cart, and anonymous-account journeys
npm run auth:login:py # PKCE login step 1 (prints browser URL + pending-login.json)
npm run auth:exchange # PKCE login step 2 (Node, needs a CF-friendly egress)
node scripts/e2e-order-payment.browser.mjs exchange "<pasted alza://identity redirect>"
# step 2 via Playwright (works even when Cloudflare challenges plain HTTP)
npm run live:e2e # real order + after-order payment through the MCP tools
# (browser-backed transport; use ALZA_HEADLESS=false to watch it)
npm run live:e2e:node # same journey over plain HTTP (in-memory MCP client); needs a
# non-challenged egress or a fresh ~/.alza-mcp/tokens.json
STOP_BEFORE_ORDER=1 npm run live:e2e # dry run: stop right before order submission
ALLOW_ANON=1 STOP_BEFORE_ORDER=1 npm run live:e2e
# anonymous dry run; ALLOW_ANON alone does not prevent ordering
node dist/index.js # run the server (waits for stdio MCP messages)
node dist/index.js --http # or serve MCP Streamable HTTP on http://127.0.0.1:3000/mcp
詳しくはこちら：
- ARCHITECTURE.md — コードがこのような構成になっている理由（CF、Playwright、ハイドレーション戦略）
- ROADMAP.md — 今後の予定
- CONTRIBUTING.md — リポジトリの構成とツールの追加方法
ロードマップ
main では、カタログ、フィルタリング、カート、チェックアウト、注文の作成とキャンセル、アカウント管理にすでに対応しています（できることおよび既知の制限事項を参照）。次の予定は以下のとおりです。
優先事項はROADMAP.mdに記載されています。すべての項目はissuesで管理しています。最初に取り組むなら、good first issueがおすすめです。
FAQ
Chromium のダウンロードに 92 MB かかるのはなぜですか？
Alza のボット対策により、通常の HTTP リクエストがブロックされることがあります。カタログでは、ヘッドレス Chromium で商品ページをレンダリングします。アカウント関連の処理では、オプションの Chrome フィンガープリント用サイドカーも利用でき、フォールバックとしてブラウザー経由のリクエストを使います。必要に応じて、postinstall フックまたは初回起動時に Chromium がインストールされます。仕組みをご覧ください。
ログインと注文はどのように保護されていますか？
- OAuth サインインでは、Alza のパスワードを MCP ツールの引数として渡しません。サインインはユーザーのブラウザーで行われ（OAuth PKCE）、MCP は返されたコードを交換するだけです。認証情報を引数として渡す必要があるツール（
register、change_password、phone_change、email_change）では、明示的なワンタイムトークンが必要です。これらのツールは、ユーザーからの直接の指示があった場合にのみ呼び出してください。 checkout_previewは、カートと配送方法を確認した後にワンタイム確認トークンを作成します。place_orderは、任意のトークンを受け付けません。web_place_order（現在動作する注文送信経路です。モバイル版のplace_orderはサーバー側で HTTP 500 を返します）と、その他すべての影響の大きい変更（cancel_order、pay_after_order、delete_accountなど）には、prepare_mutationで取得したワンタイムトークンが必要です。トークンは1回限りで、1つの操作とpayloadとして渡された正確な引数に紐づけられ、有効期限は5分です。MFA と 3-D Secure は引き続き、ユーザーがブラウザー上で操作します。- これらのツールは、実際の注文とアカウントを作成、変更、キャンセルします。トークンはエージェントによる誤操作を防ぐためのものであり、ユーザーによる操作の確認に代わるものではありません。エージェントに注文概要を表示させ、先にユーザーへ確認してください。
Chromium のダウンロードを回避できますか？
はい。既存の Chrome のデバッグポートをALZA_CDP_URLに設定してください。
# launch Chrome with debugging
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222
# tell alza-mcp-community to attach
ALZA_MCP_SKIP_INSTALL=1 ALZA_CDP_URL=http://localhost:9222 npx alza-mcp-community
MCP はお使いの Chrome を使用します。別途ダウンロードする必要はなく、初回起動が速くなり、すでにお持ちの Alza の Cookie も引き継がれます。
Alza はこれを停止させるでしょうか？
その可能性はあります。停止されることを想定してください。このプロジェクトに商用目的はなく、トラフィックを最小限に抑えるためにキャッシュを使用しています。また、issuesから削除依頼を受け付けており、Alza から削除の要請があれば従います。ただし、Alza のボット対策を回避できるため（仕組みを参照）、Alza の基準では礼儀正しいスクレイピングではなく、Alza の利用規約で禁止されている可能性もあります。個人的な自動化に使用し、大規模な利用は避けてください。
rohlik-mcp とはどのように異なりますか？
tomaspavlin/rohlik-mcp に着想を得ています。相違点は次のとおりです。
- Rohlik は Cloudflare のチャレンジで保護されていないため、rohlik-mcp は通常の HTTP を使用します。一方、Alza では実際のブラウザーが必要です。
- Alza はカタログの規模がはるかに大きく（数百万の SKU に対し、食料品リストの規模です）。
- カタログの読み取りだけでなく、購入の全行程（カート、チェックアウト、注文、キャンセル）とアカウント管理にも対応しています。また、ツールをツールセットに分類しているため、デフォルトではカタログと認証のツールセットのみが有効になります。
- ツールに加えて、MCP のリソースとプロンプトも公開しています。
免責事項
alza-mcp-community は Alza.cz a.s. と提携、承認、または後援されていません。「Alza」、「Alza.cz」、「AlzaBox」は、それぞれの所有者の商標です。
このソフトウェアの動作について。 これはリバースエンジニアリングされたクライアントです。モバイル API のルートとデータ形式は Alza の Android アプリケーションから特定されており、カタログツールはヘッドレスブラウザーを使って alza.cz のページをスクレイピングします。Alza のサーバーにアクセスするため、Cloudflare Bot Management を回避します（ヘッドレス Chromium と Chrome のフィンガープリントを使う HTTP サイドカー）。公開 APK に埋め込まれている Android アプリの OAuth クライアント認証情報を、トークン交換のデフォルトとして使用します。
法的事項。 これらはいずれも公開またはサポートされたインターフェースではなく、Alza の利用規約で、自動アクセス、ボット保護の回避、リバースエンジニアリングが禁止されている可能性があります。このソフトウェアを使用できるかどうか、およびその使用方法は、適用される法域と Alza との契約によって異なります。その判断はすべてご自身の責任で行ってください。これは法的助言ではなく、メンテナーはこのソフトウェアの使用が合法または許可されていることを表明するものではありません。
実際のアカウントに対して動作し、実際に金銭を消費します。 チェックアウト、注文、支払い、登録、アカウント削除のツールは、Alza の有効なアカウントに対して動作します。注文は実際のものであり、拘束力があります。キャンセルが成功する保証はありません。ワンタイムトークンはエージェントによる誤操作を防ぐためのものであり、各操作を自分で確認する代わりにはなりません。失ってもよいアカウントや注文でのみテストし、エージェントのコンテキストに公開したくない認証情報は決して使用しないでください。
保証なし。 MIT ライセンスに基づき「現状のまま」提供されます。メンテナーは、可用性、正確性、またはいかなる目的への適合性も保証せず、使用によって生じた注文、請求、アカウントのロック、または禁止措置について責任を負いません。上流のインターフェースは予告なく変更される可能性があるため、どのツールも動作しなくなることがあります。商取引上の判断にこれを頼りにしないでください。
セキュリティに関する問題 — SECURITY.md をご覧ください。Alza の従業員または権利者で懸念がある場合は、イシューを作成するか、メンテナーにご連絡ください。速やかに対応し、妥当な削除要請に応じます。
ライセンス
MIT。LICENSE をご覧ください。
貢献者
 Luka Budík 作成者、メンテナー |  Samuel Seidel メンテナー |  @jankryh OAuth ログインの修正 |
プロジェクト初の外部コントリビューターであり、現在は共同メンテナーでもある**Samuel Seidel**に心から感謝します。アカウント、カート、チェックアウト、注文のツール、ツールセット、型付き出力スキーマ、カテゴリーフィルタリング、実環境で検証されるテストハーネスを作成し、これらによってプロジェクトは5つのツールを備えたカタログブラウザーから、完全なショッピングエージェントへと発展しました（#1、#5）。
npm パッケージから OAuth ログインが機能しなかった原因を突き止め、修正してくれた**@jankryh**にも感謝します（#29、#30）。
コントリビューションを歓迎します。CONTRIBUTING.mdと未解決のイシューをご覧ください。
謝辞
- tomaspavlin/rohlik-mcp — 直接的なインスピレーションとなったプロジェクトで、レイアウトのパターンを参考にしています。
- topmonks/hlidac-shopu — Alza スクレイパーの参考レシピ（HTTP + プロキシ）。
- microsoft/playwright-mcp — 公式の Playwright MCP。多くのウェブサイトにとって、ブラウザー駆動型 MCP が適切な抽象化であることを示しています。
- Model Context ProtocolとTypeScript SDK。
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。