@datadive-tools/mcp 0.10.0 → 0.12.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,33 @@ 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
@@ -166,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
 
@@ -177,9 +197,10 @@ specific HTTP status from the DataDive API.
 |---|---|
 | **Authentication failed: your DATADIVE_API_KEY is invalid or expired** | The key is wrong, deleted, or expired. Generate a new one at https://2.datadive.tools/api-key. |
 | **Subscription is inactive or paused** | Resume billing at https://2.datadive.tools — the API key is valid but the subscription isn't active. |
+| **Quota exceeded** / **… quota exceeded** | The subscription's quota for that billable feature (Dive tokens, Rank Radar tracked keywords, AI Copywriter prompts, …) is used up. The message names the feature, the usage, the next refresh date when there is one, and links to the subscription overview page where it can be raised. Don't retry until it has been. |
 | **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. |