@cite42/mcp 0.1.15 → 0.1.17

package/README.md

@@ -2,10 +2,11 @@
 
 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
+- **Schedule daily or weekly trackers** for rankings, comparisons, citations, and sentiment, then ask your agent for stored run history
 - **Pull SEO data**: keyword search volume, CPC, competition, and Google Trends
 - **Mine Reddit and YouTube** for audience questions, pain points, and rising content
 - **Run full research workflows**: content gaps, topic demand, AI prompt maps, competitor analysis, and content briefs in a single call
@@ -14,14 +15,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 +32,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 +40,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,36 +78,34 @@ 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. 26 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?"*
 - *"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'."*
+- *"Create a weekly Cite42 tracker for our rankings, citations, and sentiment. Show me the estimated credits per run before activating it."*
 
 ### Example: what a session looks like
 
@@ -111,7 +126,15 @@ After restarting, just ask in plain language. Your agent picks the right Cite42
 
 The exact brands and sources change by query and model. A good result should show the tool used, model/source evidence, and a short summary you can act on.
 
-## Endpoint tools
+## Tools
+
+Cite42 exposes 26 MCP tools: 3 free account tools, 9 primitive data tools, 6 research workflows, and 8 tracker tools.
+
+### Account & pricing (free)
+
+- `cite42_credits`: check the connected account's remaining Cite42 credit balance.
+- `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.
 
 ### AI search visibility
 
@@ -123,7 +146,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.
@@ -137,6 +160,17 @@ The exact brands and sources change by query and model. A good result should sho
 - `cite42_find_ai_citation_gaps`: find queries where AI answers cite competitors but not your brand, domain, or URL.
 - `cite42_generate_content_brief`: collect AI answers, citations, keyword demand, and social signals into brief-ready data.
 
+### Trackers
+
+- `cite42_tracker_create`: create a draft daily or weekly tracker from saved rankings, compare, citations, and sentiment inputs. Creating a draft is free and does not schedule calls.
+- `cite42_tracker_update`: replace a tracker's name, cadence, and saved primitive inputs. Updating configuration is free.
+- `cite42_tracker_activate`: activate or resume recurring runs. You must pass the exact `estimatedCostMicroPerRun` from the latest tracker record as `maxCostMicroPerRun`; activation authorizes billed scheduled runs until the tracker is paused.
+- `cite42_tracker_pause`: stop future scheduled runs while preserving configuration and history. Pausing is free.
+- `cite42_tracker_delete`: permanently delete a draft or paused tracker and its run history. Active trackers must be paused first, and deletion is rejected while a run is queued or running. Financial usage records remain available.
+- `cite42_tracker_run`: queue one manual run from the saved primitive inputs. The underlying primitive calls are billed at their normal rates.
+- `cite42_trackers`: list trackers, schedules, statuses, cost estimates, and last/next run times. Reading the list is free.
+- `cite42_tracker_report`: read bounded stored run history with results, changes, status, sampled time, and costs (latest 8 by default, up to 20). Reading stored reports is free.
+
 ## Configuration
 
 - `CITE42_API_KEY`: required. Your API key from [www.cite42.dev/app/keys](https://www.cite42.dev/app/keys).
@@ -150,7 +184,7 @@ npx -y @cite42/mcp --api-key=cite42_live_your_key_here --api-base=https://www.ci
 
 ## Billing
 
-Tool calls consume Cite42 credits from your account. 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).
+Primitive and workflow calls consume Cite42 credits from your account. Tracker management and stored-history reads are free; every scheduled or manual tracker run bills its saved primitive calls at their normal rates. 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).
 
 ## Troubleshooting
 

package/dist/stdio.cjs

@@ -1,9 +1,6 @@
 #!/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;
@@ -40,6 +37,14 @@ function toCite42McpResult(value) {
     }
   };
 }
+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);
@@ -60,6 +65,7 @@ function readFlag(name) {
   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];
   }
@@ -81,9 +87,27 @@ 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 aivPatch(path, body) {
+  return aivWrite("PATCH", path, body);
+}
+async function aivDelete(path) {
   const url = `${getBaseUrl()}${path.startsWith("/") ? path : `/${path}`}`;
   const res = await fetch(url, {
-    method: "POST",
+    method: "DELETE",
+    headers: { Authorization: `Bearer ${getApiKey()}` }
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(errorMessageForMcp(res.status, path, body));
+  }
+  return toCite42McpResult(await res.json());
+}
+async function aivWrite(method, path, body) {
+  const url = `${getBaseUrl()}${path.startsWith("/") ? path : `/${path}`}`;
+  const res = await fetch(url, {
+    method,
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${getApiKey()}`
@@ -96,6 +120,21 @@ async function aivPost(path, body) {
   }
   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");
