# keepa-adapter

MCP server + OpenClaw skill for Amazon intelligence via the [Keepa API](https://keepa.com/api-docs/). 33 MCP tools cover every path in Keepa's current endpoint index, plus local snapshots, change detection, BSR analysis, and promotion measurement.

## Setup

```bash
git clone https://github.com/your-org/keepa-adapter.git
cd keepa-adapter
npm install
cp .env.example .env
# Edit .env and add your Keepa API key
```

## Install Via Claude Desktop MCPB

The easiest Claude Desktop install path is the `.mcpb` bundle from GitHub Releases.

1. Download `keepa-adapter-vX.Y.Z.mcpb` from the latest release.
2. Open the `.mcpb` file with Claude Desktop.
3. Enter your Keepa API key when Claude asks for `Keepa API Key`.
4. Enable or restart the extension if Claude Desktop prompts you.
5. Start a new Claude chat and confirm the Keepa tools are available.

The bundle passes your key to the local MCP server as `KEEPA_API_KEY`. Optional settings such as `KEEPA_TOKENS_PER_MINUTE`, `KEEPA_DEFAULT_DOMAIN`, and `KEEPA_DB_PATH` remain available for manual MCP installs.

The bundle uses `sql.js`, so it does not load native Node add-ons inside Claude Desktop. That avoids Node ABI rebuild issues and macOS Electron code-signing failures for SQLite.

## Build A Local MCPB

```bash
npm install
npm run mcpb:validate
npm run mcpb:pack
```

The packaged bundle is written to:

```bash
release/keepa-adapter-v1.2.0.mcpb
release/keepa-adapter.mcpb
```

Use the stable filename for website download links:

```text
https://github.com/BWB03/keepa-adapter/releases/latest/download/keepa-adapter.mcpb
```

### Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `KEEPA_API_KEY` | Yes | — | Your Keepa API key |
| `KEEPA_TOKENS_PER_MINUTE` | No | `5` | Token refill rate for your Keepa plan |
| `KEEPA_DEFAULT_DOMAIN` | No | `com` | Default Amazon marketplace (e.g. `uk`, `de`, `jp`, `ca`, `au`) |
| `KEEPA_DB_PATH` | No | `~/.keepa-adapter/keepa.db` | Path to SQLite database |

### International Marketplaces

All tools support international Amazon marketplaces via the `domain` parameter. Set `KEEPA_DEFAULT_DOMAIN` in your `.env` to avoid passing it on every call:

```bash
# .env
KEEPA_DEFAULT_DOMAIN=uk   # All tools now default to Amazon.co.uk
```

Supported domains: `com` (US), `uk`, `de`, `fr`, `jp`, `ca`, `it`, `es`, `in`, `mx`, `br`. Keepa only supports Brazil on a subset of endpoints; the adapter validates that restriction before sending a request.

You can still override per-call by passing `domain` explicitly to any tool.

## Usage

### As an MCP Server (Claude Desktop)

If you prefer manual JSON config instead of the `.mcpb` installer, add this server to Claude Desktop's MCP config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "keepa-adapter": {
      "command": "node",
      "args": ["/path/to/keepa-adapter/dist/index.js"],
      "env": {
        "KEEPA_API_KEY": "your_key_here"
      }
    }
  }
}
```

Or run in development mode:

```bash
npm run dev
```

### Claude Code / Codex Setup

Claude Code, Codex, and other stdio MCP clients can use the same local server command after building from source:

```json
{
  "mcpServers": {
    "keepa": {
      "command": "node",
      "args": ["/absolute/path/to/keepa-adapter/dist/index.js"],
      "env": {
        "KEEPA_API_KEY": "your_key_here"
      }
    }
  }
}
```

For Codex CLI-style configs, use the equivalent command/args/env shape supported by your client:

```toml
[mcp_servers.keepa]
command = "node"
args = ["/absolute/path/to/keepa-adapter/dist/index.js"]

[mcp_servers.keepa.env]
KEEPA_API_KEY = "your_key_here"
```

### As an OpenClaw Skill (for bots)

```typescript
import { KeepaSkill } from "keepa-adapter";

const skill = new KeepaSkill({ apiKey: "your_key" });

// Fetch product data
const products = await skill.getProduct(["B0012ZQPKG"]);

// Get daily alerts for Telegram/Slack/etc.
const alerts = await skill.getAlerts();
const summary = await skill.getDailySummary();
```

### Daily Collection (Scheduler)

Run a one-time collection of all tracked ASINs:

```bash
# Via npm
npm run collect

