@cite42/mcp 0.1.14 → 0.1.16

package/README.md

@@ -2,7 +2,7 @@
 
 MCP server for [Cite42, the AI search visibility, SEO keyword & trends API](https://www.cite42.dev): market research tools for your AI agent.
 
-Once installed, your MCP client (Claude Code, Claude Desktop, Codex CLI, Cursor, Windsurf, etc.) can:
+Once connected, Claude Code, Claude Desktop, Codex CLI, or Cursor 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
@@ -14,14 +14,16 @@ Once installed, your MCP client (Claude Code, Claude Desktop, Codex CLI, Cursor,
 
 ## Requirements
 
-- **Node.js 18 or newer** (`node --version` to check)
-- **A Cite42 API key**, free to create at [www.cite42.dev/app/keys](https://www.cite42.dev/app/keys)
+- **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
 
 ## Installation
 
-There is nothing to install manually. Every client below runs the server on demand with `npx -y @cite42/mcp`. You only need to register it once.
+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`.
 
-### Step 1: Get your API key
+### Step 1: Get your API key for local clients
+
+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)
@@ -29,7 +31,7 @@ There is nothing to install manually. Every client below runs the server on dema
 
 ### Step 2: Add the server to your client
 
-Pick **one** of the clients below and replace `cite42_live_your_key_here` with your real key.
+Pick **one** of the clients below. For Claude Code, Codex CLI, and Cursor, replace `cite42_live_your_key_here` with your real key.
 
 #### Claude Code
 
@@ -37,15 +39,29 @@ Pick **one** of the clients below and replace `cite42_live_your_key_here` with y
 claude mcp add cite42 -e CITE42_API_KEY=cite42_live_your_key_here -- npx -y @cite42/mcp
 ```
 
+#### Claude Desktop
+
+1. Open **Settings → Connectors** and click **Add**.
+2. Select **Add custom connector**.
+3. Enter **Cite42** for the name and paste this remote MCP URL:
+
+```text
+https://mcp.cite42.dev
+```
+
+4. Click **Connect** and complete the Cite42 sign-in. No API key is required.
+
+The same hosted-connector steps apply in Claude.ai.
+
 #### Codex CLI
 
 ```bash
 codex mcp add cite42 --env CITE42_API_KEY=cite42_live_your_key_here -- npx -y @cite42/mcp
 ```
 
-#### Claude Desktop
+#### Cursor
 
-Add this to `claude_desktop_config.json` (**Settings → Developer → Edit Config**):
+Add this under **Settings → MCP**, or save it to `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -61,30 +77,27 @@ Add this to `claude_desktop_config.json` (**Settings → Developer → Edit Conf
 }
 ```
 
-#### Cursor / Windsurf / other JSON-config clients
-
-Use the same JSON block as Claude Desktop in your client's `mcpServers` config (Cursor: `~/.cursor/mcp.json` or **Settings → MCP**).
-
 ### Step 3: Restart so the server loads
 
-MCP servers are started by the client, so the config is only picked up on a fresh start:
+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.
 
 - **Claude Code / Codex CLI**: exit the current session and open a **new terminal** (or start a new `claude` / `codex` session)
-- **Claude Desktop / Cursor / Windsurf**: fully quit and reopen the app
+- **Cursor**: fully quit and reopen the app
 
-You do not need to keep `npx -y @cite42/mcp` running in a separate terminal. The MCP client starts it automatically when the session needs tools.
+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.
 - **Codex CLI:** run `codex mcp list`.
-- **Claude Desktop / Cursor:** look for `cite42` in the MCP/tools indicator. 15 tools should be listed.
+- **Cursor:** look for `cite42` in the MCP/tools indicator. 15 tools should be listed.
 
 If it doesn't appear, see [Troubleshooting](#troubleshooting).
 
 ## Try it: example prompts
 
-After restarting, just ask in plain language. Your agent picks the right Cite42 tool automatically.
+After connecting or restarting, just ask in plain language. Your agent picks the right Cite42 tool automatically.
 
 - *"Use Cite42 to check which brands AI models recommend for 'best project management software'."*
 - *"Which sources do AI models cite when asked about CRM tools for startups? Is mycompany.com among them?"*
@@ -123,7 +136,7 @@ The exact brands and sources change by query and model. A good result should sho
 
 ### SEO & trend data
 
-- `cite42_keywords`: get search volume, CPC, competition, competition level, and related keyword ideas.
+- `cite42_keywords`: get seed search volume, CPC, and competition, with optional related keyword ideas.
 - `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_youtube_trends`: find YouTube rising videos, creator angles, title patterns, and opportunities.

package/dist/stdio.cjs

@@ -1,16 +1,71 @@
 #!/usr/bin/env node
 "use strict";
 
-// src/stdio.ts
-var import_mcp = require("@mastra/mcp");
-
 // src/client.ts
 var DEFAULT_BASE_URL = "https://www.cite42.dev/api/v1";
+var MICRO_CREDITS_PER_CREDIT = 1e3;
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toCredits(microCredits) {
+  return microCredits / MICRO_CREDITS_PER_CREDIT;
+}
+function formatCredits(microCredits) {
+  const credits = toCredits(microCredits);
+  return credits.toLocaleString(
+    "en-US",
+    Number.isInteger(credits) ? { maximumFractionDigits: 0 } : { minimumFractionDigits: 0, maximumFractionDigits: 2 }
+  );
+}
+function toCite42McpResult(value) {
+  if (!isJsonObject(value)) return value;
+  const { billing, warning, ...result } = value;
+  if (!isJsonObject(billing)) return value;
+  const cost = isJsonObject(billing.cost) ? billing.cost.microCredits : void 0;
+  const balance = isJsonObject(billing.balance) ? billing.balance.microCredits : void 0;
+  if (typeof cost !== "number" || !Number.isFinite(cost) || typeof balance !== "number" || !Number.isFinite(balance)) {
+    return result;
+  }
+  const lowCredits = typeof warning === "string";
+  const message = `Cite42 credits: ${formatCredits(cost)} charged; ${formatCredits(balance)} remaining.`;
+  return {
+    ...result,
+    cite42Credits: {
+      charged: toCredits(cost),
+      remaining: toCredits(balance),
+      message: lowCredits ? `${message} Low Cite42 credit balance.` : message
+    }
+  };
+}
+function toCite42CreditsBalance(balanceMicroCredits) {
+  return {
+    cite42Credits: {
+      remaining: toCredits(balanceMicroCredits),
+      message: `Cite42 credits: ${formatCredits(balanceMicroCredits)} remaining. This balance check was free.`
+    }
+  };
+}
+function errorMessageForMcp(status, path, body) {
+  try {
+    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.";
+      }
+      if (payload.error.code === "insufficient_credits") {
+        return "Insufficient Cite42 credits. Top up at https://www.cite42.dev/app/billing.";
+      }
+    }
+  } catch {
+  }
+  return `Cite42 API ${status} ${path}: ${body}`;
+}
 function readFlag(name) {
   const argv = process.argv.slice(2);
   const prefix = `--${name}=`;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
+    if (!arg) continue;
     if (arg.startsWith(prefix)) return arg.slice(prefix.length);
     if (arg === `--${name}` && i + 1 < argv.length) return argv[i + 1];
   }
@@ -43,10 +98,25 @@ async function aivPost(path, body) {
   });
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Cite42 API ${res.status} ${path}: ${text}`);
+    throw new Error(errorMessageForMcp(res.status, path, text));
   }
-  return res.json();
+  return toCite42McpResult(await res.json());
 }
+async function aivGet(path) {
+  const url = `${getBaseUrl()}${path.startsWith("/") ? path : `/${path}`}`;
+  const res = await fetch(url, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${getApiKey()}` }
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(errorMessageForMcp(res.status, path, text));
+  }
+  return toCite42McpResult(await res.json());
+}
+
+// src/server.ts
+var import_mcp = require("@mastra/mcp");
 
 // src/tools.ts
 var import_tools = require("@mastra/core/tools");
