eBay已售商品接口封装与MCP自然语言查询实战

前阵子我一直在处理一个看起来不算“酷”但实际非常刚需的问题怎么快速判断一件商品在二手市场上的真实成交价。挂牌价到处都是真正成交的数字却很难拿到。后来我把整套方案整理成了一个可以独立运行的项目核心就是标题里写的两件事eBay已售商品列表接口的封装以及让AI能直接用自然语言查询这些数据的MCP接入层。这个项目我按照社区里“Show HN”的惯例公开分享过也收到了不少讨论。这篇打算从项目角度做一个完整复盘把接口选型、服务层设计、MCP接入方式以及联调时踩过的问题都讲清楚。适合正在做电商数据分析、想给二手交易场景做估值工具或者对Model Context Protocol接入真实业务数据感兴趣的朋友。1. “已售记录”是刚需但获取门槛一直很高1.1 真实成交价能做什么又是谁在需要它已售数据的价值不在单条记录而在一段时间内的价格分布。普通用户买一件东西之前想知道“这个价格到底贵不贵”卖家上架之前需要知道定多少钱能尽快成交做闲置流转的小团队更关心的是某些品类整体热度和成交周期。如果只看当前在售的挂牌价很容易被一些挂几个月都卖不出去的“钉子户”带偏。真实成交记录代表有人真金白银付了钱它对定价判断的参考价值完全不同。这个项目最初被设计成两类用户共用一类是人直接看数据在查询界面里输入关键词、价格区间和时间范围然后看最低价、最高价、中位数和近一周趋势另一类是AI使用时通过MCP协议把同一套查询能力暴露给对话式助手。两类用法背后其实是同一套数据服务层只是入口不同。这也决定了我在架构上从一开始就分了两层稳定可复用的查询API和一个面向AI的MCP接入层。1.2 为什么抓页面不是正路官方接口才是底牌很多人第一反应是直接去爬网页版搜索结果。我早期也试过但很快放弃了原因很现实第一页面结构经常调整爬虫选择器动不动失效第二平台对异常流量有比较复杂的风控短时间大量请求很容易触发验证流程第三网页搜索结果里“已售出”和“在售”往往混杂在一起拿到的数据字段还不够稳定。维护一套能长期正常工作的爬虫成本远超大家最初的想象。相比之下官方API虽然有限额、有规则、有各种奇怪的边界条件但它提供的是结构化数据、稳定的字段语义和正规的调用方式。项目定位是做一个尽量稳定、可以被外部服务依赖的基础设施不是陪页面改版捉迷藏。所以我最终把所有数据获取都收敛到官方接口上把页面抓取这条路彻底排除在设计之外。1.3 项目的整体定位REST数据服务加MCP接入层这个项目不是简单包装一个查询方法就完事。真正费工夫的是把上游接口“翻译”成一个好用的内部服务处理认证、处理配额、归一化字段、做缓存、做重试最后对外暴露REST接口和MCP工具。这样上层无论是Web应用还是AI Agent都不需要关心底层接口细节。在设计MCP接入层时我参考了行业里常见的Model Context Protocol实践MCP服务器对外提供一组“工具”每个工具都有清晰的参数定义和返回格式。AI拿到用户的自然语言之后自己决定调用哪个工具、传什么参数然后把结构化结果再组织成自然语言回答。用户不需要懂接口文档也不需要复制粘贴什么商品ID直接问就行。2. 接口选型与令牌机制先把数据通道打牢2.1 Browse API与Finding API怎么选eBay官方对“已售商品”的查询能力分散在不同接口里最常见的是两个旧的Finding API里有查询已结束商品的方法新的Browse API里也有搜索已售商品的能力。很多初次接触的人容易迷糊我在这里把关键区别整理成一张表维度Browse API商品搜索Finding API旧版搜索返回维度商品摘要一条记录对应一个商品更偏向列表记录条目可能包含多件商品已售过滤支持筛选已售出商品语义清晰旧参数也提供已成交过滤但组合限制多数据结构新接口字段规范化程度高老接口部分字段需要自己再清洗维护状态推荐使用已经属于维护模式适用场景项目主链路仅兼容旧脚本新代码不建议依赖我项目的主力链路用的是Browse API的搜索端点。原因很简单字段更干净、过滤参数更好用、返回结构更符合现代API的习惯。Finding API我在项目里只保留了一个兼容层给少数依赖旧字段语义的历史场景用。实际调用时最关键的是理解过滤参数。搜索已售记录的核心方式是加soldItems过滤条件。比如查过去一段时间内某个关键词的成交记录请求大致长这样curl -X GET https://api.ebay.com/buy/browse/v1/item_summary/search?qkeyboardfiltersoldItems:true,priceCurrency:USDlimit50 \ -H Authorization: Bearer $ACCESS_TOKEN这里soldItems:true的意思是只返回已经售出的条目。听起来很简单但后面我会讲到这个“已售”的实际含义有它自己的边界并不代表百分之百准确。2.2 OAuth令牌获取与生命周期管理认证这块相对直接但对第一次接触的人来说有个明显的知识盲区你不能拿账号密码直接调接口得先拿到一个访问令牌。项目的服务端需要注册为开发者应用拿到客户端凭证之后用OAuth的客户端模式换取令牌。curl -X POST https://api.ebay.com/identity/v1/oauth2/token \ -H Content-Type: application/x-www-form-urlencoded \ -u CLIENT_ID:CLIENT_SECRET \ -d grant_typeclient_credentialsscopehttps://api.ebay.com/oauth/api_scope返回结果里的access_token一般有效期两小时左右。两小时听起来不短但真实服务里只要一运行起来令牌过期带来的中断就会暴露出来。我最初的做法是每次请求前都检查剩余有效期后来改成了服务启动时先拉一次令牌然后设置一个定时刷新任务在过期前五分钟主动换新。这个细节看起来不起眼实际对整体稳定性帮助非常大。另外令牌是服务端的核心机密绝对不能打进前端代码或者日志里。我在项目里把凭据通过环境变量注入日志里也做了脱敏处理避免调试时把令牌打印出来。2.3 已售筛选和排序的隐藏约束用soldItems:true之后并不等于“万事大吉”。我梳理代码时发现至少有三个隐藏约束必须注意。第一排序参数和已售筛选的组合是有限制的不是每种排序都能和已售过滤器一起用。如果你想按结束时间倒序排列最近成交记录能用的排序参数范围很有限如果想同时做价格区间过滤和已售过滤某些组合在实际请求中会被上游直接拒绝或者静默忽略。所以设计查询服务时我没有把所有参数都开放给用户而是维护了一个“允许白名单”只暴露经过验证的参数组合。第二币种必须明确。如果不显式声明币种返回的价格字段可能就是平台默认币种后续做聚合统计时还得再做一轮转换。我在内部统一用USD作为统计基准查询时强制声明避免混入其他币种的数据。第三已售过滤在不同类目上的表现有差异。平台对“已售”状态的判定在某些类目下明显更准而在一些冷门类目里返回记录会稀疏很多。这个不是bug是平台本身的策略倾向。我后来在设计统计接口时加了一个sampleSize字段让调用方知道这次统计是基于多少条样本避免被小样本的极端价格误导。3. 服务层设计把“可用的查询”变成“可用的产品”3.1 内部数据模型与字段归一化上游接口返回的字段命名和类型并不完全符合业务使用习惯。比如价格字段在接口里是一个对象包含数值和币种时间字段是ISO8601格式卖家字段嵌套了很多信息。如果让上层代码直接面对这些原始结构每个接入方都得重复踩一遍格式坑。我在服务层里定义了一套内部模型只保留真正会被用到的字段字段类型说明item_idstring平台商品ID全局去重的主键titlestring清洗后的标题去掉HTML实体pricenumber归一化后的价格数值currencystring币种统一为USDended_atISO8601成交或者结束时间统一UTC存储seller_ratingnumber卖家好评率用于辅助判断数据可信度listing_urlstring详情页地址便于用户跳转查看data_sourcestring来源标识方便排查问题归一化的目的不是为了炫技而是让下游所有功能都建立在同一套数据语义上。比如价格原始接口可能返回类似{value: 299.99, currency: USD}的结构我把它拆成price和currency两个字段再做统计时就不需要到处处理对象字段了。3.2 缓存、预热与配额调度官方接口有配额限制这是整个项目里最硬的约束之一。配额不是无限的服务做大了之后高频查询很容易把配额消耗光。我的方案是做两层缓存。第一层是进程内缓存存最近查询过且没过期的结果适合处理短时间内重复查询。第二层是共享缓存存在Redis里这样多个服务实例可以共用不会出现每个实例各查一遍的情况。对于热门关键词我还会做预热每天夜里跑一批定时任务把常用关键词的结果刷新到缓存里降低白天高峰期的实时回源比例。配额的调度逻辑我单独写了一个模块每次查询前先看缓存没有缓存才回源。同时记录每个关键词的查询频率对异常高频的热词做额外保护避免某个词突然被刷爆。3.3 容错与重试不能把上游抖动直接抛给用户接口调用一定会遇到超时、限流、5xx这类问题设计上必须给用户兜底。我的重试策略分三层第一对网络超时类错误做指数退避重试最多试三次每次间隔随机抖动一下避免多个请求同时重试造成集中请求。第二对配额耗尽类错误不做盲目重试而是直接返回缓存中的旧结果同时带一个stale: true的标记告诉调用方这个结果可能不是最新。第三对明显是参数错误或鉴权失败的错误不重试直接根据错误码把问题透出给调用方。这一套下来实际效果是用户感受到的失败率从原来的百分之几降到了千分之一以下。代价是偶尔会看到稍微旧一点的数据但对估值和统计场景来说这完全可以接受。4. MCP接入层让AI用自然语言直接查询已售数据4.1 MCP在项目里的价值MCP的核心价值不是把API包装一遍而是让AI能够安全、受控地调用外部数据能力。假设没有MCP想让AI回答“某款相机近期二手成交价”的问题通常的做法是开发者把所有数据导给模型或者让模型去访问一个开放API。前者数据会过时后者容易失控而且API密钥也不安全。MCP的方式是模型并不直接访问eBay接口而是访问一个MCP服务器。MCP服务器定义好工具模型根据用户问题决定调用哪个工具传入什么参数得到的结果以结构化JSON返回给模型再整理成回答。整个过程里真正的密钥和业务逻辑都保留在MCP服务器内部AI只负责“调度工具、组织语言”。4.2 工具定义与JSON Schema设计我这个MCP服务器定义了三个核心工具search_sold_items负责搜索近期成交记录get_price_stats负责对某组关键词做价格聚合统计get_deal_alerts负责在特定价格区间内找出明显低于历史均价的商品。每个工具都需要提供清晰的描述和参数定义因为模型要靠描述来判断什么时候用什么工具。下面这个JSON Schema示例是我实际采用的格式{ name: search_sold_items, description: 查询一段时间内已售出商品记录用于判断二手真实成交价格, inputSchema: { type: object, properties: { keyword: { type: string, description: 搜索关键词例如 iPhone 14 Pro }, min_price: { type: number, description: 最低成交价可选 }, max_price: { type: number, description: 最高成交价可选 }, days: { type: integer, description: 只看最近N天的成交记录, default: 30 }, currency: { type: string, description: 币种默认USD, default: USD } }, required: [keyword] } }工具描述写得越具体模型选择工具的准确率越高。早期我在描述里只写了“查询已售商品”结果模型经常把价格统计的需求也往这个工具上套后来把每个工具的边界描述清楚情况就改善很多。4.3 一次完整调用链路演示假设用户在对话里问“帮我看看最近两周某品牌机械键盘的二手成交价大概在什么范围预算五百美元以内。”MCP服务器这边实际发生的调用链路是模型识别出意图是“查询已售商品”匹配到search_sold_items。模型自动把“最近两周”解析成days: 14把“预算五百美元以内”映射成max_price: 500。MCP服务器收到工具调用请求后内部调用数据服务层先去缓存找没有则回源官方接口。返回结果是一组结构化商品记录模型再根据这些记录总结出价格范围、常见配置和购买建议。整个过程中用户看不到接口细节也不需要知道什么参数。这比传统的表单查询体验要自然很多也是我坚持做MCP接入层的原因。MCP服务器的实现不需要跟着某个特定客户端绑定。我最初用Python实现了基础服务器通过标准输入输出与客户端通信配置好后任何支持MCP的客户端都能接入。配置信息大概长这样{ mcpServers: { ebay-sold: { command: python, args: [/path/to/mcp_server.py], env: { EBAY_CLIENT_ID: xxx, EBAY_CLIENT_SECRET: yyy } } } }把密钥放在MCP服务器的环境变量里而不是暴露给模型这样安全性就有保障了。5. 联调实测中踩到的三个典型问题5.1 时间与时区问题商品到底什么时候“结束”第一次做统计时我发现一个很奇怪的现场有些商品的结束时间比当前时间还晚但它却出现在“已售”结果里。查了很久才发现部分列表是可立即购买或批量售出的平台对结束时间的定义和“实际卖出时间”并不完全一致。这带来一个直接影响如果我想做“最近14天成交”的统计不能只拿结束时间做过滤还要考虑其他状态字段。我后来在数据服务层加了一道二次过滤把标记为已售出、但状态有歧义的记录单独隔离在统计接口里提供一个is_reliable字段让上层决定是否纳入统计。5.2 多数量列表与“疑似未售”数据污染另一个坑是多数量列表。比如一个卖家挂了10件库存商品实际成交了1件接口里很可能还是会显示一条记录价格代表的是首件成交的代价。如果统计时不区分这批数据就会造成价格失真。我在做价格统计时加入了一个去重和降权机制同一商品ID的多条记录只保留代表性的一条同时在样本量过低时主动不过度解读。5.3 配额烧得太快缓存命中率只有30%时的反思项目刚跑起来的时候缓存命中率只有30%左右这意味着大量请求都打到上游接口配额消耗得很快。原因是查询关键词过于分散很多用户搜一次就换别的词缓存基本形同虚设。后来我加了一个关键词归一化层把同义词、品牌别名、常见的错误拼写都映射到一个主关键词上。比如有人搜“keyboard mechanical”有人搜“mechanical keyboard”统一归并成同一个搜索键。这个改动看起来简单却把命中率提升到了70%以上配额消耗的压力明显缓解。我把这几个典型问题的现象和解决方案整理成了下表问题表现解决方案时间语义混乱已售记录结束时间晚于统计窗口二次状态过滤增加可信度标记多数量列表干扰单条记录价格拉偏统计结果同一商品ID去重低样本降权关键词过于分散缓存命中率低配额快速消耗关键词归一化映射统一查询键6. 部署形态、安全边界和后续可以扩展的方向6.1 推荐的服务拆法与数据流这个项目我最终跑成了两个独立进程一个是数据服务API容器对外提供REST接口另一个是MCP服务器容器专门用于AI接入。两个容器共享Redis。数据服务API负责所有上游接口调用、令牌刷新、缓存读写和错误重试MCP服务器本身不直接访问上游接口它只调用数据服务API相当于一个翻译层。这样的拆法有一个额外好处如果未来要支持其他数据源比如别的二手平台只需在数据服务层加一个适配器MCP层可以完全不变。AI接入方感受到的唯一变化是底层数据来源的扩展。6.2 安全与合规边界做这类项目有两个底线必须要守住。第一上游接口的密钥绝对不能传到前端或者MCP的工具参数里所有的敏感信息都要留在服务端。第二对用户的调用频率要做限流不能因为接口可用就放任客户端无限请求。我在数据服务API层加了每分钟级别的限流超过阈值的请求直接返回明确的错误码同时记录日志方便追溯。从合规角度看走官方接口是相对稳妥的路径。用官方途径意味着你的调用方式、频率和数据用途都处在平台规则允许的范围内后续即使规则调整也更容易找到替代方案。6.3 从“查询工具”到“市场分析助手”的演进这个项目现在已经不只是“查价格”了我在持续往里面加一些分析能力。比如根据历史成交记录估算某个品类的中位成交周期判断一件商品放多久能卖出去再比如对同一商品在不同时间窗内的价格波动做简单预测给卖家提供“现在卖还是再等等”的参考。从我个人实际操作来看最有成就感的是MCP接入让这些功能的使用门槛降到几乎为零。以前要写脚本、拼参数才能完成的分析现在说一句话就能得到答案。未来我计划继续把数据服务层沉淀得更完善增加历史价格趋势的持久化存储让统计不再局限于当前窗口内的采样数据。如果你也在做类似的电商数据工具或者对MCP接入业务数据感兴趣项目里的接口选型、缓存策略和工具设计思路应该可以直接借鉴。