@@ -105,9 +144,27 @@ 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 use more than 500 Cite42 credits, estimate the credits and ask the user before continuing. When a result contains cite42Credits, use its message if reporting it: it is Cite42 credits, not a model or host balance.";
-var MODEL_PRICING = "Pricing in Cite42 credits: search/citations/rankings/compare are model-specific: Google AI Overview 1, Gemini 2, ChatGPT/Claude 4, Perplexity 5 per selected model. Sentiment: Google AI Overview 3, Gemini 4, ChatGPT/Claude 6, Perplexity 7. Omitting models queries all five AI surfaces. Use the models field when the user names a specific surface or asks to reduce credit use.";
-var DATA_PRICING = "Pricing in Cite42 credits: keywords 15/call, trends 1/call, Reddit trends 5/call, YouTube trends 5/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 mutation(title, options = {}) {
+  return {
+    annotations: {
+      title,
+      readOnlyHint: false,
+      destructiveHint: options.destructiveHint ?? false,
+      openWorldHint: options.openWorldHint ?? false,
+      ...options.idempotentHint === void 0 ? {} : { idempotentHint: options.idempotentHint }
+    }
+  };
+}
 function queryText(description) {
   return import_zod.z.string().trim().min(1).max(QUERY_MAX_CHARS).describe(description);
 }
@@ -119,8 +176,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."),
@@ -130,6 +231,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."),
@@ -140,6 +242,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."),
@@ -150,6 +253,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."),
@@ -161,6 +265,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."),
@@ -171,26 +276,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."),
@@ -201,6 +311,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."),
@@ -212,7 +323,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."),
@@ -225,7 +339,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".'),
@@ -235,7 +352,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."),
@@ -248,7 +368,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."),
@@ -259,7 +382,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."),
@@ -271,7 +397,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."),
@@ -281,6 +410,182 @@ var aivGenerateContentBrief = (0, import_tools.createTool)({
   }),
   execute: async (input) => aivPost("/workflows/content-brief", input)
 });
