Yahoo! Shopping MCP

Yahoo! Shopping MCP

一个开源、由社区维护的 MCP 服务，通过 Yahoo! Shopping Item Search API v3 只读搜索 Yahoo! Shopping 商品。可按关键词或 JAN 码搜索，并使用价格、库存、商品状况、配送、排序、类别、品牌、卖家、图片尺寸和分页筛选条件。本地和可自托管的部署使用 Streamable HTTP；另提供独立的 stdio 入口，供 Glama 托管和本地 stdio 客户端使用。

这不是 Yahoo! Shopping、LINE Yahoo 或 OpenAI 的官方服务。维护者不代表、不认可、不运营 Yahoo! Shopping、Yahoo! Developer Network 或 OpenAI，也不对其作出保证。

项目状态和托管端点

本项目旨在供用户自行托管。我们不提供有保证的共享或生产托管端点。

如果维护者另行分享 Cloudflare Tunnel URL 供测试使用，该 URL 属于临时验证端点。它可能随时停止、重启、更改或无法访问；不提供正常运行时间、SLA、支持、隐私或数据保留保证。请勿将其用于生产或机密工作负载。请改为在你控制的基础设施上运行此服务。

维护者运营的示例部署可能位于：

• MCP 端点：https://non-official-yahoo-shopping-mcp.notelligent.app/mcp
• 健康检查：https://non-official-yahoo-shopping-mcp.notelligent.app/healthz
• 根路径健康检查：https://non-official-yahoo-shopping-mcp.notelligent.app/

这些 URL 仅供演示和连通性检查之用。它们不是 Yahoo! 或 OpenAI 的官方服务，也不保证在线、稳定、受支持、私密，或可供任何特定用户使用。

当前的注册表和目录发布状态见docs/PUBLICATION.md。

这是一个社区实现。使用前，请自行查阅当前的 Yahoo! Developer Network 和 Yahoo! Shopping API 条款、配额、署名要求、内容限制，以及适用于你所在司法辖区和部署方式的任何规则。维护者不保证此实现或其使用方式符合第三方政策。

演示

下面的简短演示展示了通过 ChatGPT 搜索 Yahoo! Shopping，以及由此生成的 MCP Apps 商品轮播。

使用 GIF 进行内嵌播放，因为 GitHub 无法在渲染的 Markdown 中可靠地嵌入仓库本地 MP4 文件。更高画质的 MP4 文件见 assets/demo.mp4。

功能

• 用于 Yahoo! Shopping 商品搜索的只读 search_products 工具
• 关键词、JAN 码、价格、库存、商品状况、配送、排序、类别、品牌、卖家、图片尺寸和分页筛选条件
• 同一进程中，Yahoo 请求开始之间的间隔（默认为 1 秒）
• 针对 Yahoo HTTP 429 响应的指数退避，以及有次数限制的 5xx 重试
• 对经过安全筛选的 Yahoo 响应数据进行短期缓存
• 基于 SQLite 的全应用限流
• 带有 Yahoo 署名信息的 MCP Apps 商品轮播
• 对受限商品词语和非 Yahoo URL 进行保守过滤
• GET /、GET /healthz 和位于 /mcp 的 Streamable HTTP MCP

限流器是应用层的防护措施，不是 Yahoo 配额保证或 SLA。它只在单个进程内生效；不同副本需要各自配置控制措施。

协议和端点

默认的 yahoo-shopping-mcp 入口使用 MCP Streamable HTTP 传输：

• MCP 端点：/mcp
• 健康检查端点：GET /healthz
• 根健康检查端点：GET /
• MCP 身份验证：无

默认情况下，服务绑定到环回地址。未进行身份验证的端点并不意味着它会自动公开到互联网；如果要将其公开，请根据部署情况添加适当的网络、反向代理、速率限制、日志记录和数据保留控制。

Glama 托管服务

Glama 托管的 OSS 构建会通过 stdio 启动 MCP 进程，并通过 Glama 的 HTTP 网关公开其托管端点。在 Glama Dockerfile 管理页面中配置以下 CMD 参数：

["uv", "run", "yahoo-shopping-mcp-stdio"]

Glama 会在此命令外添加其 mcp-proxy 包装器。因此，实际生效的托管命令等同于：

