@cite42/mcp 0.1.17 → 0.3.0

package/README.md

@@ -6,7 +6,7 @@ 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
+- **Schedule daily or weekly trackers**: one measurement — rankings, comparisons, citations, or sentiment — over a list of prompts, with email when something changes, 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
@@ -105,7 +105,7 @@ After connecting or restarting, just ask in plain language. Your agent picks the
 - *"Get search volume, CPC, and related keywords for 'ai seo tools'."*
 - *"What are people on Reddit complaining about regarding email marketing tools?"*
 - *"Run a content brief for the topic 'ai website builder'."*
-- *"Create a weekly Cite42 tracker for our rankings, citations, and sentiment. Show me the estimated credits per run before activating it."*
+- *"Map the prompts worth tracking for our category, then create a weekly Cite42 rankings tracker for the best five. Show me the estimated credits per run before activating it."*
 
 ### Example: what a session looks like
 
@@ -115,16 +115,16 @@ After connecting or restarting, just ask in plain language. Your agent picks the
 
 **Your agent calls** `cite42_citations` **and answers something like:**
 
-> Across ChatGPT, Claude, Perplexity, and Gemini, the most-cited sources are:
+> Across ChatGPT, Perplexity, and Gemini, the most-cited sources are:
 >
-> 1. **freshbooks.com** (cited by 4/5 models)
-> 2. **wave.com** (cited by 3/5 models)
-> 3. **zoho.com/invoice** (cited by 3/5 models)
-> 4. **bonsai.com** (cited by 2/5 models)
+> 1. **freshbooks.com** (cited by 3/3 models)
+> 2. **wave.com** (cited by 2/3 models)
+> 3. **zoho.com/invoice** (cited by 2/3 models)
+> 4. **bonsai.com** (cited by 1/3 models)
 >
 > Your domain wasn't cited by any model. FreshBooks is cited mainly via comparison/"best of" listicles. A citation-gap analysis (`cite42_find_ai_citation_gaps`) can show which queries you're missing from.
 
-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.
+That is the three default surfaces; ask for `fullSweep` to add Claude and Google AI Overviews. 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.
 
 ## Tools
 
@@ -155,19 +155,19 @@ Cite42 exposes 26 MCP tools: 3 free account tools, 9 primitive data tools, 6 res
 
 - `cite42_find_content_opportunities`: find content gaps across AI search, keywords, trends, Reddit, YouTube, and citations.
 - `cite42_analyze_topic_demand`: combine keyword data, trends, AI answers, and audience conversations for a topic.
-- `cite42_map_ai_prompts`: discover and cluster buyer prompts worth tracking in AI search.
+- `cite42_map_ai_prompts`: discover and cluster buyer prompts worth tracking in AI search. Its prompts are what `cite42_tracker_create` takes, so the two chain naturally.
 - `cite42_analyze_competitor_content`: analyze AI rankings, comparisons, citations, and topic coverage for competitors.
 - `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_create`: create a draft daily or weekly tracker — one measurement applied to a list of prompts. No prompt list yet? Run `cite42_map_ai_prompts` first. Creating a draft is free and does not schedule calls.
