@datadive-tools/mcp 0.9.0 → 0.11.0

package/README.md

@@ -100,14 +100,23 @@ niches, plus pagination metadata. If you don't, see Troubleshooting below.
 | `list_niches` | Paginated list of your niches. Discovery step — returns `nicheId`s for the niche-scoped tools below. |
 | `get_niche_keywords` | Master keyword list for a niche: search volume, relevancy, competitor ASIN ranks. |
 | `get_niche_roots` | Keyword lexical roots for a niche — high-impact words with frequency and broad search volume. |
-| `get_niche_competitors` | Competitor ASINs and niche statistics (sales, revenue, ratings, opportunity score). |
+| `get_niche_competitors` | Competitor ASINs, titles, BSR, category and niche statistics (sales, revenue, ratings, opportunity score). |
 | `get_ranking_juice` | DataDive proprietary ranking-juice metric per competitor (current vs optimized listing). |
-| `list_rank_radars` | Paginated list of rank radars. Filter by `nicheId` or `status`. |
+| `list_rank_radars` | Paginated list of rank radars. Filter by `nicheId`, `searchText` or `status` (`ACTIVE` by default, plus `PAUSED`, `ARCHIVED`, `ALL`). |
 | `get_rank_radar_data` | Historical keyword rankings for a rank radar within a `startDate`/`endDate` range. |
 | `create_niche_dive` | **Spends dive tokens.** Starts new niche research from a seed ASIN. Async — returns a `diveId` to poll with `get_dive_status`. Requires `confirm: true`. |
 | `redive_niche` | **Spends dive tokens.** Refreshes an existing niche with current data — either the same competitors or a newly discovered set. Async — returns a `diveId` to poll with `get_dive_status`. Requires `confirm: true`. |
 | `get_dive_status` | Poll a dive started by `create_niche_dive` or `redive_niche`: `in_progress`, `success` (carries the `nicheId`), or `error`. |
 | `create_rank_radar` | **Spends Search Term tokens.** Starts tracking keyword rankings for an ASIN in a niche. Returns a `rankRadarId`. Requires `confirm: true`. |
+| `add_rank_radar_search_terms` | Starts tracking extra keywords on an existing rank radar. Takes one Daily Tracked Keywords slot per new keyword; reversible with `pause_rank_radar_search_terms`. |
+| `pause_rank_radar_search_terms` | Pauses individual keywords of a rank radar, keeping their history and freeing their tracking slots. Takes keyword ids from `get_rank_radar_data`. |
+| `resume_rank_radar_search_terms` | Restarts tracking on paused keywords of a rank radar. Takes back one tracking slot each. |
+| `pause_rank_radar` | Pauses a whole rank radar (what the API calls archiving — listed under `status: PAUSED`, not `ARCHIVED`). Tracking stops, the history is kept, and the tracking slots are freed. Reversible with `resume_rank_radar`. |
+| `resume_rank_radar` | Reactivates a paused rank radar, restoring as many keywords as the remaining quota allows (most relevant first). |
+| `delete_rank_radar` | **Destroys ranking history.** Deletes a rank radar permanently (listed under `status: ARCHIVED`) and frees its tracking slots. Requires `confirm: true` — prefer `pause_rank_radar` if the data may be wanted later. |
+| `delete_niche` | **Destroys niche data.** Deletes a niche with its keywords, competitors and dive history; spent dive tokens are not refunded. Blocked while a rank radar uses the niche. Requires `confirm: true`. |
+| `generate_listing_copy` | **Spends an AI Copywriter prompt.** Drafts an optimised title, bullets and description from a niche's keyword research. Nothing is published to Amazon. Async — returns a `generationId`. Requires `confirm: true`. |
+| `get_listing_copy_generation_status` | Poll a draft started by `generate_listing_copy`: `generating`, `complete` (carries the generated copy), or `failed`. Free to poll. |
 | `list_seller_profiles` | Paginated list of connected Amazon seller accounts. Discovery step — returns the `sellerId` + `marketplace` the seller-scoped tools below (and the alert tools) need. |
 | `get_seller_catalog` | Paginated catalog of a seller's own ASINs. Filter by `search`, `brand`, and `status` (Active by default). |
 | `get_seller_listing_changes` | Paginated price/content/image changes on a seller's listings. Filter by `types`, `asin`, `brand`, `search`, and a date range; optionally include ranking/conversion `correlation`. |
