@cite42/mcp 0.6.0 → 0.6.2

package/README.md

@@ -4,7 +4,7 @@
 
 MCP server for [Cite42, the AI search visibility, SEO keyword & trends API](https://www.cite42.dev): market research tools for your AI agent.
 
-Once connected, Claude Code, Claude Desktop, Codex CLI, or Cursor can:
+Once connected, Claude Code, Claude Desktop, Codex CLI, Cursor, or ChatGPT can:
 
 - **Query AI models** (ChatGPT, Claude, Perplexity, Gemini, Google AI Overviews) and see each model's answer and the sources it cites
 - **Track brand visibility** in AI answers: rankings, head-to-head comparisons, and sentiment
@@ -18,53 +18,63 @@ Once connected, Claude Code, Claude Desktop, Codex CLI, or Cursor can:
 ## Requirements
 
 - **A Cite42 account**, free to create at [cite42.dev](https://www.cite42.dev)
-- **Node.js 22.13 or newer and a Cite42 API key** for Claude Code, Codex CLI, and Cursor
+- For the API-key setup only: **Node.js 22.13 or newer and a Cite42 API key**
 
 ## Installation
 
-Claude Desktop connects to Cite42 through the hosted remote MCP URL and OAuth. Claude Code, Codex CLI, and Cursor run this package on demand with `npx -y @cite42/mcp`.
+Most clients connect to the hosted server at `https://mcp.cite42.dev` and sign in with your Cite42 account in the browser. There is no API key to create or paste, and nothing to install locally. For CI, servers, or machines without a browser, run this package with an API key instead; see [API key setup](#api-key-setup-ci-servers-no-browser).
 
-### Step 1: Get your API key for local clients
+### Claude Code
 
-Skip this step for Claude Desktop; its hosted connector authorizes through sign-in.
-
-1. Sign in at [cite42.dev](https://www.cite42.dev)
-2. Open **Dashboard → API Keys**: [www.cite42.dev/app/keys](https://www.cite42.dev/app/keys)
-3. Create a key and copy it (it looks like `cite42_live_...`)
-
-### Step 2: Add the server to your client
+```bash
+claude mcp add --transport http --scope user cite42 https://mcp.cite42.dev && claude mcp login cite42
+```
 
-Pick **one** of the clients below. For Claude Code, Codex CLI, and Cursor, replace `cite42_live_your_key_here` with your real key.
+Your browser opens to sign in. Then start Claude Code, or restart it if it was already open, and check with `/mcp`.
 
-#### Claude Code
+### Codex CLI
 
 ```bash
-claude mcp add cite42 -e CITE42_API_KEY=cite42_live_your_key_here -- npx -y @cite42/mcp
+codex mcp add cite42 --url https://mcp.cite42.dev
 ```
 
-#### Claude Desktop
+Codex opens your browser to sign in. If it doesn't, run `codex mcp login cite42`. Then start a new session.
+
+### Cursor
 
-1. Open **Settings → Connectors** and click **Add**.
-2. Select **Add custom connector**.
-3. Enter **Cite42** for the name and paste this remote MCP URL:
+[Add to Cursor](https://cursor.com/install-mcp?name=cite42&config=eyJ1cmwiOiJodHRwczovL21jcC5jaXRlNDIuZGV2In0%3D), or add this under **Settings → MCP**, or in `~/.cursor/mcp.json`:
 
-```text
-https://mcp.cite42.dev
+```json
+{
+  "mcpServers": {
+    "cite42": { "url": "https://mcp.cite42.dev" }
+  }
+}
 ```
 
-4. Click **Connect** and complete the Cite42 sign-in. No API key is required.
+Sign in with your Cite42 account when Cursor asks.
 
-The same hosted-connector steps apply in Claude.ai.
+### Claude Desktop and Claude.ai
 
-#### Codex CLI
+[Add to Claude](https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Cite42&connectorUrl=https%3A%2F%2Fmcp.cite42.dev) opens the connector dialog with Cite42 filled in. Or open **Settings → Connectors → Add custom connector**, name it **Cite42**, and paste `https://mcp.cite42.dev`. Click **Connect** and sign in. The connector appears in both Claude Desktop and Claude.ai.
+
+### ChatGPT and Codex Desktop
+
+Turn on **Developer mode** in **Settings → Security and login**, then add a plugin under **Settings → Plugins** with the MCP server URL `https://mcp.cite42.dev` and **OAuth**.
+
+### API key setup (CI, servers, no browser)
+
+Create a key at [www.cite42.dev/app/keys](https://www.cite42.dev/app/keys) (it looks like `cite42_live_...` and is shown once), then replace `cite42_live_your_key_here` below. The client starts this package on demand; you don't need to keep it running.
 
 ```bash
+# Claude Code
+claude mcp add --scope user cite42 -e CITE42_API_KEY=cite42_live_your_key_here -- npx -y @cite42/mcp
+
+# Codex CLI
 codex mcp add cite42 --env CITE42_API_KEY=cite42_live_your_key_here -- npx -y @cite42/mcp
 ```
 
-#### Cursor
-
-Add this under **Settings → MCP**, or save it to `~/.cursor/mcp.json`:
+For Cursor, save this to `~/.cursor/mcp.json`:
 
 ```json
 {
@@ -80,21 +90,14 @@ Add this under **Settings → MCP**, or save it to `~/.cursor/mcp.json`:
 }
 ```
 
-### Step 3: Restart so the server loads
-
-Local MCP servers are started by the client, so their config is only picked up on a fresh start. The Claude Desktop connector is ready after sign-in.
-
-- **Claude Code / Codex CLI**: exit the current session and open a **new terminal** (or start a new `claude` / `codex` session)
-- **Cursor**: fully quit and reopen the app
-
-You do not need to keep `npx -y @cite42/mcp` running in a separate terminal. Local MCP clients start it automatically when the session needs tools.
+Restart the client afterwards: a new terminal or `claude`/`codex` session, or fully quit and reopen Cursor.
 
-### Step 4: Verify it's running
+### Verify it's running
 
-- **Claude Code:** run `claude mcp list` and check that `cite42` shows as ✔ connected. Or type `/mcp` inside a session.
-- **Claude Desktop:** open **Settings → Connectors** and confirm Cite42 is connected.
+- **Claude Code:** run `claude mcp list` and check that `cite42` shows as connected, or type `/mcp` inside a session.
 - **Codex CLI:** run `codex mcp list`.
-- **Cursor:** look for `cite42` in the MCP/tools indicator. 29 tools should be listed.
+- **Cursor:** look for `cite42` in the MCP/tools indicator.
+- **Claude Desktop / Claude.ai:** open **Settings → Connectors** and confirm Cite42 is connected.
 
 If it doesn't appear, see [Troubleshooting](#troubleshooting).
 
@@ -178,7 +181,7 @@ Cite42 exposes 29 MCP tools: 4 free account tools (including the compatibility a
 
 ## Configuration
 
-- `CITE42_API_KEY`: required. Your API key from [www.cite42.dev/app/keys](https://www.cite42.dev/app/keys).
+- `CITE42_API_KEY`: required for the local package. Your API key from [www.cite42.dev/app/keys](https://www.cite42.dev/app/keys).
 - `CITE42_API_BASE`: optional. Defaults to `https://www.cite42.dev/api/v1`.
 
 You can also pass these as CLI flags instead of environment variables:
@@ -198,13 +201,14 @@ stdio, published npm, and local OAuth targets. Run `npm run test:stdio` for a fr
 smoke test against a loopback fake API. See [local MCP testing](../../docs/mcp-testing.md) in the repository.
 
 - **Server not listed after setup**: make sure you fully restarted the client (new terminal for CLI clients, full quit for desktop apps).
+- **"No Cite42 account is linked to this sign-in"**: you signed in with a different account than the one you use at cite42.dev. In Claude Code run `claude mcp logout cite42`, then `claude mcp login cite42` and pick the same sign-in method as on the dashboard.
 - **`command not found: npx`**: install Node.js 22.13+ from [nodejs.org](https://nodejs.org), then restart your terminal.
 - **Tool calls fail with an auth error**: check the key was passed correctly (`CITE42_API_KEY`, no quotes or trailing spaces) and is active at [www.cite42.dev/app/keys](https://www.cite42.dev/app/keys).
 - **Tool calls fail with an insufficient-balance error**: add funds at [www.cite42.dev/app](https://www.cite42.dev/app).
 
 ## Links
 
-- Website: [Cite42 MCP: AI search visibility, brand rankings, SEO keywords & trends](https://www.cite42.dev)
+- Website: [Cite42: AI visibility and SEO data for AI agents](https://www.cite42.dev)
 - API keys: [Create a Cite42 API key](https://www.cite42.dev/app/keys)
 - Docs: [Cite42 API & MCP documentation](https://www.cite42.dev/docs)
 - Pricing: [Cite42 pay-per-call pricing](https://www.cite42.dev/pricing)

package/dist/stdio.cjs

@@ -461,7 +461,7 @@ var aivMapAiPrompts = (0, import_tools.createTool)({
   id: "cite42_map_ai_prompts",
   mcp: readOnly("Map buyer prompts for AI search"),
   description: workflowDescription(
-    "Run the AI-prompt-map workflow: discover and cluster buyer prompts worth tracking from AI search, SEO demand, trends, citations, Reddit, and YouTube data. The prompts it returns are exactly what cite42_tracker_create takes, so offer to start tracking the best of them once the user has seen the map."
+    "Run the AI-prompt-map workflow: research for a list of buyer prompts worth tracking, from AI search, SEO demand, trends, citations, Reddit, and YouTube data. It returns evidence and a suggested prompt, not a finished list: write the prompts from it, then offer to track the best of them with cite42_tracker_create once the user has seen them."
   ),
   inputSchema: import_zod.z.object({
     topic: queryText("Market, product category, buyer problem, or audience to map prompts for."),
@@ -507,7 +507,7 @@ var aivGenerateContentBrief = (0, import_tools.createTool)({
   id: "cite42_generate_content_brief",
   mcp: readOnly("Generate content brief data"),
   description: workflowDescription(
-    "Run the content-brief workflow: AI answers, citations, SEO keyword demand, trends, Reddit, and YouTube signals aggregated into brief-ready data."
+    "Run the content-brief workflow: research for a content brief from AI answers, citations, SEO keyword demand, trends, Reddit, and YouTube signals. It returns evidence and a suggested prompt; write the brief from it."
   ),
   inputSchema: import_zod.z.object({
     topic: queryText("Topic, keyword, or content idea to brief."),
@@ -574,7 +574,7 @@ var TRACKER_BILLING_DESCRIPTION = "Tracker management and stored-report reads ar
 var aivTrackerCreate = (0, import_tools.createTool)({
   id: "cite42_tracker_create",
   mcp: mutation("Create Cite42 tracker draft"),
-  description: "Create a draft weekly or monthly tracker: one measurement \u2014 rankings, compare, citations, or sentiment \u2014 applied to a list of prompts, with the brand, competitors and AI surfaces set once for all of them. When the user has no prompt list yet, run cite42_map_ai_prompts first and track the prompts it recommends. Creation does not start recurring calls. " + TRACKER_BILLING_DESCRIPTION,
+  description: "Create a draft weekly or monthly tracker: one measurement \u2014 rankings, compare, citations, or sentiment \u2014 applied to a list of prompts, with the brand, competitors and AI surfaces set once for all of them. When the user has no prompt list yet, run cite42_map_ai_prompts first and track the prompts you write from its research. Creation does not start recurring calls. " + TRACKER_BILLING_DESCRIPTION,
   inputSchema: import_zod.z.object(trackerDefinitionFields),
   execute: async (input) => aivPost("/trackers", input)
 });
@@ -695,7 +695,7 @@ if (!resolveApiKey()) {
   );
   process.exit(1);
 }
-buildCite42Server("0.6.0").startStdio().catch((error) => {
+buildCite42Server("0.6.2").startStdio().catch((error) => {
   console.error("[@cite42/mcp] Fatal error:", error);
   process.exit(1);
 });

package/dist/stdio.mjs

@@ -460,7 +460,7 @@ var aivMapAiPrompts = createTool({
   id: "cite42_map_ai_prompts",
   mcp: readOnly("Map buyer prompts for AI search"),
   description: workflowDescription(
-    "Run the AI-prompt-map workflow: discover and cluster buyer prompts worth tracking from AI search, SEO demand, trends, citations, Reddit, and YouTube data. The prompts it returns are exactly what cite42_tracker_create takes, so offer to start tracking the best of them once the user has seen the map."
+    "Run the AI-prompt-map workflow: research for a list of buyer prompts worth tracking, from AI search, SEO demand, trends, citations, Reddit, and YouTube data. It returns evidence and a suggested prompt, not a finished list: write the prompts from it, then offer to track the best of them with cite42_tracker_create once the user has seen them."
   ),
   inputSchema: z.object({
     topic: queryText("Market, product category, buyer problem, or audience to map prompts for."),
@@ -506,7 +506,7 @@ var aivGenerateContentBrief = createTool({
   id: "cite42_generate_content_brief",
   mcp: readOnly("Generate content brief data"),
   description: workflowDescription(
-    "Run the content-brief workflow: AI answers, citations, SEO keyword demand, trends, Reddit, and YouTube signals aggregated into brief-ready data."
+    "Run the content-brief workflow: research for a content brief from AI answers, citations, SEO keyword demand, trends, Reddit, and YouTube signals. It returns evidence and a suggested prompt; write the brief from it."
   ),
   inputSchema: z.object({
     topic: queryText("Topic, keyword, or content idea to brief."),
@@ -573,7 +573,7 @@ var TRACKER_BILLING_DESCRIPTION = "Tracker management and stored-report reads ar
 var aivTrackerCreate = createTool({
   id: "cite42_tracker_create",
   mcp: mutation("Create Cite42 tracker draft"),
-  description: "Create a draft weekly or monthly tracker: one measurement \u2014 rankings, compare, citations, or sentiment \u2014 applied to a list of prompts, with the brand, competitors and AI surfaces set once for all of them. When the user has no prompt list yet, run cite42_map_ai_prompts first and track the prompts it recommends. Creation does not start recurring calls. " + TRACKER_BILLING_DESCRIPTION,
+  description: "Create a draft weekly or monthly tracker: one measurement \u2014 rankings, compare, citations, or sentiment \u2014 applied to a list of prompts, with the brand, competitors and AI surfaces set once for all of them. When the user has no prompt list yet, run cite42_map_ai_prompts first and track the prompts you write from its research. Creation does not start recurring calls. " + TRACKER_BILLING_DESCRIPTION,
   inputSchema: z.object(trackerDefinitionFields),
   execute: async (input) => aivPost("/trackers", input)
 });
@@ -694,7 +694,7 @@ if (!resolveApiKey()) {
   );
   process.exit(1);
 }
-buildCite42Server("0.6.0").startStdio().catch((error) => {
+buildCite42Server("0.6.2").startStdio().catch((error) => {
   console.error("[@cite42/mcp] Fatal error:", error);
   process.exit(1);
 });

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cite42/mcp",
   "mcpName": "dev.cite42/mcp",
-  "version": "0.6.0",
-  "description": "Cite42 MCP server: query the models behind ChatGPT, Claude, Perplexity & Gemini, plus Google AI Overviews, for brand rankings, AI citations, SEO keyword data, and Reddit/YouTube trends, and schedule 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.",
+  "version": "0.6.2",
+  "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",
   "bin": {