@cite42/mcp 0.6.0 → 0.6.1

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,6 +201,7 @@ 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).

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.1").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.1").startStdio().catch((error) => {
   console.error("[@cite42/mcp] Fatal error:", error);
   process.exit(1);
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cite42/mcp",
   "mcpName": "dev.cite42/mcp",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "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.",
   "license": "MIT",
   "type": "module",