{
  "markdown": "# Canopy API MCP Server\n\nA type-safe MCP (Model Context Protocol) server that provides Amazon product data through the Canopy API. Built with [xmcp](https://xmcp.dev) and deployed on Cloudflare Workers.\n\n## Features\n\n- **17 Amazon Data Tools** — product info, variants, offers, stock, sales, reviews, search, autocomplete, categories, best sellers, sellers, authors, deals, and ASIN/GTIN lookup\n- **Streamable HTTP transport** at `/mcp` (current MCP spec)\n- **File-based tools** — one file per tool under `src/tools/`\n- **Type Safety** — TypeScript types generated from the Canopy OpenAPI spec via `openapi-typescript`\n- **Flexible Auth** — OAuth 2.1 sign-in (Supabase authorization server, dynamic client registration) or an API key in any of four header formats\n- **CORS Enabled** — preflight + custom API key headers allowed\n\n## Quick Start\n\nYou'll need a Canopy API key from [canopyapi.co](https://canopyapi.co/).\n\n```bash\nnpm install\nnpm run dev      # xmcp watcher + wrangler dev (local Workers runtime)\nnpm run deploy   # build + wrangler deploy --env production\n```\n\n### Testing\n\nUse the MCP Inspector and connect to `http://localhost:8787/mcp` (or your deployed URL). Provide the API key as a request header:\n\n```bash\nnpx -y @modelcontextprotocol/inspector@latest\n```\n\nOr with curl:\n\n```bash\ncurl -X POST http://localhost:8787/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json, text/event-stream\" \\\n  -H \"CANOPY-API-KEY: $CANOPY_API_KEY\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/list\",\"params\":{}}'\n```\n\n## Authentication\n\nEvery request must carry credentials. Two modes are supported:\n\n**1. OAuth 2.1 (recommended for MCP clients).** OAuth-capable clients discover the flow automatically: an unauthenticated request returns 401 with `WWW-Authenticate: Bearer resource_metadata=\"https://mcp.canopyapi.co/.well-known/oauth-protected-resource\"`. Supabase is the authorization server (dynamic client registration supported); consent lives at canopyapi.co. The verified user's Canopy API key is resolved server-side.\n\n**2. API key headers.** Any of these forms works (checked in this order):\n\n- `CANOPY-API-KEY: your-api-key`\n- `API-KEY: your-api-key`\n- `X-API-KEY: your-api-key`\n- `Authorization: Bearer your-api-key`\n\nA missing or invalid credential returns HTTP 401 with a JSON-RPC error before the request reaches the MCP transport (see `src/middleware.ts`).\n\n## Available Tools\n\nAll 17 tools are read-only (`readOnlyHint: true`) and annotated with a `title`.\n\n### Product Information\n- `get_amazon_product` — product details by ASIN, URL, or GTIN\n- `get_amazon_product_variants` — product variants\n- `get_amazon_product_offers` — seller offers and Buy Box info\n- `get_amazon_product_stock` — stock level estimates\n- `get_amazon_product_sales` — sales estimates (weekly, monthly, annual)\n- `get_amazon_product_top_reviews` — top customer reviews (title, body, rating, helpful votes, images/videos)\n\n### Search & Discovery\n- `search_amazon_products` — search with filters and sorting\n- `get_amazon_autocomplete` — search term suggestions\n- `get_amazon_deals` — current deals\n- `get_amazon_bestsellers` — best-selling products for a category\n- `get_amazon_bestseller_categories` — best seller category list\n\n### Categories\n- `get_amazon_categories` — root category taxonomy\n- `get_amazon_category` — category details with products and subcategories\n\n### Entities\n- `get_amazon_seller` — seller information and product listings\n- `get_amazon_author` — author information and book listings\n\n### Identifiers\n- `get_amazon_asin_from_gtin` — ASIN lookup by ISBN/UPC/EAN\n- `get_amazon_gtin_from_asin` — GTIN lookup by ASIN\n\n## Project Structure\n\n```\ncanopy-api-mcp/\n├── src/\n│   ├── tools/                  # one file per tool (auto-discovered by xmcp)\n│   │   ├── get-amazon-product.ts\n│   │   └── ...\n│   ├── lib/\n│   │   └── api-key.ts          # reads API key from extra.authInfo\n│   ├── middleware.ts           # auth middleware (lifts header → authInfo.token)\n│   ├── api-client.ts           # type-safe Canopy REST client\n│   └── types/\n│       └── api.d.ts            # generated from OpenAPI\n├── xmcp.config.ts              # xmcp config (endpoint, CORS, paths)\n├── wrangler.jsonc              # Cloudflare Workers config\n├── tsconfig.json\n└── package.json\n```\n\n## Type Safety\n\n`src/types/api.d.ts` is generated from the Canopy OpenAPI spec. Regenerate when the API changes:\n\n```bash\nnpm run generate\n```\n\n## Scripts\n\n- `npm run dev` — xmcp watcher + `wrangler dev` (local Workers runtime)\n- `npm run build` — `xmcp build --cf` (emits `worker.js` for Cloudflare)\n- `npm run deploy` — build + `wrangler deploy --env production`\n- `npm run delete` — remove the deployed Worker\n- `npm run generate` — regenerate API types from the OpenAPI spec\n\n## Migration from v1.x\n\nv2.0 replaces ModelFetch with [xmcp](https://xmcp.dev). The MCP endpoint moved from `/sse/mcp` (deprecated SSE transport mount) to `/mcp` (current Streamable HTTP convention). Update any clients accordingly.\n\n## Related\n\n- [Model Context Protocol](https://modelcontextprotocol.io)\n- [xmcp framework](https://xmcp.dev)\n- [Canopy API](https://canopyapi.co/docs)\n- [Cloudflare Workers](https://workers.cloudflare.com/)\n",
  "bytes": 5226,
  "sha": "6676fb1aeaffe94fa0576629be34a470680133642c895cebb7dab5b2498bac6e",
  "repo_slug": "canopy-api/canopy-api-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_co_canopyapi_mcp_259de0cc/readme"
}