@@ -56,9 +126,16 @@ var QUERY_MAX_CHARS = 2e3;
 var SHORT_TEXT_MAX_CHARS = 200;
 var TIMEFRAME_MAX_CHARS = 80;
 var MODEL_SELECTION_DESCRIPTION = 'Optional model subset. Omit to query all five AI surfaces (chatgpt, claude, perplexity, gemini, google_ai_overview). Pass ["perplexity"] or ["perplexity","claude"] when the user asks for specific surfaces or wants to reduce cost.';
-var MCP_USAGE_GUIDANCE = "Use Cite42 for AI-search, citation, SEO, keyword, trend, and market-research data. Do not use it as a general coding or writing assistant; code-related research is fine when the goal is to compare what AI models recommend or cite. If a plan needs more than 20 endpoint calls or may cost over $5, estimate the cost and ask the user before continuing.";
-var MODEL_PRICING = "Pricing: search/citations/rankings/compare are model-specific: Google AI Overview $0.01, Gemini $0.02, ChatGPT/Claude $0.04, Perplexity $0.05 per selected model. Sentiment: Google AI Overview $0.03, Gemini $0.04, ChatGPT/Claude $0.06, Perplexity $0.07. Omitting models queries all five AI surfaces. Use the models field when the user names a specific surface or asks to reduce cost.";
-var DATA_PRICING = "Pricing: keywords $0.15/call, trends $0.01/call, Reddit trends $0.05/call, YouTube trends $0.05/call.";
+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 all five. 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 DATA_PRICING = "Data tools have flat per-call prices; call cite42_pricing for exact current rates.";
+var WORKFLOW_PRICING = "Pricing: workflow cost is calculated from the primitive endpoints that run successfully and the selected model rates.";
+function workflowDescription(description) {
+  return `${description} ${MCP_USAGE_GUIDANCE} ${MODEL_PRICING} ${DATA_PRICING} ${WORKFLOW_PRICING}`;
+}
+function readOnly(title, openWorldHint = true) {
+  return { annotations: { title, readOnlyHint: true, openWorldHint } };
+}
 function queryText(description) {
   return import_zod.z.string().trim().min(1).max(QUERY_MAX_CHARS).describe(description);
 }
@@ -70,8 +147,52 @@ function optionalShortText(description) {
 }
 var modelsInput = import_zod.z.array(modelEnum).nonempty().optional().describe(MODEL_SELECTION_DESCRIPTION);
 var competitorList = import_zod.z.array(shortText("Competitor brand/domain name.")).nonempty().max(20);