@@ -118,22 +127,38 @@ niches, plus pagination metadata. If you don't, see Troubleshooting below.
 | `list_usage` | Paginated billable usage logs (token-consumption events). Filter by `type`, `search` (user), and `startDate`/`endDate`. |
 
 All data is scoped to the organization that owns the API key. Most tools are
-read-only; the three tools below spend tokens (`get_dive_status` only polls a
-dive and is read-only) — see
-[Creating dives & rank radars](#creating-dives--rank-radars).
+read-only. The tools that change something are marked above; the ones that
+cannot be undone also require an explicit `confirm: true` — see
+[Tools that change something](#tools-that-change-something).
 
-### Creating dives & rank radars
+### Tools that change something
 
-`create_niche_dive`, `redive_niche` and `create_rank_radar` **consume billable
-tokens and cannot be undone**, so they require an explicit `confirm: true`
-argument. The assistant should confirm the cost with you before passing it. The
-amount scales with `numberOfCompetitors` (dives and re-dives) /
-`numberOfKeywords` (rank radars). Check remaining balance any time with
-`get_quota`.
+Six tools **cannot be undone**, so they require an explicit `confirm: true`
+argument. Called without it, they change nothing and return a note asking the
+assistant to confirm the cost with you first:
+
+- `create_niche_dive`, `redive_niche` — spend dive tokens (scales with
+  `numberOfCompetitors`).
+- `create_rank_radar` — spends Search Term tokens (scales with
+  `numberOfKeywords`).
+- `generate_listing_copy` — spends one AI Copywriter prompt per call.
+- `delete_niche`, `delete_rank_radar` — destroy data permanently.
+
+Check your remaining balance any time with `get_quota`.
+
+The other write tools — `pause_rank_radar`, `resume_rank_radar` and the three
+`*_rank_radar_search_terms` tools — need no confirmation. They only move Daily
+Tracked Keywords capacity, which is freed again when you pause, and each is
+undone by its counterpart.
 
 To skip the per-call confirmation (e.g. in an automated setup), set
-`DATADIVE_AUTO_CONFIRM_WRITES=true` in your client config — then these tools run
-without `confirm`.
+`DATADIVE_AUTO_CONFIRM_WRITES=true` in your client config — then all six run
+without `confirm`, deletes included.
+
+None of the three is **safe to retry** — each call spends tokens again and
+creates a separate dive / re-dive / Rank Radar, even with identical arguments. If
+a call errors or times out, check `get_dive_status` / `list_niches` /
+`list_rank_radars` for what already exists before calling again.
 
 Dives are **asynchronous**. `create_niche_dive` returns a `diveId` and an
 estimated completion time immediately; poll `get_dive_status` with that `diveId`
@@ -161,7 +186,7 @@ niche follow the refreshed data. It takes a `mode`:
 |---|---|---|---|
 | `DATADIVE_API_KEY` | yes | — | Generate at https://2.datadive.tools/api-key |
 | `DATADIVE_API_BASE_URL` | no | `https://api.datadive.tools` | Override for staging |
-| `DATADIVE_AUTO_CONFIRM_WRITES` | no | `false` | Set truthy to let `create_niche_dive` / `create_rank_radar` run without `confirm: true`. |
+| `DATADIVE_AUTO_CONFIRM_WRITES` | no | `false` | Set truthy to let every `confirm: true` tool run without it — dives, rank radar creation, listing copy **and the two deletes**. |
 
 ## Troubleshooting
 
@@ -174,7 +199,7 @@ specific HTTP status from the DataDive API.
 | **Subscription is inactive or paused** | Resume billing at https://2.datadive.tools — the API key is valid but the subscription isn't active. |
 | **Forbidden** | The key is valid but doesn't have access to that resource. Usually a niche/rank-radar that belongs to a different org. |
 | **Rate limit exceeded** | Wait a few seconds and retry. |
-| **Bad request** | Check the parameters — the message echoes the server's validation error (e.g., `pageSize must not exceed 100`). |
+| **Bad request** | Check the parameters — the message echoes the server's validation error (e.g., `pageSize must not exceed 50`). |
 | **DataDive API error (5xx)** | Transient backend issue. Try again; if it persists, contact support. |
 | **Network error reaching …** | Your machine can't reach `api.datadive.tools` — check VPN / firewall / DNS. |