@cite42/mcp 0.5.1 → 0.6.1

package/README.md

@@ -4,13 +4,13 @@
 
 MCP server for [Cite42, the AI search visibility, SEO keyword & trends API](https://www.cite42.dev): market research tools for your AI agent.
 
-Once connected, Claude Code, Claude Desktop, Codex CLI, or Cursor can:
+Once connected, Claude Code, Claude Desktop, Codex CLI, Cursor, or ChatGPT can:
 
 - **Query AI models** (ChatGPT, Claude, Perplexity, Gemini, Google AI Overviews) and see each model's answer and the sources it cites
 - **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,53 +18,63 @@ 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
+- For the API-key setup only: **Node.js 22.13 or newer and a Cite42 API key**
 
 ## Installation
 
-Claude Desktop connects to Cite42 through the hosted remote MCP URL and OAuth. Claude Code, Codex CLI, and Cursor run this package on demand with `npx -y @cite42/mcp`.
+Most clients connect to the hosted server at `https://mcp.cite42.dev` and sign in with your Cite42 account in the browser. There is no API key to create or paste, and nothing to install locally. For CI, servers, or machines without a browser, run this package with an API key instead; see [API key setup](#api-key-setup-ci-servers-no-browser).
 
-### Step 1: Get your API key for local clients
+### Claude Code
 
-Skip this step for Claude Desktop; its hosted connector authorizes through sign-in.
-
-1. Sign in at [cite42.dev](https://www.cite42.dev)
-2. Open **Dashboard → API Keys**: [www.cite42.dev/app/keys](https://www.cite42.dev/app/keys)
-3. Create a key and copy it (it looks like `cite42_live_...`)
-
-### Step 2: Add the server to your client
+```bash
+claude mcp add --transport http --scope user cite42 https://mcp.cite42.dev && claude mcp login cite42
+```
 
-Pick **one** of the clients below. For Claude Code, Codex CLI, and Cursor, replace `cite42_live_your_key_here` with your real key.
+Your browser opens to sign in. Then start Claude Code, or restart it if it was already open, and check with `/mcp`.
 
-#### Claude Code
+### Codex CLI
 
 ```bash
-claude mcp add cite42 -e CITE42_API_KEY=cite42_live_your_key_here -- npx -y @cite42/mcp
+codex mcp add cite42 --url https://mcp.cite42.dev
 ```
 
-#### Claude Desktop
+Codex opens your browser to sign in. If it doesn't, run `codex mcp login cite42`. Then start a new session.
+
+### Cursor
 
-1. Open **Settings → Connectors** and click **Add**.
-2. Select **Add custom connector**.
-3. Enter **Cite42** for the name and paste this remote MCP URL:
+[Add to Cursor](https://cursor.com/install-mcp?name=cite42&config=eyJ1cmwiOiJodHRwczovL21jcC5jaXRlNDIuZGV2In0%3D), or add this under **Settings → MCP**, or in `~/.cursor/mcp.json`:
 
-```text
-https://mcp.cite42.dev
+```json
+{
+  "mcpServers": {
+    "cite42": { "url": "https://mcp.cite42.dev" }
+  }
+}
 ```
 
-4. Click **Connect** and complete the Cite42 sign-in. No API key is required.
+Sign in with your Cite42 account when Cursor asks.
+
+### Claude Desktop and Claude.ai
 
-The same hosted-connector steps apply in Claude.ai.
+[Add to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Cite42&connectorUrl=https%3A%2F%2Fmcp.cite42.dev) opens the connector dialog with Cite42 filled in. Or open **Settings → Connectors → Add custom connector**, name it **Cite42**, and paste `https://mcp.cite42.dev`. Click **Connect** and sign in. The connector appears in both Claude Desktop and Claude.ai.
 
-#### Codex CLI
+### ChatGPT and Codex Desktop
+
+Turn on **Developer mode** in **Settings → Security and login**, then add a plugin under **Settings → Plugins** with the MCP server URL `https://mcp.cite42.dev` and **OAuth**.
+
+### API key setup (CI, servers, no browser)
+
+Create a key at [www.cite42.dev/app/keys](https://www.cite42.dev/app/keys) (it looks like `cite42_live_...` and is shown once), then replace `cite42_live_your_key_here` below. The client starts this package on demand; you don't need to keep it running.
 
 ```bash
+# Claude Code
+claude mcp add --scope user cite42 -e CITE42_API_KEY=cite42_live_your_key_here -- npx -y @cite42/mcp
+
+# Codex CLI
 codex mcp add cite42 --env CITE42_API_KEY=cite42_live_your_key_here -- npx -y @cite42/mcp
 ```
 
-#### Cursor
-
-Add this under **Settings → MCP**, or save it to `~/.cursor/mcp.json`:
+For Cursor, save this to `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -80,21 +90,14 @@ Add this under **Settings → MCP**, or save it to `~/.cursor/mcp.json`:
 }
 ```
 
-### Step 3: Restart so the server loads
+Restart the client afterwards: a new terminal or `claude`/`codex` session, or fully quit and reopen Cursor.
 
-Local MCP servers are started by the client, so their config is only picked up on a fresh start. The Claude Desktop connector is ready after sign-in.
+### Verify it's running
 
-- **Claude Code / Codex CLI**: exit the current session and open a **new terminal** (or start a new `claude` / `codex` session)
-- **Cursor**: fully quit and reopen the app
-
-You do not need to keep `npx -y @cite42/mcp` running in a separate terminal. Local MCP clients start it automatically when the session needs tools.
-
-### Step 4: Verify it's running
-
-- **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.
+- **Claude Code:** run `claude mcp list` and check that `cite42` shows as connected, or type `/mcp` inside a session.
 - **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.
+- **Claude Desktop / Claude.ai:** open **Settings → Connectors** and confirm Cite42 is connected.
 
 If it doesn't appear, see [Troubleshooting](#troubleshooting).
 
@@ -107,7 +110,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 +133,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 +149,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)
@@ -175,7 +181,7 @@ Cite42 exposes 26 MCP tools: 3 free account tools, 9 data tools, 6 research work
 
 ## Configuration
 
-- `CITE42_API_KEY`: required. Your API key from [www.cite42.dev/app/keys](https://www.cite42.dev/app/keys).
+- `CITE42_API_KEY`: required for the local package. Your API key from [www.cite42.dev/app/keys](https://www.cite42.dev/app/keys).
 - `CITE42_API_BASE`: optional. Defaults to `https://www.cite42.dev/api/v1`.
 
 You can also pass these as CLI flags instead of environment variables:
@@ -186,14 +192,19 @@ 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.
+- **"No Cite42 account is linked to this sign-in"**: you signed in with a different account than the one you use at cite42.dev. In Claude Code run `claude mcp logout cite42`, then `claude mcp login cite42` and pick the same sign-in method as on the dashboard.
+- **`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 +212,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,13 +455,13 @@ 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",
   mcp: readOnly("Map buyer prompts for AI search"),
   description: workflowDescription(
-    "Run the AI-prompt-map workflow: discover and cluster buyer prompts worth tracking from AI search, SEO demand, trends, citations, Reddit, and YouTube data. The prompts it returns are exactly what cite42_tracker_create takes, so offer to start tracking the best of them once the user has seen the map."
+    "Run the AI-prompt-map workflow: research for a list of buyer prompts worth tracking, from AI search, SEO demand, trends, citations, Reddit, and YouTube data. It returns evidence and a suggested prompt, not a finished list: write the prompts from it, then offer to track the best of them with cite42_tracker_create once the user has seen them."
   ),
   inputSchema: import_zod.z.object({
     topic: queryText("Market, product category, buyer problem, or audience to map prompts for."),
@@ -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,13 +501,13 @@ 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",
   mcp: readOnly("Generate content brief data"),
   description: workflowDescription(
-    "Run the content-brief workflow: AI answers, citations, SEO keyword demand, trends, Reddit, and YouTube signals aggregated into brief-ready data."
+    "Run the content-brief workflow: research for a content brief from AI answers, citations, SEO keyword demand, trends, Reddit, and YouTube signals. It returns evidence and a suggested prompt; write the brief from it."
   ),
   inputSchema: import_zod.z.object({
     topic: queryText("Topic, keyword, or content idea to 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,11 +570,11 @@ 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"),
-  description: "Create a draft weekly or monthly tracker: one measurement \u2014 rankings, compare, citations, or sentiment \u2014 applied to a list of prompts, with the brand, competitors and AI surfaces set once for all of them. When the user has no prompt list yet, run cite42_map_ai_prompts first and track the prompts it recommends. Creation does not start recurring calls. " + TRACKER_BILLING_DESCRIPTION,
+  description: "Create a draft weekly or monthly tracker: one measurement \u2014 rankings, compare, citations, or sentiment \u2014 applied to a list of prompts, with the brand, competitors and AI surfaces set once for all of them. When the user has no prompt list yet, run cite42_map_ai_prompts first and track the prompts you write from its research. Creation does not start recurring calls. " + TRACKER_BILLING_DESCRIPTION,
   inputSchema: import_zod.z.object(trackerDefinitionFields),
   execute: async (input) => aivPost("/trackers", input)
 });
@@ -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.1").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,13 +454,13 @@ 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",
   mcp: readOnly("Map buyer prompts for AI search"),
   description: workflowDescription(
-    "Run the AI-prompt-map workflow: discover and cluster buyer prompts worth tracking from AI search, SEO demand, trends, citations, Reddit, and YouTube data. The prompts it returns are exactly what cite42_tracker_create takes, so offer to start tracking the best of them once the user has seen the map."
+    "Run the AI-prompt-map workflow: research for a list of buyer prompts worth tracking, from AI search, SEO demand, trends, citations, Reddit, and YouTube data. It returns evidence and a suggested prompt, not a finished list: write the prompts from it, then offer to track the best of them with cite42_tracker_create once the user has seen them."
   ),
   inputSchema: z.object({
     topic: queryText("Market, product category, buyer problem, or audience to map prompts for."),
@@ -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,13 +500,13 @@ 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",
   mcp: readOnly("Generate content brief data"),
   description: workflowDescription(
-    "Run the content-brief workflow: AI answers, citations, SEO keyword demand, trends, Reddit, and YouTube signals aggregated into brief-ready data."
+    "Run the content-brief workflow: research for a content brief from AI answers, citations, SEO keyword demand, trends, Reddit, and YouTube signals. It returns evidence and a suggested prompt; write the brief from it."
   ),
   inputSchema: z.object({
     topic: queryText("Topic, keyword, or content idea to 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,11 +569,11 @@ 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"),
-  description: "Create a draft weekly or monthly tracker: one measurement \u2014 rankings, compare, citations, or sentiment \u2014 applied to a list of prompts, with the brand, competitors and AI surfaces set once for all of them. When the user has no prompt list yet, run cite42_map_ai_prompts first and track the prompts it recommends. Creation does not start recurring calls. " + TRACKER_BILLING_DESCRIPTION,
+  description: "Create a draft weekly or monthly tracker: one measurement \u2014 rankings, compare, citations, or sentiment \u2014 applied to a list of prompts, with the brand, competitors and AI surfaces set once for all of them. When the user has no prompt list yet, run cite42_map_ai_prompts first and track the prompts you write from its research. Creation does not start recurring calls. " + TRACKER_BILLING_DESCRIPTION,
   inputSchema: z.object(trackerDefinitionFields),
   execute: async (input) => aivPost("/trackers", input)
 });
@@ -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.1").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.1",
   "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"
   }
 }