+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,
+  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 toCite42CreditsBalance(microCredits);
+  }
+});
+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")
+});
+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,
+  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 {
+      ...toCite42CreditsBalance(microCredits),
+      recentCalls: (usage.recent ?? []).slice(0, 20).map((row) => ({
+        endpoint: row.endpoint,
+        status: row.status,
+        credits: typeof row.costMicro === "number" ? toCredits(row.costMicro) : void 0,
+        at: row.createdAt
+      }))
+    };
+  }
+});
 var aivSearch = (0, import_tools.createTool)({
   id: "cite42_search",
+  mcp: readOnly("Search AI models"),
   description: `Run a query against AI models (ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews) and return each model's answer along with the sources it cited. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: import_zod.z.object({
     query: queryText("The concise AI-search/market-research query to run against the selected models."),
@@ -81,6 +202,7 @@ var aivSearch = (0, import_tools.createTool)({
 });
 var aivCitations = (0, import_tools.createTool)({
   id: "cite42_citations",
+  mcp: readOnly("Find AI citations"),
   description: `Find which sources AI models cite for a query. Aggregates cited URLs across models with per-model counts; optionally checks whether a specific URL is cited. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: import_zod.z.object({
     query: queryText("The concise query to look up cited sources for."),
@@ -91,6 +213,7 @@ var aivCitations = (0, import_tools.createTool)({
 });
 var aivRankings = (0, import_tools.createTool)({
   id: "cite42_rankings",
+  mcp: readOnly("Measure AI brand rankings"),
   description: `Measure how a set of brands/competitors rank in AI answers for a query: mention rate, average position, and a per-model breakdown across ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: import_zod.z.object({
     query: queryText("The concise query to measure brand/competitor visibility on."),
@@ -101,6 +224,7 @@ var aivRankings = (0, import_tools.createTool)({
 });
 var aivCompare = (0, import_tools.createTool)({
   id: "cite42_compare",
+  mcp: readOnly("Compare brand against competitors"),
   description: `Compare one primary brand head-to-head against a competitor set in AI answers: per-brand rankings plus a co-mention graph of which brands the models name together. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: import_zod.z.object({
     query: queryText("The concise query to compare the brand and competitors on."),
@@ -112,6 +236,7 @@ var aivCompare = (0, import_tools.createTool)({
 });
 var aivSentiment = (0, import_tools.createTool)({
   id: "cite42_sentiment",
+  mcp: readOnly("Score brand sentiment in AI answers"),
   description: `Score how each AI model talks about a brand for a query: a positive/neutral/negative split per model with the verbatim phrases driving the tone, plus an aggregate across models. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: import_zod.z.object({
     query: queryText("The concise query whose answers are scored for brand sentiment."),
@@ -122,26 +247,31 @@ var aivSentiment = (0, import_tools.createTool)({
 });
 var aivKeywords = (0, import_tools.createTool)({
   id: "cite42_keywords",
-  description: `Classic keyword data for a seed term: monthly search volume, CPC, competition, and (optionally) LLM-curated related keyword ideas with volume, CPC, competition, and competition level from provider candidates. A flat-priced data tool, not a multi-model AI-search query. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  mcp: readOnly("Get SEO keyword data"),
+  description: `Classic keyword data for a seed term. Omit ideas when the user only needs that seed's monthly search volume, CPC, or competition. Set ideas:true only when the user asks for related, alternative, or long-tail suggestions from provider candidates. A flat-priced data tool, not a multi-model AI-search query. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: import_zod.z.object({
     seed: queryText("Seed keyword or concise topic to fetch search volume, CPC, and competition for."),
     country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code for localized metrics. Defaults to "us".'),
-    ideas: import_zod.z.boolean().optional().describe("When true, also return LLM-curated related keyword ideas with volume, CPC, competition, and competition level.")
+    ideas: import_zod.z.boolean().optional().describe(
+      "Omit for volume, CPC, and competition on the seed only. Set true only for related, alternative, or long-tail keyword ideas."
+    )
   }),
   execute: async (input) => aivPost("/keywords", input)
 });
 var aivTrends = (0, import_tools.createTool)({
   id: "cite42_trends",
+  mcp: readOnly("Get Google Trends data"),
   description: `Google Trends interest-over-time, related and rising queries, and a rising/falling/stable label for a term. A flat-priced data tool, not an AI-model query. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: import_zod.z.object({
     term: queryText("Search term or concise topic to pull Google Trends interest-over-time for."),
     timeframe: import_zod.z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trends window, e.g. "past_12_months", "past_30_days", "past_5_years".'),
-    geo: import_zod.z.string().trim().max(SHORT_TEXT_MAX_CHARS).optional().describe('Optional location name (e.g. "United States"). Worldwide when omitted.')
+    geo: import_zod.z.string().trim().max(SHORT_TEXT_MAX_CHARS).optional().describe('Optional location name (e.g. "United Kingdom"). Defaults to the United States when omitted.')
   }),
   execute: async (input) => aivPost("/trends", input)
 });
 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}`,
   inputSchema: import_zod.z.object({
     topic: queryText("Topic, category, product, or audience to research on Reddit."),
@@ -152,6 +282,7 @@ var aivRedditTrends = (0, import_tools.createTool)({
 });
 var aivYoutubeTrends = (0, import_tools.createTool)({
   id: "cite42_youtube_trends",
+  mcp: readOnly("Get YouTube trend data"),
   description: `YouTube trend data for rising videos, creator angles, title patterns, channel examples, and video-market opportunities around a topic. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: import_zod.z.object({
     topic: queryText("Topic, keyword, niche, or audience to research on YouTube."),
@@ -163,7 +294,10 @@ var aivYoutubeTrends = (0, import_tools.createTool)({
 var channelEnum = import_zod.z.enum(["ai_search", "seo_keywords", "google_trends", "reddit", "youtube"]);
 var aivFindContentOpportunities = (0, import_tools.createTool)({
   id: "cite42_find_content_opportunities",
-  description: `Run the content-opportunities workflow: fans out across AI search, SEO keywords, trends, Reddit, YouTube, and citations and returns the aggregated data in one response. ${MCP_USAGE_GUIDANCE}`,
+  mcp: readOnly("Find content opportunities"),
+  description: workflowDescription(
+    "Run the content-opportunities workflow: fans out across AI search, SEO keywords, trends, Reddit, YouTube, and citations and returns the aggregated data in one response."
+  ),
   inputSchema: import_zod.z.object({
     topic: queryText("Market, niche, product category, or audience to research."),
     audience: optionalShortText("Optional target audience or ICP."),
@@ -176,7 +310,10 @@ var aivFindContentOpportunities = (0, import_tools.createTool)({
 });
 var aivAnalyzeTopicDemand = (0, import_tools.createTool)({
   id: "cite42_analyze_topic_demand",
-  description: `Run the topic-demand workflow: SEO keyword data, Google Trends, AI answers, and audience conversations, aggregated in one response. ${MCP_USAGE_GUIDANCE}`,
+  mcp: readOnly("Analyze topic demand"),
+  description: workflowDescription(
+    "Run the topic-demand workflow: SEO keyword data, Google Trends, AI answers, and audience conversations, aggregated in one response."
+  ),
   inputSchema: import_zod.z.object({
     topic: queryText("Topic, keyword, category, or audience demand to analyze."),
     country: import_zod.z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
@@ -186,7 +323,10 @@ var aivAnalyzeTopicDemand = (0, import_tools.createTool)({
 });
 var aivMapAiPrompts = (0, import_tools.createTool)({
   id: "cite42_map_ai_prompts",
-  description: `Run the AI-prompt-map workflow: discover and cluster buyer prompts worth tracking from AI search, SEO demand, trends, citations, Reddit, and YouTube data. ${MCP_USAGE_GUIDANCE}`,
+  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."
+  ),
   inputSchema: import_zod.z.object({
     topic: queryText("Market, product category, buyer problem, or audience to map prompts for."),
     audience: optionalShortText("Optional target audience or ICP."),
@@ -199,7 +339,10 @@ var aivMapAiPrompts = (0, import_tools.createTool)({
 });
 var aivAnalyzeCompetitorContent = (0, import_tools.createTool)({
   id: "cite42_analyze_competitor_content",
-  description: `Run the competitor-content workflow: AI rankings, head-to-head comparison, citations, keyword demand, and topic coverage, aggregated in one response. ${MCP_USAGE_GUIDANCE}`,
+  mcp: readOnly("Analyze competitor content"),
+  description: workflowDescription(
+    "Run the competitor-content workflow: AI rankings, head-to-head comparison, citations, keyword demand, and topic coverage, aggregated in one response."
+  ),
   inputSchema: import_zod.z.object({
     competitors: competitorList.describe("Competitor brands, domains, or channels to analyze."),
     topic: import_zod.z.string().trim().min(1).max(QUERY_MAX_CHARS).optional().describe("Optional topic/category to constrain the analysis."),
@@ -210,7 +353,10 @@ var aivAnalyzeCompetitorContent = (0, import_tools.createTool)({
 });
 var aivFindAiCitationGaps = (0, import_tools.createTool)({
   id: "cite42_find_ai_citation_gaps",
-  description: `Run the AI-citation-gaps workflow: find queries where AI answers cite others but not your brand, domain, or URL, with the supporting data. ${MCP_USAGE_GUIDANCE}`,
+  mcp: readOnly("Find AI citation gaps"),
+  description: workflowDescription(
+    "Run the AI-citation-gaps workflow: find queries where AI answers cite others but not your brand, domain, or URL, with the supporting data."
+  ),
   inputSchema: import_zod.z.object({
     query: queryText("AI-search query to inspect for citation gaps."),
     brand: shortText("Brand or domain that should earn citations."),
@@ -222,7 +368,10 @@ var aivFindAiCitationGaps = (0, import_tools.createTool)({
 });
 var aivGenerateContentBrief = (0, import_tools.createTool)({
   id: "cite42_generate_content_brief",
-  description: `Run the content-brief workflow: AI answers, citations, SEO keyword demand, trends, Reddit, and YouTube signals aggregated into brief-ready data. ${MCP_USAGE_GUIDANCE}`,
+  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."
+  ),
   inputSchema: import_zod.z.object({
     topic: queryText("Topic, keyword, or content idea to brief."),
     audience: optionalShortText("Optional target audience or ICP."),
@@ -233,6 +382,37 @@ var aivGenerateContentBrief = (0, import_tools.createTool)({
   execute: async (input) => aivPost("/workflows/content-brief", input)
 });
 
+// src/server.ts
+var CITE42_TOOLS = {
+  cite42_credits: aivCredits,
+  cite42_pricing: aivPricing,
+  cite42_usage: aivUsage,
+  cite42_search: aivSearch,
+  cite42_rankings: aivRankings,
+  cite42_compare: aivCompare,
+  cite42_citations: aivCitations,
+  cite42_sentiment: aivSentiment,
+  cite42_keywords: aivKeywords,
+  cite42_trends: aivTrends,
+  cite42_reddit_trends: aivRedditTrends,
+  cite42_youtube_trends: aivYoutubeTrends,
+  cite42_find_content_opportunities: aivFindContentOpportunities,
+  cite42_analyze_topic_demand: aivAnalyzeTopicDemand,
+  cite42_map_ai_prompts: aivMapAiPrompts,
+  cite42_analyze_competitor_content: aivAnalyzeCompetitorContent,
+  cite42_find_ai_citation_gaps: aivFindAiCitationGaps,
+  cite42_generate_content_brief: aivGenerateContentBrief
+};
+function buildCite42Server(version) {
+  return new import_mcp.MCPServer({
+    id: "cite42",
+    name: "Cite42",
+    version,
+    description: "AI market data API: AI search, citations, SEO keywords, trends, and workflows.",
+    tools: CITE42_TOOLS
+  });
+}
+
 // src/stdio.ts
 if (!resolveApiKey()) {
   console.error(
@@ -240,30 +420,7 @@ if (!resolveApiKey()) {
   );
   process.exit(1);
 }
-var server = new import_mcp.MCPServer({
-  id: "cite42",
-  name: "Cite42",
-  version: "0.1.14",
-  description: "AI market data API: AI search, citations, SEO keywords, trends, and workflows.",
-  tools: {
-    cite42_search: aivSearch,
-    cite42_rankings: aivRankings,
-    cite42_compare: aivCompare,
-    cite42_citations: aivCitations,
-    cite42_sentiment: aivSentiment,
-    cite42_keywords: aivKeywords,
-    cite42_trends: aivTrends,
-    cite42_reddit_trends: aivRedditTrends,
-    cite42_youtube_trends: aivYoutubeTrends,
-    cite42_find_content_opportunities: aivFindContentOpportunities,
-    cite42_analyze_topic_demand: aivAnalyzeTopicDemand,
-    cite42_map_ai_prompts: aivMapAiPrompts,
-    cite42_analyze_competitor_content: aivAnalyzeCompetitorContent,
-    cite42_find_ai_citation_gaps: aivFindAiCitationGaps,
-    cite42_generate_content_brief: aivGenerateContentBrief
-  }
-});
-server.startStdio().catch((error) => {
+buildCite42Server("0.1.16").startStdio().catch((error) => {
   console.error("[@cite42/mcp] Fatal error:", error);
   process.exit(1);
 });

package/dist/stdio.mjs

@@ -1,15 +1,70 @@
 #!/usr/bin/env node
 
-// src/stdio.ts
-import { MCPServer } from "@mastra/mcp";
-
 // src/client.ts
 var DEFAULT_BASE_URL = "https://www.cite42.dev/api/v1";
+var MICRO_CREDITS_PER_CREDIT = 1e3;
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toCredits(microCredits) {
+  return microCredits / MICRO_CREDITS_PER_CREDIT;
+}
+function formatCredits(microCredits) {
+  const credits = toCredits(microCredits);
+  return credits.toLocaleString(
+    "en-US",
+    Number.isInteger(credits) ? { maximumFractionDigits: 0 } : { minimumFractionDigits: 0, maximumFractionDigits: 2 }
+  );
+}
+function toCite42McpResult(value) {
+  if (!isJsonObject(value)) return value;
+  const { billing, warning, ...result } = value;
+  if (!isJsonObject(billing)) return value;
+  const cost = isJsonObject(billing.cost) ? billing.cost.microCredits : void 0;
+  const balance = isJsonObject(billing.balance) ? billing.balance.microCredits : void 0;
+  if (typeof cost !== "number" || !Number.isFinite(cost) || typeof balance !== "number" || !Number.isFinite(balance)) {
+    return result;
+  }
+  const lowCredits = typeof warning === "string";
+  const message = `Cite42 credits: ${formatCredits(cost)} charged; ${formatCredits(balance)} remaining.`;
+  return {
+    ...result,
+    cite42Credits: {
+      charged: toCredits(cost),
+      remaining: toCredits(balance),
+      message: lowCredits ? `${message} Low Cite42 credit balance.` : message
+    }
+  };
+}
+function toCite42CreditsBalance(balanceMicroCredits) {
+  return {
+    cite42Credits: {
+      remaining: toCredits(balanceMicroCredits),
+      message: `Cite42 credits: ${formatCredits(balanceMicroCredits)} remaining. This balance check was free.`
+    }
+  };
+}
+function errorMessageForMcp(status, path, body) {
+  try {
+    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.";
+      }
+      if (payload.error.code === "insufficient_credits") {
+        return "Insufficient Cite42 credits. Top up at https://www.cite42.dev/app/billing.";
+      }
+    }
+  } catch {
+  }
+  return `Cite42 API ${status} ${path}: ${body}`;
+}
 function readFlag(name) {
   const argv = process.argv.slice(2);
   const prefix = `--${name}=`;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
+    if (!arg) continue;
     if (arg.startsWith(prefix)) return arg.slice(prefix.length);
     if (arg === `--${name}` && i + 1 < argv.length) return argv[i + 1];
   }
@@ -42,10 +97,25 @@ async function aivPost(path, body) {
   });
   if (!res.ok) {
     const text = await res.text();
-    throw new Error(`Cite42 API ${res.status} ${path}: ${text}`);
+    throw new Error(errorMessageForMcp(res.status, path, text));
   }
-  return res.json();
+  return toCite42McpResult(await res.json());
 }
+async function aivGet(path) {
+  const url = `${getBaseUrl()}${path.startsWith("/") ? path : `/${path}`}`;
+  const res = await fetch(url, {
+    method: "GET",
+    headers: { Authorization: `Bearer ${getApiKey()}` }
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(errorMessageForMcp(res.status, path, text));
+  }
+  return toCite42McpResult(await res.json());
+}
+
+// src/server.ts
+import { MCPServer } from "@mastra/mcp";
 
 // src/tools.ts
 import { createTool } from "@mastra/core/tools";
@@ -55,9 +125,16 @@ var QUERY_MAX_CHARS = 2e3;
 var SHORT_TEXT_MAX_CHARS = 200;
 var TIMEFRAME_MAX_CHARS = 80;
 var MODEL_SELECTION_DESCRIPTION = 'Optional model subset. Omit to query all five AI surfaces (chatgpt, claude, perplexity, gemini, google_ai_overview). Pass ["perplexity"] or ["perplexity","claude"] when the user asks for specific surfaces or wants to reduce cost.';
-var MCP_USAGE_GUIDANCE = "Use Cite42 for AI-search, citation, SEO, keyword, trend, and market-research data. Do not use it as a general coding or writing assistant; code-related research is fine when the goal is to compare what AI models recommend or cite. If a plan needs more than 20 endpoint calls or may cost over $5, estimate the cost and ask the user before continuing.";
-var MODEL_PRICING = "Pricing: search/citations/rankings/compare are model-specific: Google AI Overview $0.01, Gemini $0.02, ChatGPT/Claude $0.04, Perplexity $0.05 per selected model. Sentiment: Google AI Overview $0.03, Gemini $0.04, ChatGPT/Claude $0.06, Perplexity $0.07. Omitting models queries all five AI surfaces. Use the models field when the user names a specific surface or asks to reduce cost.";
-var DATA_PRICING = "Pricing: keywords $0.15/call, trends $0.01/call, Reddit trends $0.05/call, YouTube trends $0.05/call.";
+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 all five. 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 DATA_PRICING = "Data tools have flat per-call prices; call cite42_pricing for exact current rates.";
+var WORKFLOW_PRICING = "Pricing: workflow cost is calculated from the primitive endpoints that run successfully and the selected model rates.";
+function workflowDescription(description) {
+  return `${description} ${MCP_USAGE_GUIDANCE} ${MODEL_PRICING} ${DATA_PRICING} ${WORKFLOW_PRICING}`;
+}
+function readOnly(title, openWorldHint = true) {
+  return { annotations: { title, readOnlyHint: true, openWorldHint } };
+}
 function queryText(description) {
   return z.string().trim().min(1).max(QUERY_MAX_CHARS).describe(description);
 }
@@ -69,8 +146,52 @@ function optionalShortText(description) {
 }
 var modelsInput = z.array(modelEnum).nonempty().optional().describe(MODEL_SELECTION_DESCRIPTION);
 var competitorList = z.array(shortText("Competitor brand/domain name.")).nonempty().max(20);
+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,
+  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 toCite42CreditsBalance(microCredits);
+  }
+});
+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")
+});
+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,
+  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 {
+      ...toCite42CreditsBalance(microCredits),
+      recentCalls: (usage.recent ?? []).slice(0, 20).map((row) => ({
+        endpoint: row.endpoint,
+        status: row.status,
+        credits: typeof row.costMicro === "number" ? toCredits(row.costMicro) : void 0,
+        at: row.createdAt
+      }))
+    };
+  }
+});
 var aivSearch = createTool({
   id: "cite42_search",
+  mcp: readOnly("Search AI models"),
   description: `Run a query against AI models (ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews) and return each model's answer along with the sources it cited. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: z.object({
     query: queryText("The concise AI-search/market-research query to run against the selected models."),
@@ -80,6 +201,7 @@ var aivSearch = createTool({
 });
 var aivCitations = createTool({
   id: "cite42_citations",
+  mcp: readOnly("Find AI citations"),
   description: `Find which sources AI models cite for a query. Aggregates cited URLs across models with per-model counts; optionally checks whether a specific URL is cited. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: z.object({
     query: queryText("The concise query to look up cited sources for."),
@@ -90,6 +212,7 @@ var aivCitations = createTool({
 });
 var aivRankings = createTool({
   id: "cite42_rankings",
+  mcp: readOnly("Measure AI brand rankings"),
   description: `Measure how a set of brands/competitors rank in AI answers for a query: mention rate, average position, and a per-model breakdown across ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: z.object({
     query: queryText("The concise query to measure brand/competitor visibility on."),
@@ -100,6 +223,7 @@ var aivRankings = createTool({
 });
 var aivCompare = createTool({
   id: "cite42_compare",
+  mcp: readOnly("Compare brand against competitors"),
   description: `Compare one primary brand head-to-head against a competitor set in AI answers: per-brand rankings plus a co-mention graph of which brands the models name together. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: z.object({
     query: queryText("The concise query to compare the brand and competitors on."),
@@ -111,6 +235,7 @@ var aivCompare = createTool({
 });
 var aivSentiment = createTool({
   id: "cite42_sentiment",
+  mcp: readOnly("Score brand sentiment in AI answers"),
   description: `Score how each AI model talks about a brand for a query: a positive/neutral/negative split per model with the verbatim phrases driving the tone, plus an aggregate across models. ${MODEL_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: z.object({
     query: queryText("The concise query whose answers are scored for brand sentiment."),
@@ -121,26 +246,31 @@ var aivSentiment = createTool({
 });
 var aivKeywords = createTool({
   id: "cite42_keywords",
-  description: `Classic keyword data for a seed term: monthly search volume, CPC, competition, and (optionally) LLM-curated related keyword ideas with volume, CPC, competition, and competition level from provider candidates. A flat-priced data tool, not a multi-model AI-search query. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
+  mcp: readOnly("Get SEO keyword data"),
+  description: `Classic keyword data for a seed term. Omit ideas when the user only needs that seed's monthly search volume, CPC, or competition. Set ideas:true only when the user asks for related, alternative, or long-tail suggestions from provider candidates. A flat-priced data tool, not a multi-model AI-search query. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: z.object({
     seed: queryText("Seed keyword or concise topic to fetch search volume, CPC, and competition for."),
     country: z.string().trim().max(8).optional().describe('ISO-2 country code for localized metrics. Defaults to "us".'),
-    ideas: z.boolean().optional().describe("When true, also return LLM-curated related keyword ideas with volume, CPC, competition, and competition level.")
+    ideas: z.boolean().optional().describe(
+      "Omit for volume, CPC, and competition on the seed only. Set true only for related, alternative, or long-tail keyword ideas."
+    )
   }),
   execute: async (input) => aivPost("/keywords", input)
 });
 var aivTrends = createTool({
   id: "cite42_trends",
+  mcp: readOnly("Get Google Trends data"),
   description: `Google Trends interest-over-time, related and rising queries, and a rising/falling/stable label for a term. A flat-priced data tool, not an AI-model query. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: z.object({
     term: queryText("Search term or concise topic to pull Google Trends interest-over-time for."),
     timeframe: z.string().trim().max(TIMEFRAME_MAX_CHARS).optional().describe('Trends window, e.g. "past_12_months", "past_30_days", "past_5_years".'),
-    geo: z.string().trim().max(SHORT_TEXT_MAX_CHARS).optional().describe('Optional location name (e.g. "United States"). Worldwide when omitted.')
+    geo: z.string().trim().max(SHORT_TEXT_MAX_CHARS).optional().describe('Optional location name (e.g. "United Kingdom"). Defaults to the United States when omitted.')
   }),
   execute: async (input) => aivPost("/trends", input)
 });
 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}`,
   inputSchema: z.object({
     topic: queryText("Topic, category, product, or audience to research on Reddit."),
@@ -151,6 +281,7 @@ var aivRedditTrends = createTool({
 });
 var aivYoutubeTrends = createTool({
   id: "cite42_youtube_trends",
+  mcp: readOnly("Get YouTube trend data"),
   description: `YouTube trend data for rising videos, creator angles, title patterns, channel examples, and video-market opportunities around a topic. ${DATA_PRICING} ${MCP_USAGE_GUIDANCE}`,
   inputSchema: z.object({
     topic: queryText("Topic, keyword, niche, or audience to research on YouTube."),
@@ -162,7 +293,10 @@ var aivYoutubeTrends = createTool({
 var channelEnum = z.enum(["ai_search", "seo_keywords", "google_trends", "reddit", "youtube"]);
 var aivFindContentOpportunities = createTool({
   id: "cite42_find_content_opportunities",
-  description: `Run the content-opportunities workflow: fans out across AI search, SEO keywords, trends, Reddit, YouTube, and citations and returns the aggregated data in one response. ${MCP_USAGE_GUIDANCE}`,
+  mcp: readOnly("Find content opportunities"),
+  description: workflowDescription(
+    "Run the content-opportunities workflow: fans out across AI search, SEO keywords, trends, Reddit, YouTube, and citations and returns the aggregated data in one response."
+  ),
   inputSchema: z.object({
     topic: queryText("Market, niche, product category, or audience to research."),
     audience: optionalShortText("Optional target audience or ICP."),
@@ -175,7 +309,10 @@ var aivFindContentOpportunities = createTool({
 });
 var aivAnalyzeTopicDemand = createTool({
   id: "cite42_analyze_topic_demand",
-  description: `Run the topic-demand workflow: SEO keyword data, Google Trends, AI answers, and audience conversations, aggregated in one response. ${MCP_USAGE_GUIDANCE}`,
+  mcp: readOnly("Analyze topic demand"),
+  description: workflowDescription(
+    "Run the topic-demand workflow: SEO keyword data, Google Trends, AI answers, and audience conversations, aggregated in one response."
+  ),
   inputSchema: z.object({
     topic: queryText("Topic, keyword, category, or audience demand to analyze."),
     country: z.string().trim().max(8).optional().describe('ISO-2 country code. Defaults to "us".'),
@@ -185,7 +322,10 @@ var aivAnalyzeTopicDemand = createTool({
 });
 var aivMapAiPrompts = createTool({
   id: "cite42_map_ai_prompts",
-  description: `Run the AI-prompt-map workflow: discover and cluster buyer prompts worth tracking from AI search, SEO demand, trends, citations, Reddit, and YouTube data. ${MCP_USAGE_GUIDANCE}`,
+  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."
+  ),
   inputSchema: z.object({
     topic: queryText("Market, product category, buyer problem, or audience to map prompts for."),
     audience: optionalShortText("Optional target audience or ICP."),
@@ -198,7 +338,10 @@ var aivMapAiPrompts = createTool({
 });
 var aivAnalyzeCompetitorContent = createTool({
   id: "cite42_analyze_competitor_content",
-  description: `Run the competitor-content workflow: AI rankings, head-to-head comparison, citations, keyword demand, and topic coverage, aggregated in one response. ${MCP_USAGE_GUIDANCE}`,
+  mcp: readOnly("Analyze competitor content"),
+  description: workflowDescription(
+    "Run the competitor-content workflow: AI rankings, head-to-head comparison, citations, keyword demand, and topic coverage, aggregated in one response."
+  ),
   inputSchema: z.object({
     competitors: competitorList.describe("Competitor brands, domains, or channels to analyze."),
     topic: z.string().trim().min(1).max(QUERY_MAX_CHARS).optional().describe("Optional topic/category to constrain the analysis."),
@@ -209,7 +352,10 @@ var aivAnalyzeCompetitorContent = createTool({
 });
 var aivFindAiCitationGaps = createTool({
   id: "cite42_find_ai_citation_gaps",
-  description: `Run the AI-citation-gaps workflow: find queries where AI answers cite others but not your brand, domain, or URL, with the supporting data. ${MCP_USAGE_GUIDANCE}`,
+  mcp: readOnly("Find AI citation gaps"),
+  description: workflowDescription(
+    "Run the AI-citation-gaps workflow: find queries where AI answers cite others but not your brand, domain, or URL, with the supporting data."
+  ),
   inputSchema: z.object({
     query: queryText("AI-search query to inspect for citation gaps."),
     brand: shortText("Brand or domain that should earn citations."),
@@ -221,7 +367,10 @@ var aivFindAiCitationGaps = createTool({
 });
 var aivGenerateContentBrief = createTool({
   id: "cite42_generate_content_brief",
-  description: `Run the content-brief workflow: AI answers, citations, SEO keyword demand, trends, Reddit, and YouTube signals aggregated into brief-ready data. ${MCP_USAGE_GUIDANCE}`,
+  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."
+  ),
   inputSchema: z.object({
     topic: queryText("Topic, keyword, or content idea to brief."),
     audience: optionalShortText("Optional target audience or ICP."),
@@ -232,6 +381,37 @@ var aivGenerateContentBrief = createTool({
   execute: async (input) => aivPost("/workflows/content-brief", input)
 });
 
+// src/server.ts
+var CITE42_TOOLS = {
+  cite42_credits: aivCredits,
+  cite42_pricing: aivPricing,
+  cite42_usage: aivUsage,
+  cite42_search: aivSearch,
+  cite42_rankings: aivRankings,
+  cite42_compare: aivCompare,
+  cite42_citations: aivCitations,
+  cite42_sentiment: aivSentiment,
+  cite42_keywords: aivKeywords,
+  cite42_trends: aivTrends,
+  cite42_reddit_trends: aivRedditTrends,
+  cite42_youtube_trends: aivYoutubeTrends,
+  cite42_find_content_opportunities: aivFindContentOpportunities,
+  cite42_analyze_topic_demand: aivAnalyzeTopicDemand,
+  cite42_map_ai_prompts: aivMapAiPrompts,
+  cite42_analyze_competitor_content: aivAnalyzeCompetitorContent,
+  cite42_find_ai_citation_gaps: aivFindAiCitationGaps,
+  cite42_generate_content_brief: aivGenerateContentBrief
+};
+function buildCite42Server(version) {
+  return new MCPServer({
+    id: "cite42",
+    name: "Cite42",
+    version,
+    description: "AI market data API: AI search, citations, SEO keywords, trends, and workflows.",
+    tools: CITE42_TOOLS
+  });
+}
+
 // src/stdio.ts
 if (!resolveApiKey()) {
   console.error(
@@ -239,30 +419,7 @@ if (!resolveApiKey()) {
   );
   process.exit(1);
 }
-var server = new MCPServer({
-  id: "cite42",
-  name: "Cite42",
-  version: "0.1.14",
-  description: "AI market data API: AI search, citations, SEO keywords, trends, and workflows.",
-  tools: {
-    cite42_search: aivSearch,
-    cite42_rankings: aivRankings,
-    cite42_compare: aivCompare,
-    cite42_citations: aivCitations,
-    cite42_sentiment: aivSentiment,
-    cite42_keywords: aivKeywords,
-    cite42_trends: aivTrends,
-    cite42_reddit_trends: aivRedditTrends,
-    cite42_youtube_trends: aivYoutubeTrends,
-    cite42_find_content_opportunities: aivFindContentOpportunities,
-    cite42_analyze_topic_demand: aivAnalyzeTopicDemand,
-    cite42_map_ai_prompts: aivMapAiPrompts,
-    cite42_analyze_competitor_content: aivAnalyzeCompetitorContent,
-    cite42_find_ai_citation_gaps: aivFindAiCitationGaps,
-    cite42_generate_content_brief: aivGenerateContentBrief
-  }
-});
-server.startStdio().catch((error) => {
+buildCite42Server("0.1.16").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.1.14",
+  "version": "0.1.16",
   "description": "Cite42 MCP server: query ChatGPT, Claude, Perplexity, Gemini & Google AI Overviews for brand rankings, AI citations, SEO keyword data, and Reddit/YouTube trends. Works with Claude Code, Claude Desktop, Codex CLI, Cursor, and any MCP client.",
   "license": "MIT",
   "type": "module",
@@ -16,6 +16,8 @@
   "scripts": {
     "build": "tsup && chmod +x dist/stdio.mjs",
     "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
@@ -24,9 +26,11 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@types/node": "^20.19.27",
     "tsup": "^8.0.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
   },
   "publishConfig": {
     "access": "public"