@recomention/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Astrael OÜ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# @recomention/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An MCP server for [recomention](https://www.recomention.com): ask Claude Code, Cursor or Codex
+*"is my product recommended by ChatGPT for meeting scheduling?"* and have it start a report, wait
+for it, and read the result — every engine's "named in n of m answers", who is recommended instead,
+the sources the engines read, and the fix list.
+
+It is a thin stdio client for the public JSON API v1 at `https://api.recomention.com/v1`. It holds no state.
+It runs locally, as a process your MCP client starts. For ChatGPT, Claude.ai and other clients that
+connect to a remote server, use the hosted connector at `https://mcp.recomention.com/mcp` instead: it
+signs in with your recomention account (OAuth), no API key needed. Setup for each client:
+<https://docs.recomention.com/mcp/>.
+
+Requires Node.js 20 or newer (`npx` comes with it).
+
+## Environment
+
+| Variable | | |
+| --- | --- | --- |
+| `RECOMENTION_API_KEY` | required for reports | Create one at `/account` → Developers. Shown once. Without it, public rankings and suggested questions still work. |
+| `RECOMENTION_BASE_URL` | optional | Defaults to `https://api.recomention.com`. An older `https://www.recomention.com` (or the apex, a web preview, or a local Next dev server on port 3000–3099) still works: it reaches the site's deprecated `/api/v1` alias. Any other bare origin, such as the API preview Worker or a local API Worker (`http://localhost:8790`), uses `/v1`. |
+| `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `PERPLEXITY_API_KEY`, `GEMINI_API_KEY`, `XAI_API_KEY`, `DATAFORSEO_API_KEY` (Google AI Overview, `login:password`) | optional | Only for `funding: "byok"` (Bring Your Own Key), which needs an active Agent plan on the account. Any subset works and engines without a key are reported as skipped, but one of OpenAI, Anthropic or Gemini is required. Read from this server's environment, never from a tool argument, so your keys never pass through the model's context. |
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add recomention \
+  --env RECOMENTION_API_KEY=YOUR_API_KEY \
+  --env RECOMENTION_BASE_URL=https://api.recomention.com \
+  -- npx -y @recomention/mcp
+```
+
+Replace `YOUR_API_KEY` with your key. Add `--scope user` to use it in every project. Check it with `claude mcp list`, or `/mcp` inside a session.
+
+### Cursor (`~/.cursor/mcp.json`, or `.cursor/mcp.json` in a project) and other JSON-configured clients
+
+```json
+{
+  "mcpServers": {
+    "recomention": {
+      "command": "npx",
+      "args": ["-y", "@recomention/mcp"],
+      "env": { "RECOMENTION_API_KEY": "<key>", "RECOMENTION_BASE_URL": "https://api.recomention.com" }
+    }
+  }
+}
+```
+
+Keep a project-level `.cursor/mcp.json` that holds a key out of version control.
+
+### Codex
+
+```bash
+codex mcp add recomention \
+  --env RECOMENTION_API_KEY=YOUR_API_KEY \
+  --env RECOMENTION_BASE_URL=https://api.recomention.com \
+  -- npx -y @recomention/mcp
+```
+
+or in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.recomention]
+command = "npx"
+args = ["-y", "@recomention/mcp"]
+env = { RECOMENTION_API_KEY = "<key>", RECOMENTION_BASE_URL = "https://api.recomention.com" }
+```
+
+## Tools
+
+| 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_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_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. |
+
+Reading results honestly: an engine in `enginesSkipped` did not run (for example *"provider rejected
+the key"*) — it is never an engine that left the product out. A report with `simulated: true` is test
+data.
+
+## Setup prompt
+
+The account page's **Copy setup prompt** button copies this (with the site's own URL). Paste it into
+your agent:
+
+```text
+Set up the recomention MCP server so you can check whether AI engines (ChatGPT, Claude, Perplexity, Gemini, Grok) recommend a product.
+
+1. Add this MCP server to your MCP configuration (Claude Code: `claude mcp add`; Cursor: ~/.cursor/mcp.json; Codex: ~/.codex/config.toml):
+   command: npx -y @recomention/mcp
+   env: RECOMENTION_API_KEY=<ask me for my API key; never write it into a repository>
+        RECOMENTION_BASE_URL=https://api.recomention.com
+   Claude Code one-liner: claude mcp add recomention --env RECOMENTION_API_KEY=<key> --env RECOMENTION_BASE_URL=https://api.recomention.com -- npx -y @recomention/mcp
+2. Restart or reload MCP servers, then call recomention_rankings_list to confirm it works.
+
+How to use it:
+- To check a product, first call recomention_suggest_prompts with its domain, category and a one-line description, show me the questions, and let me edit them.
+- Starting a report spends money: an agency credit, or calls on my own provider keys (that needs my Agent plan). Always ask me before calling recomention_report_start, and say which funding it will use.
+- On my own keys, any subset works, but one of OpenAI, Anthropic or Gemini is required. If the start is refused with a `limit` (plan, projects, reportsPerMonth, perDay, concurrent), tell me which limit and do not retry around it.
+- Reports take several minutes. Poll recomention_report_status about once a minute; do not start a second report for the same product while one is running.
+- When it is COMPLETE, call recomention_report_get and summarise: the overall score, each engine's "named in n of m answers", who is recommended instead, and the top three fixes. Quote counts as "n of m", never as yes/no.
+- An engine listed under enginesSkipped did not run (for example "provider rejected the key"). Say so; never describe it as an engine that did not mention the product.
+- A report with simulated: true is a test run with made-up answers. Say that plainly and do not draw conclusions from it.
+
+Docs: https://www.recomention.com/developers
+```
+
+The canonical text lives in `packages/core/src/config/developers.ts` (`setupPrompt`); keep this copy
+in step with it.
+
+## Skills
+
+`skills/` holds agent skills in the slash-command style: copy a folder into `.claude/skills/` (Claude
+Code) or your agent's equivalent.
+
+- `ai-visibility-check` — check one product end to end.
+- `fix-list-review` — turn a finished report into a prioritised, honest plan of work.
+- `competitor-watch` — compare who the engines name in a category, from public rankings and your reports.
+- `distribution-kit` — read a finished report's kit and work through its channel plan, one channel at a time.
+
+## Develop
+
+```bash
+npm install
+npm test            # in-memory client against the server, fake API; metadata/version checks
+npm run smoke       # spawns the stdio server against RECOMENTION_BASE_URL
+npm run build       # clean dist/ (bin: recomention-mcp)
+npm run smoke:pack  # packs the tarball (with pnpm), checks its contents, runs it against a fake local API
+```
+
+In the monorepo, run them as `pnpm --filter @recomention/mcp <script>`.
+
+Run `smoke --start` only against a local server with `RECOMENTION_MOCK=1`: against a live
+deployment it spends a credit.
+
+`prepack` empties and rebuilds `dist/`, so a pack or publish always ships the current sources and
+no test files. `version` lives in `package.json`; the server reads it at startup, and `server.json`
+(the MCP Registry entry, `io.github.recomention/mcp`) must carry the same number — a test fails
+otherwise.
+
+This repository is published from the recomention monorepo, where development happens. Bugs and
+questions: [issues](https://github.com/recomention/mcp/issues) or support@recomention.com.
+
+## Licence
+
+[MIT](./LICENSE).

package/dist/api.js

@@ -0,0 +1,104 @@
+/**
+ * A thin client for the recomention JSON API v1. Everything the MCP server
+ * does goes through here; it holds no state and no business rules of its own.
+ */
+export const PROVIDERS = ["OPENAI", "ANTHROPIC", "PERPLEXITY", "GEMINI", "GROK", "AI_OVERVIEW"];
+/** Where BYOK keys come from: the MCP server's own environment, never a tool argument. */
+export const PROVIDER_ENV = {
+    OPENAI: "OPENAI_API_KEY",
+    ANTHROPIC: "ANTHROPIC_API_KEY",
+    PERPLEXITY: "PERPLEXITY_API_KEY",
+    GEMINI: "GEMINI_API_KEY",
+    GROK: "XAI_API_KEY",
+    // Google AI Overview through DataForSEO: the API login and password as `login:password`.
+    AI_OVERVIEW: "DATAFORSEO_API_KEY",
+};
+export function providerKeysFromEnv(env = process.env) {
+    const keys = {};
+    for (const p of PROVIDERS) {
+        const value = env[PROVIDER_ENV[p]]?.trim();
+        if (value)
+            keys[p] = value;
+    }
+    return keys;
+}
+export class ApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "ApiError";
+    }
+}
+/** Where the hosted API lives. Paths are /v1/... */
+export const DEFAULT_BASE_URL = "https://api.recomention.com";
+/**
+ * The v1 root under a configured base URL. A copy of packages/core/src/shared/api-base.ts
+ * (this package is published and imports no workspace code): keep the two in step.
+ *
+ *   .../v1, .../api, .../api/v1      -> used as written (.../api gains /v1)
+ *   a bare site origin               -> <origin>/api/v1 (the site's deprecated alias: an older config still works)
+ *                                       www.recomention.com, recomention.com, a *recomention-web-preview.*.workers.dev
+ *                                       host, or localhost/127.0.0.1 on ports 3000-3099 (a local Next dev server)
+ *   any other bare origin            -> <origin>/v1 (the API host, its preview Worker, a local API Worker)
+ */
+export function apiV1Root(base) {
+    const url = new URL(base);
+    const path = url.pathname.replace(/\/+$/, "");
+    const origin = url.origin;
+    if (path.endsWith("/v1"))
+        return `${origin}${path}`;
+    if (path.endsWith("/api"))
+        return `${origin}${path}/v1`;
+    if (path)
+        return `${origin}${path}/v1`;
+    return isSiteOrigin(url) ? `${origin}/api/v1` : `${origin}/v1`;
+}
+function isSiteOrigin(url) {
+    const host = url.hostname.toLowerCase();
+    if (host === "recomention.com" || host === "www.recomention.com")
+        return true;
+    if (/(^|-)recomention-web-preview\.[a-z0-9-]+\.workers\.dev$/.test(host))
+        return true;
+    if (host === "localhost" || host === "127.0.0.1" || host === "[::1]") {
+        const port = Number(url.port || (url.protocol === "https:" ? 443 : 80));
+        return port >= 3000 && port <= 3099;
+    }
+    return false;
+}
+export function createApi(options) {
+    const base = options.baseUrl.replace(/\/+$/, "");
+    const root = apiV1Root(base);
+    const doFetch = options.fetch ?? fetch;
+    async function call(method, path, body, auth = true) {
+        if (auth && !options.apiKey)
+            throw new ApiError(401, "RECOMENTION_API_KEY is not set. Create a key in your recomention account (Developers) and add it to this MCP server's env.");
+        const headers = { accept: "application/json", "user-agent": options.userAgent ?? "recomention-mcp" };
+        if (auth && options.apiKey)
+            headers.authorization = `Bearer ${options.apiKey}`;
+        if (body !== undefined)
+            headers["content-type"] = "application/json";
+        let res;
+        try {
+            res = await doFetch(`${root}${path}`, { method, headers, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(30_000) });
+        }
+        catch (error) {
+            throw new ApiError(0, `Couldn't reach ${base}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const data = (await res.json().catch(() => null));
+        if (!res.ok)
+            throw new ApiError(res.status, data?.error ?? `HTTP ${res.status}`);
+        return data;
+    }
+    return {
+        baseUrl: base,
+        root,
+        rankings: () => call("GET", "/rankings", undefined, false),
+        ranking: (slug) => call("GET", `/rankings/${encodeURIComponent(slug)}`, undefined, false),
+        reports: () => call("GET", "/reports"),
+        report: (slug) => call("GET", `/reports/${encodeURIComponent(slug)}`),
+        kit: (slug) => call("GET", `/reports/${encodeURIComponent(slug)}/kit`),
+        status: (slug) => call("GET", `/reports/${encodeURIComponent(slug)}/status`),
+        start: (body) => call("POST", "/reports", body),
+    };
+}

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * recomention MCP server over stdio.
+ *
+ *   RECOMENTION_API_KEY    an API key from your account (Developers). Needed for reports.
+ *   RECOMENTION_BASE_URL   defaults to https://api.recomention.com (an older https://www.recomention.com still works)
+ *
+ * stdout carries the protocol, so anything human goes to stderr.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createApi, DEFAULT_BASE_URL } from "./api.js";
+import { createServer, SERVER_VERSION } from "./server.js";
+const baseUrl = process.env.RECOMENTION_BASE_URL?.trim() || DEFAULT_BASE_URL;
+// The API key travels as a bearer token: refuse plain http anywhere but this machine.
+{
+    let parsed = null;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch { /* reported below */ }
+    const local = parsed !== null && ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname);
+    if (!parsed || (parsed.protocol !== "https:" && !(local && parsed.protocol === "http:"))) {
+        console.error(`RECOMENTION_BASE_URL must be an https:// URL (http:// only for localhost). Got: ${baseUrl}`);
+        process.exit(1);
+    }
+}
+const api = createApi({ baseUrl, apiKey: process.env.RECOMENTION_API_KEY?.trim() || undefined, userAgent: `recomention-mcp/${SERVER_VERSION}` });
+const server = createServer(api);
+await server.connect(new StdioServerTransport());
+console.error(`recomention MCP server ${SERVER_VERSION} on stdio → ${api.root}${process.env.RECOMENTION_API_KEY ? "" : " (no RECOMENTION_API_KEY: rankings only)"}`);

