@recomention/mcp 0.1.1 → 0.1.3

package/README.md

@@ -73,11 +73,11 @@ env = { RECOMENTION_API_KEY = "<key>", RECOMENTION_BASE_URL = "https://api.recom
 | Tool | Cost | |
 | --- | --- | --- |
 | `recomention_rankings_list` | free | Public AI rankings. No key needed. |
-| `recomention_rankings_get(slug)` | free | One ranking with every answer it counted. |
+| `recomention_rankings_get(slug, question?, engine?)` | free | One ranking without answer texts: its questions numbered from 1 with each engine's usable answers, and every product named, as "named in n of m usable answers". Pass `question` (1-based) for that question's answers and citations, and `engine` with it for one engine's answers. |
 | `recomention_suggest_prompts({domain, category, description})` | free | Buyer questions from fixed templates. No model call. Never names the product. |
 | `recomention_report_start({domain, description, category, plan, prompts?, engines?, funding})` | **spends** | `funding: "credits"` uses one agency credit (plan `FULL`); `funding: "byok"` runs on your provider keys and needs an active Agent plan; a refusal names the plan limit it hit. |
 | `recomention_report_status(slug)` | free | PENDING / RUNNING / COMPLETE / FAILED, with progress. |
-| `recomention_report_get(slug)` | free | The full report JSON. |
+| `recomention_report_get(slug, question?)` | free | The report without answer texts, with per-question counts numbered from 1. Pass `question` (1-based: 1 is the first) for that question's answers and citations. `0` is deprecated and also means the first. |
 | `recomention_distribution_kit(slug)` | free | Markdown files built from a finished report: product, competitors, AI visibility, where to get mentioned, channel plan. |
 | `recomention_reports_list` | free | Your reports, newest first. |
 

package/dist/ranking.js

@@ -0,0 +1,96 @@
+/**
+ * What the MCP ranking tool returns. The public ranking JSON carries every answer's
+ * text, products and citations for every prompt (about 270 KB for ai-search-engine,
+ * over 300 KB for the largest), more than an agent's tool result can hold, so the tool
+ * gave agents nothing usable. By default it now returns the ranking without the
+ * answers: its prompts numbered from 1 with each engine's usable answers, and the
+ * top products as "named in n of m usable answers", overall and by engine. One
+ * prompt's answers come back when the agent asks for that question by its number,
+ * optionally narrowed to one engine's answers (a whole prompt can run to 65 KB).
+ *
+ * Questions are numbered from 1 in the order the ranking lists its prompts, the same
+ * numbering the ranking's answers use (`prompt: 1` is the first), and the same as
+ * recomention_report_get.
+ *
+ * Counting follows the ranking's honesty rules: only answered runs are in a
+ * denominator. Failed calls, runs that were never made and searches with no AI
+ * Overview are not answers that named nobody, so they are reported apart.
+ * Pure; operates on the public API's JSON, so the API stays unchanged.
+ * Kept in step with core's application/mcp-ranking.ts (the hosted server); this package ships without core.
+ */
+import { QuestionNotFoundError } from "./report.js";
+/** Products shown with engine counts by default; the rest, mostly named once or twice, by name and count. */
+export const TOP_BRANDS = 30;
+const n = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+function engineRow(c) {
+    return {
+        answered: n(c.answered), failed: n(c.failed), notRun: n(c.notRun),
+        ...(n(c.noAnswer) ? { noAnswer: n(c.noAnswer) } : {}),
+        ...(typeof c.skipped === "string" ? { skipped: c.skipped } : {}),
+    };
+}
+function promptSummary(p, number) {
+    const coverage = Array.isArray(p.coverage) ? p.coverage : [];
+    return {
+        question: number, text: p.text,
+        usableAnswers: coverage.reduce((sum, c) => sum + n(c.answered), 0),
+        engines: Object.fromEntries(coverage.map((c) => [String(c.engine), engineRow(c)])),
+    };
+}
+export function compactRanking(body, question, engine) {
+    const ranking = body?.ranking;
+    if (!ranking || !Array.isArray(ranking.prompts) || !Array.isArray(ranking.answers))
+        return body;
+    const { prompts, answers } = ranking;
+    const head = { slug: ranking.slug, category: ranking.category, month: ranking.month, checkedAt: ranking.checkedAt, engines: ranking.engines, url: ranking.url };
+    if (engine !== undefined && question === undefined)
+        throw new QuestionNotFoundError("engine narrows one question's answers: pass question as well.");
+    if (question !== undefined) {
+        const match = Number.isInteger(question) && question >= 1 ? prompts[question - 1] : undefined;
+        if (!match)
+            throw new QuestionNotFoundError(prompts.length ? `No question ${question}; questions are numbered 1 to ${prompts.length}.` : `No question ${question}; this ranking has no questions.`);
+        const coverage = (match.coverage ?? []).filter((c) => engine === undefined || c.engine === engine);
+        if (engine !== undefined && !coverage.length)
+            throw new QuestionNotFoundError(`${engine} is not one of this ranking's engines: ${(match.coverage ?? []).map((c) => String(c.engine)).join(", ")}.`);
+        const { engines: _byEngine, ...summary } = promptSummary({ ...match, coverage }, question);
+        return {
+            ranking: {
+                ...head,
+                question: {
+                    ...summary,
+                    ...(engine !== undefined ? { engine } : {}),
+                    coverage: coverage.map((c) => ({ engine: c.engine, ...engineRow(c) })),
+                    answers: answers.filter((a) => a.prompt === question && (engine === undefined || a.engine === engine)).map(({ prompt: _prompt, ...a }) => a),
+                },
+            },
+        };
+    }
+    // An engine's usable answers across every prompt: the denominator for its count of each product.
+    const usableBy = new Map();
+    for (const p of prompts)
+        for (const c of p.coverage ?? [])
+            usableBy.set(String(c.engine), (usableBy.get(String(c.engine)) ?? 0) + n(c.answered));
+    const usable = [...usableBy.values()].reduce((a, b) => a + b, 0);
+    const brands = Array.isArray(ranking.brands) ? ranking.brands : [];
+    return {
+        ranking: {
+            ...head,
+            runsPerPrompt: ranking.runsPerPrompt,
+            ...(ranking.engineCheckedAt ? { engineCheckedAt: ranking.engineCheckedAt } : {}),
+            usableAnswers: usable,
+            engineAnswers: Object.fromEntries(usableBy),
+            questions: prompts.map((p, i) => promptSummary(p, i + 1)),
+            products: brands.slice(0, TOP_BRANDS).map((b) => ({
+                name: b.name, ...(b.domain ? { domain: b.domain } : {}),
+                named: `${n(b.mentions)} of ${usable} usable answers`,
+                ...(typeof b.avgPosition === "number" ? { avgPosition: b.avgPosition } : {}),
+                byEngine: Object.fromEntries(Object.entries(b.byEngine ?? {}).map(([engine, count]) => [engine, `${n(count)} of ${usableBy.get(engine) ?? 0}`])),
+            })),
+            // The rest by name and count only, so a product past the top is never mistaken for one no answer named.
+            otherProducts: brands.slice(TOP_BRANDS).map((b) => `${String(b.name)} (${n(b.mentions)})`),
+            productsShown: `products: the ${Math.min(TOP_BRANDS, brands.length)} most-named of ${brands.length} products, in the ranking's order. otherProducts: the rest, each with the number of usable answers that named it.`,
+            ...(Array.isArray(ranking.merged) && ranking.merged.length ? { merged: ranking.merged } : {}),
+            answersOmitted: "Answer texts, products and citations are left out to fit an agent's context. Call again with question set to a question's number (1 is the first) for its answers. Only answered runs are usable answers; failed, not-run and no-overview runs are counted apart, never as answers that named nobody.",
+        },
+    };
+}

package/dist/report.js

@@ -1,5 +1,5 @@
 const usable = (a) => !a.failed && !a.noAnswer && (a.mentioned === true || a.mentioned === false);
-export function questionSummary(q) {
+export function questionSummary(q, number) {
     const answers = Array.isArray(q.answers) ? q.answers : [];
     const byEngine = new Map();
     for (const a of answers) {
@@ -16,31 +16,46 @@ export function questionSummary(q) {
     const named = [...byEngine.values()].reduce((n, e) => n + e.named, 0);
     const of = [...byEngine.values()].reduce((n, e) => n + e.usable, 0);
     return {
-        order: q.order, text: q.text, intent: q.intent, stage: q.stage,
+        question: number, text: q.text, intent: q.intent, stage: q.stage,
         named: `${named} of ${of} usable answers`,
         engines: Object.fromEntries([...byEngine].map(([engine, e]) => [engine, { named: `${e.named} of ${e.usable}`, notUsable: e.notUsable }])),
     };
 }
+/**
+ * The agent asked for a question the report does not have. Thrown, not returned: the
+ * API answered 200, so a returned { error } would reach the agent as a successful result.
+ * Both servers turn it into a tool error (isError: true) carrying this message.
+ */
+export class QuestionNotFoundError extends Error {
+    name = "QuestionNotFoundError";
+}
+const ZERO_IS_DEPRECATED = "question 0 is deprecated: questions are numbered from 1, and 0 reads as 1, the first question.";
 export function compactReport(body, question) {
     const report = body?.report;
     if (!report || !Array.isArray(report.questions))
         return body;
     const questions = report.questions;
     if (question !== undefined) {
-        // By the question's own order (real reports number from 0), never by list position.
-        const match = questions.find((q) => q.order === question);
-        if (!match) {
-            const orders = questions.map((q) => Number(q.order)).filter(Number.isFinite);
-            return { error: orders.length ? `No question with order ${question}; orders run ${Math.min(...orders)} to ${Math.max(...orders)}.` : `No question with order ${question}.` };
-        }
-        return { report: { slug: report.slug, brand: report.brand, domain: report.domain, simulated: report.simulated, enginesSkipped: report.enginesSkipped, question: match } };
+        // 1-based: question n is the n-th in the report's order. The deprecated 0 also means the first.
+        const index = question === 0 ? 0 : question - 1;
+        const match = Number.isInteger(index) && index >= 0 ? questions[index] : undefined;
+        if (!match)
+            throw new QuestionNotFoundError(questions.length ? `No question ${question}; questions are numbered 1 to ${questions.length}.` : `No question ${question}; this report has no questions.`);
+        const { order: _storedOrder, ...rest } = match;
+        return {
+            report: {
+                slug: report.slug, brand: report.brand, domain: report.domain, simulated: report.simulated, enginesSkipped: report.enginesSkipped,
+                question: { question: index + 1, ...rest },
+                ...(question === 0 ? { numbering: ZERO_IS_DEPRECATED } : {}),
+            },
+        };
     }
     return {
         ...body,
         report: {
             ...report,
-            questions: questions.map(questionSummary),
-            answersOmitted: `Answer texts, brands and citations are left out to fit an agent's context. Call again with question set to a question's order (from 0) for its answers. Engines in enginesSkipped did not run.`,
+            questions: questions.map((q, i) => questionSummary(q, i + 1)),
+            answersOmitted: `Answer texts, brands and citations are left out to fit an agent's context. Call again with question set to a question's number (1 is the first) for its answers. Engines in enginesSkipped did not run.`,
         },
     };
 }

package/dist/server.js

@@ -4,6 +4,7 @@ import { z } from "zod";
 import { ApiError, PROVIDERS, providerKeysFromEnv } from "./api.js";
 import { suggestPrompts } from "./suggest.js";
 import { compactReport } from "./report.js";
+import { compactRanking } from "./ranking.js";
 export const SERVER_NAME = "recomention";
 /**
  * package.json's version, read at startup: one number for npm, the MCP handshake and the
@@ -27,6 +28,12 @@ async function run(fn) {
     }
 }
 const slug = z.string().min(1).max(100).describe("The slug from a previous call.");
+/** Kept in step with core's application/hosted-mcp.ts; this package ships without core. */
+const QUESTION_NUMBER = "1-based question number, as the summary shows it: 1 is the first question, n the n-th. " +
+    "0 is deprecated and also reads as the first question (older agents counted from 0), so 0 and 1 return the same question.";
+/** Kept in step with core's application/hosted-mcp.ts. Rankings are a newer tool: no deprecated 0. */
+const RANKING_QUESTION_NUMBER = "1-based question number, as the summary shows it: 1 is the first question, n the n-th.";
+const RANKING_ENGINE = "With question: only this engine's answers to it.";
 /**
  * The recomention tools. Read tools are free. `recomention_report_start` is the
  * only tool that spends anything (an agency credit, or calls on the user's own
@@ -42,10 +49,12 @@ export function createServer(api, env = process.env) {
     }, () => run(() => api.rankings()));
     server.registerTool("recomention_rankings_get", {
         title: "Get an AI ranking",
-        description: "One public AI ranking by slug: every product named, how many answers named it (as n of m), and the verbatim answers. Free.",
-        inputSchema: { slug },
+        description: "One public AI ranking by slug: its questions with each engine's usable answers, and the most-named products as \"named in n of m usable answers\", overall and by engine. " +
+            "Answer texts are left out to fit your context: pass question (1-based: 1 is the first question, the number each summary entry shows) to read that question's answers, the products they named and their citations, and engine with it for one engine's answers only. " +
+            "Failed and not-run calls are counted apart, never as answers that named nobody. Free.",
+        inputSchema: { slug, question: z.number().int().min(1).max(200).optional().describe(RANKING_QUESTION_NUMBER), engine: z.enum(PROVIDERS).optional().describe(RANKING_ENGINE) },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, ({ slug }) => run(() => api.ranking(slug)));
+    }, ({ slug, question, engine }) => run(async () => compactRanking((await api.ranking(slug)), question, engine)));
     server.registerTool("recomention_suggest_prompts", {
         title: "Suggest buyer questions",
         description: "Suggest buyer-intent questions to check for a product, from fixed templates. No model call and no cost. The product's own name never appears in a question. Show them to the user to edit before starting a report.",
@@ -93,9 +102,9 @@ export function createServer(api, env = process.env) {
     server.registerTool("recomention_report_get", {
         title: "Get a report",
         description: "A report as JSON: the overall score, each engine's runs mentioned of runs total, competitors named instead, cited sources, the fix list and, per question, how many usable answers named the product. " +
-            "Answer texts are left out to fit your context: pass question (its order, from 0) to read that question's answers and citations. " +
+            "Answer texts are left out to fit your context: pass question (1-based: 1 is the first question, the number each summary entry shows) to read that question's answers and citations. " +
             "Engines in enginesSkipped did not run; never describe them as not mentioning the product. simulated: true means test data. Free.",
-        inputSchema: { slug, question: z.number().int().min(0).max(200).optional().describe("A question's order number, to read its answers.") },
+        inputSchema: { slug, question: z.number().int().min(0).max(200).optional().describe(QUESTION_NUMBER) },
         annotations: { readOnlyHint: true, openWorldHint: true },
     }, ({ slug, question }) => run(async () => compactReport((await api.report(slug)), question)));
     server.registerTool("recomention_distribution_kit", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recomention/mcp",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "MCP server for recomention: ask whether AI engines recommend a product, from Claude Code, Cursor or Codex.",
   "type": "module",
   "license": "MIT",
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.1",
-    "zod": "^4.4.3"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",

package/skills/ai-visibility-check/SKILL.md

@@ -15,7 +15,7 @@ user's own provider keys), so this skill always asks before it starts one.
    repository's README or landing page if the user is working in the product's own repo, and confirm.
 2. **Look for free evidence first.** Call `recomention_rankings_list`. If a public ranking matches the
    category, call `recomention_rankings_get` and tell the user where the product appears (as "named in
-   n of m answers"), or that it is absent. This costs nothing.
+   n of m answers", from `products` or `otherProducts`), or that it is absent from both. This costs nothing.
 3. **Draft the questions.** Call `recomention_suggest_prompts` and show the list. Let the user edit,
    add or remove questions. None may contain the product's name — a question that names it measures
    nothing. Remove any that do and say why.

package/skills/fix-list-review/SKILL.md

@@ -18,8 +18,9 @@ Reads a finished report with the `recomention_*` MCP tools. Costs nothing: it on
    suggests it (point at the evidence: a competitor's share of answers, a cited source the product is
    missing from, a question where it never appears), and the effort.
 4. **Ground it in the answers.** For the two or three questions where the product is absent most
-   often, quote one short excerpt of an engine answer and the products it named instead. Use
-   `questions[].answers[]`; skip answers with `failed: true`.
+   often, quote one short excerpt of an engine answer and the products it named instead. Call
+   `recomention_report_get` again with `question` set to that question's number (1 is the first) for
+   its answers; skip answers with `failed: true`.
 5. **Separate what the user controls from what they don't.** Their own site and docs: concrete edits
    they can make now (if you are in the product's repository, offer to draft them). Third-party pages
    (`sources` the engines cite): who to contact and what an honest inclusion request looks like.