+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({
+  frequency: import_zod.z.enum(["daily", "weekly"]),
+  timezone: import_zod.z.string().trim().min(1).max(100).refine((timezone) => {
+    try {
+      new Intl.DateTimeFormat("en-US", { timeZone: timezone }).format();
+      return true;
+    } catch {
+      return false;
+    }
+  }, "Timezone must be a valid IANA timezone.").describe("IANA timezone, for example Europe/London or America/New_York."),
+  time: import_zod.z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/).describe("Local run time in 24-hour HH:mm format."),
+  weekday: import_zod.z.number().int().min(0).max(6).optional().describe("Weekly day, where 0 is Sunday and 6 is Saturday.")
+}).superRefine((cadence, context) => {
+  if (cadence.frequency === "weekly" && cadence.weekday === void 0) {
+    context.addIssue({
+      code: "custom",
+      path: ["weekday"],
+      message: "weekday is required for a weekly tracker"
+    });
+  }
+});
+var trackerItemInput = import_zod.z.discriminatedUnion("primitive", [
+  import_zod.z.object({
+    primitive: import_zod.z.literal("rankings"),
+    input: import_zod.z.object({
+      query: queryText("Prompt to measure brand visibility for."),
+      competitors: competitorList,
+      models: modelsInput
+    })
+  }),
+  import_zod.z.object({
+    primitive: import_zod.z.literal("compare"),
+    input: import_zod.z.object({
+      query: queryText("Prompt to compare the brand and competitors for."),
+      brand: shortText("Primary brand to compare."),
+      competitors: import_zod.z.array(shortText("Competitor brand/domain name.")).nonempty().max(10),
+      models: modelsInput
+    })
+  }),
+  import_zod.z.object({
+    primitive: import_zod.z.literal("citations"),
+    input: import_zod.z.object({
+      query: queryText("Prompt whose cited sources should be tracked."),
+      url: import_zod.z.string().trim().max(500).optional(),
+      models: modelsInput
+    })
+  }),
+  import_zod.z.object({
+    primitive: import_zod.z.literal("sentiment"),
+    input: import_zod.z.object({
+      query: queryText("Prompt whose brand sentiment should be tracked."),
+      brand: shortText("Brand whose sentiment should be scored."),
+      models: modelsInput
+    })
+  })
+]);
+var trackerDefinitionFields = {
+  name: import_zod.z.string().trim().min(1).max(100),
+  cadence: trackerCadenceInput,
+  items: import_zod.z.array(trackerItemInput).min(1).max(25).describe("Primitive calls to execute and store on each scheduled run.")
+};
+var TRACKER_BILLING_DESCRIPTION = "Tracker management and stored-report reads are free. Each scheduled or manual run bills the underlying primitive calls at their normal per-model rates; the activation response and tracker record expose the accepted maximum cost per run.";
+var aivTrackerCreate = (0, import_tools.createTool)({
+  id: "cite42_tracker_create",
+  mcp: mutation("Create Cite42 tracker draft"),
+  description: `Create a draft daily or weekly tracker from ordinary rankings, compare, citations, and sentiment primitive inputs. Creation does not start recurring calls. ${TRACKER_BILLING_DESCRIPTION}`,
+  inputSchema: import_zod.z.object(trackerDefinitionFields),
+  execute: async (input) => aivPost("/trackers", input)
+});
+var aivTrackerUpdate = (0, import_tools.createTool)({
+  id: "cite42_tracker_update",
+  mcp: mutation("Update Cite42 tracker", { destructiveHint: true }),
+  description: `Replace a tracker configuration with a validated name, cadence, and primitive item set. An edit returns the tracker to draft so its new recurring cost can be confirmed. ${TRACKER_BILLING_DESCRIPTION}`,
+  inputSchema: import_zod.z.object({ trackerId: trackerIdInput, ...trackerDefinitionFields }),
+  execute: async ({ trackerId, ...input }) => aivPatch(`/trackers/${encodeURIComponent(trackerId)}`, input)
+});
+var aivTrackerActivate = (0, import_tools.createTool)({
+  id: "cite42_tracker_activate",
+  mcp: mutation("Activate Cite42 tracker", {
+    openWorldHint: true,
+    idempotentHint: true
+  }),
+  description: `Activate or resume recurring daily or weekly primitive calls. maxCostMicroPerRun must equal the tracker estimate being accepted; activation authorizes future billed calls until the tracker is paused. ${TRACKER_BILLING_DESCRIPTION}`,
+  inputSchema: import_zod.z.object({
+    trackerId: trackerIdInput,
+    maxCostMicroPerRun: import_zod.z.number().int().nonnegative().describe("Exact estimatedCostMicroPerRun returned by the latest tracker record.")
+  }),
+  execute: async ({ trackerId, maxCostMicroPerRun }) => aivPost(`/trackers/${encodeURIComponent(trackerId)}/activate`, { maxCostMicroPerRun })
+});
+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.",
+  inputSchema: import_zod.z.object({ trackerId: trackerIdInput }),
+  execute: async ({ trackerId }) => aivPost(`/trackers/${encodeURIComponent(trackerId)}/pause`, {})
+});
+var aivTrackerDelete = (0, import_tools.createTool)({
+  id: "cite42_tracker_delete",
+  mcp: mutation("Permanently delete Cite42 tracker", {
+    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.",
+  inputSchema: import_zod.z.object({ trackerId: trackerIdInput }),
+  execute: async ({ trackerId }) => aivDelete(`/trackers/${encodeURIComponent(trackerId)}`)
+});
+var aivTrackerRun = (0, import_tools.createTool)({
+  id: "cite42_tracker_run",
+  mcp: mutation("Run Cite42 tracker now", {
+    openWorldHint: true,
+    idempotentHint: true
+  }),
+  description: `Queue one manual run using the tracker\u2019s saved primitive inputs. A repeated requestToken returns the same logical run. ${TRACKER_BILLING_DESCRIPTION}`,
+  inputSchema: import_zod.z.object({
+    trackerId: trackerIdInput,
+    requestToken: import_zod.z.string().trim().min(1).max(200).describe("Stable caller-generated token used to deduplicate a retried manual run.")
+  }),
+  execute: async ({ trackerId, requestToken }) => aivPost(`/trackers/${encodeURIComponent(trackerId)}/runs`, { requestToken })
+});
+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, primitive configuration, cost estimate, accepted per-run maximum, and next/last run times. Free: costs 0 credits.",
+  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-primitive results, changes from the prior comparable observation, statuses, sampled times, and costs. Free: costs 0 credits.",
+  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.")
+  }),
+  execute: async ({ trackerId, limit }) => aivGet(`/trackers/${encodeURIComponent(trackerId)}/report?limit=${limit}`)
+});
+
+// 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,
+  cite42_tracker_create: aivTrackerCreate,
+  cite42_tracker_update: aivTrackerUpdate,
+  cite42_tracker_activate: aivTrackerActivate,
+  cite42_tracker_pause: aivTrackerPause,
+  cite42_tracker_delete: aivTrackerDelete,
+  cite42_tracker_run: aivTrackerRun,
+  cite42_trackers: aivTrackers,
+  cite42_tracker_report: aivTrackerReport
+};
+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()) {
@@ -289,30 +594,7 @@ if (!resolveApiKey()) {
   );
   process.exit(1);
 }