+- `cite42_tracker_update`: replace the whole tracker definition — name, cadence, measurement, prompts and configuration. A tracker read returns the same shape, so read it, change what you need, and send it back. Updating 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. The response carries the balance, the cost per run and `runsDryAt` — the date the balance stops covering your active trackers — and activation is refused when the balance cannot cover even the next run.
 - `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_tracker_run`: queue one manual run of every saved prompt. Each prompt is billed as its own primitive call at the normal rate.
 - `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.
 
@@ -184,7 +184,7 @@ npx -y @cite42/mcp --api-key=cite42_live_your_key_here --api-base=https://www.ci
 
 ## Billing
 
-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).
+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 one call per saved prompt at the normal rate. Activating or resuming a tracker requires explicit confirmation of the current maximum credits per run and authorizes recurring billed calls until you pause it. Calls fail with a clear error if the API key is missing or credits run out. See [www.cite42.dev/pricing](https://www.cite42.dev/pricing).
 
 ## Troubleshooting
 

package/dist/stdio.cjs

@@ -143,9 +143,10 @@ var modelEnum = import_zod.z.enum(["chatgpt", "claude", "perplexity", "gemini",
 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 MODEL_SELECTION_DESCRIPTION = 'Optional model subset. Omit to query the default surfaces (chatgpt, perplexity, gemini). Pass ["perplexity"] or ["perplexity","claude"] when the user names specific surfaces or wants to reduce cost. The full set is chatgpt, claude, perplexity, gemini, google_ai_overview \u2014 to query all of them, set fullSweep instead of listing them.';
+var FULL_SWEEP_DESCRIPTION = "Query all five AI surfaces instead of the three default ones, adding claude and google_ai_overview. Costs more per call. Use it when the user wants complete cross-model coverage, is comparing surfaces against each other, or asks specifically about Claude or Google AI Overviews. Ignored when models is given.";
 var MCP_USAGE_GUIDANCE = "Covers AI-search, citation, SEO, keyword, trend, and market-research data. If a plan needs more than 20 endpoint calls or may use more than 500 Cite42 credits, estimate the credits and ask the user before continuing. When a result contains cite42Credits, that figure is Cite42 credits, not a model or host balance. Free (0 credits): cite42_credits for the remaining balance, cite42_pricing for exact per-tool prices and cost estimates, cite42_usage for recent calls.";
-var MODEL_PRICING = "Pricing is per selected AI surface; omitting models queries 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 MODEL_PRICING = "Pricing is per selected AI surface. Omitting models queries the three default surfaces (chatgpt, perplexity, gemini); fullSweep: true queries all five, adding claude and google_ai_overview for more credits. Use the models field when the user names a surface or asks to reduce credit use, and call cite42_pricing for exact current rates.";
 var 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) {
@@ -175,6 +176,7 @@ function optionalShortText(description) {
   return import_zod.z.string().trim().min(1).max(SHORT_TEXT_MAX_CHARS).optional().describe(description);
 }
 var modelsInput = import_zod.z.array(modelEnum).nonempty().optional().describe(MODEL_SELECTION_DESCRIPTION);
+var fullSweepInput = import_zod.z.boolean().optional().describe(FULL_SWEEP_DESCRIPTION);
 var competitorList = import_zod.z.array(shortText("Competitor brand/domain name.")).nonempty().max(20);
 var aivCredits = (0, import_tools.createTool)({
   id: "cite42_credits",
@@ -225,7 +227,8 @@ var aivSearch = (0, import_tools.createTool)({
   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."),
-    models: modelsInput
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input) => aivPost("/search", input)
 });
@@ -236,7 +239,8 @@ var aivCitations = (0, import_tools.createTool)({
   inputSchema: import_zod.z.object({
     query: queryText("The concise query to look up cited sources for."),
     url: import_zod.z.string().trim().max(500).optional().describe("Optional URL to check whether it was cited."),
-    models: modelsInput
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input) => aivPost("/citations", input)
 });
@@ -247,7 +251,8 @@ var aivRankings = (0, import_tools.createTool)({
   inputSchema: import_zod.z.object({
     query: queryText("The concise query to measure brand/competitor visibility on."),
     competitors: competitorList.describe("Brand or domain names to track within the AI-generated answers."),
-    models: modelsInput
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input) => aivPost("/rankings", input)
 });
@@ -259,7 +264,8 @@ var aivCompare = (0, import_tools.createTool)({
     query: queryText("The concise query to compare the brand and competitors on."),
     brand: shortText("Your brand, ranked alongside the competitors."),
     competitors: import_zod.z.array(shortText("Competitor brand/domain name.")).nonempty().max(10).describe("Competitor brand/domain names (up to 10) to rank against your brand."),
-    models: modelsInput
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input) => aivPost("/compare", input)
 });
@@ -270,7 +276,8 @@ var aivSentiment = (0, import_tools.createTool)({
   inputSchema: import_zod.z.object({
     query: queryText("The concise query whose answers are scored for brand sentiment."),
     brand: shortText("The brand to score sentiment for in each model answer."),
-    models: modelsInput
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input) => aivPost("/sentiment", input)
 });
@@ -354,7 +361,7 @@ var aivMapAiPrompts = (0, import_tools.createTool)({
   id: "cite42_map_ai_prompts",
   mcp: readOnly("Map buyer prompts for AI search"),
   description: workflowDescription(
-    "Run the AI-prompt-map workflow: discover and cluster buyer prompts worth tracking from AI search, SEO demand, trends, citations, Reddit, and YouTube data."
+    "Run the AI-prompt-map workflow: discover and cluster buyer prompts worth tracking from AI search, SEO demand, trends, citations, Reddit, and YouTube data. The prompts it returns are exactly what cite42_tracker_create takes, so offer to start tracking the best of them once the user has seen the map."
   ),
   inputSchema: import_zod.z.object({
     topic: queryText("Market, product category, buyer problem, or audience to map prompts for."),
@@ -391,7 +398,8 @@ var aivFindAiCitationGaps = (0, import_tools.createTool)({
     brand: shortText("Brand or domain that should earn citations."),
     url: import_zod.z.string().trim().max(500).optional().describe("Optional exact URL to check for citations."),
     competitors: competitorList.optional().describe("Competitor brands/domains."),
-    models: modelsInput
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input) => aivPost("/workflows/ai-citation-gaps", input)
 });
@@ -432,58 +440,38 @@ var trackerCadenceInput = import_zod.z.object({
     });
   }
 });
-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 trackerPrimitiveInput = import_zod.z.enum(["rankings", "compare", "citations", "sentiment"]).describe(
+  "What to measure on every prompt: rankings (which brands get named), compare (the brand against named competitors), citations (which sources are cited), or sentiment (how one brand is described). One measurement per tracker."
+);
+var trackerPromptsInput = import_zod.z.array(queryText("A prompt to run on every scheduled run.")).min(1).max(25).describe(
+  "Prompts to track, up to 25. Each is billed as its own call on every run. Keep the wording stable so runs stay comparable, avoid dates, and do not repeat a prompt."
+);
 var trackerDefinitionFields = {
-  name: import_zod.z.string().trim().min(1).max(100),
+  name: import_zod.z.string().trim().min(1).max(100).describe("Human-readable tracker name."),
   cadence: trackerCadenceInput,
-  items: import_zod.z.array(trackerItemInput).min(1).max(25).describe("Primitive calls to execute and store on each scheduled run.")
+  primitive: trackerPrimitiveInput,
+  prompts: trackerPromptsInput,
+  brand: import_zod.z.string().trim().min(1).max(SHORT_TEXT_MAX_CHARS).nullish().describe("Required for compare and sentiment. Not used by rankings or citations."),
+  competitors: import_zod.z.array(shortText("Brand or domain name.")).max(20).nullish().describe(
+    "Required for rankings (the brands to track, including your own) and compare (the rivals to rank against, up to 10). Not used by citations or sentiment."
+  ),
+  url: import_zod.z.string().trim().min(1).max(500).nullish().describe("Citations only: a URL to report on as cited or not cited."),
+  models: import_zod.z.array(modelEnum).nonempty().nullish().describe(
+    "AI surfaces to query for every prompt. Omit for the three defaults (chatgpt, perplexity, gemini), or list surfaces explicitly \u2014 including all five \u2014 to fix the recurring cost."
+  )
 };
-var TRACKER_BILLING_DESCRIPTION = "Tracker management and stored-report reads are free. Each scheduled or manual run bills the underlying primitive calls at their normal per-model rates; the activation response and tracker record expose the accepted maximum cost per run.";
+var TRACKER_BILLING_DESCRIPTION = "Tracker management and stored-report reads are free. Each scheduled or manual run bills one call per prompt at the normal per-model rates; the activation response and tracker record expose the accepted maximum cost per run.";
 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}`,
