Canopy API

Canopy MCP 服务 — 面向 AI Agent 的 Amazon 产品数据 API

通过 Model Context Protocol 提供 Amazon 产品数据 API。将 Claude、ChatGPT、Cursor 或任何 MCP 客户端连接到实时 Amazon 数据——Amazon 搜索 API、评论 API、价格追踪器、ASIN 查询、畅销商品、优惠和销售估算——由 Canopy API 提供支持。无需无头浏览器，也无需脆弱的 HTML 抓取：通过标准 MCP 工具传输类型化 JSON。

使用 xmcp 构建，并部署在 Cloudflare Workers 上。使用托管的远程 MCP 服务 https://mcp.canopyapi.co/mcp，或从此代码仓库自行托管。设置指南和客户端使用教程请参阅 Amazon MCP 服务页面。

为什么需要 Amazon MCP 服务？

AI Agent 和大模型应用越来越需要实时电商数据。此服务为任何兼容 MCP 的助手或 Agent 框架提供直接访问 Amazon 的工具：

• 购物助手 — 面向 Agent 的 Amazon 搜索 API：搜索产品、比较价格和 Buy Box 报价，并在聊天中展示优惠和优惠券
• 价格监控与竞争情报 — Amazon 价格追踪 API，可查询任意 ASIN 的价格、库存估算和卖家报价
• 产品研究与市场分析 — Amazon 产品研究工具，提供畅销排名、销售估算和品类分类体系
• 商品目录丰富化 — ASIN 查询及 ASIN ↔ GTIN/UPC/ISBN/EAN 转换，另提供图片、变体和规格
• 评论分析 — Amazon 评论 API，返回评分、有用票数和媒体内容齐全的精选客户评论，便于生成摘要

可用作 Claude MCP 服务（Desktop、Code 和 claude.ai 连接器目录）、ChatGPT MCP 连接器（Apps SDK，支持丰富的产品小组件）、Cursor 和 MCP Inspector，也适用于任何基于 MCP SDK、LangChain 或 OpenAI Agents SDK 构建的 Agent。

功能

• 17 种 Amazon 数据工具 — 产品信息、变体、报价、库存、销售、评论、搜索、自动补全、品类、畅销商品、卖家、作者、优惠和 ASIN/GTIN 查询
• /mcp 上的 Streamable HTTP 传输（当前 MCP 规范）
• 基于文件的工具 — src/tools/ 下每个工具对应一个文件
• 类型安全 — 通过 openapi-typescript 根据 Canopy OpenAPI 规范生成 TypeScript 类型
• 灵活的身份验证 — OAuth 2.1 登录（Supabase 授权服务、动态客户端注册），或使用四种请求头格式中的任意一种传入 API 密钥
• 启用 CORS — 允许预检请求和自定义 API 密钥请求头

快速开始

使用托管服务（无需安装）

将远程 MCP 服务添加到客户端，并使用 OAuth 登录，或提供 Canopy API 密钥：

https://mcp.canopyapi.co/mcp

Claude 和其他支持 OAuth 的 MCP 客户端会自动引导你完成登录。在 canopyapi.co 获取 API 密钥，并参阅 Amazon MCP 服务指南了解各客户端的设置说明。

安装为 Agent 插件

此仓库是一个 Agent 插件（规范 1.0.0）。插件根目录就是仓库根目录。兼容的客户端会读取 plugin.json，从 skills/ 加载技能，并连接到 mcp.json 中声明的 MCP 服务。

canopy-api-mcp/
├── plugin.json          # Agent Plugins 1.0.0 manifest
├── mcp.json             # hosted Streamable HTTP server
└── skills/
    └── amazon-product-research/
        ├── SKILL.md
        └── references/tools.md

mcp.json 指向与上述相同的托管端点：

{
  "mcpServers": {
    "canopy": {
      "type": "streamable-http",
      "url": "https://mcp.canopyapi.co/mcp"
    }
  }
}

授权由客户端负责。支持 OAuth 的客户端会从服务端自动发现登录方式。插件不会嵌入 API 密钥：Agent Plugins 将 headers 视为公开的包数据，而不是存放机密信息的位置。如果客户端仅支持静态标头，请在该客户端中设置 CANOPY-API-KEY。

Cursor。 插件列出后，可从 Customize 或 Cursor Marketplace 安装。若要在插件正式列出前试用此目录，请将此仓库复制到 ~/.cursor/plugins/local/canopy-api-mcp（指向该文件夹以外位置的符号链接会被忽略），重新加载窗口，并在 Customize 中确认 Canopy 服务和 amazon-product-research 技能。

其他 Agent Plugins 客户端。 加载此目录。客户端需要支持 Agent Plugins 1.0.0 和 streamable-http 传输。规范中没有归档文件或注册表协议：此目录就是该软件包。

server.json 保持不变。它是 MCP Registry 服务卡片，格式与 plugin.json 不同。npm install、npm run dev 和 npm run deploy 均保持不变。

根据已发布的架构验证软件包：

npm run validate:plugin

自行运行

你需要从 canopyapi.co 获取 Canopy API 密钥。

npm install
npm run dev      # xmcp watcher + wrangler dev (local Workers runtime)
npm run deploy   # build + wrangler deploy --env production

