内容
# 硬件采购 MCP
本地只读 MCP 服务器，用于查找硬件列表并返回直接的产品链接。目前支持：
- **统一采购搜索** - 跨配置的提供商的规范化候选名单，提供商故障报告而不是隐藏成功结果。
- **eBay 浏览 API** - 目的地感知的搜索、筛选、交付价格排名、卖家数据和详细商品查找。
- **百思买产品 API** - 目录搜索、产品详情、运费重量和成本字段、评分和开箱查找。
它从不添加商品到购物车、结账、竞标或购买任何商品。
## 协议安全性
此服务器使用 MCP stdio 传输。标准输出仅用于 JSON-RPC 消息。环境加载集中运行，并启用 dotenv 静默模式，因此启动横幅和正常日志不会损坏协议流。
请勿在服务器上添加 `console.log` 调用。对于本地诊断，请使用 `process.stderr.write`，或在稍后添加日志记录时使用 MCP 结构化日志记录。
## 结果可见性
每个工具都返回结构化的 MCP 数据。搜索和详情工具还会在文本响应中包含重要字段，因为某些 MCP 客户端不会将 `structuredContent` 明显暴露给模型。
详情文本包括直接链接、价格、运费、预估总价、状况、卖家信息、退货、商品规格和提供商特定的字段（如果可用）。完整的原始提供商响应通过 `include_raw` 保留，需在支持时选择加入。
如果所有明确请求的提供商都失败，`search_hardware` 将返回 MCP 工具错误，而不是将失败呈现为普通的零结果搜索。部分提供商故障仍然是警告，同时成功结果将被保留。
## 为什么目的地很重要
对于 eBay，运费估算在提供目的地国家和邮政编码时变得更加准确。MCP 工具描述告诉 Claude 在将运费总额视为最终之前要求这些信息。
百思买的公共产品 API 公开目录运费字段，但精确的地址特定结账报价需要百思买的限制性商业 API。返回的产品 URL 应打开以确认最终总价。
## 工具
| 工具 | 用途 |
|---|---|
| `get_procurement_status` | 显示配置的提供商和非机密默认值 |
| `search_hardware` | 搜索配置的提供商并返回一个排名的候选名单，包含直接链接 |
| `search_ebay` | 搜索和筛选 eBay 列表；按价格和返回的运费成本排名 |
| `get_ebay_item` | 检索详细的列表、运费、方面、可用性、退货和直接链接 |
| `search_bestbuy` | 搜索百思买产品，包含价格和可用性筛选 |
| `get_bestbuy_product` | 通过 SKU 检索百思买产品详情 |
| `get_bestbuy_open_box` | 检索百思买的开箱优惠，适用于某个 SKU |
详情工具默认省略完整的原始提供商响应以减少上下文使用。仅当规范化字段不足时，才将 `include_raw` 设置为 true。
## 设置
```bash
npm install
cp .env.example .env
npm run build
```
填写 `.env`：
```env
EBAY_CLIENT_ID=你的客户端 ID
EBAY_CLIENT_SECRET=你的客户端密钥
EBAY_MARKETPLACE_ID=EBAY_US
BESTBUY_API_KEY=你的 API 密钥
# 可选默认值。如果 Claude 应该始终询问，请留空邮政编码。
DEFAULT_SHIP_TO_COUNTRY=US
DEFAULT_SHIP_TO_POSTAL_CODE=
```
默认情况下，仅搜索配置的提供商。你可以配置 eBay、百思买或两者。
## Claude 桌面版
指向构建的 JavaScript 文件：
```json
{
"mcpServers": {
"hardware-procurement": {
"command": "node",
"args": ["/绝对路径/到/ebay-search-mcp/dist/index.js"]
}
}
}
```
如果 Claude 桌面版找不到 `node`，请将 `command` 替换为 `where node` 在 Windows 上或 `which node` 在 macOS/Linux 上返回的完整路径。
拉取或合并更改后，请始终重建并重启 Claude 桌面版：
```bash
npm install
npm run build
```
## 排查无效 JSON 启动错误
诸如 `Unexpected token` 之类的错误，后面跟着不是 JSON 的文本，意味着某些内容在 MCP 响应之前写入了标准输出。运行：
```bash
npm test
```
协议回归测试启动编译后的服务器，确认启动时不会产生标准输出，进行 MCP 初始化握手，列出工具，调用已知的提供商故障路径，并验证每个标准输出行都是有效的 JSON。
还请确认 Claude 桌面版指向当前的 `dist/index.js`，而不是旧克隆或 TypeScript 源代码。
## AliExpress 状态
AliExpress 暂时不包含在内。公开的项目通常会公开暴露目的地运输的 AliExpress 浏览器端点，并依赖于登录的 cookie。这在本地有效，但比官方的 eBay 和百思买集成更脆弱，需要具有明确警告和限制的单独提供商实现。
下一个有意义的步骤是可选的 `aliexpress` 适配器，位于其自己的环境标志后面，不会将不稳定的爬虫与可靠的提供商混合。
