@cite42/mcp 0.6.2 → 0.7.0

package/README.md

@@ -149,7 +149,7 @@ Cite42 exposes 29 MCP tools: 4 free account tools (including the compatibility a
 - `cite42_rankings`: measure how brands rank in AI answers, including mention rate, average position, and per-model breakdown.
 - `cite42_compare`: compare one brand against competitors in AI answers.
 - `cite42_sentiment`: score positive, neutral, and negative sentiment for a brand, with supporting phrases.
-- `cite42_recommendations`: request an optional paid next-step report using saved results or supplied evidence, with business context. Insufficient evidence and rule-only fallback are free.
+- `cite42_recommendations`: page-level recommendations. A page URL alone gets a free technical check with suggested buyer questions; with a buyer question it measures citations and compares your page with up to two pages the AI surfaces cited, charged only when it includes verified page-comparison advice (plus the citations check it ran).
 
 ### SEO & trend data
 
@@ -245,11 +245,17 @@ the complete prompt/configuration set, methodology and complete coverage to matc
 Individual prompts remain small samples (at most five surfaces); percentage-point changes are withheld
 below 10 answers per group in each run. This guardrail does not establish statistical significance.
 
-`cite42_recommendations` is a separate, optional paid report. Use exactly one `requestId` returned by
-an earlier call, a user-owned `trackerRunId`, or a structured `evidence` array. Optional `context`
-accepts brand, domain, audience and goal for this request only. Check `cite42_pricing` for the current
-flat report price and obtain the user's agreement before running the add-on. Insufficient evidence
-and rule-only fallback are free.
+`cite42_recommendations` is a separate, optional report. With no saved result, `url` alone runs a free
+technical check (robots.txt crawler access, indexing, rendering) and suggests buyer questions, and `url`
+with `query` first runs a citations check, priced like `cite42_citations`. Otherwise use one `requestId`
+returned by an earlier call, a user-owned `trackerRunId`, or a structured `evidence` array. Pass `url` for the page
+that should answer the prompt, or `context.domain` to look for a match in that site's sitemap, and
+`query` to choose a prompt when the evidence covers several. Optional `context` also accepts brand,
+audience and goal for this request only. The report fetches that page, its robots.txt and up to two
+pages the AI surfaces cited, as returned HTML without JavaScript. Check `cite42_pricing` for the
+current report price and obtain the user's agreement before running the add-on. It is charged only
+when the report includes page-comparison recommendations backed by quotes from the inspected pages;
+everything else is free.
 
 For rankings evidence, provide `context.brand` to identify the tracked brand you want advice for.
 Without it, the measurements remain available but the tool asks which brand to focus on for free;

package/dist/stdio.cjs

@@ -178,7 +178,7 @@ var SHORT_TEXT_MAX_CHARS = 200;
 var TIMEFRAME_MAX_CHARS = 80;
 var MODEL_SELECTION_DESCRIPTION = 'Optional model subset. Omit to query the default surfaces (chatgpt, perplexity, gemini). Pass ["perplexity"] or ["perplexity","claude"] when the user names specific surfaces or wants to reduce cost. The full set is chatgpt, claude, perplexity, gemini, google_ai_overview \u2014 to query all of them, set fullSweep instead of listing them.';
 var FULL_SWEEP_DESCRIPTION = "Query all five AI surfaces instead of the three default ones, adding claude and google_ai_overview. Costs more per call. Use it when the user wants complete cross-model coverage, is comparing surfaces against each other, or asks specifically about Claude or Google AI Overviews. Ignored when models is given.";
-var MCP_USAGE_GUIDANCE = "Covers AI-search, citation, SEO, keyword, trend, and market-research data. If a plan needs more than 20 endpoint calls or may use more than $5 USD, estimate the cost in USD and ask the user before continuing. Quote Cite42 costs and balances in USD using cite42Billing or the USD pricing table. Legacy credit fields are for compatibility only. These funds belong to Cite42, not the host or model provider. AI visibility metrics include counts; quote them with percentages, not as a market-wide score. Optional recommendations are a separate paid call, never automatic. After a visibility result, offer recommendations using its requestId; run only when the user requests advice and knows the additional cost. Free: cite42_balance for the remaining balance, cite42_pricing for exact per-tool prices and cost estimates, cite42_usage for recent calls.";
+var MCP_USAGE_GUIDANCE = "Covers AI-search, citation, SEO, keyword, trend, and market-research data. If a plan needs more than 20 endpoint calls or may use more than $5 USD, estimate the cost in USD and ask the user before continuing. Quote Cite42 costs and balances in USD using cite42Billing or the USD pricing table. Legacy credit fields are for compatibility only. These funds belong to Cite42, not the host or model provider. AI visibility metrics include counts; quote them with percentages, not as a market-wide score. Optional recommendations are a separate paid call, never automatic. Recommendations take the requestId of a visibility result and the page URL, or a page URL alone for a free technical check; they run only when the user requests advice and knows any additional cost. Free: cite42_balance for the remaining balance, cite42_pricing for exact per-tool prices and cost estimates, cite42_usage for recent calls.";
 var MODEL_PRICING = "Pricing is per selected AI surface. Omitting models queries the three default surfaces (chatgpt, perplexity, gemini); fullSweep: true queries all five, adding claude and google_ai_overview at a higher cost. Use the models field when the user names a surface or asks to reduce spending, and call cite42_pricing for exact current rates.";
 var DATA_PRICING = "Data tools have flat per-call prices; call cite42_pricing for exact current rates.";
 var KEYWORDS_PRICING = "Pricing: billed by outcome \u2014 cheapest when the seed has no search volume, more when it has metrics, most with ideas:true. Call cite42_pricing for exact current rates.";
@@ -209,7 +209,7 @@ function shortText(description) {
 var aivRecommendations = (0, import_tools.createTool)({
   id: "cite42_recommendations",
   mcp: readOnly("Recommend AI visibility next steps"),
-  description: "Optional evidence-backed AI visibility recommendations. Flat price from cite42_pricing per completed AI report; insufficient evidence and rule-only fallback are free. Supports rankings, compare, citations and sentiment, including usable workflow steps. No crawling, fresh research, keyword advice or tracker activation. " + MCP_USAGE_GUIDANCE,
+  description: "Page-level AI visibility recommendations. With a saved result (requestId, trackerRunId or evidence) it reports on one measured prompt, charged only when the report includes page-comparison advice backed by quotes from inspected pages. Without one: url alone runs a free technical check of the page (robots.txt crawler access, indexing, rendering) and returns suggested buyer questions; url with query first runs a citations check, priced like cite42_citations, then the report. Prices are in cite42_pricing. Fetches the page, its robots.txt and up to two pages the AI surfaces cited, as returned HTML without JavaScript. No site-wide crawl, keyword advice or tracker activation. " + MCP_USAGE_GUIDANCE,
   inputSchema: import_zod.z.object({
     requestId: import_zod.z.string().trim().min(1).max(128).optional().describe("A requestId from your own successful Cite42 call within the last 30 days."),
     trackerRunId: import_zod.z.string().trim().min(1).max(128).optional().describe("A specific finished run of your own tracker within the last 30 days."),
@@ -219,6 +219,9 @@ var aivRecommendations = (0, import_tools.createTool)({
       result: import_zod.z.record(import_zod.z.string(), import_zod.z.unknown()),
       measuredAt: import_zod.z.string().datetime()
     })).min(1).max(20).optional(),
+    url: import_zod.z.string().trim().url().max(2e3).optional().describe("Your page that should answer the prompt. Without a saved result, url alone runs a free technical check; url with query runs a citations check first."),
+    query: import_zod.z.string().trim().min(1).max(2e3).optional().describe("A buyer question. With a saved result it picks one measured prompt; without one it is the question measured."),
+    models: import_zod.z.array(modelEnum).nonempty().optional().describe("AI surfaces for the citations check that runs without a saved result. Ignored with a saved result."),
     context: import_zod.z.object({
       brand: import_zod.z.string().trim().min(1).max(200).optional(),
       domain: import_zod.z.string().trim().min(1).max(250).optional(),
@@ -226,8 +229,13 @@ var aivRecommendations = (0, import_tools.createTool)({
       goal: import_zod.z.string().trim().min(1).max(400).optional()
     }).optional()
   }).superRefine((input, ctx) => {
-    if ([input.requestId, input.trackerRunId, input.evidence].filter((value) => value !== void 0).length !== 1) {
-      ctx.addIssue({ code: "custom", message: "Provide exactly one of requestId, trackerRunId or evidence." });
+    const sources = [input.requestId, input.trackerRunId, input.evidence].filter((value) => value !== void 0).length;
+    if (sources > 1) ctx.addIssue({ code: "custom", message: "Provide at most one of requestId, trackerRunId or evidence." });
+    if (sources === 0 && !input.url) {
+      ctx.addIssue({ code: "custom", message: "Provide requestId, trackerRunId or evidence, or url for a page without saved results." });
+    }
+    if (sources === 0 && input.query && (input.url?.length ?? 0) > 500) {
+      ctx.addIssue({ code: "custom", message: "url must be at most 500 characters to run a citations check." });
     }
     if (new TextEncoder().encode(JSON.stringify(input)).length > 64 * 1024) {
       ctx.addIssue({ code: "custom", message: "Recommendation input must fit within 64KB." });
@@ -695,7 +703,7 @@ if (!resolveApiKey()) {
   );
   process.exit(1);
 }
-buildCite42Server("0.6.2").startStdio().catch((error) => {
+buildCite42Server("0.7.0").startStdio().catch((error) => {
   console.error("[@cite42/mcp] Fatal error:", error);
   process.exit(1);
 });

package/dist/stdio.mjs

@@ -177,7 +177,7 @@ var SHORT_TEXT_MAX_CHARS = 200;
 var TIMEFRAME_MAX_CHARS = 80;
 var MODEL_SELECTION_DESCRIPTION = 'Optional model subset. Omit to query the default surfaces (chatgpt, perplexity, gemini). Pass ["perplexity"] or ["perplexity","claude"] when the user names specific surfaces or wants to reduce cost. The full set is chatgpt, claude, perplexity, gemini, google_ai_overview \u2014 to query all of them, set fullSweep instead of listing them.';
 var FULL_SWEEP_DESCRIPTION = "Query all five AI surfaces instead of the three default ones, adding claude and google_ai_overview. Costs more per call. Use it when the user wants complete cross-model coverage, is comparing surfaces against each other, or asks specifically about Claude or Google AI Overviews. Ignored when models is given.";
-var MCP_USAGE_GUIDANCE = "Covers AI-search, citation, SEO, keyword, trend, and market-research data. If a plan needs more than 20 endpoint calls or may use more than $5 USD, estimate the cost in USD and ask the user before continuing. Quote Cite42 costs and balances in USD using cite42Billing or the USD pricing table. Legacy credit fields are for compatibility only. These funds belong to Cite42, not the host or model provider. AI visibility metrics include counts; quote them with percentages, not as a market-wide score. Optional recommendations are a separate paid call, never automatic. After a visibility result, offer recommendations using its requestId; run only when the user requests advice and knows the additional cost. Free: cite42_balance for the remaining balance, cite42_pricing for exact per-tool prices and cost estimates, cite42_usage for recent calls.";
+var MCP_USAGE_GUIDANCE = "Covers AI-search, citation, SEO, keyword, trend, and market-research data. If a plan needs more than 20 endpoint calls or may use more than $5 USD, estimate the cost in USD and ask the user before continuing. Quote Cite42 costs and balances in USD using cite42Billing or the USD pricing table. Legacy credit fields are for compatibility only. These funds belong to Cite42, not the host or model provider. AI visibility metrics include counts; quote them with percentages, not as a market-wide score. Optional recommendations are a separate paid call, never automatic. Recommendations take the requestId of a visibility result and the page URL, or a page URL alone for a free technical check; they run only when the user requests advice and knows any additional cost. Free: cite42_balance for the remaining balance, cite42_pricing for exact per-tool prices and cost estimates, cite42_usage for recent calls.";
 var MODEL_PRICING = "Pricing is per selected AI surface. Omitting models queries the three default surfaces (chatgpt, perplexity, gemini); fullSweep: true queries all five, adding claude and google_ai_overview at a higher cost. Use the models field when the user names a surface or asks to reduce spending, and call cite42_pricing for exact current rates.";
 var DATA_PRICING = "Data tools have flat per-call prices; call cite42_pricing for exact current rates.";
 var KEYWORDS_PRICING = "Pricing: billed by outcome \u2014 cheapest when the seed has no search volume, more when it has metrics, most with ideas:true. Call cite42_pricing for exact current rates.";
@@ -208,7 +208,7 @@ function shortText(description) {
 var aivRecommendations = createTool({
   id: "cite42_recommendations",
   mcp: readOnly("Recommend AI visibility next steps"),
-  description: "Optional evidence-backed AI visibility recommendations. Flat price from cite42_pricing per completed AI report; insufficient evidence and rule-only fallback are free. Supports rankings, compare, citations and sentiment, including usable workflow steps. No crawling, fresh research, keyword advice or tracker activation. " + MCP_USAGE_GUIDANCE,
+  description: "Page-level AI visibility recommendations. With a saved result (requestId, trackerRunId or evidence) it reports on one measured prompt, charged only when the report includes page-comparison advice backed by quotes from inspected pages. Without one: url alone runs a free technical check of the page (robots.txt crawler access, indexing, rendering) and returns suggested buyer questions; url with query first runs a citations check, priced like cite42_citations, then the report. Prices are in cite42_pricing. Fetches the page, its robots.txt and up to two pages the AI surfaces cited, as returned HTML without JavaScript. No site-wide crawl, keyword advice or tracker activation. " + MCP_USAGE_GUIDANCE,
   inputSchema: z.object({
     requestId: z.string().trim().min(1).max(128).optional().describe("A requestId from your own successful Cite42 call within the last 30 days."),
     trackerRunId: z.string().trim().min(1).max(128).optional().describe("A specific finished run of your own tracker within the last 30 days."),
@@ -218,6 +218,9 @@ var aivRecommendations = createTool({
       result: z.record(z.string(), z.unknown()),
       measuredAt: z.string().datetime()
     })).min(1).max(20).optional(),
+    url: z.string().trim().url().max(2e3).optional().describe("Your page that should answer the prompt. Without a saved result, url alone runs a free technical check; url with query runs a citations check first."),
+    query: z.string().trim().min(1).max(2e3).optional().describe("A buyer question. With a saved result it picks one measured prompt; without one it is the question measured."),
+    models: z.array(modelEnum).nonempty().optional().describe("AI surfaces for the citations check that runs without a saved result. Ignored with a saved result."),
     context: z.object({
       brand: z.string().trim().min(1).max(200).optional(),
       domain: z.string().trim().min(1).max(250).optional(),
@@ -225,8 +228,13 @@ var aivRecommendations = createTool({
       goal: z.string().trim().min(1).max(400).optional()
     }).optional()
   }).superRefine((input, ctx) => {
-    if ([input.requestId, input.trackerRunId, input.evidence].filter((value) => value !== void 0).length !== 1) {
-      ctx.addIssue({ code: "custom", message: "Provide exactly one of requestId, trackerRunId or evidence." });
+    const sources = [input.requestId, input.trackerRunId, input.evidence].filter((value) => value !== void 0).length;
+    if (sources > 1) ctx.addIssue({ code: "custom", message: "Provide at most one of requestId, trackerRunId or evidence." });
+    if (sources === 0 && !input.url) {
+      ctx.addIssue({ code: "custom", message: "Provide requestId, trackerRunId or evidence, or url for a page without saved results." });
+    }
+    if (sources === 0 && input.query && (input.url?.length ?? 0) > 500) {
+      ctx.addIssue({ code: "custom", message: "url must be at most 500 characters to run a citations check." });
     }
     if (new TextEncoder().encode(JSON.stringify(input)).length > 64 * 1024) {
       ctx.addIssue({ code: "custom", message: "Recommendation input must fit within 64KB." });
@@ -694,7 +702,7 @@ if (!resolveApiKey()) {
   );
   process.exit(1);
 }
-buildCite42Server("0.6.2").startStdio().catch((error) => {
+buildCite42Server("0.7.0").startStdio().catch((error) => {
   console.error("[@cite42/mcp] Fatal error:", error);
   process.exit(1);
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cite42/mcp",
   "mcpName": "dev.cite42/mcp",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Cite42 MCP server: AI visibility and SEO data for AI agents. See how the AI models behind ChatGPT, Claude, Perplexity and Gemini, plus Google AI Overviews, mention your brand and which sources they cite, with SEO keyword data, Google, Reddit and YouTube trends, and weekly or monthly trackers that watch a list of prompts over time. Works with Claude Code, Claude Desktop, Codex CLI, Cursor, and any MCP client.",
   "license": "MIT",
   "type": "module",