mcp-proxy -- uv run yahoo-shopping-mcp-stdio

此存储库的常规 yahoo-shopping-mcp 命令和 Dockerfile 仍使用 Streamable HTTP，以便自托管。在 Glama 的环境架构中设置 YAHOO_SHOPPING_APP_ID，并且仅在构建检查时使用非生产环境占位值。

本地插件包

此存储库包含供本地使用的元数据：

• .codex-plugin/plugin.json：本地插件元数据、提示词和徽标
• .mcp.json：本地 MCP 客户端配置
• assets/logo.svg：商品搜索图标

这些文件不提供应用商店页面或共享托管服务。使用前，请启动自己的服务并配置自己的 Yahoo Client ID。

快速开始

要求：Python 3.12+、uv 和由操作员获取的 Yahoo! Shopping API appid。

make sync-dev
YAHOO_SHOPPING_APP_ID="your-app-id" make run

本地 MCP 端点为 http://127.0.0.1:8000/mcp，健康检查地址为 http://127.0.0.1:8000/healthz。

如需在受控部署中绑定到其他接口或端口：

YAHOO_SHOPPING_APP_ID="your-app-id" make run HOST=0.0.0.0 PORT=8080

请将 Yahoo Client ID 保存在环境变量中。切勿提交它，也不要将它放入搜索查询中。

Docker 和自托管

创建本地环境模板并启动容器：

make init-env
make up

默认的本地 Compose 端点为 http://127.0.0.1:18000/mcp。请参阅部署，了解面向生产环境的容器和反向代理检查清单。

如需不使用 Compose 直接运行容器，请构建镜像并将容器端口发布到环回地址：

docker build --tag yahoo-shopping-mcp:local .
docker run --rm \
  --name yahoo-shopping-mcp \
  --publish 127.0.0.1:18000:8000 \
  --env YAHOO_SHOPPING_APP_ID="your-app-id" \
  --volume yahoo-shopping-mcp-data:/data \
  yahoo-shopping-mcp:local

MCP 端点为 http://127.0.0.1:18000/mcp，健康检查地址为 http://127.0.0.1:18000/healthz。如需使用已发布的带版本预览镜像，请将本地构建替换为 GitHub Container Registry 中的特定标签：

CONTAINER_IMAGE="ghcr.io/ymuichiro/yahoo-shopping-mcp:v0.9.0-preview.2"
docker pull "$CONTAINER_IMAGE"
docker run --rm \
  --name yahoo-shopping-mcp \
  --publish 127.0.0.1:18000:8000 \
  --env YAHOO_SHOPPING_APP_ID="your-app-id" \
  --volume yahoo-shopping-mcp-data:/data \
  "$CONTAINER_IMAGE"

直接启动应用时，请使用 YAHOO_SHOPPING_MCP_* 环境变量。Compose 会将其便捷变量 ALLOWED_HOSTS 和 ALLOWED_ORIGINS 映射到应用设置。

可选的 Cloudflare Tunnel

Cloudflare Tunnel 是一种可选的开发者部署方式，并非必需。只有通过以下方式才会启用：

make up-tunnel

仅在使用该 Compose 配置时设置 CLOUDFLARE_TUNNEL_TOKEN。隧道主机名和已发布的应用在 Cloudflare 中配置，不属于此存储库。请将 .env 中的本地值替换为部署所用的确切外部主机名和源站地址：

YAHOO_SHOPPING_APP_ID=replace-with-your-yahoo-app-id
CLOUDFLARE_TUNNEL_TOKEN=replace-with-your-cloudflare-tunnel-token
ALLOWED_HOSTS=mcp.example.com
ALLOWED_ORIGINS=https://mcp.example.com

隧道不会添加 MCP 身份验证。请勿将维护者分享的隧道 URL 视为受支持的托管服务；请使用由你控制的主机名和基础设施。

Claude Desktop

此仓库提供两个启动命令：

• yahoo-shopping-mcp：用于本地或可自托管部署的 Streamable HTTP
• yahoo-shopping-mcp-stdio：用于本地 stdio 客户端和 Glama 托管服务的 stdio