package/dist/server.js

@@ -0,0 +1,113 @@
+import { readFileSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { ApiError, PROVIDERS, providerKeysFromEnv } from "./api.js";
+import { suggestPrompts } from "./suggest.js";
+export const SERVER_NAME = "recomention";
+/**
+ * package.json's version, read at startup: one number for npm, the MCP handshake and the
+ * user agent. `../package.json` is the package root from both src/ and dist/, and npm always
+ * ships it. server.json carries the same number for the registry; a test keeps them in step.
+ */
+export const SERVER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+function ok(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+function fail(error) {
+    const message = error instanceof ApiError ? `${error.status ? `HTTP ${error.status}: ` : ""}${error.message}` : error instanceof Error ? error.message : String(error);
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+async function run(fn) {
+    try {
+        return ok(await fn());
+    }
+    catch (error) {
+        return fail(error);
+    }
+}
+const slug = z.string().min(1).max(100).describe("The slug from a previous call.");
+/**
+ * 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
+ * provider keys), and its description says so, so an agent asks first.
+ */
+export function createServer(api, env = process.env) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    server.registerTool("recomention_rankings_list", {
+        title: "List AI rankings",
+        description: "List recomention's public AI rankings: for each category, which products the AI engines name when asked its buyer questions, month by month. Free.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, () => 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 },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, ({ slug }) => run(() => api.ranking(slug)));
+    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.",
+        inputSchema: {
+            domain: z.string().min(3).describe("The product's domain, e.g. example.com"),
+            category: z.string().min(2).describe("What buyers search for, e.g. meeting scheduling"),
+            description: z.string().max(300).optional().describe("One line on what the product does"),
+            count: z.number().int().min(1).max(12).optional(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async (input) => ok({ prompts: suggestPrompts(input) }));
+    server.registerTool("recomention_report_start", {
+        title: "Start a report (spends a credit or your provider keys)",
+        description: "Start a recomention report: the questions are asked of every engine on the plan several times each, with live web search. " +
+            "THIS SPENDS MONEY: funding \"credits\" uses one agency credit from the user's account (plan must be FULL); funding \"byok\" runs on the user's own provider keys from this server's environment (OPENAI_API_KEY, ANTHROPIC_API_KEY, PERPLEXITY_API_KEY, GEMINI_API_KEY, XAI_API_KEY, DATAFORSEO_API_KEY as login:password for Google AI Overview) and needs an active Agent plan on the account. " +
+            "Any subset of keys works and engines without a key are reported as skipped, but one of OpenAI, Anthropic or Gemini is required. A refusal names the plan limit it hit. " +
+            "Always ask the user before calling it. Reports take several minutes: poll recomention_report_status about once a minute.",
+        inputSchema: {
+            domain: z.string().min(3),
+            description: z.string().min(3).max(300),
+            category: z.string().min(2).max(120),
+            brand: z.string().max(80).optional().describe("Defaults to the name in the domain"),
+            plan: z.enum(["QUICK", "FULL", "DEEP"]).default("FULL"),
+            prompts: z.array(z.string().min(8).max(200)).max(40).optional().describe("Questions to ask; the rest are written for you. None may name the product."),
+            engines: z.array(z.enum(PROVIDERS)).min(1).optional().describe("A subset of the plan's engines"),
+            funding: z.enum(["credits", "byok"]),
+            idempotencyKey: z.string().regex(/^[A-Za-z0-9_-]{16,128}$/).optional().describe("Reuse to make a retried start land on the same report"),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, ({ prompts, funding, ...rest }) => run(async () => {
+        const providerKeys = funding === "byok" ? providerKeysFromEnv(env) : undefined;
+        if (funding === "byok" && !Object.keys(providerKeys ?? {}).length) {
+            throw new Error("funding \"byok\" needs at least one provider key in this MCP server's env (OPENAI_API_KEY, ANTHROPIC_API_KEY, PERPLEXITY_API_KEY, GEMINI_API_KEY, XAI_API_KEY or DATAFORSEO_API_KEY).");
+        }
+        // The keys go to the API in the request body and nowhere else: never into the tool result.
+        const started = await api.start({ ...rest, funding, ...(prompts?.length ? { seedPrompts: prompts } : {}), ...(providerKeys ? { providerKeys } : {}) });
+        return { ...started, next: "Poll recomention_report_status with this slug about once a minute." };
+    }));
+    server.registerTool("recomention_report_status", {
+        title: "Report status",
+        description: "Where a report is: PENDING, RUNNING, COMPLETE or FAILED, with answers stored so far. Free.",
+        inputSchema: { slug },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, ({ 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. " +
+            "Engines in enginesSkipped did not run; never describe them as not mentioning the product. simulated: true means test data. Free.",
+        inputSchema: { slug },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, ({ slug }) => run(() => api.report(slug)));
+    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). " +
+            "Read README.md first. Every count is \"n of m answers\"; nothing in it promises traffic. Show the user every draft before anything is posted. Free.",
+        inputSchema: { slug },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, ({ slug }) => run(() => api.kit(slug)));
+    server.registerTool("recomention_reports_list", {
+        title: "List my reports",
+        description: "The reports in the account that owns the API key, newest first. Free.",
+        inputSchema: {},
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, () => run(() => api.reports()));
+    return server;
+}

package/dist/suggest.js

@@ -0,0 +1,47 @@
+/**
+ * Buyer questions for a category, from fixed templates: no model call, no
+ * network, no cost, and the same input always gives the same questions.
+ *
+ * The product's own name never appears in a question — the point of a check
+ * is whether the engines name it unprompted — so anything that would contain
+ * it is dropped.
+ */
+const TEMPLATES = [
+    { intent: "best_in_category", text: (c) => `what is the best ${c} tool right now?` },
+    { intent: "recommendation", text: (c) => `which ${c} software would you recommend for a small team?` },
+    { intent: "recommendation", text: (c) => `what ${c} tools do startups use in 2026?` },
+    { intent: "use_case", text: (c, d) => (d ? `i need something for ${d}. what ${c} tool should i use?` : `what ${c} tool is easiest to set up?`) },
+    { intent: "alternatives", text: (c) => `what are good alternatives to the most popular ${c} tools?` },
+    { intent: "use_case", text: (c) => `best ${c} tool for a solo founder on a budget?` },
+    { intent: "comparison", text: (c) => `compare the top 5 ${c} tools for features and price` },
+    { intent: "use_case", text: (c) => `which ${c} tool works best for agencies with many clients?` },
+    { intent: "recommendation", text: (c) => `what ${c} software has the best free plan?` },
+    { intent: "use_case", text: (c) => `best ${c} tool for enterprise security and compliance?` },
+    { intent: "comparison", text: (c) => `which ${c} tool has the best integrations?` },
+    { intent: "best_in_category", text: (c) => `top rated ${c} apps according to reviews` },
+];
+function brandOf(domain) {
+    const host = domain.trim().toLowerCase().replace(/^https?:\/\//, "").replace(/^www\./, "").split("/")[0];
+    return host.split(".")[0] ?? host;
+}
+function clean(text) {
+    return text.replace(/\s+/g, " ").trim().toLowerCase();
+}
+export function suggestPrompts(input) {
+    const category = clean(input.category).replace(/\b(software|tools?|apps?)$/, "").trim() || clean(input.category);
+    const description = clean(input.description ?? "").replace(/[.?!]+$/, "");
+    const brand = brandOf(input.domain);
+    const count = Math.min(Math.max(input.count ?? 10, 1), TEMPLATES.length);
+    const seen = new Set();
+    const out = [];
+    for (const t of TEMPLATES) {
+        const text = clean(t.text(category, description));
+        if ((brand.length >= 3 && text.includes(brand)) || seen.has(text))
+            continue;
+        seen.add(text);
+        out.push({ text, intent: t.intent });
+        if (out.length === count)
+            break;
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@recomention/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "MCP server for recomention: ask whether AI engines recommend a product, from Claude Code, Cursor or Codex.",
+  "type": "module",
+  "license": "MIT",
+  "mcpName": "io.github.recomention/mcp",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-visibility",
+    "llm",
+    "claude-code",
+    "cursor",
+    "codex"
+  ],
+  "homepage": "https://www.recomention.com/developers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/recomention/mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/recomention/mcp/issues",
+    "email": "support@recomention.com"
+  },
+  "bin": {
+    "recomention-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.js",
+    "!dist/**/*.map",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "tsx": "^4.23.12",
+    "typescript": "^5",
+    "@recomention/tsconfig": "0.1.0"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "start": "tsx src/index.ts",
+    "clean": "node scripts/clean-dist.mjs",
+    "build": "node scripts/clean-dist.mjs && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test src/*.test.ts",
+    "smoke": "tsx scripts/smoke.ts",
+    "smoke:pack": "tsx scripts/pack-smoke.ts"
+  }
 }

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

@@ -0,0 +1,44 @@
+---
+name: ai-visibility-check
+description: Check whether AI engines (ChatGPT, Claude, Perplexity, Gemini, Grok) recommend a product, using the recomention MCP server. Use when the user asks "is my product recommended by ChatGPT/AI for <category>?", wants an AI visibility or AI search check, or names a domain and a category to check.
+---
+
+# AI visibility check
+
+Uses the `recomention_*` MCP tools. Starting a report spends money (an agency credit, or calls on the
+user's own provider keys), so this skill always asks before it starts one.
+
+## Steps
+
+1. **Collect the inputs.** You need the product's domain, the category buyers search for (e.g.
+   "meeting scheduling"), and one line on what it does. Ask for whatever is missing; read it from the
+   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.
+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.
+4. **Confirm spend, then start.** Say what will run: plan (credits run `FULL`), the engines, the
+   funding (`credits` or `byok`). Only after the user agrees, call `recomention_report_start` with the
+   edited questions as `prompts` and a fresh `idempotencyKey` (random, 16+ characters). Reuse that key
+   if you have to retry the same start.
+5. **Wait.** Poll `recomention_report_status` about once a minute and report progress
+   ("answers stored / planned"). Do not start a second report for the same product meanwhile.
+6. **Read it out.** When COMPLETE, call `recomention_report_get` and summarise:
+   - the overall score (0–100) and, per engine, `runsMentioned` of `runsTotal` answers;
+   - the top competitors named instead (share of answers);
+   - the sources the engines cited most, and whether the product is on them;
+   - the top three items of the fix list;
+   - the report link (`url`) for the full detail.
+
+## Honesty rules
+
+- Rates, never yes/no: "ChatGPT named it in 4 of 9 answers", not "ChatGPT recommends it".
+- An engine in `enginesSkipped` did not run. Give its reason (e.g. "provider rejected the key"). Never
+  call it an engine that did not mention the product, and never count it as zero.
+- An answer with `failed: true` was excluded from every count; do not treat it as "not mentioned".
+- `simulated: true` means test data with made-up answers. Say so first, and draw no conclusions.
+- Every report is a dated snapshot. Say the date when you quote numbers.
+- If the report FAILED, say so and show its `error`. Credit-funded reports that fail get their credit
+  back automatically; do not retry more than once without asking.

package/skills/competitor-watch/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: competitor-watch
+description: See which products AI engines name in a category and how a product compares with its competitors, from recomention's public rankings and the user's own reports. Use when the user asks who ChatGPT/AI recommends for a category, how they compare with a competitor in AI answers, or whether that changed since the last check.
+---
+
+# Competitor watch
+
+Uses the `recomention_*` MCP tools. Everything here is read-only and free unless the user asks for a
+new report.
+
+## Steps
+
+1. **Public rankings first.** Call `recomention_rankings_list`; for each ranking that matches the
+   category, call `recomention_rankings_get`. Present the ranked products as "named in n of m answers"
+   with the average position, per engine where it differs, and the date it was checked.
+2. **The user's own reports.** Call `recomention_reports_list` and pick COMPLETE reports in the same
+   category (non-simulated). For each, `recomention_report_get` and read `competitors` (share of
+   answers, average rank) and per-engine `runsMentioned` of `runsTotal`.
+3. **Compare like with like.** Only compare runs that asked the same questions (a re-check of the same
+   report does; two unrelated reports usually do not) — say so when they differ. Put the user's product
+   and its named competitors side by side: share of answers, engines that name each, average position.
+4. **What changed.** If there are two or more comparable reports, list who moved up or down between the
+   dates, and by how many answers. Small moves (one or two answers) are within run-to-run variation;
+   call them that.
+5. **Offer, don't start.** If nothing current covers the category, suggest a new report via the
+   `ai-visibility-check` skill — and say that starting one spends a credit or the user's provider keys.
+
+## Rules
+
+- Rates, never yes/no. Always give the denominator and the date.
+- Engines that were skipped or calls that failed are excluded, never counted as "not named".
+- Simulated reports are test data: leave them out of any comparison.
+- Name products only as the engines did; do not add your own opinion of which is better.

package/skills/distribution-kit/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: distribution-kit
+description: Turn a finished recomention report into distribution work: read its kit (product, competitors, AI visibility, where to get mentioned, channel plan) and work through the channel plan with the user, one channel at a time. Use when the user asks how to get their product recommended by AI engines, where to get mentioned, or what to do with a recomention report.
+---
+
+# Distribution kit
+
+Reads a finished report's Distribution Kit with the `recomention_*` MCP tools. Costs nothing: it only reads.
+
+## Steps
+
+1. **Load the kit.** Get the slug (the last path segment of a `/r/<slug>` link, or pick from
+   `recomention_reports_list`) and call `recomention_distribution_kit`. A 409 means the report is not
+   finished: call `recomention_report_status`, say where it is, and stop.
+2. **Read every file, `README.md` first.** If the files say SIMULATED TEST DATA, tell the user and stop:
+   a test run's answers are made up.
+3. **Summarise in five lines:** the score, each engine's "named in n of m answers", skipped engines and
+   why, the top rivals, and the top three channels from `channel-plan.md`.
+4. **Work the channel plan in order, one channel at a time.** For each, take the pages for that channel
+   from `where-to-get-mentioned.md`, open them, and confirm they are still relevant before suggesting
+   anything. Then draft the first task (a reply, a pitch email, a review request, a page on the user's
+   own site) and show it to the user. Nothing is posted or sent without their yes.
+5. **Close the loop.** Suggest a new report in about a month with the same questions, to see whether
+   the engines' answers changed.
+
+## Rules
+
+- Be openly the product's maker everywhere: no fake reviews, no posing as a customer, no paid placement
+  dressed as editorial, no vote manipulation.
+- The kit counts citations; it did not read the pages. Check a page before acting on it.
+- Quote counts as "n of m". An engine listed as skipped did not run; it is not a zero.
+- Never promise traffic or rankings.

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

@@ -0,0 +1,36 @@
+---
+name: fix-list-review
+description: Turn a finished recomention report into a prioritised, honest plan of work — what to change on the site, which third-party pages matter, and what to re-measure. Use when the user has a recomention report slug or link and asks what to do about it, how to improve their AI visibility, or to review the fix list.
+---
+
+# Fix list review
+
+Reads a finished report with the `recomention_*` MCP tools. Costs nothing: it only reads.
+
+## Steps
+
+1. **Load the report.** Get the slug (the last path segment of a `/r/<slug>` link, or pick from
+   `recomention_reports_list`). Call `recomention_report_get`. If `status` is not COMPLETE, call
+   `recomention_report_status`, say where it is, and stop.
+2. **State the baseline** in one short paragraph: overall score, per-engine `runsMentioned` of
+   `runsTotal`, skipped engines with their reasons, the check date, and whether it is simulated.
+3. **Walk the fix list** (`actionPlan`) in order. For each item give: what to do, why the report
+   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`.
+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.
+6. **Say how to know it worked.** A later report with the same questions shows the change; suggest
+   re-checking in about a month rather than days, since engines' answers move slowly.
+
+## Rules
+
+- Never suggest fake reviews, paid placements dressed as editorial, posing as a customer, or any
+  other way of presenting the product as an unrelated third party. Community threads: answering
+  openly as the founder is the honest option.
+- Do not promise ranking outcomes. The report measures what engines said and where they looked.
+- Quote counts as "n of m". An engine in `enginesSkipped` is not a zero.
+- A simulated report has made-up answers: do not build a plan on it.