@recomention/mcp 0.1.2 → 0.1.3

package/README.md

@@ -73,7 +73,7 @@ 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. |

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/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
@@ -30,6 +31,9 @@ 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
@@ -45,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.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recomention/mcp",
-  "version": "0.1.2",
+  "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",

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.