@datadive-tools/mcp 0.7.0 → 0.8.0

package/dist/index.js

@@ -4,6 +4,8 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.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) {
@@ -18,7 +20,7 @@ function loadConfig(env = process.env) {
   const autoConfirmWrites = ["1", "true", "yes"].includes(
     (env.DATADIVE_AUTO_CONFIRM_WRITES ?? "").trim().toLowerCase()
   );
-  return { apiKey, baseUrl, autoConfirmWrites };
+  return { credentials: { kind: "api-key", apiKey }, baseUrl, autoConfirmWrites };
 }
 
 // src/server.ts
@@ -103,7 +105,7 @@ function extractMessage(body) {
 }
 
 // package.json
-var version = "0.7.0";
+var version = "0.8.0";
 
 // src/http/client.ts
 var PKG_VERSION = version;
@@ -142,7 +144,7 @@ async function httpGet(ctx, path, query) {
     res = await fetch(url, {
       method: "GET",
       headers: {
-        "x-api-key": ctx.config.apiKey,
+        ...authHeaders(ctx.config),
         accept: "application/json",
         "user-agent": userAgent(ctx.toolName)
       }
@@ -159,7 +161,7 @@ async function httpPost(ctx, path, body) {
     res = await fetch(url, {
       method: "POST",
       headers: {
-        "x-api-key": ctx.config.apiKey,
+        ...authHeaders(ctx.config),
         accept: "application/json",
         "content-type": "application/json",
         "user-agent": userAgent(ctx.toolName)
@@ -203,6 +205,10 @@ function buildUrl(baseUrl, path, query) {
 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;
@@ -225,6 +231,7 @@ var listNichesTool = {
   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" },
@@ -244,6 +251,7 @@ var getNicheKeywordsTool = {
   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" },
@@ -262,6 +270,7 @@ var getNicheRootsTool = {
   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" },
@@ -280,6 +289,7 @@ var getNicheCompetitorsTool = {
   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" },
@@ -298,6 +308,7 @@ var getRankingJuiceTool = {
   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" },
@@ -351,6 +362,7 @@ var listRankRadarsTool = {
   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" },
@@ -379,6 +391,7 @@ var getRankRadarDataTool = {
   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" },
@@ -628,6 +641,7 @@ var getAsinInventoryDistributionTool = {
   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: inputSchema14,
+  annotations: { readOnlyHint: true },
   handler: async (args, ctx) => {
     return await httpGet(
       { config: ctx.config, toolName: "get_asin_inventory_distribution" },
@@ -659,6 +673,7 @@ var listIndexingIssueAlertsTool = {
   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" },
@@ -681,6 +696,7 @@ var listBlindSpendAlertsTool = {
   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" },
@@ -704,6 +720,7 @@ var getQuotaTool = {
   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: inputSchema15,
+  annotations: { readOnlyHint: true },
   handler: async (_args, ctx) => {
     return await httpGet({ config: ctx.config, toolName: "get_quota" }, "/v1/quota");
   }
@@ -724,6 +741,7 @@ var listUsageTool = {
   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: inputSchema16,
+  annotations: { readOnlyHint: true },
   handler: async (args, ctx) => {
     return await httpGet(
       { config: ctx.config, toolName: "list_usage" },
@@ -763,6 +781,9 @@ var allTools = [
 ];
 
 // src/server.ts
+function requiredScope(tool) {
+  return tool.annotations?.readOnlyHint === true ? SCOPE_READ : SCOPE_WRITE;
+}
 function buildServer(config) {
   const server = new McpServer({
     name: "datadive",
@@ -778,6 +799,18 @@ function buildServer(config) {
         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 = [