@datadive-tools/mcp 0.7.0 → 0.9.0

package/dist/lib.js

@@ -0,0 +1,909 @@
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/config.ts
+var SCOPE_READ = "datadive.read";
+var SCOPE_WRITE = "datadive.write";
+var DEFAULT_BASE_URL = "https://api.datadive.tools";
+var KEY_HELP_URL = "https://2.datadive.tools/api-key";
+function loadConfig(env = process.env) {
+  const apiKey = (env.DATADIVE_API_KEY ?? "").trim();
+  if (!apiKey) {
+    throw new Error(
+      `DATADIVE_API_KEY environment variable is required. Generate one at ${KEY_HELP_URL} and add it to your MCP client config under env.DATADIVE_API_KEY.`
+    );
+  }
+  const rawBase = (env.DATADIVE_API_BASE_URL ?? DEFAULT_BASE_URL).trim();
+  const baseUrl = rawBase.replace(/\/+$/, "");
+  const autoConfirmWrites = ["1", "true", "yes"].includes(
+    (env.DATADIVE_AUTO_CONFIRM_WRITES ?? "").trim().toLowerCase()
+  );
+  return { credentials: { kind: "api-key", apiKey }, baseUrl, autoConfirmWrites };
+}
+
+// src/tools/list-niches.ts
+import { z } from "zod";
+
+// src/http/errors.ts
+var KEY_HELP_URL2 = "https://2.datadive.tools/api-key";
+var ApiError = class _ApiError extends Error {
+  kind;
+  status;
+  body;
+  constructor(kind, status, message, body) {
+    super(message);
+    this.name = "ApiError";
+    this.kind = kind;
+    this.status = status;
+    this.body = body;
+  }
+  static fromHttp(status, body) {
+    const serverMsg = extractMessage(body);
+    if (status === 400) {
+      return new _ApiError(
+        "bad_request",
+        400,
+        serverMsg ? `Bad request: ${serverMsg}` : "Bad request: invalid parameters.",
+        body
+      );
+    }
+    if (status === 401) {
+      return new _ApiError(
+        "auth",
+        401,
+        `Authentication failed: your DATADIVE_API_KEY is invalid or expired. Generate a new key at ${KEY_HELP_URL2}.`,
+        body
+      );
+    }
+    if (status === 402) {
+      return new _ApiError(
+        "payment",
+        402,
+        "Subscription is inactive or paused. Resume billing at https://2.datadive.tools to use the API.",
+        body
+      );
+    }
+    if (status === 403) {
+      return new _ApiError(
+        "forbidden",
+        403,
+        serverMsg ? `Forbidden: ${serverMsg}` : "Forbidden: this API key cannot access the requested resource.",
+        body
+      );
+    }
+    if (status === 404) {
+      return new _ApiError("not_found", 404, serverMsg ? `Not found: ${serverMsg}` : "Resource not found.", body);
+    }
+    if (status === 429) {
+      return new _ApiError("rate_limit", 429, "Rate limit exceeded. Wait a few seconds and retry.", body);
+    }
+    if (status >= 500) {
+      return new _ApiError(
+        "server",
+        status,
+        `DataDive API error (${status}). ${serverMsg ?? "Please try again."}`.trim(),
+        body
+      );
+    }
+    return new _ApiError("http", status, serverMsg ?? `HTTP ${status}`, body);
+  }
+};
+function extractMessage(body) {
+  if (!body || typeof body !== "object") return null;
+  const b = body;
+  if (typeof b.message === "string") return b.message;
+  if (Array.isArray(b.message) && b.message.every((m) => typeof m === "string")) {
+    return b.message.join("; ");
+  }
+  if (typeof b.error === "string") return b.error;
+  return null;
+}
+
+// package.json
+var version = "0.9.0";
+
+// src/http/client.ts
+var PKG_VERSION = version;
+var LATEST_VERSION_HEADER = "x-datadive-mcp-latest";
+var pendingUpgradeNotice = null;
+var hasWarned = false;
+function isNewerVersion(latest, current) {
+  const parse = (v) => v.split(/[-+]/)[0].split(".").map((n) => parseInt(n, 10) || 0);
+  const a = parse(latest);
+  const b = parse(current);
+  for (let i = 0; i < 3; i++) {
+    const da = a[i] ?? 0;
+    const db = b[i] ?? 0;
+    if (da !== db) return da > db;
+  }
+  return false;
+}
+function noteLatestVersion(latest) {
+  if (!latest || hasWarned) return;
+  if (isNewerVersion(latest, PKG_VERSION)) {
+    pendingUpgradeNotice = `A newer version of datadive-mcp is available (${latest}; you are running ${PKG_VERSION}). Update by reinstalling the latest from npm \u2014 e.g. \`npm install -g @datadive-tools/mcp@latest\` \u2014 or bump the @datadive-tools/mcp version in your MCP client config, then restart the client.`;
+  }
+}
+function takeUpgradeNotice() {
+  if (!pendingUpgradeNotice) return null;
+  const notice = pendingUpgradeNotice;
+  pendingUpgradeNotice = null;
+  hasWarned = true;
+  return notice;
+}
+var PAGINATION_KEYS = ["currentPage", "lastPage", "hasNext", "hasPrev", "pageSize", "total"];
+async function httpGet(ctx, path, query) {
+  const url = buildUrl(ctx.config.baseUrl, path, query);
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "GET",
+      headers: {
+        ...authHeaders(ctx.config),
+        accept: "application/json",
+        "user-agent": userAgent(ctx.toolName)
+      }
+    });
+  } catch (e) {
+    throw networkError(url, e);
+  }
+  return handleResponse(res);
+}
+async function httpPost(ctx, path, body) {
+  const url = buildUrl(ctx.config.baseUrl, path);
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: {
+        ...authHeaders(ctx.config),
+        accept: "application/json",
+        "content-type": "application/json",
+        "user-agent": userAgent(ctx.toolName)
+      },
+      body: JSON.stringify(body)
+    });
+  } catch (e) {
+    throw networkError(url, e);
+  }
+  return handleResponse(res);
+}
+function networkError(url, e) {
+  const msg = e instanceof Error ? e.message : String(e);
+  return new ApiError("network", 0, `Network error reaching ${url}: ${msg}`);
+}
+async function handleResponse(res) {
+  noteLatestVersion(res.headers.get(LATEST_VERSION_HEADER));
+  const text = await res.text();
+  let body;
+  try {
+    body = text.length > 0 ? JSON.parse(text) : null;
+  } catch {
+    body = text;
+  }
+  if (!res.ok) {
+    throw ApiError.fromHttp(res.status, body);
+  }
+  return unwrap(body);
+}
+function buildUrl(baseUrl, path, query) {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  const u = new URL(`${baseUrl}${normalizedPath}`);
+  if (query) {
+    for (const [k, v] of Object.entries(query)) {
+      if (v === void 0 || v === null) continue;
+      u.searchParams.set(k, String(v));
+    }
+  }
+  return u.toString();
+}
+function userAgent(toolName) {
+  return `datadive-mcp/${PKG_VERSION} tool/${toolName}`;
+}
+function authHeaders(config) {
+  const c = config.credentials;
+  return c.kind === "bearer" ? { authorization: `Bearer ${c.token}` } : { "x-api-key": c.apiKey };
+}
+function unwrap(body) {
+  if (!isObject(body)) return body;
+  if (!("data" in body)) return body;
+  for (const key of PAGINATION_KEYS) {
+    if (key in body) return body;
+  }
+  return body.data;
+}
+function isObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// src/tools/list-niches.ts
+var inputSchema = {
+  currentPage: z.number().int().min(1).optional().describe("Page number, 1-indexed. Defaults to 1."),
+  pageSize: z.number().int().min(1).max(100).optional().describe("Items per page (max 100). Defaults to 20.")
+};
+var listNichesTool = {
+  name: "list_niches",
+  title: "List DataDive Niches",
+  description: "Use this first when the user asks about their niches, or to find a `nicheId` for use with `get_niche_keywords`, `get_niche_competitors`, or `get_ranking_juice`. Retrieves a paginated list of Niches. Each Niche represents a market segment or product category being tracked. Returns nicheId, heroKeyword, nicheLabel, marketplace (com/uk/de/...), and latestResearchDate per niche, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).",
+  inputSchema,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "list_niches" },
+      "/v1/niches",
+      { currentPage: args.currentPage, pageSize: args.pageSize }
+    );
+  }
+};
+
+// src/tools/get-niche-keywords.ts
+import { z as z2 } from "zod";
+var inputSchema2 = {
+  nicheId: z2.string().min(1).describe("The unique identifier of the Niche (from `list_niches`).")
+};
+var getNicheKeywordsTool = {
+  name: "get_niche_keywords",
+  title: "Get Master Keyword List for a Niche",
+  description: 'Use this when the user asks about keywords, search terms, or search volume for a niche. Retrieves the master keyword list for the specified Niche \u2014 the relevant search terms monitored for ranking and performance metrics. For each keyword, returns search volume, relevancy (numeric score or "Outlier"), and competitor ASIN organic ranks (asinRanks: { ASIN -> rank | null }). Also returns the latestResearchDate.',
+  inputSchema: inputSchema2,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "get_niche_keywords" },
+      `/v1/niches/${encodeURIComponent(args.nicheId)}/keywords`
+    );
+  }
+};
+
+// src/tools/get-niche-roots.ts
+import { z as z3 } from "zod";
+var inputSchema3 = {
+  nicheId: z3.string().min(1).describe("The unique identifier of the Niche (from `list_niches`).")
+};
+var getNicheRootsTool = {
+  name: "get_niche_roots",
+  title: "Get Keyword Roots for a Niche",
+  description: "Use this when the user wants to find the highest-impact words across a niche's keywords, asks about 'keyword roots', or wants to prioritize terms for a listing. Retrieves the keyword lexical roots for the Niche \u2014 individual words or word-combinations extracted from the Master Keyword List (e.g. 'bluetooth headphones' yields roots 'bluetooth', 'headphones', 'bluetooth headphones'). Returns `roots` and `normalizedRoots` tables, each item with root, frequency (how many keywords contain it), broadSearchVolume (summed search volume of those keywords), and broadSearchVolumeRatio (0-1, relative to the top root), plus the per-keyword breakdowns and latestResearchDate.",
+  inputSchema: inputSchema3,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "get_niche_roots" },
+      `/v1/niches/${encodeURIComponent(args.nicheId)}/roots`
+    );
+  }
+};
+
+// src/tools/get-niche-competitors.ts
+import { z as z4 } from "zod";
+var inputSchema4 = {
+  nicheId: z4.string().min(1).describe("The unique identifier of the Niche (from `list_niches`).")
+};
+var getNicheCompetitorsTool = {
+  name: "get_niche_competitors",
+  title: "Get Competitors and Niche Statistics",
+  description: "Use this for competitor ASINs, sales/revenue benchmarks, or niche opportunity scoring. Retrieves the list of Competitors within the specified Niche along with Niche statistics. For the Niche: keyword statistics, opportunity evaluation, benchmark median values, and overall competitor strength assessment. For each Competitor: ASIN, sales, revenue, ratings, reviews, price, image URL, and ranking data.",
+  inputSchema: inputSchema4,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "get_niche_competitors" },
+      `/v1/niches/${encodeURIComponent(args.nicheId)}/competitors`
+    );
+  }
+};
+
+// src/tools/get-ranking-juice.ts
+import { z as z5 } from "zod";
+var inputSchema5 = {
+  nicheId: z5.string().min(1).describe("The unique identifier of the Niche (from `list_niches`).")
+};
+var getRankingJuiceTool = {
+  name: "get_ranking_juice",
+  title: "Get Ranking Juices for a Niche",
+  description: "Use this when the user asks 'how do I rank higher', 'what's my ranking juice', or wants listing-optimization guidance. Retrieves the Ranking Juices for each Competitor within the specified Niche. Ranking Juice is DataDive's proprietary metric identifying the key factors driving search-ranking success for each Competitor's listing. Returns currentListing and optimizedListing breakdowns (rankingJuice + per-property contributions: title, bullets, description) plus per-competitor listing scores and the latestResearchDate.",
+  inputSchema: inputSchema5,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "get_ranking_juice" },
+      `/v1/niches/${encodeURIComponent(args.nicheId)}/ranking-juices`
+    );
+  }
+};
+
+// src/tools/list-rank-radars.ts
+import { z as z6 } from "zod";
+
+// src/types/api.ts
+var ISO_8601 = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
+var SUPPORTED_MARKETPLACES = [
+  "com",
+  "ca",
+  "co.uk",
+  "com.mx",
+  "in",
+  "fr",
+  "de",
+  "es",
+  "it",
+  "co.jp"
+];
+var RANK_RADAR_STATUSES = ["ACTIVE", "PAUSED", "ARCHIVED"];
+var ALERT_STATUSES = ["active", "resolved", "all"];
+var BILLABLE_FEATURE_TYPES = [
+  "DIVED_ASINS",
+  "PRODUCT_BRIEF_ASINS",
+  "AI_COPYWRITER_PROMPTS",
+  "RANK_RADAR_KEYWORDS"
+];
+var CATALOG_STATUSES = ["Active", "all"];
+var LISTING_CHANGE_TYPES = ["Price", "Content", "Image"];
+var LISTING_CHANGE_SORT_BY = ["date", "type"];
+var SORT_ORDER = ["ASC", "DESC"];
+
+// src/tools/list-rank-radars.ts
+var inputSchema6 = {
+  currentPage: z6.number().int().min(1).optional().describe("Page number, 1-indexed. Defaults to 1."),
+  pageSize: z6.number().int().min(1).max(100).optional().describe("Items per page (max 100). Defaults to 20."),
+  nicheId: z6.string().min(1).optional().describe("Filter Rank Radars by Niche identifier. Use after `list_niches`."),
+  status: z6.enum(RANK_RADAR_STATUSES).optional().describe(
+    "Filter by Rank Radar status. By default, returns only ACTIVE Rank Radars. Allowed: ACTIVE, PAUSED, ARCHIVED."
+  ),
+  searchText: z6.string().optional().describe("Filter Rank Radars by ASIN or product title.")
+};
+var listRankRadarsTool = {
+  name: "list_rank_radars",
+  title: "List Rank Radars",
+  description: "Use this to find a `rankRadarId` before calling `get_rank_radar_data`. Filter by `nicheId` if the user has already identified a niche. Retrieves a paginated list of Rank Radars \u2014 keyword-rank trackers monitoring organic and sponsored positions for specific ASINs over time. Each item includes id, asin (with id, krtId, asin), marketplace, keywordCount, title, imageUrl, and summary metrics: top10KW, top10SV, top50KW, top50SV. Supports pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).",
+  inputSchema: inputSchema6,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "list_rank_radars" },
+      "/v1/niches/rank-radars",
+      {
+        currentPage: args.currentPage,
+        pageSize: args.pageSize,
+        nicheId: args.nicheId,
+        status: args.status,
+        searchText: args.searchText
+      }
+    );
+  }
+};
+
+// src/tools/get-rank-radar-data.ts
+import { z as z7 } from "zod";
+var ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+var inputSchema7 = {
+  rankRadarId: z7.string().uuid().describe("The Rank Radar UUID (from `list_rank_radars`)."),
+  startDate: z7.string().regex(ISO_DATE, "startDate must be in yyyy-mm-dd format").describe("Start date for the ranking data range, yyyy-mm-dd (e.g. 2024-03-26)."),
+  endDate: z7.string().regex(ISO_DATE, "endDate must be in yyyy-mm-dd format").describe("End date for the ranking data range, yyyy-mm-dd (e.g. 2024-04-26). Must be on or after startDate.")
+};
+var getRankRadarDataTool = {
+  name: "get_rank_radar_data",
+  title: "Get Keyword Rankings for a Rank Radar",
+  description: "Use this to analyze keyword ranking trends over time. Requires startDate and endDate (yyyy-mm-dd). Retrieves historical keyword ranking data for the specified Rank Radar within the date range. Returns an array of tracked keywords; each has id, keyword, searchVolume, ranks (per-day { date, organicRank, impressionRank }), and any highlight annotations. Use after `list_rank_radars` to discover a `rankRadarId`.",
+  inputSchema: inputSchema7,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "get_rank_radar_data" },
+      `/v1/niches/rank-radars/${encodeURIComponent(args.rankRadarId)}`,
+      { startDate: args.startDate, endDate: args.endDate }
+    );
+  }
+};
+
+// src/tools/create-rank-radar.ts
+import { z as z8 } from "zod";
+
+// src/tools/confirm.ts
+function requireConfirmation(confirm, ctx, costNote) {
+  if (confirm === true || ctx.config.autoConfirmWrites) return null;
+  return {
+    status: "confirmation_required",
+    message: "This action spends billable tokens and cannot be undone. Confirm the cost with the user, then call again with `confirm: true` to proceed.",
+    costNote
+  };
+}
+
+// src/tools/create-rank-radar.ts
+var inputSchema8 = {
+  asin: z8.string().min(1).describe("The ASIN to track keyword rankings for."),
+  numberOfKeywords: z8.number().int().min(1).describe("How many keywords to track (minimum 1). More keywords = broader tracking but more Search Term tokens."),
+  nicheId: z8.string().min(1).describe("The niche this Rank Radar belongs to. Get one from `list_niches`."),
+  confirm: z8.boolean().optional().describe(
+    "Must be true to proceed \u2014 creating a Rank Radar spends Search Term tokens. Confirm the cost with the user first."
+  )
+};
+var createRankRadarTool = {
+  name: "create_rank_radar",
+  title: "Create a Rank Radar",
+  description: "Use this to start tracking organic and sponsored keyword rankings for an ASIN within a niche. \u26A0\uFE0F Spends Search Term tokens (cost scales with `numberOfKeywords`) and cannot be undone \u2014 set `confirm: true` only after the user approves the cost. Returns the new `rankRadarId`; read its data later with `get_rank_radar_data`. Requires `asin`, `numberOfKeywords` (min 1), and a `nicheId` from `list_niches`.",
+  inputSchema: inputSchema8,
+  // destructiveHint is technically "additive" here (this creates a new Rank Radar, it
+  // doesn't destroy data), but we flag it destructive so clients prompt before the
+  // irreversible token spend. The confirm gate enforces this server-side regardless.
+  annotations: { readOnlyHint: false, destructiveHint: true },
+  handler: async (args, ctx) => {
+    const pending = requireConfirmation(
+      args.confirm,
+      ctx,
+      `Creating this Rank Radar consumes Search Term tokens \u2014 one per keyword tracked (${args.numberOfKeywords} requested).`
+    );
+    if (pending) return pending;
+    return await httpPost(
+      { config: ctx.config, toolName: "create_rank_radar" },
+      "/v1/niches/rank-radars",
+      {
+        asin: args.asin,
+        numberOfKeywords: args.numberOfKeywords,
+        nicheId: args.nicheId
+      }
+    );
+  }
+};
+
+// src/tools/create-niche-dive.ts
+import { z as z9 } from "zod";
+var inputSchema9 = {
+  marketplace: z9.enum(SUPPORTED_MARKETPLACES).describe(
+    "Amazon marketplace of the seed ASIN. Note these are full domain suffixes: com, ca, co.uk, com.mx, in, fr, de, es, it, co.jp (e.g. UK is `co.uk`, not `uk`)."
+  ),
+  asin: z9.string().min(1).describe("The seed ASIN to start the dive from (e.g. B08N5WRWNW). Competitors are built around it."),
+  numberOfCompetitors: z9.number().int().min(2).describe("How many competitors to analyze (minimum 2). More competitors = deeper niche but more dive tokens."),
+  confirm: z9.boolean().optional().describe("Must be true to proceed \u2014 creating a dive spends dive tokens. Confirm the cost with the user first.")
+};
+var createNicheDiveTool = {
+  name: "create_niche_dive",
+  title: "Create a Niche Dive",
+  description: "Use this to start new niche research from a seed ASIN. \u26A0\uFE0F Spends dive tokens (cost scales with `numberOfCompetitors`) and cannot be undone \u2014 set `confirm: true` only after the user approves the cost. The dive runs asynchronously: this returns immediately with a `diveId` and an `estimatedCompletionDate`. Poll `get_dive_status` with that `diveId` until it reports `success` (which carries the new `nicheId` for use with `list_niches`, `get_niche_keywords`, etc.). Requires `marketplace`, `asin`, and `numberOfCompetitors` (min 2).",
+  inputSchema: inputSchema9,
+  // destructiveHint is technically "additive" here (a dive creates a new niche, it
+  // doesn't destroy data), but we flag it destructive so clients prompt before the
+  // irreversible token spend. The confirm gate enforces this server-side regardless.
+  annotations: { readOnlyHint: false, destructiveHint: true },
+  handler: async (args, ctx) => {
+    const pending = requireConfirmation(
+      args.confirm,
+      ctx,
+      `Creating this dive consumes dive tokens \u2014 one batch per competitor analyzed (${args.numberOfCompetitors} requested).`
+    );
+    if (pending) return pending;
+    return await httpPost(
+      { config: ctx.config, toolName: "create_niche_dive" },
+      "/v1/niches/dives",
+      {
+        marketplace: args.marketplace,
+        asin: args.asin,
+        numberOfCompetitors: args.numberOfCompetitors
+      }
+    );
+  }
+};
+
+// src/tools/redive-niche.ts
+import { z as z10 } from "zod";
+var inputSchema10 = {
+  nicheId: z10.string().min(1).describe("The niche to re-dive. Get one from `list_niches`."),
+  mode: z10.enum(["same_competitors", "discover"]).describe(
+    "How to pick the competitors for the refreshed dive. `same_competitors` re-runs the niche's current competitor set and takes no other argument \u2014 use it to refresh stale data. `discover` searches for a fresh competitor set, which is what you want when the niche has changed."
+  ),
+  numberOfCompetitors: z10.number().int().min(2).optional().describe(
+    "Total ASINs the refreshed dive should contain, including `lockedAsins`. Required in `discover` mode and rejected in `same_competitors` mode. Dive tokens are spent per ASIN."
+  ),
+  heroAsin: z10.string().min(1).optional().describe(
+    "`discover` mode only. Seed product the competitor discovery starts from. Defaults to the niche's highest-selling competitor, preferring one the user's own connected seller account owns."
+  ),
+  lockedAsins: z10.array(z10.string().min(1)).optional().describe(
+    "`discover` mode only. ASINs that must stay in the competitor set regardless of what discovery finds. Cannot exceed `numberOfCompetitors`, and cannot overlap `excludedAsins`."
+  ),
+  excludedAsins: z10.array(z10.string().min(1)).optional().describe("`discover` mode only. ASINs discovery must never select."),
+  confirm: z10.boolean().optional().describe(
+    "Must be true to proceed \u2014 a re-dive spends dive tokens. Confirm the cost with the user first."
+  )
+};
+var rediveNicheTool = {
+  name: "redive_niche",
+  title: "Re-dive an Existing Niche",
+  description: "Use this to refresh an existing niche's research with current Amazon data, instead of creating a new niche with `create_niche_dive`. \u26A0\uFE0F Spends dive tokens (one batch per ASIN dived) and cannot be undone \u2014 set `confirm: true` only after the user approves the cost. Two modes: `same_competitors` re-dives the niche's current competitor set (no other argument needed) and `discover` finds a fresh set, sized by `numberOfCompetitors` and steerable with `heroAsin` / `lockedAsins` / `excludedAsins`. Runs asynchronously: returns a `diveId` and an `estimatedCompletionDate` \u2014 poll `get_dive_status` with that `diveId` until it reports `success`. The niche keeps its `nicheId`, so existing rank radars and reports follow the refreshed data.",
+  inputSchema: inputSchema10,
+  // Same reasoning as create_niche_dive: a re-dive is additive rather than destructive, but the
+  // irreversible token spend is what clients need to prompt on. The confirm gate enforces it regardless.
+  annotations: { readOnlyHint: false, destructiveHint: true },
+  handler: async (args, ctx) => {
+    if (args.mode === "discover" && args.numberOfCompetitors === void 0) {
+      throw new ApiError(
+        "bad_request",
+        400,
+        'numberOfCompetitors is required in `discover` mode \u2014 it is how many ASINs the refreshed dive will contain, and therefore what it costs. Ask the user how many competitors they want (minimum 2), or use mode "same_competitors" to re-dive the niche\'s current set.'
+      );
+    }
+    const pending = requireConfirmation(
+      args.confirm,
+      ctx,
+      args.mode === "discover" ? `Re-diving this niche consumes dive tokens \u2014 one batch per ASIN analyzed (${args.numberOfCompetitors} requested).` : "Re-diving this niche consumes dive tokens \u2014 one batch per competitor currently in the niche. Use `get_niche_competitors` first if the user needs the exact count."
+    );
+    if (pending) return pending;
+    return await httpPost(
+      { config: ctx.config, toolName: "redive_niche" },
+      `/v1/niches/${encodeURIComponent(args.nicheId)}/redive`,
+      {
+        mode: args.mode,
+        numberOfCompetitors: args.numberOfCompetitors,
+        heroAsin: args.heroAsin,
+        lockedAsins: args.lockedAsins,
+        excludedAsins: args.excludedAsins
+      }
+    );
+  }
+};
+
+// src/tools/get-dive-status.ts
+import { z as z11 } from "zod";
+var inputSchema11 = {
+  diveId: z11.string().min(1).describe("The dive identifier returned by `create_niche_dive` or `redive_niche`.")
+};
+var getDiveStatusTool = {
+  name: "get_dive_status",
+  title: "Get Niche Dive Status",
+  description: "Use this to poll a niche dive started with `create_niche_dive` or `redive_niche` until it finishes. Returns one of three shapes keyed by `status`: `in_progress` (with `estimatedCompletionDate`), `success` (with the `nicheId` plus `tokensUsed`/`tokensLeft`), or `error` (with an `error` message). On `success`, use the `nicheId` with `list_niches`, `get_niche_keywords`, `get_niche_competitors`, etc. (for a re-dive it is the same niche you passed in, now carrying refreshed data). Re-poll periodically \u2014 dives can take minutes; the `estimatedCompletionDate` hints at when to check.",
+  inputSchema: inputSchema11,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "get_dive_status" },
+      `/v1/niches/dives/${encodeURIComponent(args.diveId)}`
+    );
+  }
+};
+
+// src/tools/list-seller-profiles.ts
+import { z as z12 } from "zod";
+var inputSchema12 = {
+  currentPage: z12.number().int().min(1).optional().describe("Page number, 1-indexed. Defaults to 1."),
+  pageSize: z12.number().int().min(1).max(50).optional().describe("Items per page (max 50). Defaults to 20.")
+};
+var listSellerProfilesTool = {
+  name: "list_seller_profiles",
+  title: "List Connected Amazon Seller Profiles",
+  description: 'Use this when the user asks which Amazon seller accounts are connected, or as the discovery step to find the `sellerId` and `marketplace` required by `get_asin_inventory_distribution`, `get_seller_catalog`, `get_seller_listing_changes`, and the alert tools. Returns a paginated list of the organization\'s connected seller profiles \u2014 each item has sellerId, sellerName, marketplace (e.g. "com", "co.uk"), hasAdApi (whether Advertising API credentials are connected), and createdAt \u2014 plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).',
+  inputSchema: inputSchema12,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "list_seller_profiles" },
+      "/v1/seller_profiles",
+      {
+        currentPage: args.currentPage,
+        pageSize: args.pageSize
+      }
+    );
+  }
+};
+
+// src/tools/get-seller-catalog.ts
+import { z as z14 } from "zod";
+
+// src/tools/seller-scoped.ts
+import { z as z13 } from "zod";
+var sellerScopedInputSchema = {
+  sellerId: z13.string().min(1).describe(
+    "Amazon seller account ID. Get it from `list_seller_profiles`, or find it on the Connections page at https://2.datadive.tools."
+  ),
+  marketplace: z13.enum(SUPPORTED_MARKETPLACES).describe('Amazon marketplace code, e.g. "com" for amazon.com or "co.uk" for amazon.co.uk.')
+};
+function sellerMarketplacePath(sellerId, marketplace, suffix) {
+  return `/v1/seller_profiles/${encodeURIComponent(sellerId)}/marketplaces/${encodeURIComponent(
+    marketplace
+  )}/${suffix}`;
+}
+
+// src/tools/get-seller-catalog.ts
+var inputSchema13 = {
+  ...sellerScopedInputSchema,
+  search: z14.string().min(1).optional().describe("Case-insensitive partial match on product title or brand."),
+  brand: z14.string().min(1).optional().describe("Case-insensitive partial match on brand name."),
+  status: z14.enum(CATALOG_STATUSES).optional().describe('Listing status filter. "Active" (default) or "all".'),
+  currentPage: z14.number().int().min(1).optional().describe("Page number, 1-indexed. Defaults to 1."),
+  pageSize: z14.number().int().min(1).max(50).optional().describe("Items per page (max 50). Defaults to 20.")
+};
+var getSellerCatalogTool = {
+  name: "get_seller_catalog",
+  title: "List Catalog ASINs for a Seller",
+  description: "Use this when the user wants to browse or search a seller's own Amazon catalog \u2014 the products they sell on a given marketplace. Requires a `sellerId` + `marketplace` (use `list_seller_profiles` to discover them). Filter by `search` (title/brand), `brand`, and `status` (Active by default, or all). Returns a paginated list where each item has asin, title, parentAsin, brand, status, imageUrl, and hasVariations, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).",
+  inputSchema: inputSchema13,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "get_seller_catalog" },
+      sellerMarketplacePath(args.sellerId, args.marketplace, "catalog"),
+      {
+        search: args.search,
+        brand: args.brand,
+        status: args.status,
+        currentPage: args.currentPage,
+        pageSize: args.pageSize
+      }
+    );
+  }
+};
+
+// src/tools/get-seller-listing-changes.ts
+import { z as z15 } from "zod";
+var inputSchema14 = {
+  ...sellerScopedInputSchema,
+  types: z15.array(z15.enum(LISTING_CHANGE_TYPES)).min(1).optional().describe('Filter to specific change types. Omit for all. Any of "Price", "Content", "Image".'),
+  asin: z15.string().min(1).optional().describe("Filter to an exact ASIN or parent ASIN."),
+  brand: z15.string().min(1).optional().describe("Case-insensitive partial match on brand name."),
+  search: z15.string().min(1).optional().describe("Case-insensitive partial match on product title or brand."),
+  startDate: z15.string().regex(ISO_8601, "startDate must be an ISO-8601 date or timestamp (e.g. 2026-05-01 or 2026-05-01T00:00:00Z)").optional().describe("ISO-8601 date/timestamp; return only changes detected on or after this time."),
+  endDate: z15.string().regex(ISO_8601, "endDate must be an ISO-8601 date or timestamp (e.g. 2026-05-31 or 2026-05-31T23:59:59Z)").optional().describe("ISO-8601 date/timestamp; return only changes detected on or before this time."),
+  sortBy: z15.enum(LISTING_CHANGE_SORT_BY).optional().describe('Sort field. "date" (default) or "type".'),
+  sortOrder: z15.enum(SORT_ORDER).optional().describe('Sort direction. "DESC" (default) or "ASC".'),
+  includeCorrelations: z15.boolean().optional().describe(
+    "When true, include the ranking/conversion `correlation` object per change (CVR and search-term movement before vs after). Defaults to false."
+  ),
+  currentPage: z15.number().int().min(1).optional().describe("Page number, 1-indexed. Defaults to 1."),
+  pageSize: z15.number().int().min(1).max(50).optional().describe("Items per page (max 50). Defaults to 20.")
+};
+var getSellerListingChangesTool = {
+  name: "get_seller_listing_changes",
+  title: "List Listing Changes for a Seller",
+  description: "Use this when the user asks what changed on their Amazon listings \u2014 price, content (title/bullets/description), or image edits \u2014 for a seller account. Requires a `sellerId` + `marketplace` (use `list_seller_profiles` to discover them). Filter by `types`, `asin`/parent ASIN, `brand`, `search`, and a `startDate`/`endDate` range; sort with `sortBy`/`sortOrder`. Set `includeCorrelations: true` to attach the ranking/conversion impact per change. Returns a paginated list where each item has asin, title, imageUrl, date, type, contentType, description, previousValue, newValue, and (optionally) correlation, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).",
+  inputSchema: inputSchema14,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "get_seller_listing_changes" },
+      sellerMarketplacePath(args.sellerId, args.marketplace, "listing-changes"),
+      {
+        // The API accepts `types` as a comma-separated list.
+        types: args.types?.join(","),
+        asin: args.asin,
+        brand: args.brand,
+        search: args.search,
+        startDate: args.startDate,
+        endDate: args.endDate,
+        sortBy: args.sortBy,
+        sortOrder: args.sortOrder,
+        includeCorrelations: args.includeCorrelations,
+        currentPage: args.currentPage,
+        pageSize: args.pageSize
+      }
+    );
+  }
+};
+
+// src/tools/get-asin-inventory-distribution.ts
+import { z as z16 } from "zod";
+var inputSchema15 = {
+  sellerId: z16.string().min(1).describe(
+    "Amazon seller account ID as connected to DataDive. Get it from `list_seller_profiles`, or find it on the Connections page at https://2.datadive.tools."
+  ),
+  marketplace: z16.enum(SUPPORTED_MARKETPLACES).describe('Amazon marketplace code, e.g. "com" for amazon.com or "co.uk" for amazon.co.uk.'),
+  asin: z16.string().regex(/^[A-Z0-9]{10}$/, "ASIN must be 10 uppercase alphanumeric characters (e.g. B08XYZ1234).").describe(
+    "Amazon Standard Identification Number (10 uppercase alphanumeric characters, e.g. B08XYZ1234)."
+  )
+};
+var getAsinInventoryDistributionTool = {
+  name: "get_asin_inventory_distribution",
+  title: "Get Per-Fulfillment-Center Inventory Distribution for an ASIN",
+  description: "Use this when the user asks about inventory levels, stock by fulfillment center, or where their units are sitting across Amazon's fulfillment network for a specific ASIN. Requires the Amazon sellerId (from `list_seller_profiles` or the user's DataDive Connections page at https://2.datadive.tools), the marketplace code, and the ASIN. Returns totalSellableUnits and a per-FC `distribution` array (fc, state, availableStock, availableStockPercentage). `lastUpdatedAt` may be null when no successful inventory ingestion has occurred in the last 30 days.",
+  inputSchema: inputSchema15,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "get_asin_inventory_distribution" },
+      `/v1/sellers/${encodeURIComponent(args.sellerId)}/marketplaces/${encodeURIComponent(
+        args.marketplace
+      )}/asins/${encodeURIComponent(args.asin)}/inventory`
+    );
+  }
+};
+
+// src/tools/alert-query.ts
+import { z as z17 } from "zod";
+var alertsQueryInputSchema = {
+  sellerId: z17.string().min(1).max(50).optional().describe('Filter to a single connected Amazon seller account ID, e.g. "A1B2C3D4E5".'),
+  marketplace: z17.enum(SUPPORTED_MARKETPLACES).optional().describe('Filter to a single Amazon marketplace code, e.g. "com" for amazon.com or "co.uk" for amazon.co.uk.'),
+  status: z17.enum(ALERT_STATUSES).optional().describe(
+    "Lifecycle filter. `active` (default) returns unresolved alerts, `resolved` returns resolved alerts, `all` returns both. Dismissed alerts are never returned."
+  ),
+  updatedSince: z17.string().regex(ISO_8601, "updatedSince must be an ISO-8601 date or timestamp (e.g. 2026-05-01 or 2026-05-01T00:00:00Z)").optional().describe(
+    "ISO-8601 timestamp; return only alerts surfaced at or after this time (filters on `lastAlertedAt`). Use it to incrementally sync since your last poll. Defaults to the last 30 days when omitted."
+  ),
+  currentPage: z17.number().int().min(1).optional().describe("Page number, 1-indexed. Defaults to 1."),
+  pageSize: z17.number().int().min(1).max(50).optional().describe("Items per page (max 50). Defaults to 20.")
+};
+
+// src/tools/list-indexing-issue-alerts.ts
+var listIndexingIssueAlertsTool = {
+  name: "list_indexing_issue_alerts",
+  title: "List Indexing-Issue Alerts",
+  description: "Use this to find products that may have lost search visibility. Retrieves a paginated list of indexing-issue alerts across the user's connected Amazon seller accounts \u2014 an alert fires when one of their ASINs is no longer indexed for its tracked keywords. By default returns active (unresolved) alerts from the last 30 days; filter by `sellerId`, `marketplace`, `status`, or `updatedSince` (for incremental polling). Each item includes id, asin, title, imageUrl, isParent, sellerId, marketplace, lastAlertedAt, and resolvedAt. Supports pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).",
+  inputSchema: alertsQueryInputSchema,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "list_indexing_issue_alerts" },
+      "/v1/alerts/indexing-issues",
+      {
+        sellerId: args.sellerId,
+        marketplace: args.marketplace,
+        status: args.status,
+        updatedSince: args.updatedSince,
+        currentPage: args.currentPage,
+        pageSize: args.pageSize
+      }
+    );
+  }
+};
+
+// src/tools/list-blind-spend-alerts.ts
+var listBlindSpendAlertsTool = {
+  name: "list_blind_spend_alerts",
+  title: "List Blind-Spend (Wasted-Spend) Alerts",
+  description: "Use this to find wasted PPC ad spend. Retrieves a paginated list of blind-spend alerts across the user's connected Amazon seller accounts \u2014 an alert flags ad spend on customer search terms that produced little or no sales. By default returns active (unresolved) alerts from the last 30 days; filter by `sellerId`, `marketplace`, `status`, or `updatedSince` (for incremental polling). Each item includes id, asin, title, imageUrl, sellerId, marketplace, lastAlertedAt, resolvedAt, wastedSpend (total ad spend across unresolved terms), totalKeywordCount, unresolvedKeywordCount, and searchTerms \u2014 the unresolved wasted-spend search terms, each with term, spend, sales, clicks, cvr (0-1), and impressions. Supports pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).",
+  inputSchema: alertsQueryInputSchema,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "list_blind_spend_alerts" },
+      "/v1/alerts/blind-spend",
+      {
+        sellerId: args.sellerId,
+        marketplace: args.marketplace,
+        status: args.status,
+        updatedSince: args.updatedSince,
+        currentPage: args.currentPage,
+        pageSize: args.pageSize
+      }
+    );
+  }
+};
+
+// src/tools/get-quota.ts
+var inputSchema16 = {};
+var getQuotaTool = {
+  name: "get_quota",
+  title: "Get Quota Usage",
+  description: "Use this when the user asks how much quota or how many tokens they have left, or before creating a Niche Dive or Rank Radar to check remaining headroom. Returns current quota usage and capacity for each billable feature \u2014 DIVED_ASINS (Dive tokens), RANK_RADAR_KEYWORDS (tracked keywords), PRODUCT_BRIEF_ASINS, and AI_COPYWRITER_PROMPTS \u2014 each with `used` and `capacity` (null when unlimited / not applicable), plus `nextRefreshDate` (ISO-8601 timestamp of the next quota reset, or null). Takes no arguments.",
+  inputSchema: inputSchema16,
+  annotations: { readOnlyHint: true },
+  handler: async (_args, ctx) => {
+    return await httpGet({ config: ctx.config, toolName: "get_quota" }, "/v1/quota");
+  }
+};
+
+// src/tools/list-usage.ts
+import { z as z18 } from "zod";
+var inputSchema17 = {
+  type: z18.enum(BILLABLE_FEATURE_TYPES).optional().describe("Filter to a single billable feature type. Omit to return all types."),
+  search: z18.string().min(1).optional().describe("Case-insensitive partial match on the user's name or email."),
+  startDate: z18.string().regex(ISO_8601, "startDate must be an ISO-8601 date or timestamp (e.g. 2026-05-01 or 2026-05-01T00:00:00Z)").optional().describe("ISO-8601 date/timestamp; return only usage logs recorded on or after this time."),
+  endDate: z18.string().regex(ISO_8601, "endDate must be an ISO-8601 date or timestamp (e.g. 2026-05-31 or 2026-05-31T23:59:59Z)").optional().describe("ISO-8601 date/timestamp; return only usage logs recorded on or before this time."),
+  currentPage: z18.number().int().min(1).optional().describe("Page number, 1-indexed. Defaults to 1."),
+  pageSize: z18.number().int().min(1).max(200).optional().describe("Items per page (max 200). Defaults to 50.")
+};
+var listUsageTool = {
+  name: "list_usage",
+  title: "List Billable Usage Logs",
+  description: "Use this when the user asks who consumed tokens, how their quota was spent, or wants an audit of billable activity over a date range. Retrieves a paginated list of billable feature usage logs for the organization \u2014 each entry is a token-consumption event (a dive, rank-radar creation, AI copywriter prompt, etc.). Filter by `type` (billable feature), `search` (user name/email), and `startDate`/`endDate`. Each item includes name, email, qty (tokens consumed), type, action (specific operation), nicheId/nicheName, rankRadarId, and date, plus pagination metadata (currentPage, pageSize, total, lastPage, hasNext, hasPrev).",
+  inputSchema: inputSchema17,
+  annotations: { readOnlyHint: true },
+  handler: async (args, ctx) => {
+    return await httpGet(
+      { config: ctx.config, toolName: "list_usage" },
+      "/v1/usage",
+      {
+        type: args.type,
+        search: args.search,
+        startDate: args.startDate,
+        endDate: args.endDate,
+        currentPage: args.currentPage,
+        pageSize: args.pageSize
+      }
+    );
+  }
+};
+
+// src/tools/index.ts
+var allTools = [
+  listNichesTool,
+  getNicheKeywordsTool,
+  getNicheRootsTool,
+  getNicheCompetitorsTool,
+  getRankingJuiceTool,
+  listRankRadarsTool,
+  getRankRadarDataTool,
+  createRankRadarTool,
+  createNicheDiveTool,
+  rediveNicheTool,
+  getDiveStatusTool,
+  listSellerProfilesTool,
+  getSellerCatalogTool,
+  getSellerListingChangesTool,
+  getAsinInventoryDistributionTool,
+  listIndexingIssueAlertsTool,
+  listBlindSpendAlertsTool,
+  getQuotaTool,
+  listUsageTool
+];
+
+// src/server.ts
+function requiredScope(tool) {
+  return tool.annotations?.readOnlyHint === true ? SCOPE_READ : SCOPE_WRITE;
+}
+function buildServer(config) {
+  const server = new McpServer({
+    name: "datadive",
+    version: PKG_VERSION
+  });
+  for (const tool of allTools) {
+    server.registerTool(
+      tool.name,
+      {
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        annotations: tool.annotations
+      },
+      async (args) => {
+        const scope = requiredScope(tool);
+        if (config.scopes && !config.scopes.includes(scope)) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: `Insufficient scope: this tool requires the "${scope}" scope, which was not granted to this connection. Reconnect DataDive and enable the missing permission to use it.`
+              }
+            ]
+          };
+        }
+        try {
+          const data = await tool.handler(args, { config });
+          const content = [
+            {
+              type: "text",
+              text: JSON.stringify(data, null, 2)
+            }
+          ];
+          const notice = takeUpgradeNotice();
+          if (notice) {
+            content.push({
+              type: "text",
+              text: `\u26A0\uFE0F datadive-mcp update available \u2014 ${notice}`
+            });
+          }
+          return { content };
+        } catch (err) {
+          return {
+            isError: true,
+            content: [
+              {
+                type: "text",
+                text: err instanceof ApiError ? err.message : err instanceof Error ? err.message : String(err)
+              }
+            ]
+          };
+        }
+      }
+    );
+  }
+  return server;
+}
+export {
+  ApiError,
+  PKG_VERSION,
+  SCOPE_READ,
+  SCOPE_WRITE,
+  allTools,
+  buildServer,
+  loadConfig,
+  requiredScope
+};
+//# sourceMappingURL=lib.js.map