-var server = new import_mcp.MCPServer({
-  id: "cite42",
-  name: "Cite42",
-  version: "0.1.15",
-  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.17").startStdio().catch((error) => {
   console.error("[@cite42/mcp] Fatal error:", error);
   process.exit(1);
 });

package/dist/stdio.mjs

@@ -1,8 +1,5 @@
 #!/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;
@@ -39,6 +36,14 @@ function toCite42McpResult(value) {
     }
   };
 }
+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);
@@ -59,6 +64,7 @@ function readFlag(name) {
   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];
   }
@@ -80,9 +86,27 @@ 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 aivPatch(path, body) {
+  return aivWrite("PATCH", path, body);
+}
+async function aivDelete(path) {
   const url = `${getBaseUrl()}${path.startsWith("/") ? path : `/${path}`}`;
   const res = await fetch(url, {
-    method: "POST",
+    method: "DELETE",
+    headers: { Authorization: `Bearer ${getApiKey()}` }
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(errorMessageForMcp(res.status, path, body));
+  }
+  return toCite42McpResult(await res.json());
+}
+async function aivWrite(method, path, body) {
+  const url = `${getBaseUrl()}${path.startsWith("/") ? path : `/${path}`}`;
+  const res = await fetch(url, {
+    method,
     headers: {
       "Content-Type": "application/json",
       Authorization: `Bearer ${getApiKey()}`
@@ -95,6 +119,21 @@ async function aivPost(path, body) {
   }
   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";
@@ -104,9 +143,27 @@ 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 use more than 500 Cite42 credits, estimate the credits and ask the user before continuing. When a result contains cite42Credits, use its message if reporting it: it is Cite42 credits, not a model or host balance.";
-var MODEL_PRICING = "Pricing in Cite42 credits: search/citations/rankings/compare are model-specific: Google AI Overview 1, Gemini 2, ChatGPT/Claude 4, Perplexity 5 per selected model. Sentiment: Google AI Overview 3, Gemini 4, ChatGPT/Claude 6, Perplexity 7. Omitting models queries all five AI surfaces. Use the models field when the user names a specific surface or asks to reduce credit use.";
-var DATA_PRICING = "Pricing in Cite42 credits: keywords 15/call, trends 1/call, Reddit trends 5/call, YouTube trends 5/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 mutation(title, options = {}) {
+  return {
+    annotations: {
+      title,
+      readOnlyHint: false,
+      destructiveHint: options.destructiveHint ?? false,
+      openWorldHint: options.openWorldHint ?? false,
+      ...options.idempotentHint === void 0 ? {} : { idempotentHint: options.idempotentHint }
+    }
+  };
+}
 function queryText(description) {
   return z.string().trim().min(1).max(QUERY_MAX_CHARS).describe(description);
 }
@@ -118,8 +175,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."),
@@ -129,6 +230,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."),
@@ -139,6 +241,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."),
@@ -149,6 +252,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."),
@@ -160,6 +264,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."),
@@ -170,26 +275,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."),
@@ -200,6 +310,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."),
@@ -211,7 +322,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."),
@@ -224,7 +338,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".'),
@@ -234,7 +351,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."),
@@ -247,7 +367,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."),
@@ -258,7 +381,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."),
@@ -270,7 +396,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."),
@@ -280,6 +409,182 @@ var aivGenerateContentBrief = createTool({
   }),
   execute: async (input) => aivPost("/workflows/content-brief", input)
 });
+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({
+  frequency: z.enum(["daily", "weekly"]),
+  timezone: z.string().trim().min(1).max(100).refine((timezone) => {
+    try {
+      new Intl.DateTimeFormat("en-US", { timeZone: timezone }).format();
+      return true;
+    } catch {
+      return false;
+    }
+  }, "Timezone must be a valid IANA timezone.").describe("IANA timezone, for example Europe/London or America/New_York."),
+  time: z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/).describe("Local run time in 24-hour HH:mm format."),
+  weekday: z.number().int().min(0).max(6).optional().describe("Weekly day, where 0 is Sunday and 6 is Saturday.")
+}).superRefine((cadence, context) => {
+  if (cadence.frequency === "weekly" && cadence.weekday === void 0) {
+    context.addIssue({
+      code: "custom",
+      path: ["weekday"],
+      message: "weekday is required for a weekly tracker"
+    });
+  }
+});
+var trackerItemInput = z.discriminatedUnion("primitive", [
+  z.object({
+    primitive: z.literal("rankings"),
+    input: z.object({
+      query: queryText("Prompt to measure brand visibility for."),
+      competitors: competitorList,
+      models: modelsInput
+    })
+  }),
+  z.object({
+    primitive: z.literal("compare"),
+    input: z.object({
+      query: queryText("Prompt to compare the brand and competitors for."),
+      brand: shortText("Primary brand to compare."),
+      competitors: z.array(shortText("Competitor brand/domain name.")).nonempty().max(10),
+      models: modelsInput
+    })
+  }),
+  z.object({
+    primitive: z.literal("citations"),
+    input: z.object({
+      query: queryText("Prompt whose cited sources should be tracked."),
+      url: z.string().trim().max(500).optional(),
+      models: modelsInput
+    })
+  }),
+  z.object({
+    primitive: z.literal("sentiment"),
+    input: z.object({
+      query: queryText("Prompt whose brand sentiment should be tracked."),
+      brand: shortText("Brand whose sentiment should be scored."),
+      models: modelsInput
+    })
+  })
+]);
+var trackerDefinitionFields = {
+  name: z.string().trim().min(1).max(100),
+  cadence: trackerCadenceInput,
+  items: z.array(trackerItemInput).min(1).max(25).describe("Primitive calls to execute and store on each scheduled run.")
+};
+var TRACKER_BILLING_DESCRIPTION = "Tracker management and stored-report reads are free. Each scheduled or manual run bills the underlying primitive calls at their normal per-model rates; the activation response and tracker record expose the accepted maximum cost per run.";
+var aivTrackerCreate = createTool({
+  id: "cite42_tracker_create",
+  mcp: mutation("Create Cite42 tracker draft"),
+  description: `Create a draft daily or weekly tracker from ordinary rankings, compare, citations, and sentiment primitive inputs. Creation does not start recurring calls. ${TRACKER_BILLING_DESCRIPTION}`,
+  inputSchema: z.object(trackerDefinitionFields),
+  execute: async (input) => aivPost("/trackers", input)
+});
+var aivTrackerUpdate = createTool({
+  id: "cite42_tracker_update",
+  mcp: mutation("Update Cite42 tracker", { destructiveHint: true }),
+  description: `Replace a tracker configuration with a validated name, cadence, and primitive item set. An edit returns the tracker to draft so its new recurring cost can be confirmed. ${TRACKER_BILLING_DESCRIPTION}`,
+  inputSchema: z.object({ trackerId: trackerIdInput, ...trackerDefinitionFields }),
+  execute: async ({ trackerId, ...input }) => aivPatch(`/trackers/${encodeURIComponent(trackerId)}`, input)
+});
+var aivTrackerActivate = createTool({
+  id: "cite42_tracker_activate",
+  mcp: mutation("Activate Cite42 tracker", {
+    openWorldHint: true,
+    idempotentHint: true
+  }),
+  description: `Activate or resume recurring daily or weekly primitive calls. maxCostMicroPerRun must equal the tracker estimate being accepted; activation authorizes future billed calls until the tracker is paused. ${TRACKER_BILLING_DESCRIPTION}`,
+  inputSchema: z.object({
+    trackerId: trackerIdInput,
+    maxCostMicroPerRun: z.number().int().nonnegative().describe("Exact estimatedCostMicroPerRun returned by the latest tracker record.")
+  }),
+  execute: async ({ trackerId, maxCostMicroPerRun }) => aivPost(`/trackers/${encodeURIComponent(trackerId)}/activate`, { maxCostMicroPerRun })
+});
+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.",
+  inputSchema: z.object({ trackerId: trackerIdInput }),
+  execute: async ({ trackerId }) => aivPost(`/trackers/${encodeURIComponent(trackerId)}/pause`, {})
+});
+var aivTrackerDelete = createTool({
+  id: "cite42_tracker_delete",
+  mcp: mutation("Permanently delete Cite42 tracker", {
+    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.",
+  inputSchema: z.object({ trackerId: trackerIdInput }),
+  execute: async ({ trackerId }) => aivDelete(`/trackers/${encodeURIComponent(trackerId)}`)
+});
+var aivTrackerRun = createTool({
+  id: "cite42_tracker_run",
+  mcp: mutation("Run Cite42 tracker now", {
+    openWorldHint: true,
+    idempotentHint: true
+  }),
+  description: `Queue one manual run using the tracker\u2019s saved primitive inputs. A repeated requestToken returns the same logical run. ${TRACKER_BILLING_DESCRIPTION}`,
+  inputSchema: z.object({
+    trackerId: trackerIdInput,
+    requestToken: z.string().trim().min(1).max(200).describe("Stable caller-generated token used to deduplicate a retried manual run.")
+  }),
+  execute: async ({ trackerId, requestToken }) => aivPost(`/trackers/${encodeURIComponent(trackerId)}/runs`, { requestToken })
+});
+var aivTrackers = createTool({
+  id: "cite42_trackers",
+  mcp: readOnly("List Cite42 trackers", false),
+  description: "List the connected account\u2019s trackers with status, cadence, primitive configuration, cost estimate, accepted per-run maximum, and next/last run times. Free: costs 0 credits.",
+  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-primitive results, changes from the prior comparable observation, statuses, sampled times, and costs. Free: costs 0 credits.",
+  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.")
+  }),
+  execute: async ({ trackerId, limit }) => aivGet(`/trackers/${encodeURIComponent(trackerId)}/report?limit=${limit}`)
+});
+
+// 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,
+  cite42_tracker_create: aivTrackerCreate,
+  cite42_tracker_update: aivTrackerUpdate,
+  cite42_tracker_activate: aivTrackerActivate,
+  cite42_tracker_pause: aivTrackerPause,
+  cite42_tracker_delete: aivTrackerDelete,
+  cite42_tracker_run: aivTrackerRun,
+  cite42_trackers: aivTrackers,
+  cite42_tracker_report: aivTrackerReport
+};
+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()) {
@@ -288,30 +593,7 @@ if (!resolveApiKey()) {
   );
   process.exit(1);
 }
-var server = new MCPServer({
-  id: "cite42",
-  name: "Cite42",
-  version: "0.1.15",
-  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.17").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.15",
+  "version": "0.1.17",
   "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"