+  description: "Create a draft daily or weekly tracker: one measurement \u2014 rankings, compare, citations, or sentiment \u2014 applied to a list of prompts, with the brand, competitors and AI surfaces set once for all of them. When the user has no prompt list yet, run cite42_map_ai_prompts first and track the prompts it recommends. Creation does not start recurring calls. " + TRACKER_BILLING_DESCRIPTION,
   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}`,
+  description: `Replace a tracker definition: name, cadence, measurement, prompts and configuration. Send the complete definition, not a partial patch \u2014 a tracker read returns this exact shape, so read it, change what you need, and send it back. 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)
 });
@@ -493,7 +481,7 @@ var aivTrackerActivate = (0, import_tools.createTool)({
     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}`,
+  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. The response carries a billing block with the balance, the cost per run, and runsDryAt \u2014 the date the balance stops covering the account's active trackers \u2014 so relay it. Activation is refused when the balance cannot cover even the next run; tell the user to top up at cite42.dev/app/billing. ${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.")
@@ -594,7 +582,7 @@ if (!resolveApiKey()) {
   );
   process.exit(1);
 }
-buildCite42Server("0.1.17").startStdio().catch((error) => {
+buildCite42Server("0.3.0").startStdio().catch((error) => {
   console.error("[@cite42/mcp] Fatal error:", error);
   process.exit(1);
 });

package/dist/stdio.mjs

@@ -142,9 +142,10 @@ var modelEnum = z.enum(["chatgpt", "claude", "perplexity", "gemini", "google_ai_
 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 MODEL_SELECTION_DESCRIPTION = 'Optional model subset. Omit to query the default surfaces (chatgpt, perplexity, gemini). Pass ["perplexity"] or ["perplexity","claude"] when the user names specific surfaces or wants to reduce cost. The full set is chatgpt, claude, perplexity, gemini, google_ai_overview \u2014 to query all of them, set fullSweep instead of listing them.';
+var FULL_SWEEP_DESCRIPTION = "Query all five AI surfaces instead of the three default ones, adding claude and google_ai_overview. Costs more per call. Use it when the user wants complete cross-model coverage, is comparing surfaces against each other, or asks specifically about Claude or Google AI Overviews. Ignored when models is given.";
 var MCP_USAGE_GUIDANCE = "Covers AI-search, citation, SEO, keyword, trend, and market-research data. If a plan needs more than 20 endpoint calls or may use more than 500 Cite42 credits, estimate the credits and ask the user before continuing. When a result contains cite42Credits, that figure is Cite42 credits, not a model or host balance. Free (0 credits): cite42_credits for the remaining balance, cite42_pricing for exact per-tool prices and cost estimates, cite42_usage for recent calls.";
-var MODEL_PRICING = "Pricing is per selected AI surface; omitting models queries 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 MODEL_PRICING = "Pricing is per selected AI surface. Omitting models queries the three default surfaces (chatgpt, perplexity, gemini); fullSweep: true queries all five, adding claude and google_ai_overview for more credits. Use the models field when the user names a surface or asks to reduce credit use, and call cite42_pricing for exact current rates.";
 var 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) {
@@ -174,6 +175,7 @@ function optionalShortText(description) {
   return z.string().trim().min(1).max(SHORT_TEXT_MAX_CHARS).optional().describe(description);
 }
 var modelsInput = z.array(modelEnum).nonempty().optional().describe(MODEL_SELECTION_DESCRIPTION);
+var fullSweepInput = z.boolean().optional().describe(FULL_SWEEP_DESCRIPTION);
 var competitorList = z.array(shortText("Competitor brand/domain name.")).nonempty().max(20);
 var aivCredits = createTool({
   id: "cite42_credits",
@@ -224,7 +226,8 @@ var aivSearch = createTool({
   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."),
-    models: modelsInput
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input) => aivPost("/search", input)
 });
@@ -235,7 +238,8 @@ var aivCitations = createTool({
   inputSchema: z.object({
     query: queryText("The concise query to look up cited sources for."),
     url: z.string().trim().max(500).optional().describe("Optional URL to check whether it was cited."),
-    models: modelsInput
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input) => aivPost("/citations", input)
 });
@@ -246,7 +250,8 @@ var aivRankings = createTool({
   inputSchema: z.object({
     query: queryText("The concise query to measure brand/competitor visibility on."),
     competitors: competitorList.describe("Brand or domain names to track within the AI-generated answers."),
-    models: modelsInput
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input) => aivPost("/rankings", input)
 });
@@ -258,7 +263,8 @@ var aivCompare = createTool({
     query: queryText("The concise query to compare the brand and competitors on."),
     brand: shortText("Your brand, ranked alongside the competitors."),
     competitors: z.array(shortText("Competitor brand/domain name.")).nonempty().max(10).describe("Competitor brand/domain names (up to 10) to rank against your brand."),
-    models: modelsInput
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input) => aivPost("/compare", input)
 });
@@ -269,7 +275,8 @@ var aivSentiment = createTool({
   inputSchema: z.object({
     query: queryText("The concise query whose answers are scored for brand sentiment."),
     brand: shortText("The brand to score sentiment for in each model answer."),
-    models: modelsInput
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input) => aivPost("/sentiment", input)
 });
@@ -353,7 +360,7 @@ var aivMapAiPrompts = createTool({
   id: "cite42_map_ai_prompts",
   mcp: readOnly("Map buyer prompts for AI search"),
   description: workflowDescription(
-    "Run the AI-prompt-map workflow: discover and cluster buyer prompts worth tracking from AI search, SEO demand, trends, citations, Reddit, and YouTube data."
+    "Run the AI-prompt-map workflow: discover and cluster buyer prompts worth tracking from AI search, SEO demand, trends, citations, Reddit, and YouTube data. The prompts it returns are exactly what cite42_tracker_create takes, so offer to start tracking the best of them once the user has seen the map."
   ),
   inputSchema: z.object({
     topic: queryText("Market, product category, buyer problem, or audience to map prompts for."),
@@ -390,7 +397,8 @@ var aivFindAiCitationGaps = createTool({
     brand: shortText("Brand or domain that should earn citations."),
     url: z.string().trim().max(500).optional().describe("Optional exact URL to check for citations."),
     competitors: competitorList.optional().describe("Competitor brands/domains."),
-    models: modelsInput
+    models: modelsInput,
+    fullSweep: fullSweepInput
   }),
   execute: async (input) => aivPost("/workflows/ai-citation-gaps", input)
 });
@@ -431,58 +439,38 @@ var trackerCadenceInput = z.object({
     });
   }
 });
-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 trackerPrimitiveInput = z.enum(["rankings", "compare", "citations", "sentiment"]).describe(
+  "What to measure on every prompt: rankings (which brands get named), compare (the brand against named competitors), citations (which sources are cited), or sentiment (how one brand is described). One measurement per tracker."
+);
+var trackerPromptsInput = z.array(queryText("A prompt to run on every scheduled run.")).min(1).max(25).describe(
+  "Prompts to track, up to 25. Each is billed as its own call on every run. Keep the wording stable so runs stay comparable, avoid dates, and do not repeat a prompt."
+);
 var trackerDefinitionFields = {
-  name: z.string().trim().min(1).max(100),
+  name: z.string().trim().min(1).max(100).describe("Human-readable tracker name."),
   cadence: trackerCadenceInput,
-  items: z.array(trackerItemInput).min(1).max(25).describe("Primitive calls to execute and store on each scheduled run.")
+  primitive: trackerPrimitiveInput,
+  prompts: trackerPromptsInput,
+  brand: z.string().trim().min(1).max(SHORT_TEXT_MAX_CHARS).nullish().describe("Required for compare and sentiment. Not used by rankings or citations."),
+  competitors: z.array(shortText("Brand or domain name.")).max(20).nullish().describe(
+    "Required for rankings (the brands to track, including your own) and compare (the rivals to rank against, up to 10). Not used by citations or sentiment."
+  ),
+  url: z.string().trim().min(1).max(500).nullish().describe("Citations only: a URL to report on as cited or not cited."),
+  models: z.array(modelEnum).nonempty().nullish().describe(
+    "AI surfaces to query for every prompt. Omit for the three defaults (chatgpt, perplexity, gemini), or list surfaces explicitly \u2014 including all five \u2014 to fix the recurring cost."
+  )
 };
-var TRACKER_BILLING_DESCRIPTION = "Tracker management and stored-report reads are free. Each scheduled or manual run bills the underlying primitive calls at their normal per-model rates; the activation response and tracker record expose the accepted maximum cost per run.";
+var TRACKER_BILLING_DESCRIPTION = "Tracker management and stored-report reads are free. Each scheduled or manual run bills one call per prompt at the normal per-model rates; the activation response and tracker record expose the accepted maximum cost per run.";
 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}`,
+  description: "Create a draft daily or weekly tracker: one measurement \u2014 rankings, compare, citations, or sentiment \u2014 applied to a list of prompts, with the brand, competitors and AI surfaces set once for all of them. When the user has no prompt list yet, run cite42_map_ai_prompts first and track the prompts it recommends. Creation does not start recurring calls. " + TRACKER_BILLING_DESCRIPTION,
   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}`,
+  description: `Replace a tracker definition: name, cadence, measurement, prompts and configuration. Send the complete definition, not a partial patch \u2014 a tracker read returns this exact shape, so read it, change what you need, and send it back. 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)
 });