# Or directly
npx tsx src/scheduler/runner.ts
```

Schedule with cron for daily monitoring:

```cron
0 6 * * * cd /path/to/keepa-adapter && KEEPA_API_KEY=xxx npm run collect
```


## Playbooks

- [Amazon Monitoring Playbook](docs/amazon-monitoring-playbook.md) - Operating workflow for turning Keepa price, BSR, buy box, sales, variation, and promo signals into actions.

## MCP Tools Reference

### Read Tools

| Tool | Description |
|------|-------------|
| `keepa_get_product` | Fetch current product data for 1-100 ASINs (title, brand, prices, BSR, rating, buy box, images, features, variations, monthly sales, offer counts, out-of-stock %, Subscribe & Save status) |
| `keepa_get_price_history` | Get price/rank/review time series history (includes list price, lightning deal, FBA/FBM prices, offer counts) |
| `keepa_get_buy_box` | Get buy box ownership, seller info, and offers |
| `keepa_get_variations` | Get variation family tree (parent/child relationships) |
| `keepa_check_tokens` | Check remaining API tokens and refresh rate |

### Monitoring Tools

| Tool | Description |
|------|-------------|
| `keepa_track_asins` | Add ASINs to the adapter's local monitoring list |
| `keepa_take_snapshot` | Fetch + store snapshot, return changes vs previous |
| `keepa_get_changes` | Query detected changes by ASIN, severity, or date range |
| `keepa_analyze_bsr_trend` | Analyze BSR trend and flag deterioration |
| `keepa_check_variations` | Check for orphaned children, parent changes, attribute drift |

### Market Intelligence Tools

| Tool | Description |
|------|-------------|
| `keepa_get_sales_history` | Get monthly sales volume time series (units sold over time) |
| `keepa_get_deals` | Get ASIN-specific coupon, promotion, and lightning-deal history from `/product` |
| `keepa_get_seller_stats` | Get product-level Buy Box win %, average price, and FBA status from `/product` |
| `keepa_get_best_sellers` | Get the best seller ASIN list for a category |
| `keepa_get_category` | Look up category details (name, parent, children, product count) |

### Official Keepa API Tools

| Tool | Keepa operation |
|------|-----------------|
| `keepa_search_products` | Product Search (`/search?type=product`) |
| `keepa_find_products` | Product Finder (`/query`, POST) |
| `keepa_browse_deals` | Browsing Deals (`/deal`, POST) |
| `keepa_search_categories` | Category Search (`/search?type=category`) |
| `keepa_get_sellers` | Seller Information (`/seller`) |
| `keepa_find_sellers` | Seller Finder (`/sellerquery`, POST) |
| `keepa_get_top_sellers` | Most Rated Sellers (`/topseller`) |
| `keepa_get_lightning_deals` | Lightning Deals (`/lightningdeal`) |
| `keepa_get_graph_image` | Graph Image API (`/graphimage`) |
| `keepa_add_api_trackings` | Add Keepa-hosted trackings (`/tracking?type=add`) |
| `keepa_remove_api_tracking` | Remove one or all Keepa-hosted trackings |
| `keepa_get_api_trackings` | Get or list Keepa-hosted trackings |
| `keepa_get_tracking_notifications` | Retrieve tracking notifications; read-only by default |
| `keepa_get_tracking_lists` | List named tracking lists |
| `keepa_set_tracking_webhook` | Configure the Keepa notification webhook |

`keepa_track_asins` remains a lightweight local snapshot list. The `keepa_*_api_tracking*` tools use Keepa's hosted Tracking API and affect the Keepa account associated with the API key.

### Promo Tools

| Tool | Description |
|------|-------------|
| `keepa_add_promo` | Register a promo event (coupon, Lightning Deal, etc.) |
| `keepa_list_promos` | List promo events for an ASIN |
| `keepa_analyze_promo_impact` | Measure rank/price lift before, during, and after a promo |

## Example Prompts

Once connected via Claude Desktop, try:

- "Show me product data for ASIN B0012ZQPKG"
- "Track these ASINs: B0012ZQPKG, B001234567"
- "Take a snapshot of all tracked ASINs and show me what changed"
- "Analyze the BSR trend for B0012ZQPKG over the last 10 days"
- "Check if any of my tracked products lost the buy box"
- "Add a coupon promo for B0012ZQPKG starting today"
- "Show me sales history for B0012ZQPKG"
- "What deals or coupons are active for B0012ZQPKG?"
- "Show me buy box stats by seller for B0012ZQPKG"
- "What are the best sellers in category 3760911?"
- "Look up category 3760911"
- "How many API tokens do I have left?"

## Price Format

All price fields (`amazon_price`, `new_price`, `buy_box_price`) are returned in **dollars**, not cents. The adapter converts from Keepa's raw cent values automatically.

```
snapshot.new_price  →  35.99   (dollars, ready to display)
```

Do **not** divide by 100 — the conversion is already done. Keepa's API returns prices in cents (e.g. `3599`), but the adapter handles that internally.

## Change Detection Severity

When snapshots are compared, changes are classified:

| Severity | Triggers |
|----------|----------|
| **Critical** | Title changed, buy box seller changed, parent ASIN lost/changed (orphaned) |
| **Warning** | Images changed, BSR worsened >20%, Amazon price changed >10%, rating dropped, monthly sales dropped >30%, new offer count went to 0, out-of-stock % increased ≥10 points |
| **Info** | Review count changed, features changed, description changed, new offer count changed >50%, Subscribe & Save status changed |

## Development

```bash
npm run build          # Build with tsup
npm test               # Run unit tests
npm run mcpb:validate  # Validate MCPB bundle
npm run mcpb:pack      # Build release/keepa-adapter-vX.Y.Z.mcpb
npm run test:watch     # Watch mode
npm run test:integration  # Integration tests (requires KEEPA_API_KEY)
npm run discover       # Hit live API and save raw response for schema modeling
npm run export:asins -- --input exports/todd-hydrapak-asins.txt
```

### Raw ASIN Export

For one-off catalog dumps, put ASINs in a text file and run:

```bash
KEEPA_API_KEY=xxx npm run export:asins -- --input exports/todd-hydrapak-asins.txt
```

The exporter writes a timestamped `exports/keepa-raw-*` folder with raw Keepa JSON plus CSVs for product fields, decoded price/rank histories, variations, and offers. By default it skips the higher-token offer scrape; add `--buybox --offers 20` when seller/offer detail is needed.

## MCPB Release Flow

Version tags create GitHub Releases with the packaged `.mcpb` attached:

```bash
git tag v1.2.0
git push origin v1.2.0
```

The release workflow runs tests, builds the adapter, validates the MCPB manifest, packs the bundle, and uploads `release/*.mcpb` as a release asset.

## MCPB Test Checklist

- Run `npm test`.
- Run `npm run build`.
- Run `npm run mcpb:validate`.
- Run `npm run mcpb:pack`.
- Confirm `release/keepa-adapter-v1.2.0.mcpb` exists.
- Confirm `release/keepa-adapter.mcpb` exists for stable website download links.
- Open the `.mcpb` file with Claude Desktop.
- Enter `KEEPA_API_KEY` in the install form.
- Confirm Keepa tools appear in Claude Desktop.
- Run a low-cost call such as `keepa_check_tokens`.
- Temporarily install with a missing or invalid key and confirm the adapter returns a clear API-key error rather than crashing.
- Push a version tag and confirm the GitHub Action attaches the `.mcpb` to the release.

## Troubleshooting

- **Claude Desktop does not show the tools:** restart Claude Desktop, confirm the extension is enabled, and reinstall the `.mcpb` if needed.
- **Missing API key errors:** reinstall or edit the extension configuration and enter a valid Keepa API key.
- **Invalid Keepa key or token errors:** verify the key works against Keepa directly and has enough token budget.
- **Node/runtime errors:** use the `.mcpb` install path when possible. For manual installs, confirm `node --version` is `18` or newer.
- **Build output looks stale:** run `npm run build`, then `npm run mcpb:pack` again.
- **Network/API failures:** confirm the machine running Claude Desktop can reach `https://api.keepa.com`.
- **Manual JSON config does not work:** use an absolute path to `dist/index.js`, keep `command` as `node`, and restart the MCP client after editing config.

## Token Budget

Keepa charges tokens per API call. At 5 tokens/min (default plan):

- **7,200 tokens/day** — 100 ASINs daily is comfortable
- Batch up to 100 ASINs per call for efficiency
- Token cost is surfaced in every response so Claude/bots can plan ahead
- The rate limiter self-adjusts from API response headers

Upgrade your Keepa plan for faster sweeps and on-demand history pulls.

## License

MIT