martdata

martdata

martdata は、ホスト型 HasData Walmart MCP サーバーへの小規模なローカルブリッジです。このサーバーは、Walmart のストアフロント データを JSON で返します。商品 ID または URL を指定して、商品ページ全体を 1 件取得したり、その商品のカスタマーレビューをページごとに取得したり、 価格、フルフィルメント、並べ替えフィルターを指定してストアフロント全体を対象にキーワード検索やカテゴリ検索を実行したりできます。

このブリッジ自体は商品データを保持しません。ライブ エンドポイントからそのまま取得したツール一覧をローカルで返し、各ツール呼び出しを 上流に転送して、返ってきた内容を変更せずに返します。取得できるのは、公開されている ストアフロントデータに対する読み取り専用の 3 種類の取得処理です。カート、チェックアウト、注文、 支払いのツールは含まれておらず、個人の連絡先データも返されません。

ツール

• hasdata_walmart_product_getWalmartProduct — itemId または url で、Walmart の商品を 1 件、全項目取得します（両方指定した場合は URL が優先されます）。任意の引数： domain（walmart.com / walmart.ca）、language （en / es / fr）、競合販売者のオファーも取得する otherOffers。商品名、 ブランド、価格と在庫状況、購入ボックスの販売者、 評価、バリエーション、フルフィルメントの詳細、その他の販売者のブロックを返します。取得したスキーマでは 必須とされている引数はありません。itemId と url は 互いに代替として使用できます。
• hasdata_walmart_reviews_getWalmartReviews — itemId または url で、1 商品の カスタマーレビューを 1 ページ 10 件取得します。任意の引数：domain、language、page、sort（関連度順、新着順、 役立った順、評価の高い順または低い順、古い順）、rating （星評価 1 種類）、aspectId（頻繁に言及されるトピック 1 つ）、condition、verifiedPurchasesOnly。 各レビューの評価、本文、投稿者、 投票数に加え、商品の評価内訳、AI によるレビューの要約、観点ごとのスコア、後続の呼び出しでフィルターに使用できる値を示す filters ブロックを返します。
• hasdata_walmart_search_getSearchResults — キーワード q でストアフロントを検索するか、catId でカテゴリを 閲覧するか、url を使って検索 URL 全体をスクレイピングします。 任意の引数：domain、language、sort（最適一致、価格の昇順または降順、ベストセラー、評価の高い商品、新着商品）、page、minPrice、 maxPrice、deliveryType（shipping / pickup）、 name:value 形式で絞り込む facet。価格、評価、販売者、フルフィルメントの詳細を含む 商品一覧に加え、facets ブロックと ページネーションを返します。

設定

• HASDATA_WALMART_MCP_URL（任意）— 上流エンドポイントを上書きします。既定値は https://mcp.hasdata.com/mcp?apis=walmart です。（この 上書き用フックは、この再構築版独自の、再構築であることを明示した実装です。）
• HASDATA_API_KEY（任意）— 設定すると、上流への各リクエストに、呼び出し元自身の HasData API キーを指定する x-api-key: <key> ヘッダーが付加されます。設定されていない場合、キーのヘッダーは送信されません。（ヘッダー名と環境変数名は、オリジナルのレジストリ記録で固定されています。この環境変数からキーを転送する動作は、再構築であることを明示した実装です。オリジナルの サーフェスはキーなしで取得されました。）

転送の仕組み

最初のツール呼び出し時に、クライアントは上流とのストリーム可能な HTTP セッションを開きます。JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、clientInfo name martdata）を送信し、続いて notifications/initialized 通知を送信してから、呼び出し元の引数を変更せずに含めた tools/call リクエストを送信します。上流が initialize への応答で Mcp-Session-Id ヘッダーを返した場合、 その値はセッションの後続のすべてのリクエストに付加され、プロセスが終了するまでセッションが再利用されます。 応答は通常の JSON またはサーバー送信イベントで届く場合があり、どちらも読み取ります。

上流からの成功した結果は、上流が設定した isError フラグも含め、そのまま渡されます。 JSON-RPC エラー、2xx 以外のステータス、読み取れない応答、または完了できないリクエストによる失敗は、テキストが martdata error: で始まる isError 結果として返されます（このエラー表示は、この再構築版独自の、再構築であることを明示した実装です）。

CLI

各ツールは、1 つの JSON 引数文字列を受け取るサブコマンドでもあります。

npx @reneturcios/martdata hasdata_walmart_product_getWalmartProduct '{"itemId":"14977205582"}'
npx @reneturcios/martdata hasdata_walmart_reviews_getWalmartReviews '{"itemId":"14977205582","sort":"mostRecent"}'
npx @reneturcios/martdata hasdata_walmart_search_getSearchResults '{"q":"coffee maker","maxPrice":90}'
npx @reneturcios/martdata --version

終了コード：成功時は 0、isError の結果の場合は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

npx -y @reneturcios/martdata mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "martdata": {
      "command": "npx",
      "args": ["-y", "@reneturcios/martdata", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/martdata
docker run --rm ghcr.io/cloudcorprecords/martdata --version

コンテナのデフォルトコマンドは mcp であるため、最初の形式では stdio MCP サーバーとして動作します。それ以外の引数は通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートはすべてスタブ化された JSON-RPC アップストリームに対して実行され、実際のネットワーク呼び出しは行いません。

ライセンス

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