@recomention/mcp 0.1.0 → 0.1.2

package/README.md

@@ -77,7 +77,7 @@ env = { RECOMENTION_API_KEY = "<key>", RECOMENTION_BASE_URL = "https://api.recom
 | `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/report.js

@@ -0,0 +1,61 @@
+const usable = (a) => !a.failed && !a.noAnswer && (a.mentioned === true || a.mentioned === false);
+export function questionSummary(q, number) {
+    const answers = Array.isArray(q.answers) ? q.answers : [];
+    const byEngine = new Map();
+    for (const a of answers) {
+        const e = byEngine.get(String(a.engine)) ?? { named: 0, usable: 0, notUsable: 0 };
+        if (usable(a)) {
+            e.usable++;
+            if (a.mentioned === true)
+                e.named++;
+        }
+        else
+            e.notUsable++;
+        byEngine.set(String(a.engine), e);
+    }
+    const named = [...byEngine.values()].reduce((n, e) => n + e.named, 0);
+    const of = [...byEngine.values()].reduce((n, e) => n + e.usable, 0);
+    return {
+        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) {
+        // 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((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

@@ -3,6 +3,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { ApiError, PROVIDERS, providerKeysFromEnv } from "./api.js";
 import { suggestPrompts } from "./suggest.js";
+import { compactReport } from "./report.js";
 export const SERVER_NAME = "recomention";
 /**
  * package.json's version, read at startup: one number for npm, the MCP handshake and the
@@ -26,6 +27,9 @@ 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.";
 /**
  * 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
@@ -91,11 +95,12 @@ export function createServer(api, env = process.env) {
     }, ({ slug }) => run(() => api.status(slug)));
     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 every question with every answer. " +
+        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 (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 },
+        inputSchema: { slug, question: z.number().int().min(0).max(200).optional().describe(QUESTION_NUMBER) },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, ({ slug }) => run(() => api.report(slug)));
+    }, ({ slug, question }) => run(async () => compactReport((await api.report(slug)), question)));
     server.registerTool("recomention_distribution_kit", {
         title: "Get the distribution kit",
         description: "Markdown files built from a finished report, for planning distribution: product.md, competitors.md, ai-visibility.md, where-to-get-mentioned.md (third-party pages, subreddits and videos the engines cite for a rival and not for this product) and channel-plan.md (channels ranked by those citations, each with a first task). " +

package/package.json

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