martdata

martdata

martdata 是一个小型本地桥接程序，用于连接托管的 HasData Walmart MCP 服务。该服务以 JSON 格式返回 Walmart 店面 数据。它可以根据商品 ID 或 URL 获取单个商品的完整页面， 分页浏览该商品的客户评价，并使用价格、配送方式和排序 筛选条件，在店面中按关键词或类别搜索。

该桥接程序不保存任何商品数据。它会在本地返回工具列表， 内容与从实时端点捕获的结果完全一致，并将每次工具调用 转发至上游，原样返回收到的内容。捕获到的功能仅包含对 公开店面数据的 3 种只读获取操作：不包含购物车、结账、 订单或支付工具，也不会返回任何个人联系信息。

工具

• hasdata_walmart_product_getWalmartProduct — 根据 itemId 或 url 获取一个 Walmart 商品的完整信息 （如果两者都提供，则以 URL 为准）。可选参数： domain（walmart.com / walmart.ca）、language （en / es / fr），以及用于同时收集其他卖家报价的 otherOffers。返回标题、品牌、价格和库存情况、 购买框卖家、评分、变体、配送详情以及其他卖家信息。 捕获的架构中没有标记为必填的参数：itemId 和 url 可以互为替代。
• hasdata_walmart_reviews_getWalmartReviews — 根据 itemId 或 url 获取单个商品的客户评价，每页 10 条。可选参数： domain、language、page、sort（最相关、最新、 最有帮助、评分最高或最低、最早）、rating（一个星级值）、 aspectId（一个高频提及主题）、condition，以及 verifiedPurchasesOnly。返回每条评价的评分、文本、作者 和投票数，以及商品的评分分布、AI 评价摘要、各方面评分， 还有列出后续调用可用于筛选的值的筛选条件区块。
• hasdata_walmart_search_getSearchResults — 使用关键词 q 搜索店面，或通过 catId 浏览类别，也可以通过 url 抓取完整搜索 URL。可选参数：domain、language、 sort（最佳匹配、价格从低到高或从高到低、畅销商品、 高评分、新品）、page、minPrice 和 maxPrice、 deliveryType（shipping / pickup），以及采用 name:value 格式的缩小范围 facet。返回包含价格、 评分、卖家和配送详情的商品列表，以及分面区块和分页信息。

配置

• HASDATA_WALMART_MCP_URL（可选）— 覆盖上游端点。默认值为 https://mcp.hasdata.com/mcp?apis=walmart。（此覆盖接口是 本次重建中明确标注的自行补充功能。）
• HASDATA_API_KEY（可选）— 设置后，每个上游请求都会携带 x-api-key: <key> 标头，其中使用调用方自己的 HasData API 密钥。 未设置时，不会发送密钥标头。（标头名称和环境变量名称由 原始项目的注册记录确定；从此环境变量转发密钥是明确标注的 重建功能，原始功能未使用密钥。）

转发机制

首次调用工具时，客户端会在上游打开一个可流式传输的 HTTP 会话：先发送 JSON-RPC initialize 请求（协议版本 2025-03-26，clientInfo 名称为 martdata），然后发送 notifications/initialized 通知，接着发送携带调用方参数且 未经更改的 tools/call 请求。如果上游在回复 initialize 时返回 Mcp-Session-Id 标头，则该值会随会话中的每个后续 请求一同发送；该会话会在进程存续期间重复使用。 回复可能采用普通 JSON 或服务器发送事件的形式；两种格式 都会被读取。

上游的成功结果会原样传递，包括上游设置的任何 isError 标志。失败情况——JSON-RPC 错误、非 2xx 状态、无法读取的 响应，或无法完成的请求——会作为 isError 结果返回，其 文本以 martdata error: 开头（此错误呈现方式是本次重建中 明确标注的自行补充功能）。

命令行

每个工具也是一个子命令，接受一个 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 服务；任何其他参数都会正常传递给命令行。

开发

npm install
npm run build
npm test
npm run dev

测试套件完全针对存根化的 JSON-RPC 上游运行，不会进行实时网络调用。

许可证

MIT — 参见 LICENSE。