@cite42/mcp 0.1.6 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +142 -82
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,110 +1,170 @@
1
1
  # @cite42/mcp
2
2
 
3
- `@cite42/mcp` is a stdio MCP server that exposes Cite42 APIs to your agent.
3
+ MCP server for [Cite42](https://cite42.dev): AI search visibility, SEO keywords, and trend research tools for your AI agent.
4
4
 
5
- Use it to get:
5
+ Once installed, your MCP client (Claude Code, Claude Desktop, Codex CLI, Cursor, Windsurf, etc.) can:
6
6
 
7
- - AI search answers and citations across major LLM sources
8
- - Brand ranking and sentiment signals from AI answers
9
- - SEO keyword, CPC, competition, and search trend data
10
- - Reddit + YouTube trend and opportunity intelligence
11
- - End-to-end research workflows (content gaps, topic demand, prompt mapping)
7
+ - **Query AI models** (ChatGPT, Claude, Perplexity, Gemini, Google AI Overviews) and see each model's answer and the sources it cites
8
+ - **Track brand visibility** in AI answers: rankings, head-to-head comparisons, and sentiment
9
+ - **Pull SEO data**: keyword search volume, CPC, competition, and Google Trends
10
+ - **Mine Reddit and YouTube** for audience questions, pain points, and rising content
11
+ - **Run full research workflows**: content gaps, topic demand, AI prompt maps, competitor analysis, and content briefs in a single call
12
12
 
13
- ## Step-by-step setup
13
+ ---
14
14
 
15
- 1. Create a Cite42 API key
15
+ ## Requirements
16
16
 
17
- - Go to: https://cite42.dev/app/keys
18
- - Copy your key (format: `cite42_live_...`)
17
+ - **Node.js 18 or newer** (`node --version` to check)
18
+ - **A Cite42 API key**, free to create at [cite42.dev/app/keys](https://cite42.dev/app/keys)
19
19
 
20
- 2. Confirm your Node.js version
20
+ ## Installation
21
21
 
22
- - MCP runtime requires Node.js 18 or newer
22
+ There is nothing to install manually. Every client below runs the server on demand with `npx -y @cite42/mcp`. You only need to register it once.
23
23
 
24
- 3. Add the MCP server to your client
24
+ ### Step 1: Get your API key
25
25
 
26
- - Keep the same command for all clients: `npx -y @cite42/mcp`
27
- - Pass your API key using environment variables (recommended)
26
+ 1. Sign in at [cite42.dev](https://cite42.dev)
27
+ 2. Open **Dashboard → API Keys**: [cite42.dev/app/keys](https://cite42.dev/app/keys)
28
+ 3. Create a key and copy it (it looks like `cite42_live_...`)
28
29
 
29
- 4. Configure one client
30
+ ### Step 2: Add the server to your client
30
31
 
31
- - Claude Code
32
+ Pick **one** of the clients below and replace `cite42_live_your_key_here` with your real key.
32
33
 
33
- ```bash
34
- claude mcp add cite42 -e CITE42_API_KEY=cite42_live_your_key_here -- npx -y @cite42/mcp
35
- ```
34
+ #### Claude Code
36
35
 
37
- - Codex CLI
36
+ ```bash
37
+ claude mcp add cite42 -e CITE42_API_KEY=cite42_live_your_key_here -- npx -y @cite42/mcp
38
+ ```
38
39
 
39
- ```bash
40
- codex mcp add cite42 --env CITE42_API_KEY=cite42_live_your_key_here -- npx -y @cite42/mcp
41
- ```
40
+ #### Codex CLI
42
41
 
43
- - Cursor (`mcpServers` config)
42
+ ```bash
43
+ codex mcp add cite42 --env CITE42_API_KEY=cite42_live_your_key_here -- npx -y @cite42/mcp
44
+ ```
44
45
 
45
- ```json
46
- {
47
- "mcpServers": {
48
- "cite42": {
49
- "command": "npx",
50
- "args": ["-y", "@cite42/mcp"],
51
- "env": {
52
- "CITE42_API_KEY": "cite42_live_your_key_here"
53
- }
54
- }
55
- }
56
- }
57
- ```
46
+ #### Claude Desktop
58
47
 
59
- 5. Restart your MCP client
48
+ Add this to `claude_desktop_config.json` (**Settings → Developer → Edit Config**):
60
49
 
61
- 6. Try your first request
50
+ ```json
51
+ {
52
+ "mcpServers": {
53
+ "cite42": {
54
+ "command": "npx",
55
+ "args": ["-y", "@cite42/mcp"],
56
+ "env": {
57
+ "CITE42_API_KEY": "cite42_live_your_key_here"
58
+ }
59
+ }
60
+ }
61
+ }
62
+ ```
62
63
 
63
- - Example prompt:
64
- `Use Cite42 to find AI-cited competitors for "best project management software".`
64
+ #### Cursor / Windsurf / other JSON-config clients
65
+
66
+ Use the same JSON block as Claude Desktop in your client's `mcpServers` config (Cursor: `~/.cursor/mcp.json` or **Settings → MCP**).
67
+
68
+ ### Step 3: Restart so the server loads
69
+
70
+ MCP servers are started by the client, so the config is only picked up on a fresh start:
71
+
72
+ - **Claude Code / Codex CLI**: exit the current session and open a **new terminal** (or start a new `claude` / `codex` session)
73
+ - **Claude Desktop / Cursor / Windsurf**: fully quit and reopen the app
74
+
75
+ ### Step 4: Verify it's running
76
+
77
+ - **Claude Code:** run `claude mcp list` and check that `cite42` shows as ✔ connected. Or type `/mcp` inside a session.
78
+ - **Codex CLI:** run `codex mcp list`.
79
+ - **Claude Desktop / Cursor:** look for `cite42` in the MCP/tools indicator. 15 tools should be listed.
80
+
81
+ If it doesn't appear, see [Troubleshooting](#troubleshooting).
82
+
83
+ ## Try it: example prompts
84
+
85
+ After restarting, just ask in plain language. Your agent picks the right Cite42 tool automatically.
86
+
87
+ - *"Use Cite42 to check which brands AI models recommend for 'best project management software'."*
88
+ - *"Which sources do AI models cite when asked about CRM tools for startups? Is mycompany.com among them?"*
89
+ - *"Get search volume, CPC, and related keywords for 'ai seo tools'."*
90
+ - *"What are people on Reddit complaining about regarding email marketing tools?"*
91
+ - *"Run a content brief for the topic 'ai website builder'."*
92
+
93
+ ### Example: what a session looks like
94
+
95
+ **You ask:**
96
+
97
+ > Use Cite42 to find AI-cited competitors for "best invoicing software for freelancers".
98
+
99
+ **Your agent calls** `cite42_citations` **and answers something like:**
100
+
101
+ > Across ChatGPT, Claude, Perplexity, and Gemini, the most-cited sources are:
102
+ >
103
+ > 1. **freshbooks.com** (cited by 4/5 models)
104
+ > 2. **wave.com** (cited by 3/5 models)
105
+ > 3. **zoho.com/invoice** (cited by 3/5 models)
106
+ > 4. **bonsai.com** (cited by 2/5 models)
107
+ >
108
+ > Your domain wasn't cited by any model. FreshBooks is cited mainly via comparison/"best of" listicles. A citation-gap analysis (`cite42_find_ai_citation_gaps`) can show which queries you're missing from.
65
109
 
66
110
  ## Available tools
67
111
 
68
- - AI search
69
- - `cite42_search`
70
- - `cite42_citations`
71
- - `cite42_rankings`
72
- - `cite42_compare`
73
- - `cite42_sentiment`
74
- - SEO and trend intelligence
75
- - `cite42_keywords`
76
- - `cite42_trends`
77
- - `cite42_reddit_trends`
78
- - `cite42_youtube_trends`
79
- - Workflows
80
- - `cite42_find_content_opportunities`
81
- - `cite42_analyze_topic_demand`
82
- - `cite42_map_ai_prompts`
83
- - `cite42_analyze_competitor_content`
84
- - `cite42_find_ai_citation_gaps`
85
- - `cite42_generate_content_brief`
86
-
87
- ## Optional configuration
88
-
89
- - Required:
90
-
91
- ```bash
92
- CITE42_API_KEY=cite42_live_your_key_here
93
- ```
94
-
95
- - Optional:
96
-
97
- ```bash
98
- CITE42_API_BASE=https://api.cite42.dev/v1
99
- ```
100
-
101
- - You can also pass flags directly:
102
-
103
- ```bash
104
- npx -y @cite42/mcp --api-key=cite42_live_your_key_here --api-base=https://api.cite42.dev/v1
105
- ```
112
+ ### AI search visibility
113
+
114
+ | Tool | What it does |
115
+ | --- | --- |
116
+ | `cite42_search` | Run a query against ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews; returns each model's answer plus cited sources |
117
+ | `cite42_citations` | Aggregate which URLs the AI models cite for a query; optionally check if a specific URL is cited |
118
+ | `cite42_rankings` | Measure how brands rank in AI answers: mention rate, average position, per-model breakdown |
119
+ | `cite42_compare` | Head-to-head brand comparison in AI answers, including a co-mention graph |
120
+ | `cite42_sentiment` | Positive/neutral/negative sentiment per model for a brand, with the verbatim phrases driving it |
121
+
122
+ ### SEO & trend data
123
+
124
+ | Tool | What it does |
125
+ | --- | --- |
126
+ | `cite42_keywords` | Search volume, CPC, competition, and related keyword ideas for a seed term |
127
+ | `cite42_trends` | Google Trends interest over time, related/rising queries, rising/falling label |
128
+ | `cite42_reddit_trends` | Audience questions, pain points, rising threads, and product mentions on Reddit |
129
+ | `cite42_youtube_trends` | Rising videos, creator angles, title patterns, and opportunities on YouTube |
130
+
131
+ ### Research workflows (multi-source, one call)
132
+
133
+ | Tool | What it does |
134
+ | --- | --- |
135
+ | `cite42_find_content_opportunities` | Content gaps across AI search, keywords, trends, Reddit, YouTube, and citations |
136
+ | `cite42_analyze_topic_demand` | Keyword data + trends + AI answers + audience conversations for a topic |
137
+ | `cite42_map_ai_prompts` | Discover and cluster the buyer prompts worth tracking in AI search |
138
+ | `cite42_analyze_competitor_content` | AI rankings, comparisons, citations, and topic coverage for a competitor |
139
+ | `cite42_find_ai_citation_gaps` | Queries where AI answers cite others but not your brand/domain/URL |
140
+ | `cite42_generate_content_brief` | AI answers, citations, keyword demand, and social signals aggregated into a brief |
141
+
142
+ ## Configuration
143
+
144
+ | Variable | Required | Default | Description |
145
+ | --- | --- | --- | --- |
146
+ | `CITE42_API_KEY` | Yes | (none) | Your API key from [cite42.dev/app/keys](https://cite42.dev/app/keys) |
147
+ | `CITE42_API_BASE` | No | `https://api.cite42.dev/v1` | Override the API base URL |
148
+
149
+ You can also pass these as CLI flags instead of environment variables:
150
+
151
+ ```bash
152
+ npx -y @cite42/mcp --api-key=cite42_live_your_key_here --api-base=https://api.cite42.dev/v1
153
+ ```
106
154
 
107
155
  ## Billing
108
156
 
109
- Tool calls consume Cite42 credits. Calls will fail if the API key is missing or credits are insufficient.
157
+ Tool calls consume Cite42 credits from your account. Calls fail with a clear error if the API key is missing or credits run out. See [cite42.dev/pricing](https://cite42.dev/pricing).
158
+
159
+ ## Troubleshooting
160
+
161
+ - **Server not listed after setup**: make sure you fully restarted the client (new terminal for CLI clients, full quit for desktop apps).
162
+ - **`command not found: npx`**: install Node.js 18+ from [nodejs.org](https://nodejs.org), then restart your terminal.
163
+ - **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 [cite42.dev/app/keys](https://cite42.dev/app/keys).
164
+ - **Tool calls fail with a credits error**: top up credits at [cite42.dev/app](https://cite42.dev/app).
165
+
166
+ ## Links
110
167
 
168
+ - Website: [cite42.dev](https://cite42.dev)
169
+ - API keys: [cite42.dev/app/keys](https://cite42.dev/app/keys)
170
+ - Docs: [cite42.dev/docs](https://cite42.dev/docs)
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@cite42/mcp",
3
- "version": "0.1.6",
4
- "description": "Bring Cite42 market-research and citation tools into any MCP client (Claude, Codex, Cursor, etc.) with a single npm install.",
3
+ "version": "0.1.8",
4
+ "description": "Cite42 MCP server: query ChatGPT, Claude, Perplexity, Gemini & Google AI Overviews for brand rankings, AI citations, SEO keyword data, and Reddit/YouTube trends. Works with Claude Code, Claude Desktop, Codex CLI, Cursor, and any MCP client.",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "bin": {