@cite42/mcp 0.5.1 → 0.6.0

package/README.md

@@ -10,7 +10,7 @@ Once connected, Claude Code, Claude Desktop, Codex CLI, or Cursor can:
 - **Track brand visibility** in AI answers: rankings, head-to-head comparisons, and sentiment
 - **Schedule weekly or monthly trackers**: one measurement — rankings, comparisons, citations, or sentiment — over a list of prompts, with setup confirmation and a useful email after every run, then ask your agent for stored history
 - **Pull SEO data**: keyword search volume, CPC, competition, and Google Trends
-- **Mine Reddit and YouTube** for audience questions, pain points, and rising content
+- **Research Reddit discussions and YouTube content** for audience questions, pain points, and content ideas
 - **Run full research workflows**: content gaps, topic demand, AI prompt maps, competitor analysis, and content briefs in a single call
 
 ---
@@ -18,7 +18,7 @@ Once connected, Claude Code, Claude Desktop, Codex CLI, or Cursor can:
 ## Requirements
 
 - **A Cite42 account**, free to create at [cite42.dev](https://www.cite42.dev)
-- **Node.js 18 or newer and a Cite42 API key** for Claude Code, Codex CLI, and Cursor
+- **Node.js 22.13 or newer and a Cite42 API key** for Claude Code, Codex CLI, and Cursor
 
 ## Installation
 
@@ -94,7 +94,7 @@ You do not need to keep `npx -y @cite42/mcp` running in a separate terminal. Loc
 - **Claude Code:** run `claude mcp list` and check that `cite42` shows as ✔ connected. Or type `/mcp` inside a session.
 - **Claude Desktop:** open **Settings → Connectors** and confirm Cite42 is connected.
 - **Codex CLI:** run `codex mcp list`.
-- **Cursor:** look for `cite42` in the MCP/tools indicator. 26 tools should be listed.
+- **Cursor:** look for `cite42` in the MCP/tools indicator. 29 tools should be listed.
 
 If it doesn't appear, see [Troubleshooting](#troubleshooting).
 
@@ -107,7 +107,7 @@ After connecting or restarting, just ask in plain language. Your agent picks the
 - *"Get search volume, CPC, and related keywords for 'ai seo tools'."*
 - *"What are people on Reddit complaining about regarding email marketing tools?"*
 - *"Run a content brief for the topic 'ai website builder'."*
-- *"Map the prompts worth tracking for our category, then create a weekly Cite42 rankings tracker for the best five. Show me the estimated credits per run before activating it."*
+- *"Map the prompts worth tracking for our category, then create a weekly Cite42 rankings tracker for the best five. Show me the estimated cost in USD per run before activating it."*
 
 ### Example: what a session looks like
 
@@ -130,11 +130,12 @@ That is the three default surfaces; ask for `fullSweep` to add Claude and Google
 
 ## Tools
 
-Cite42 exposes 26 MCP tools: 3 free account tools, 9 data tools, 6 research workflows, and 8 tracker tools.
+Cite42 exposes 29 MCP tools: 4 free account tools (including the compatibility alias), 11 data/report tools, 6 research workflows, and 8 tracker tools.
 
 ### Account & pricing (free)
 
-- `cite42_credits`: check the connected account's remaining Cite42 credit balance.
+- `cite42_balance`: check the connected account’s remaining Cite42 balance in USD.
+- `cite42_credits`: compatibility alias for older integrations.
 - `cite42_pricing`: get current per-tool prices and estimate a planned set of calls.
 - `cite42_usage`: read recent call status and cost together with the remaining balance.
 
@@ -145,12 +146,14 @@ Cite42 exposes 26 MCP tools: 3 free account tools, 9 data tools, 6 research work
 - `cite42_rankings`: measure how brands rank in AI answers, including mention rate, average position, and per-model breakdown.
 - `cite42_compare`: compare one brand against competitors in AI answers.
 - `cite42_sentiment`: score positive, neutral, and negative sentiment for a brand, with supporting phrases.
+- `cite42_recommendations`: request an optional paid next-step report using saved results or supplied evidence, with business context. Insufficient evidence and rule-only fallback are free.
 
 ### SEO & trend data
 
 - `cite42_keywords`: get seed search volume, CPC, and competition, with optional related keyword ideas.
+- `cite42_keywords_batch`: check volume, CPC, and competition for two to 50 seed keywords in one request; billed by outcome (call `cite42_pricing` for rates).
 - `cite42_trends`: get Google Trends interest over time, related and rising queries, and a trend label.
-- `cite42_reddit_trends`: find Reddit audience questions, pain points, rising threads, and product mentions.
+- `cite42_reddit_trends`: find relevant Reddit discussions and supported questions, pain points, and product mentions, with source quotes. Uses a limited sample of titles and excerpts, not complete comment conversations or measured growth. Read `relevantThreads`; `risingThreads` remains a deprecated compatibility alias. Check `analysis.status` and `warnings` for coverage and analysis failures.
 - `cite42_youtube_trends`: find YouTube rising videos, creator angles, title patterns, and opportunities.
 
 ### Research workflows (multi-source, one call)
@@ -186,14 +189,18 @@ npx -y @cite42/mcp --api-key=cite42_live_your_key_here --api-base=https://www.ci
 
 ## Billing
 
-Tool and workflow calls consume Cite42 credits from your account. Tracker management and stored-history reads are free; every scheduled or manual tracker run bills one call per saved prompt at the normal rate. Activating or resuming a tracker requires explicit confirmation of the current maximum credits per run and authorizes recurring billed calls until you pause it. Calls fail with a clear error if the API key is missing or credits run out. See [www.cite42.dev/pricing](https://www.cite42.dev/pricing).
+Tool and workflow calls charge your Cite42 balance in USD. Tracker management and stored-history reads are free; every scheduled or manual tracker run bills one call per saved prompt at the normal rate. Activating or resuming a tracker requires explicit confirmation of the current maximum cost in USD per run and authorizes recurring billed calls until you pause it. Calls fail with a clear error if the API key is missing or your balance runs out. See [www.cite42.dev/pricing](https://www.cite42.dev/pricing).
 
 ## Troubleshooting
 
+For contributor testing, run `npm run inspect` to open the official MCP Inspector with local
+stdio, published npm, and local OAuth targets. Run `npm run test:stdio` for a free built-executable
+smoke test against a loopback fake API. See [local MCP testing](../../docs/mcp-testing.md) in the repository.
+
 - **Server not listed after setup**: make sure you fully restarted the client (new terminal for CLI clients, full quit for desktop apps).
-- **`command not found: npx`**: install Node.js 18+ from [nodejs.org](https://nodejs.org), then restart your terminal.
+- **`command not found: npx`**: install Node.js 22.13+ from [nodejs.org](https://nodejs.org), then restart your terminal.
 - **Tool calls fail with an auth error**: check the key was passed correctly (`CITE42_API_KEY`, no quotes or trailing spaces) and is active at [www.cite42.dev/app/keys](https://www.cite42.dev/app/keys).
-- **Tool calls fail with a credits error**: top up credits at [www.cite42.dev/app](https://www.cite42.dev/app).
+- **Tool calls fail with an insufficient-balance error**: add funds at [www.cite42.dev/app](https://www.cite42.dev/app).
 
 ## Links
 
@@ -201,3 +208,53 @@ Tool and workflow calls consume Cite42 credits from your account. Tracker manage
 - API keys: [Create a Cite42 API key](https://www.cite42.dev/app/keys)
 - Docs: [Cite42 API & MCP documentation](https://www.cite42.dev/docs)
 - Pricing: [Cite42 pay-per-call pricing](https://www.cite42.dev/pricing)
+
+### USD billing and older clients
+
+Quote the `cite42Billing` block for the amount charged and remaining Cite42 balance.
+Its `chargedUsd` and `remainingUsd` values are decimal strings in USD. Legacy
+`cite42Credits` numbers keep their original units for compatibility.
+
+Call `cite42_pricing` with `{ "currency": "USD" }` for dollar prices. With no argument,
+the legacy table is preserved and dollar prices are in the `usd` block.
+REST clients can use `GET /v1/pricing?currency=USD`; the default REST response remains
+compatible with existing installations. Update the MCP package to receive the new
+USD guidance and `cite42_balance` tool. Tracker activation still accepts the exact
+integer `maxCostMicroPerRun` returned by the API; present its USD equivalent to users.
+
+## Optional AI visibility recommendations
+
+`cite42_rankings`, `cite42_compare`, `cite42_citations` and `cite42_sentiment` include a `metrics`
+block. Show mention/citation percentages with their counts (for example, **66.7% — 2 of 3 checked
+answers**). Sentiment percentages describe AI-estimated tone, not the percentage of positive answers.
+Failed, empty and incomplete observations are excluded; no usable sample is unavailable, not zero.
+Only comparable tracker runs provide automatic history. Each reported run includes `metrics` grouped
+by primitive and brand/watched URL, with `current`, `previous`, `previousRunId`, and `changes`.
+Each group states `models` and `methodologyVersion`. Its `comparison` is `comparable`, `baseline`
+(no earlier run, or a new measurement baseline after an old-format run), or `unavailable`;
+`comparisonReason` explains skipped comparisons. A successful run with unavailable comparison data
+is not a failed run, and its email does not claim "no changes". Completed manual-run replays include
+the same immediate predecessor as tracker reports.
+Citation groups preserve the original watched URL; normalized identities are only used for matching.
+Counts sum distinct prompts: four prompts × five surfaces can supply 20 answers. Comparisons require
+the complete prompt/configuration set, methodology and complete coverage to match the preceding run.
+Individual prompts remain small samples (at most five surfaces); percentage-point changes are withheld
+below 10 answers per group in each run. This guardrail does not establish statistical significance.
+
+`cite42_recommendations` is a separate, optional paid report. Use exactly one `requestId` returned by
+an earlier call, a user-owned `trackerRunId`, or a structured `evidence` array. Optional `context`
+accepts brand, domain, audience and goal for this request only. Check `cite42_pricing` for the current
+flat report price and obtain the user's agreement before running the add-on. Insufficient evidence
+and rule-only fallback are free.
+
+For rankings evidence, provide `context.brand` to identify the tracked brand you want advice for.
+Without it, the measurements remain available but the tool asks which brand to focus on for free;
+it never guesses ownership or advises you to improve a competitor's offering. Comparison evidence
+already identifies its target through `input.brand`.
+
+Sources must be complete and no more than 30 days old, within 20 observations and 64KB. Supported
+successful workflow steps can be reused. The tool does not inspect websites, retrieve host memory,
+perform fresh research, recommend keywords, or activate paid tracking. Suggestions are labelled
+inferred and do not establish website defects or causes. Tracker follow-up requires a cadence and
+timezone choice plus separate activation approval. Identical completed retries are free for two
+minutes; an in-flight duplicate is refused without another charge and can be retried shortly.

package/dist/stdio.cjs

@@ -4,6 +4,19 @@
 // src/client.ts
 var DEFAULT_BASE_URL = "https://www.cite42.dev/api/v1";
 var MICRO_CREDITS_PER_CREDIT = 1e3;
+function toUsd(micro) {
+  const [whole, fraction = ""] = (micro / 1e5).toFixed(5).split(".");
+  return `${whole}.${fraction.slice(0, Math.max(2, fraction.replace(/0+$/, "").length))}`;
+}
+function toCite42Balance(micro) {
+  return {
+    cite42Billing: {
+      currency: "USD",
+      remainingUsd: toUsd(micro),
+      message: `Cite42 balance: $${toUsd(micro)} USD remaining. This balance check was free.`
+    }
+  };
+}
 function isJsonObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -30,19 +43,33 @@ function toCite42McpResult(value) {
   if (typeof cost !== "number" || !Number.isFinite(cost) || typeof balance !== "number" || !Number.isFinite(balance)) {
     return result;
   }
+  const originalCost = isJsonObject(billing.originalCost) ? billing.originalCost.microCredits : void 0;
+  const replay = typeof result.replayOf === "string" && typeof originalCost === "number" && Number.isFinite(originalCost);
+  const lowBalanceNotice = typeof warning === "string" ? " Low Cite42 balance." : "";
+  const cite42Billing = {
+    currency: "USD",
+    chargedUsd: toUsd(cost),
+    remainingUsd: toUsd(balance),
+    ...replay ? { originalChargedUsd: toUsd(originalCost) } : {},
+    message: (replay ? `Replay of an identical request from the last 2 minutes. This attempt was free; $${toUsd(originalCost)} USD was charged once, by the original Cite42 call.` : `Cite42: $${toUsd(cost)} USD charged; $${toUsd(balance)} USD remaining.`) + lowBalanceNotice
+  };
   const lowCredits = typeof warning === "string";
   const message = `Cite42 credits: ${formatCredits(cost)} charged; ${formatCredits(balance)} remaining.`;
   return {
     ...result,
+    cite42Billing,
+    // Legacy numeric fields retain their original units for existing integrations.
     cite42Credits: {
       charged: toCredits(cost),
       remaining: toCredits(balance),
-      message: lowCredits ? `${message} Low Cite42 credit balance.` : message
+      ...replay ? { originalCharged: toCredits(originalCost) } : {},
+      message: replay ? `Replay of an identical request from the last 2 minutes. This attempt was free; ${toCredits(originalCost)} credits were charged once, by the original call.` : lowCredits ? `${message} Low Cite42 credit balance.` : message
     }
   };
 }
 function toCite42CreditsBalance(balanceMicroCredits) {
   return {
+    ...toCite42Balance(balanceMicroCredits),
     cite42Credits: {
       remaining: toCredits(balanceMicroCredits),
       message: `Cite42 credits: ${formatCredits(balanceMicroCredits)} remaining. This balance check was free.`
@@ -54,10 +81,10 @@ function errorMessageForMcp(status, path, body) {
     const payload = JSON.parse(body);
     if (isJsonObject(payload) && isJsonObject(payload.error) && typeof payload.error.code === "string") {
       if (payload.error.code === "daily_limit_exceeded" || payload.error.code === "monthly_limit_exceeded") {
-        return "Cite42 credit limit reached. Adjust your limit at https://www.cite42.dev/app/billing.";
+        return "Cite42 spending limit reached. Adjust your limit at https://www.cite42.dev/app/billing.";
       }
       if (payload.error.code === "insufficient_credits") {
-        return "Insufficient Cite42 credits. Top up at https://www.cite42.dev/app/billing.";
+        return "Insufficient Cite42 balance. Add funds at https://www.cite42.dev/app/billing.";
       }
     }
   } catch {
@@ -90,8 +117,8 @@ function getApiKey() {
 function getBaseUrl() {
   return readFlag("api-base") ?? process.env.CITE42_API_BASE ?? DEFAULT_BASE_URL;
 }
-async function aivPost(path, body) {
-  return aivWrite("POST", path, body);
+async function aivPost(path, body, signal) {
+  return aivWrite("POST", path, body, signal);
 }
 async function aivPatch(path, body) {
   return aivWrite("PATCH", path, body);
@@ -108,7 +135,8 @@ async function aivDelete(path) {
   }
   return toCite42McpResult(await res.json());
 }
-async function aivWrite(method, path, body) {
+async function aivWrite(method, path, body, signal) {
+  signal?.throwIfAborted();
   const url = `${getBaseUrl()}${path.startsWith("/") ? path : `/${path}`}`;
   const res = await fetch(url, {
     method,
@@ -116,7 +144,8 @@ async function aivWrite(method, path, body) {
       "Content-Type": "application/json",
       Authorization: `Bearer ${getApiKey()}`
     },
-    body: JSON.stringify(body)
+    body: JSON.stringify(body),
+    signal
   });
   if (!res.ok) {
     const text = await res.text();
@@ -149,8 +178,8 @@ var SHORT_TEXT_MAX_CHARS = 200;
 var TIMEFRAME_MAX_CHARS = 80;
 var MODEL_SELECTION_DESCRIPTION = 'Optional model subset. Omit to query the default surfaces (chatgpt, perplexity, gemini). Pass ["perplexity"] or ["perplexity","claude"] when the user names specific surfaces or wants to reduce cost. The full set is chatgpt, claude, perplexity, gemini, google_ai_overview \u2014 to query all of them, set fullSweep instead of listing them.';
 var FULL_SWEEP_DESCRIPTION = "Query all five AI surfaces instead of the three default ones, adding claude and google_ai_overview. Costs more per call. Use it when the user wants complete cross-model coverage, is comparing surfaces against each other, or asks specifically about Claude or Google AI Overviews. Ignored when models is given.";
-var MCP_USAGE_GUIDANCE = "Covers AI-search, citation, SEO, keyword, trend, and market-research data. If a plan needs more than 20 endpoint calls or may use more than 500 Cite42 credits, estimate the credits and ask the user before continuing. When a result contains cite42Credits, that figure is Cite42 credits, not a model or host balance. Free (0 credits): cite42_credits for the remaining balance, cite42_pricing for exact per-tool prices and cost estimates, cite42_usage for recent calls.";
-var MODEL_PRICING = "Pricing is per selected AI surface. Omitting models queries the three default surfaces (chatgpt, perplexity, gemini); fullSweep: true queries all five, adding claude and google_ai_overview for more credits. Use the models field when the user names a surface or asks to reduce credit use, and call cite42_pricing for exact current rates.";
+var MCP_USAGE_GUIDANCE = "Covers AI-search, citation, SEO, keyword, trend, and market-research data. If a plan needs more than 20 endpoint calls or may use more than $5 USD, estimate the cost in USD and ask the user before continuing. Quote Cite42 costs and balances in USD using cite42Billing or the USD pricing table. Legacy credit fields are for compatibility only. These funds belong to Cite42, not the host or model provider. AI visibility metrics include counts; quote them with percentages, not as a market-wide score. Optional recommendations are a separate paid call, never automatic. After a visibility result, offer recommendations using its requestId; run only when the user requests advice and knows the additional cost. Free: cite42_balance for the remaining balance, cite42_pricing for exact per-tool prices and cost estimates, cite42_usage for recent calls.";
+var MODEL_PRICING = "Pricing is per selected AI surface. Omitting models queries the three default surfaces (chatgpt, perplexity, gemini); fullSweep: true queries all five, adding claude and google_ai_overview at a higher cost. Use the models field when the user names a surface or asks to reduce spending, and call cite42_pricing for exact current rates.";
 var DATA_PRICING = "Data tools have flat per-call prices; call cite42_pricing for exact current rates.";
 var KEYWORDS_PRICING = "Pricing: billed by outcome \u2014 cheapest when the seed has no search volume, more when it has metrics, most with ideas:true. Call cite42_pricing for exact current rates.";
 var WORKFLOW_PRICING = "Pricing: workflow cost is calculated from the tools that run successfully and the selected model rates.";
@@ -177,16 +206,59 @@ function queryText(description) {
 function shortText(description) {
   return import_zod.z.string().trim().min(1).max(SHORT_TEXT_MAX_CHARS).describe(description);
 }
+var aivRecommendations = (0, import_tools.createTool)({
+  id: "cite42_recommendations",
+  mcp: readOnly("Recommend AI visibility next steps"),
+  description: "Optional evidence-backed AI visibility recommendations. Flat price from cite42_pricing per completed AI report; insufficient evidence and rule-only fallback are free. Supports rankings, compare, citations and sentiment, including usable workflow steps. No crawling, fresh research, keyword advice or tracker activation. " + MCP_USAGE_GUIDANCE,
+  inputSchema: import_zod.z.object({
+    requestId: import_zod.z.string().trim().min(1).max(128).optional().describe("A requestId from your own successful Cite42 call within the last 30 days."),
+    trackerRunId: import_zod.z.string().trim().min(1).max(128).optional().describe("A specific finished run of your own tracker within the last 30 days."),
+    evidence: import_zod.z.array(import_zod.z.object({
+      primitive: import_zod.z.enum(["rankings", "compare", "citations", "sentiment"]),
+      input: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()),
+      result: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()),
+      measuredAt: import_zod.z.string().datetime()
+    })).min(1).max(20).optional(),
+    context: import_zod.z.object({
+      brand: import_zod.z.string().trim().min(1).max(200).optional(),
+      domain: import_zod.z.string().trim().min(1).max(250).optional(),
+      audience: import_zod.z.string().trim().min(1).max(400).optional(),
+      goal: import_zod.z.string().trim().min(1).max(400).optional()
+    }).optional()
+  }).superRefine((input, ctx) => {
+    if ([input.requestId, input.trackerRunId, input.evidence].filter((value) => value !== void 0).length !== 1) {
+      ctx.addIssue({ code: "custom", message: "Provide exactly one of requestId, trackerRunId or evidence." });
+    }
+    if (new TextEncoder().encode(JSON.stringify(input)).length > 64 * 1024) {
+      ctx.addIssue({ code: "custom", message: "Recommendation input must fit within 64KB." });
+    }
+  }),
+  execute: async (input) => aivPost("/recommendations", input)
+});
 function optionalShortText(description) {
   return import_zod.z.string().trim().min(1).max(SHORT_TEXT_MAX_CHARS).optional().describe(description);
 }
 var modelsInput = import_zod.z.array(modelEnum).nonempty().optional().describe(MODEL_SELECTION_DESCRIPTION);
 var fullSweepInput = import_zod.z.boolean().optional().describe(FULL_SWEEP_DESCRIPTION);
 var competitorList = import_zod.z.array(shortText("Competitor brand/domain name.")).nonempty().max(20);
+var aivBalance = (0, import_tools.createTool)({
+  id: "cite42_balance",
+  mcp: readOnly("Check Cite42 balance", false),
+  description: "Check the remaining Cite42 balance for the connected account. Free. " + MCP_USAGE_GUIDANCE,
+  inputSchema: import_zod.z.object({}),
+  execute: async () => {
+    const usage = await aivGet("/usage");
+    const microCredits = usage.balance?.microCredits;
+    if (typeof microCredits !== "number" || !Number.isFinite(microCredits)) {
+      throw new Error("Cite42 usage response did not include a balance.");
+    }
+    return toCite42Balance(microCredits);
+  }
+});
 var aivCredits = (0, import_tools.createTool)({
   id: "cite42_credits",
-  mcp: readOnly("Check Cite42 credit balance", false),
-  description: "Check the remaining Cite42 credit balance for the connected account. Free: costs 0 credits. " + MCP_USAGE_GUIDANCE,
+  mcp: readOnly("Check Cite42 balance (legacy alias)", false),
+  description: "Check the remaining Cite42 balance for the connected account. Free. " + MCP_USAGE_GUIDANCE,
   inputSchema: import_zod.z.object({}),
   execute: async () => {
     const usage = await aivGet("/usage");
@@ -200,14 +272,16 @@ var aivCredits = (0, import_tools.createTool)({
 var aivPricing = (0, import_tools.createTool)({
   id: "cite42_pricing",
   mcp: readOnly("Get Cite42 price table", false),
-  description: 'Get the exact Cite42 price table in credits: per-model rates, flat-rate tools, workflow maximums, and which tools are free. Use it to answer any "how much does X cost" question or to estimate a plan before running it. Free: costs 0 credits. ' + MCP_USAGE_GUIDANCE,
-  inputSchema: import_zod.z.object({}),
-  execute: async () => aivGet("/pricing")
+  description: 'Get the exact Cite42 price table. Pass currency: USD for dollar prices; otherwise read the usd block (legacy fields are compatibility only): per-model rates, flat-rate tools, workflow maximums, and which tools are free. Use it to answer any "how much does X cost" question or to estimate a plan before running it. Free. ' + MCP_USAGE_GUIDANCE,
+  inputSchema: import_zod.z.object({
+    currency: import_zod.z.enum(["USD", "credits"]).optional().describe("Use USD for dollar prices. Omit only for legacy compatibility.")
+  }),
+  execute: async (input) => input.currency === "USD" ? aivGet("/pricing?currency=USD") : { ...await aivGet("/pricing"), usd: await aivGet("/pricing?currency=USD") }
 });
 var aivUsage = (0, import_tools.createTool)({
   id: "cite42_usage",
   mcp: readOnly("Get recent Cite42 usage", false),
-  description: "Get recent Cite42 usage for the connected account: the last calls with their cost and status, plus the remaining credit balance. Free: costs 0 credits. " + MCP_USAGE_GUIDANCE,
+  description: "Get recent Cite42 usage for the connected account: the last calls with their cost and status, plus the remaining balance in USD. Free. " + MCP_USAGE_GUIDANCE,
   inputSchema: import_zod.z.object({}),
   execute: async () => {
     const usage = await aivGet("/usage");
@@ -221,6 +295,7 @@ var aivUsage = (0, import_tools.createTool)({
         endpoint: row.endpoint,
         status: row.status,
         credits: typeof row.costMicro === "number" ? toCredits(row.costMicro) : void 0,
+        costUsd: typeof row.costMicro === "number" ? toUsd(row.costMicro) : void 0,
         at: row.createdAt
       }))
     };
@@ -302,6 +377,23 @@ var aivKeywords = (0, import_tools.createTool)({
   }),
   execute: async (input) => aivPost("/keywords", input)
 });
+var aivKeywordsBatch = (0, import_tools.createTool)({
+  id: "cite42_keywords_batch",
+  mcp: readOnly("Get batch SEO keyword data"),
+  description: `Check search volume, CPC, and competition for two to 50 distinct seed keywords in one request. No related ideas. Billed by outcome; call cite42_pricing for current rates. ${MCP_USAGE_GUIDANCE}`,
+  inputSchema: import_zod.z.object({
+    seeds: import_zod.z.array(import_zod.z.string().trim().min(1).max(80).refine(
+      (seed) => seed.split(/\s+/).length <= 10,
+      "Each keyword must contain at most 10 words."
+    )).min(2).max(50).refine(
+      (seeds) => new Set(seeds.map((seed) => seed.toLowerCase().replace(/\s+/g, " "))).size === seeds.length,
+      "Keywords must be distinct."
+    ).describe("Two to 50 distinct seed keywords."),
+    country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
+    language: import_zod.z.string().trim().max(8).optional().describe("Optional ISO-2 language code.")
+  }),
+  execute: async (input) => aivPost("/keywords/batch", input)
+});
 var aivTrends = (0, import_tools.createTool)({
   id: "cite42_trends",
   mcp: readOnly("Get Google Trends data"),
@@ -315,14 +407,14 @@ var aivTrends = (0, import_tools.createTool)({
 });
 var aivRedditTrends = (0, import_tools.createTool)({
   id: "cite42_reddit_trends",
-  mcp: readOnly("Get Reddit trend data"),
-  description: `Reddit trend data for audience questions, pain points, rising threads, repeated phrases, mentioned products, and source URLs around a topic. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  mcp: readOnly("Find Reddit discussions"),
+  description: `Discover relevant Reddit discussions through Gemini Google Search. Returns labeled model summaries, citations and coverage warnings, with no author quotes or quote-based insights. Does not measure growth or read complete comment conversations. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: import_zod.z.object({
     topic: queryText("Topic, category, product, or audience to research on Reddit."),
     subreddits: import_zod.z.array(shortText("Subreddit name without r/.")).max(20).optional().describe("Optional subreddit names, without r/."),
     timeframe: import_zod.z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Conversation window, e.g. "past_7_days", "past_30_days", "past_90_days".')
   }),
-  execute: async (input) => aivPost("/reddit/trends", input)
+  execute: async (input, context) => aivPost("/reddit/trends", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
 var aivYoutubeTrends = (0, import_tools.createTool)({
   id: "cite42_youtube_trends",
@@ -350,7 +442,7 @@ var aivFindContentOpportunities = (0, import_tools.createTool)({
     country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
     channels: import_zod.z.array(channelEnum).optional().describe("Optional data sources to include.")
   }),
-  execute: async (input) => aivPost("/workflows/content-opportunities", input)
+  execute: async (input, context) => aivPost("/workflows/content-opportunities", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
 var aivAnalyzeTopicDemand = (0, import_tools.createTool)({
   id: "cite42_analyze_topic_demand",
@@ -363,7 +455,7 @@ var aivAnalyzeTopicDemand = (0, import_tools.createTool)({
     country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
     timeframe: import_zod.z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trend window. Defaults to "past_12_months".')
   }),
-  execute: async (input) => aivPost("/workflows/topic-demand", input)
+  execute: async (input, context) => aivPost("/workflows/topic-demand", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
 var aivMapAiPrompts = (0, import_tools.createTool)({
   id: "cite42_map_ai_prompts",
@@ -379,7 +471,7 @@ var aivMapAiPrompts = (0, import_tools.createTool)({
     country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
     timeframe: import_zod.z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trend window. Defaults to "past_12_months".')
   }),
-  execute: async (input) => aivPost("/workflows/ai-prompt-map", input)
+  execute: async (input, context) => aivPost("/workflows/ai-prompt-map", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
 var aivAnalyzeCompetitorContent = (0, import_tools.createTool)({
   id: "cite42_analyze_competitor_content",
@@ -393,7 +485,7 @@ var aivAnalyzeCompetitorContent = (0, import_tools.createTool)({
     brand: optionalShortText("Optional primary brand/domain to compare against."),
     country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".')
   }),
-  execute: async (input) => aivPost("/workflows/competitor-content", input)
+  execute: async (input, context) => aivPost("/workflows/competitor-content", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
 var aivFindAiCitationGaps = (0, import_tools.createTool)({
   id: "cite42_find_ai_citation_gaps",
@@ -409,7 +501,7 @@ var aivFindAiCitationGaps = (0, import_tools.createTool)({
     models: modelsInput,
     fullSweep: fullSweepInput
   }),
-  execute: async (input) => aivPost("/workflows/ai-citation-gaps", input)
+  execute: async (input, context) => aivPost("/workflows/ai-citation-gaps", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
 var aivGenerateContentBrief = (0, import_tools.createTool)({
   id: "cite42_generate_content_brief",
@@ -424,7 +516,7 @@ var aivGenerateContentBrief = (0, import_tools.createTool)({
     goal: optionalShortText("Optional content goal, e.g. rank, earn citations, convert."),
     country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".')
   }),
-  execute: async (input) => aivPost("/workflows/content-brief", input)
+  execute: async (input, context) => aivPost("/workflows/content-brief", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
 var trackerIdInput = import_zod.z.string().trim().min(1).max(128).describe("Cite42 tracker ID returned by a tracker management or report tool.");
 var trackerCadenceInput = import_zod.z.object({
@@ -478,7 +570,7 @@ var trackerDefinitionFields = {
     "AI surfaces to query for every prompt. Omit for the three defaults (chatgpt, perplexity, gemini), or list surfaces explicitly \u2014 including all five \u2014 to fix the recurring cost."
   )
 };
-var TRACKER_BILLING_DESCRIPTION = "Tracker management and stored-report reads are free. Each scheduled or manual run bills one call per prompt at the normal per-model rates; the activation response and tracker record expose the accepted maximum cost per run.";
+var TRACKER_BILLING_DESCRIPTION = "Tracker management and stored-report reads are free. Each scheduled or manual run bills one call per prompt at the normal per-model rates; the activation response and tracker record expose the accepted maximum cost per run. Present the returned USD amounts to users; activation still takes the exact estimatedCostMicroPerRun integer returned by the tracker.";
 var aivTrackerCreate = (0, import_tools.createTool)({
   id: "cite42_tracker_create",
   mcp: mutation("Create Cite42 tracker draft"),
@@ -509,7 +601,7 @@ var aivTrackerActivate = (0, import_tools.createTool)({
 var aivTrackerPause = (0, import_tools.createTool)({
   id: "cite42_tracker_pause",
   mcp: mutation("Pause Cite42 tracker", { idempotentHint: true }),
-  description: "Pause future recurring calls for a tracker while preserving its configuration and stored run history. Free: costs 0 credits.",
+  description: "Pause future recurring calls for a tracker while preserving its configuration and stored run history. Free.",
   inputSchema: import_zod.z.object({ trackerId: trackerIdInput }),
   execute: async ({ trackerId }) => aivPost(`/trackers/${encodeURIComponent(trackerId)}/pause`, {})
 });
@@ -519,7 +611,7 @@ var aivTrackerDelete = (0, import_tools.createTool)({
     destructiveHint: true,
     idempotentHint: true
   }),
-  description: "Permanently delete a draft or paused tracker, including its saved configuration and run history. Active trackers must be paused first, and deletion is rejected while a run is queued or running. Financial usage and credit ledger records are retained. Free: costs 0 credits.",
+  description: "Permanently delete a draft or paused tracker, including its saved configuration and run history. Active trackers must be paused first, and deletion is rejected while a run is queued or running. Financial usage and billing ledger records are retained. Free.",
   inputSchema: import_zod.z.object({ trackerId: trackerIdInput }),
   execute: async ({ trackerId }) => aivDelete(`/trackers/${encodeURIComponent(trackerId)}`)
 });
@@ -539,14 +631,14 @@ var aivTrackerRun = (0, import_tools.createTool)({
 var aivTrackers = (0, import_tools.createTool)({
   id: "cite42_trackers",
   mcp: readOnly("List Cite42 trackers", false),
-  description: "List the connected account\u2019s trackers with status, cadence, tool configuration, cost estimate, accepted per-run maximum, and next/last run times. Free: costs 0 credits.",
+  description: "List the connected account\u2019s trackers with status, cadence, tool configuration, cost estimate, accepted per-run maximum, and next/last run times. Free.",
   inputSchema: import_zod.z.object({}),
   execute: async () => aivGet("/trackers")
 });
 var aivTrackerReport = (0, import_tools.createTool)({
   id: "cite42_tracker_report",
   mcp: readOnly("Read Cite42 tracker report", false),
-  description: "Read bounded stored run history for one tracker, including per-tool results, changes from the prior comparable observation, statuses, sampled times, and costs. Free: costs 0 credits.",
+  description: "Read bounded stored run history for one tracker, including per-tool results, changes from the prior comparable observation, statuses, sampled times, and costs. Free.",
   inputSchema: import_zod.z.object({
     trackerId: trackerIdInput,
     limit: import_zod.z.number().int().min(1).max(20).optional().default(8).describe("Most recent runs to return, capped for LLM context.")
@@ -556,6 +648,7 @@ var aivTrackerReport = (0, import_tools.createTool)({
 
 // src/server.ts
 var CITE42_TOOLS = {
+  cite42_balance: aivBalance,
   cite42_credits: aivCredits,
   cite42_pricing: aivPricing,
   cite42_usage: aivUsage,
@@ -564,7 +657,9 @@ var CITE42_TOOLS = {
   cite42_compare: aivCompare,
   cite42_citations: aivCitations,
   cite42_sentiment: aivSentiment,
+  cite42_recommendations: aivRecommendations,
   cite42_keywords: aivKeywords,
+  cite42_keywords_batch: aivKeywordsBatch,
   cite42_trends: aivTrends,
   cite42_reddit_trends: aivRedditTrends,
   cite42_youtube_trends: aivYoutubeTrends,
@@ -600,7 +695,7 @@ if (!resolveApiKey()) {
   );
   process.exit(1);
 }
-buildCite42Server("0.5.1").startStdio().catch((error) => {
+buildCite42Server("0.6.0").startStdio().catch((error) => {
   console.error("[@cite42/mcp] Fatal error:", error);
   process.exit(1);
 });

package/dist/stdio.mjs

@@ -3,6 +3,19 @@
 // src/client.ts
 var DEFAULT_BASE_URL = "https://www.cite42.dev/api/v1";
 var MICRO_CREDITS_PER_CREDIT = 1e3;
+function toUsd(micro) {
+  const [whole, fraction = ""] = (micro / 1e5).toFixed(5).split(".");
+  return `${whole}.${fraction.slice(0, Math.max(2, fraction.replace(/0+$/, "").length))}`;
+}
+function toCite42Balance(micro) {
+  return {
+    cite42Billing: {
+      currency: "USD",
+      remainingUsd: toUsd(micro),
+      message: `Cite42 balance: $${toUsd(micro)} USD remaining. This balance check was free.`
+    }
+  };
+}
 function isJsonObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -29,19 +42,33 @@ function toCite42McpResult(value) {
   if (typeof cost !== "number" || !Number.isFinite(cost) || typeof balance !== "number" || !Number.isFinite(balance)) {
     return result;
   }
+  const originalCost = isJsonObject(billing.originalCost) ? billing.originalCost.microCredits : void 0;
+  const replay = typeof result.replayOf === "string" && typeof originalCost === "number" && Number.isFinite(originalCost);
+  const lowBalanceNotice = typeof warning === "string" ? " Low Cite42 balance." : "";
+  const cite42Billing = {
+    currency: "USD",
+    chargedUsd: toUsd(cost),
+    remainingUsd: toUsd(balance),
+    ...replay ? { originalChargedUsd: toUsd(originalCost) } : {},
+    message: (replay ? `Replay of an identical request from the last 2 minutes. This attempt was free; $${toUsd(originalCost)} USD was charged once, by the original Cite42 call.` : `Cite42: $${toUsd(cost)} USD charged; $${toUsd(balance)} USD remaining.`) + lowBalanceNotice
+  };
   const lowCredits = typeof warning === "string";
   const message = `Cite42 credits: ${formatCredits(cost)} charged; ${formatCredits(balance)} remaining.`;
   return {
     ...result,
+    cite42Billing,
+    // Legacy numeric fields retain their original units for existing integrations.
     cite42Credits: {
       charged: toCredits(cost),
       remaining: toCredits(balance),
-      message: lowCredits ? `${message} Low Cite42 credit balance.` : message
+      ...replay ? { originalCharged: toCredits(originalCost) } : {},
+      message: replay ? `Replay of an identical request from the last 2 minutes. This attempt was free; ${toCredits(originalCost)} credits were charged once, by the original call.` : lowCredits ? `${message} Low Cite42 credit balance.` : message
     }
   };
 }
 function toCite42CreditsBalance(balanceMicroCredits) {
   return {
+    ...toCite42Balance(balanceMicroCredits),
     cite42Credits: {
       remaining: toCredits(balanceMicroCredits),
       message: `Cite42 credits: ${formatCredits(balanceMicroCredits)} remaining. This balance check was free.`
@@ -53,10 +80,10 @@ function errorMessageForMcp(status, path, body) {
     const payload = JSON.parse(body);
     if (isJsonObject(payload) && isJsonObject(payload.error) && typeof payload.error.code === "string") {
       if (payload.error.code === "daily_limit_exceeded" || payload.error.code === "monthly_limit_exceeded") {
-        return "Cite42 credit limit reached. Adjust your limit at https://www.cite42.dev/app/billing.";
+        return "Cite42 spending limit reached. Adjust your limit at https://www.cite42.dev/app/billing.";
       }
       if (payload.error.code === "insufficient_credits") {
-        return "Insufficient Cite42 credits. Top up at https://www.cite42.dev/app/billing.";
+        return "Insufficient Cite42 balance. Add funds at https://www.cite42.dev/app/billing.";
       }
     }
   } catch {
@@ -89,8 +116,8 @@ function getApiKey() {
 function getBaseUrl() {
   return readFlag("api-base") ?? process.env.CITE42_API_BASE ?? DEFAULT_BASE_URL;
 }
-async function aivPost(path, body) {
-  return aivWrite("POST", path, body);
+async function aivPost(path, body, signal) {
+  return aivWrite("POST", path, body, signal);
 }
 async function aivPatch(path, body) {
   return aivWrite("PATCH", path, body);
@@ -107,7 +134,8 @@ async function aivDelete(path) {
   }
   return toCite42McpResult(await res.json());
 }
-async function aivWrite(method, path, body) {
+async function aivWrite(method, path, body, signal) {
+  signal?.throwIfAborted();
   const url = `${getBaseUrl()}${path.startsWith("/") ? path : `/${path}`}`;
   const res = await fetch(url, {
     method,
@@ -115,7 +143,8 @@ async function aivWrite(method, path, body) {
       "Content-Type": "application/json",
       Authorization: `Bearer ${getApiKey()}`
     },
-    body: JSON.stringify(body)
+    body: JSON.stringify(body),
+    signal
   });
   if (!res.ok) {
     const text = await res.text();
@@ -148,8 +177,8 @@ var SHORT_TEXT_MAX_CHARS = 200;
 var TIMEFRAME_MAX_CHARS = 80;
 var MODEL_SELECTION_DESCRIPTION = 'Optional model subset. Omit to query the default surfaces (chatgpt, perplexity, gemini). Pass ["perplexity"] or ["perplexity","claude"] when the user names specific surfaces or wants to reduce cost. The full set is chatgpt, claude, perplexity, gemini, google_ai_overview \u2014 to query all of them, set fullSweep instead of listing them.';
 var FULL_SWEEP_DESCRIPTION = "Query all five AI surfaces instead of the three default ones, adding claude and google_ai_overview. Costs more per call. Use it when the user wants complete cross-model coverage, is comparing surfaces against each other, or asks specifically about Claude or Google AI Overviews. Ignored when models is given.";
-var MCP_USAGE_GUIDANCE = "Covers AI-search, citation, SEO, keyword, trend, and market-research data. If a plan needs more than 20 endpoint calls or may use more than 500 Cite42 credits, estimate the credits and ask the user before continuing. When a result contains cite42Credits, that figure is Cite42 credits, not a model or host balance. Free (0 credits): cite42_credits for the remaining balance, cite42_pricing for exact per-tool prices and cost estimates, cite42_usage for recent calls.";
-var MODEL_PRICING = "Pricing is per selected AI surface. Omitting models queries the three default surfaces (chatgpt, perplexity, gemini); fullSweep: true queries all five, adding claude and google_ai_overview for more credits. Use the models field when the user names a surface or asks to reduce credit use, and call cite42_pricing for exact current rates.";
+var MCP_USAGE_GUIDANCE = "Covers AI-search, citation, SEO, keyword, trend, and market-research data. If a plan needs more than 20 endpoint calls or may use more than $5 USD, estimate the cost in USD and ask the user before continuing. Quote Cite42 costs and balances in USD using cite42Billing or the USD pricing table. Legacy credit fields are for compatibility only. These funds belong to Cite42, not the host or model provider. AI visibility metrics include counts; quote them with percentages, not as a market-wide score. Optional recommendations are a separate paid call, never automatic. After a visibility result, offer recommendations using its requestId; run only when the user requests advice and knows the additional cost. Free: cite42_balance for the remaining balance, cite42_pricing for exact per-tool prices and cost estimates, cite42_usage for recent calls.";
+var MODEL_PRICING = "Pricing is per selected AI surface. Omitting models queries the three default surfaces (chatgpt, perplexity, gemini); fullSweep: true queries all five, adding claude and google_ai_overview at a higher cost. Use the models field when the user names a surface or asks to reduce spending, and call cite42_pricing for exact current rates.";
 var DATA_PRICING = "Data tools have flat per-call prices; call cite42_pricing for exact current rates.";
 var KEYWORDS_PRICING = "Pricing: billed by outcome \u2014 cheapest when the seed has no search volume, more when it has metrics, most with ideas:true. Call cite42_pricing for exact current rates.";
 var WORKFLOW_PRICING = "Pricing: workflow cost is calculated from the tools that run successfully and the selected model rates.";
@@ -176,16 +205,59 @@ function queryText(description) {
 function shortText(description) {
   return z.string().trim().min(1).max(SHORT_TEXT_MAX_CHARS).describe(description);
 }
+var aivRecommendations = createTool({
+  id: "cite42_recommendations",
+  mcp: readOnly("Recommend AI visibility next steps"),
+  description: "Optional evidence-backed AI visibility recommendations. Flat price from cite42_pricing per completed AI report; insufficient evidence and rule-only fallback are free. Supports rankings, compare, citations and sentiment, including usable workflow steps. No crawling, fresh research, keyword advice or tracker activation. " + MCP_USAGE_GUIDANCE,
+  inputSchema: z.object({
+    requestId: z.string().trim().min(1).max(128).optional().describe("A requestId from your own successful Cite42 call within the last 30 days."),
+    trackerRunId: z.string().trim().min(1).max(128).optional().describe("A specific finished run of your own tracker within the last 30 days."),
+    evidence: z.array(z.object({
+      primitive: z.enum(["rankings", "compare", "citations", "sentiment"]),
+      input: z.record(z.string(), z.unknown()),
+      result: z.record(z.string(), z.unknown()),
+      measuredAt: z.string().datetime()
+    })).min(1).max(20).optional(),
+    context: z.object({
+      brand: z.string().trim().min(1).max(200).optional(),
+      domain: z.string().trim().min(1).max(250).optional(),
+      audience: z.string().trim().min(1).max(400).optional(),
+      goal: z.string().trim().min(1).max(400).optional()
+    }).optional()
+  }).superRefine((input, ctx) => {
+    if ([input.requestId, input.trackerRunId, input.evidence].filter((value) => value !== void 0).length !== 1) {
+      ctx.addIssue({ code: "custom", message: "Provide exactly one of requestId, trackerRunId or evidence." });
+    }
+    if (new TextEncoder().encode(JSON.stringify(input)).length > 64 * 1024) {
+      ctx.addIssue({ code: "custom", message: "Recommendation input must fit within 64KB." });
+    }
+  }),
+  execute: async (input) => aivPost("/recommendations", input)
+});
 function optionalShortText(description) {
   return z.string().trim().min(1).max(SHORT_TEXT_MAX_CHARS).optional().describe(description);
 }
 var modelsInput = z.array(modelEnum).nonempty().optional().describe(MODEL_SELECTION_DESCRIPTION);
 var fullSweepInput = z.boolean().optional().describe(FULL_SWEEP_DESCRIPTION);
 var competitorList = z.array(shortText("Competitor brand/domain name.")).nonempty().max(20);
+var aivBalance = createTool({
+  id: "cite42_balance",
+  mcp: readOnly("Check Cite42 balance", false),
+  description: "Check the remaining Cite42 balance for the connected account. Free. " + MCP_USAGE_GUIDANCE,
+  inputSchema: z.object({}),
+  execute: async () => {
+    const usage = await aivGet("/usage");
+    const microCredits = usage.balance?.microCredits;
+    if (typeof microCredits !== "number" || !Number.isFinite(microCredits)) {
+      throw new Error("Cite42 usage response did not include a balance.");
+    }
+    return toCite42Balance(microCredits);
+  }
+});
 var aivCredits = createTool({
   id: "cite42_credits",
-  mcp: readOnly("Check Cite42 credit balance", false),
-  description: "Check the remaining Cite42 credit balance for the connected account. Free: costs 0 credits. " + MCP_USAGE_GUIDANCE,
+  mcp: readOnly("Check Cite42 balance (legacy alias)", false),
+  description: "Check the remaining Cite42 balance for the connected account. Free. " + MCP_USAGE_GUIDANCE,
   inputSchema: z.object({}),
   execute: async () => {
     const usage = await aivGet("/usage");
@@ -199,14 +271,16 @@ var aivCredits = createTool({
 var aivPricing = createTool({
   id: "cite42_pricing",
   mcp: readOnly("Get Cite42 price table", false),
-  description: 'Get the exact Cite42 price table in credits: per-model rates, flat-rate tools, workflow maximums, and which tools are free. Use it to answer any "how much does X cost" question or to estimate a plan before running it. Free: costs 0 credits. ' + MCP_USAGE_GUIDANCE,
-  inputSchema: z.object({}),
-  execute: async () => aivGet("/pricing")
+  description: 'Get the exact Cite42 price table. Pass currency: USD for dollar prices; otherwise read the usd block (legacy fields are compatibility only): per-model rates, flat-rate tools, workflow maximums, and which tools are free. Use it to answer any "how much does X cost" question or to estimate a plan before running it. Free. ' + MCP_USAGE_GUIDANCE,
+  inputSchema: z.object({
+    currency: z.enum(["USD", "credits"]).optional().describe("Use USD for dollar prices. Omit only for legacy compatibility.")
+  }),
+  execute: async (input) => input.currency === "USD" ? aivGet("/pricing?currency=USD") : { ...await aivGet("/pricing"), usd: await aivGet("/pricing?currency=USD") }
 });
 var aivUsage = createTool({
   id: "cite42_usage",
   mcp: readOnly("Get recent Cite42 usage", false),
-  description: "Get recent Cite42 usage for the connected account: the last calls with their cost and status, plus the remaining credit balance. Free: costs 0 credits. " + MCP_USAGE_GUIDANCE,
+  description: "Get recent Cite42 usage for the connected account: the last calls with their cost and status, plus the remaining balance in USD. Free. " + MCP_USAGE_GUIDANCE,
   inputSchema: z.object({}),
   execute: async () => {
     const usage = await aivGet("/usage");
@@ -220,6 +294,7 @@ var aivUsage = createTool({
         endpoint: row.endpoint,
         status: row.status,
         credits: typeof row.costMicro === "number" ? toCredits(row.costMicro) : void 0,
+        costUsd: typeof row.costMicro === "number" ? toUsd(row.costMicro) : void 0,
         at: row.createdAt
       }))
     };
@@ -301,6 +376,23 @@ var aivKeywords = createTool({
   }),
   execute: async (input) => aivPost("/keywords", input)
 });
+var aivKeywordsBatch = createTool({
+  id: "cite42_keywords_batch",
+  mcp: readOnly("Get batch SEO keyword data"),
+  description: `Check search volume, CPC, and competition for two to 50 distinct seed keywords in one request. No related ideas. Billed by outcome; call cite42_pricing for current rates. ${MCP_USAGE_GUIDANCE}`,
+  inputSchema: z.object({
+    seeds: z.array(z.string().trim().min(1).max(80).refine(
+      (seed) => seed.split(/\s+/).length <= 10,
+      "Each keyword must contain at most 10 words."
+    )).min(2).max(50).refine(
+      (seeds) => new Set(seeds.map((seed) => seed.toLowerCase().replace(/\s+/g, " "))).size === seeds.length,
+      "Keywords must be distinct."
+    ).describe("Two to 50 distinct seed keywords."),
+    country: z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
+    language: z.string().trim().max(8).optional().describe("Optional ISO-2 language code.")
+  }),
+  execute: async (input) => aivPost("/keywords/batch", input)
+});
 var aivTrends = createTool({
   id: "cite42_trends",
   mcp: readOnly("Get Google Trends data"),
@@ -314,14 +406,14 @@ var aivTrends = createTool({
 });
 var aivRedditTrends = createTool({
   id: "cite42_reddit_trends",
-  mcp: readOnly("Get Reddit trend data"),
-  description: `Reddit trend data for audience questions, pain points, rising threads, repeated phrases, mentioned products, and source URLs around a topic. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  mcp: readOnly("Find Reddit discussions"),
+  description: `Discover relevant Reddit discussions through Gemini Google Search. Returns labeled model summaries, citations and coverage warnings, with no author quotes or quote-based insights. Does not measure growth or read complete comment conversations. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: z.object({
     topic: queryText("Topic, category, product, or audience to research on Reddit."),
     subreddits: z.array(shortText("Subreddit name without r/.")).max(20).optional().describe("Optional subreddit names, without r/."),
     timeframe: z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Conversation window, e.g. "past_7_days", "past_30_days", "past_90_days".')
   }),
-  execute: async (input) => aivPost("/reddit/trends", input)
+  execute: async (input, context) => aivPost("/reddit/trends", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
 var aivYoutubeTrends = createTool({
   id: "cite42_youtube_trends",
@@ -349,7 +441,7 @@ var aivFindContentOpportunities = createTool({
     country: z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
     channels: z.array(channelEnum).optional().describe("Optional data sources to include.")
   }),
-  execute: async (input) => aivPost("/workflows/content-opportunities", input)
+  execute: async (input, context) => aivPost("/workflows/content-opportunities", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
 var aivAnalyzeTopicDemand = createTool({
   id: "cite42_analyze_topic_demand",
@@ -362,7 +454,7 @@ var aivAnalyzeTopicDemand = createTool({
     country: z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
     timeframe: z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trend window. Defaults to "past_12_months".')
   }),
-  execute: async (input) => aivPost("/workflows/topic-demand", input)
+  execute: async (input, context) => aivPost("/workflows/topic-demand", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
 var aivMapAiPrompts = createTool({
   id: "cite42_map_ai_prompts",
@@ -378,7 +470,7 @@ var aivMapAiPrompts = createTool({
     country: z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
     timeframe: z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trend window. Defaults to "past_12_months".')
   }),
-  execute: async (input) => aivPost("/workflows/ai-prompt-map", input)
+  execute: async (input, context) => aivPost("/workflows/ai-prompt-map", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
 var aivAnalyzeCompetitorContent = createTool({
   id: "cite42_analyze_competitor_content",
@@ -392,7 +484,7 @@ var aivAnalyzeCompetitorContent = createTool({
     brand: optionalShortText("Optional primary brand/domain to compare against."),
     country: z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".')
   }),
-  execute: async (input) => aivPost("/workflows/competitor-content", input)
+  execute: async (input, context) => aivPost("/workflows/competitor-content", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
 var aivFindAiCitationGaps = createTool({
   id: "cite42_find_ai_citation_gaps",
@@ -408,7 +500,7 @@ var aivFindAiCitationGaps = createTool({
     models: modelsInput,
     fullSweep: fullSweepInput
   }),
-  execute: async (input) => aivPost("/workflows/ai-citation-gaps", input)
+  execute: async (input, context) => aivPost("/workflows/ai-citation-gaps", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
 var aivGenerateContentBrief = createTool({
   id: "cite42_generate_content_brief",
@@ -423,7 +515,7 @@ var aivGenerateContentBrief = createTool({
     goal: optionalShortText("Optional content goal, e.g. rank, earn citations, convert."),
     country: z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".')
   }),
-  execute: async (input) => aivPost("/workflows/content-brief", input)
+  execute: async (input, context) => aivPost("/workflows/content-brief", input, context?.abortSignal ?? context?.mcp?.extra.signal)
 });
 var trackerIdInput = z.string().trim().min(1).max(128).describe("Cite42 tracker ID returned by a tracker management or report tool.");
 var trackerCadenceInput = z.object({
@@ -477,7 +569,7 @@ var trackerDefinitionFields = {
     "AI surfaces to query for every prompt. Omit for the three defaults (chatgpt, perplexity, gemini), or list surfaces explicitly \u2014 including all five \u2014 to fix the recurring cost."
   )
 };
-var TRACKER_BILLING_DESCRIPTION = "Tracker management and stored-report reads are free. Each scheduled or manual run bills one call per prompt at the normal per-model rates; the activation response and tracker record expose the accepted maximum cost per run.";
+var TRACKER_BILLING_DESCRIPTION = "Tracker management and stored-report reads are free. Each scheduled or manual run bills one call per prompt at the normal per-model rates; the activation response and tracker record expose the accepted maximum cost per run. Present the returned USD amounts to users; activation still takes the exact estimatedCostMicroPerRun integer returned by the tracker.";
 var aivTrackerCreate = createTool({
   id: "cite42_tracker_create",
   mcp: mutation("Create Cite42 tracker draft"),
@@ -508,7 +600,7 @@ var aivTrackerActivate = createTool({
 var aivTrackerPause = createTool({
   id: "cite42_tracker_pause",
   mcp: mutation("Pause Cite42 tracker", { idempotentHint: true }),
-  description: "Pause future recurring calls for a tracker while preserving its configuration and stored run history. Free: costs 0 credits.",
+  description: "Pause future recurring calls for a tracker while preserving its configuration and stored run history. Free.",
   inputSchema: z.object({ trackerId: trackerIdInput }),
   execute: async ({ trackerId }) => aivPost(`/trackers/${encodeURIComponent(trackerId)}/pause`, {})
 });
@@ -518,7 +610,7 @@ var aivTrackerDelete = createTool({
     destructiveHint: true,
     idempotentHint: true
   }),
-  description: "Permanently delete a draft or paused tracker, including its saved configuration and run history. Active trackers must be paused first, and deletion is rejected while a run is queued or running. Financial usage and credit ledger records are retained. Free: costs 0 credits.",
+  description: "Permanently delete a draft or paused tracker, including its saved configuration and run history. Active trackers must be paused first, and deletion is rejected while a run is queued or running. Financial usage and billing ledger records are retained. Free.",
   inputSchema: z.object({ trackerId: trackerIdInput }),
   execute: async ({ trackerId }) => aivDelete(`/trackers/${encodeURIComponent(trackerId)}`)
 });
@@ -538,14 +630,14 @@ var aivTrackerRun = createTool({
 var aivTrackers = createTool({
   id: "cite42_trackers",
   mcp: readOnly("List Cite42 trackers", false),
-  description: "List the connected account\u2019s trackers with status, cadence, tool configuration, cost estimate, accepted per-run maximum, and next/last run times. Free: costs 0 credits.",
+  description: "List the connected account\u2019s trackers with status, cadence, tool configuration, cost estimate, accepted per-run maximum, and next/last run times. Free.",
   inputSchema: z.object({}),
   execute: async () => aivGet("/trackers")
 });
 var aivTrackerReport = createTool({
   id: "cite42_tracker_report",
   mcp: readOnly("Read Cite42 tracker report", false),
-  description: "Read bounded stored run history for one tracker, including per-tool results, changes from the prior comparable observation, statuses, sampled times, and costs. Free: costs 0 credits.",
+  description: "Read bounded stored run history for one tracker, including per-tool results, changes from the prior comparable observation, statuses, sampled times, and costs. Free.",
   inputSchema: z.object({
     trackerId: trackerIdInput,
     limit: z.number().int().min(1).max(20).optional().default(8).describe("Most recent runs to return, capped for LLM context.")
@@ -555,6 +647,7 @@ var aivTrackerReport = createTool({
 
 // src/server.ts
 var CITE42_TOOLS = {
+  cite42_balance: aivBalance,
   cite42_credits: aivCredits,
   cite42_pricing: aivPricing,
   cite42_usage: aivUsage,
@@ -563,7 +656,9 @@ var CITE42_TOOLS = {
   cite42_compare: aivCompare,
   cite42_citations: aivCitations,
   cite42_sentiment: aivSentiment,
+  cite42_recommendations: aivRecommendations,
   cite42_keywords: aivKeywords,
+  cite42_keywords_batch: aivKeywordsBatch,
   cite42_trends: aivTrends,
   cite42_reddit_trends: aivRedditTrends,
   cite42_youtube_trends: aivYoutubeTrends,
@@ -599,7 +694,7 @@ if (!resolveApiKey()) {
   );
   process.exit(1);
 }
-buildCite42Server("0.5.1").startStdio().catch((error) => {
+buildCite42Server("0.6.0").startStdio().catch((error) => {
   console.error("[@cite42/mcp] Fatal error:", error);
   process.exit(1);
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cite42/mcp",
   "mcpName": "dev.cite42/mcp",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Cite42 MCP server: query the models behind ChatGPT, Claude, Perplexity & Gemini, plus Google AI Overviews, for brand rankings, AI citations, SEO keyword data, and Reddit/YouTube trends, and schedule weekly or monthly trackers that watch a list of prompts over time. Works with Claude Code, Claude Desktop, Codex CLI, Cursor, and any MCP client.",
   "license": "MIT",
   "type": "module",
@@ -16,21 +16,24 @@
   "scripts": {
     "build": "tsup && chmod +x dist/stdio.mjs",
     "dev": "tsup --watch",
+    "inspect": "npm run build && node scripts/inspect.mjs",
+    "test:stdio": "npm run build && node --test tests/stdio.test.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && npm run audit:security",
+    "audit:security": "npm audit --omit=dev --audit-level=high"
   },
   "dependencies": {
-    "@mastra/core": "^1.35.0",
-    "@mastra/mcp": "^1.7.0",
+    "@mastra/core": "^1.68.0",
+    "@mastra/mcp": "^1.18.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@types/node": "^20.19.27",
+    "@types/node": "^22.19.0",
     "tsup": "^8.0.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "publishConfig": {
     "access": "public"
@@ -66,12 +69,15 @@
     "scheduled-monitoring"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.13.0"
   },
   "author": "Cite42 <support@cite42.dev> (https://www.cite42.dev)",
   "homepage": "https://www.cite42.dev",
   "bugs": {
     "email": "support@cite42.dev",
     "url": "https://www.cite42.dev/app/support"
+  },
+  "overrides": {
+    "esbuild": "^0.28.2"
   }
 }