运行 make sync-dev 后，要在本地运行 stdio 入口点，请将以下内容添加到 claude_desktop_config.json。将目录替换为此仓库的绝对路径：

{
  "mcpServers": {
    "yahoo-shopping": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/yahoo-shopping-mcp",
        "yahoo-shopping-mcp-stdio"
      ],
      "env": {
        "YAHOO_SHOPPING_APP_ID": "your-app-id"
      }
    }
  }
}

将 Yahoo Client ID 保留在服务环境中，切勿提交。

要连接经过身份验证的自托管部署，请打开 Claude Desktop 的 设置 → 连接器 → 添加自定义连接器，并输入完整的 HTTPS MCP URL，包括 /mcp：

https://mcp.example.com/mcp

完成该部署提供的身份验证流程。目前维护者的演示端点未经过身份验证且为临时端点，因此不要将其用作生产环境中的 Claude 连接器。将 YAHOO_SHOPPING_APP_ID 保留在 MCP 服务中，切勿将其放入 Claude Desktop 配置。

对于本地开发，请启动服务，并使用 MCP Inspector 验证端点：

YAHOO_SHOPPING_APP_ID="your-app-id" make run

Streamable HTTP 端点为 http://127.0.0.1:8000/mcp。请参阅 MCP 文档中的本地 服务和远程服务。

使用工具

从 ChatGPT Developer Mode 或其他 MCP 客户端使用已启动的端点。无需 MCP 身份验证标头。

search_products 至少需要提供 query 和 jan_code 中的一项。重要限制包括：

• query：1–200 个字符
• jan_code：由 8–13 位数字组成的字符串
• genre_category_ids 和 brand_ids：包含 1–20 个正整数的数组
• results：1–50
• start：不小于 1
• start + results <= 1000
• 同时提供 price_from 和 price_to 时，price_from <= price_to

完整约定请参阅 docs/API.md。

示例：

{
  "query": "desk lamp",
  "in_stock": true,
  "sort": "-score",
  "results": 10,
  "start": 1
}

工具会在 content[0].text 中返回模型可读取的 JSON，产品数据位于 results 下。 轮播数据会在 structuredContent.products 中返回。UI 资源的版本为 ui://yahoo-shopping/product-carousel-v4.html，并会显示 Yahoo 署名信息。

服务不会下单、处理付款、修改账户，也不保证商品的可售性、价格、卖家、配送或法律合规性。

隐私与安全

搜索字段会发送给运营者的 MCP 服务和 Yahoo! Shopping。 服务仅在短期缓存中存储经过安全过滤的 Yahoo 响应数据，并在本地存储中保存全局速率限制状态。服务不提供用户账户，也不会持久化完整聊天记录。

请勿将机密信息、付款数据、密码、政府身份标识或敏感个人数据用作搜索词。公开运营者必须发布与其实际基础设施相符的隐私、支持和数据保留详情。

安全过滤器较为保守，不能保证完整的商品分类。它不能替代 Yahoo 的政策、法律建议或运营者审核。

请参阅 PRIVACY.md、TERMS.md、 SECURITY.md 和 docs/DATA_HANDLING.md。

Yahoo! Developer Network 参考资料

以下官方页面定义了适用于运营者自有 Yahoo! 应用的外部要求。这些要求不属于本仓库的许可条款，也不能替代对现行版本的查阅：

• Yahoo! Developer Network 指南
• Yahoo! Shopping API 门户
• Yahoo! Shopping 商品搜索 v3
• 署名和归属规则
• 使用限制
• 开发者指南和 Client ID 注册

每位运营者都必须自行获取并妥善保管自己的 Client ID，并在运行此服务之前独立确认适用的条款、使用限制、署名和法律要求。

开发与验证

make test

测试使用 httpx.MockTransport，CI 不会调用 Yahoo!。有关 MCP Inspector 和 UI 检查，请参阅 docs/VERIFICATION.md。可供审查的正向和反向测试用例见 docs/SUBMISSION_TEST_CASES.md。

欢迎贡献。在提交更改之前，请阅读 CONTRIBUTING.md。如需支持，请使用 SUPPORT.md；请按照 SECURITY.md 中的私密流程报告安全问题。

日语文档

日语概要和入门步骤请参阅 docs/README.ja.md。

许可证

MIT