测试

运行 npm test 以构建工作器并运行回归测试套件。输出架构测试使用模拟的 REST 响应，验证空值字段（不可用的价格、优惠券、评分）在传递给 MCP 客户端之前会被移除、响应符合所公布的 JSON Schema，并且格式错误的值仍会被拒绝。这些测试不需要真实的 Canopy API 密钥。

使用 MCP Inspector 并连接到 http://localhost:8787/mcp（或你的已部署 URL）。将 API 密钥作为请求标头提供：

npx -y @modelcontextprotocol/inspector@latest

或者使用 curl：

curl -X POST http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "CANOPY-API-KEY: $CANOPY_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

身份验证

每个请求都必须携带凭据。支持两种模式：

1. OAuth 2.1（推荐用于 MCP 客户端）。 支持 OAuth 的客户端会自动发现流程：未通过身份验证的请求会返回 401，并附带 WWW-Authenticate: Bearer resource_metadata="https://mcp.canopyapi.co/.well-known/oauth-protected-resource"。Supabase 是授权服务器（支持动态客户端注册）；用户同意页面位于 canopyapi.co。已验证用户的 Canopy API 密钥会在服务端解析。

2. API 密钥标头。 以下任一格式均可使用（按此顺序检查）：

• CANOPY-API-KEY: your-api-key
• API-KEY: your-api-key
• X-API-KEY: your-api-key
• Authorization: Bearer your-api-key

缺少凭据或凭据无效时，会在请求到达 MCP 传输之前返回带有 JSON-RPC 错误的 HTTP 401（参见 src/middleware.ts）。

可用工具

全部 17 个工具均为只读（readOnlyHint: true），并带有 title 注释。

产品信息

• get_amazon_product — 根据 ASIN、URL 或 GTIN 获取产品详情
• get_amazon_product_variants — 获取产品变体
• get_amazon_product_offers — 获取卖家报价和 Buy Box 信息
• get_amazon_product_stock — 获取库存水平估算
• get_amazon_product_sales — 获取销售额估算（每周、每月、每年）
• get_amazon_product_top_reviews — 获取热门客户评论（标题、正文、评分、有用票数、图片/视频）

搜索与发现

• search_amazon_products — 使用筛选条件和排序方式搜索
• get_amazon_autocomplete — 获取搜索词建议
• get_amazon_deals — 获取当前优惠，可按类别筛选
• get_amazon_bestsellers — 获取某类别的畅销产品
• get_amazon_bestseller_categories — 获取畅销品类别列表

分类

• get_amazon_categories — 根类别体系
• get_amazon_category — 包含产品和子类别的类别详情

实体

• get_amazon_seller — 卖家信息和产品列表
• get_amazon_author — 作者信息和图书列表

标识符

• get_amazon_asin_from_gtin — 根据 ISBN/UPC/EAN 查询 ASIN
• get_amazon_gtin_from_asin — 根据 ASIN 查询 GTIN

项目结构

canopy-api-mcp/
├── plugin.json                 # Agent Plugins 1.0.0 manifest
├── mcp.json                    # MCP server declaration (Streamable HTTP)
├── skills/
│   └── amazon-product-research/
│       ├── SKILL.md
│       └── references/tools.md
├── server.json                 # MCP Registry server card (separate from plugin.json)
├── LICENSE                     # MIT License
├── src/
│   ├── tools/                  # one file per tool (auto-discovered by xmcp)
│   │   ├── get-amazon-product.ts
│   │   └── ...
│   ├── lib/
│   │   └── api-key.ts          # reads API key from extra.authInfo
│   ├── middleware.ts           # auth middleware (lifts header → authInfo.token)
│   ├── api-client.ts           # type-safe Canopy REST client
│   └── types/
│       └── api.d.ts            # generated from OpenAPI
├── xmcp.config.ts              # xmcp config (endpoint, CORS, paths)
├── wrangler.jsonc              # Cloudflare Workers config
├── worker-entry.ts             # Workers entry (unchanged)
├── tsconfig.json
└── package.json

类型安全

src/types/api.d.ts 根据 Canopy OpenAPI 规范生成。API 变更时请重新生成：

npm run generate

脚本

• npm run dev — xmcp 监视器 + wrangler dev（本地 Workers 运行时）
• npm run build — xmcp build --cf（为 Cloudflare 生成 worker.js）
• npm run deploy — 构建 + wrangler deploy --env production
• npm run delete — 删除已部署的 Worker
• npm run generate — 根据 OpenAPI 规范重新生成 API 类型
• npm run validate:plugin — 根据 Agent Plugins 1.0.0 检查 plugin.json、mcp.json 和 skills/

从 v1.x 迁移

v2.0 使用 xmcp 替代 ModelFetch。MCP 端点从 /sse/mcp（已弃用的 SSE 传输挂载点）迁移至 /mcp（当前的 Streamable HTTP 约定）。请相应更新客户端。

许可证

本项目根据 MIT 许可证 发布。版权所有 (c) 2026 Canopy API。

相关链接

• 模型上下文协议
• xmcp 框架
• Amazon MCP 服务 — Canopy
• Canopy API
• Cloudflare Workers