@@ -492,7 +480,7 @@ var aivTrackerActivate = createTool({
     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}`,
+  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. The response carries a billing block with the balance, the cost per run, and runsDryAt \u2014 the date the balance stops covering the account's active trackers \u2014 so relay it. Activation is refused when the balance cannot cover even the next run; tell the user to top up at cite42.dev/app/billing. ${TRACKER_BILLING_DESCRIPTION}`,
   inputSchema: z.object({
     trackerId: trackerIdInput,
     maxCostMicroPerRun: z.number().int().nonnegative().describe("Exact estimatedCostMicroPerRun returned by the latest tracker record.")
@@ -593,7 +581,7 @@ if (!resolveApiKey()) {
   );
   process.exit(1);
 }
-buildCite42Server("0.1.17").startStdio().catch((error) => {
+buildCite42Server("0.3.0").startStdio().catch((error) => {
   console.error("[@cite42/mcp] Fatal error:", error);
   process.exit(1);
 });

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cite42/mcp",
   "mcpName": "dev.cite42/mcp",
-  "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.",
+  "version": "0.3.0",
+  "description": "Cite42 MCP server: query ChatGPT, Claude, Perplexity, Gemini & Google AI Overviews for brand rankings, AI citations, SEO keyword data, and Reddit/YouTube trends, and schedule daily or weekly trackers that watch a list of prompts over time. Works with Claude Code, Claude Desktop, Codex CLI, Cursor, and any MCP client.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -60,7 +60,10 @@
     "claude-code",
     "cursor",
     "reddit",
-    "youtube"
+    "youtube",
+    "ai-visibility-tracking",
+    "rank-tracking",
+    "scheduled-monitoring"
   ],
   "engines": {
     "node": ">=18"