@cite42/mcp 0.1.5 → 0.1.7

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 +112 -53
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,40 +1,51 @@
1
1
  # @cite42/mcp
2
2
 
3
- Use Cite42 inside Claude Code, Codex CLI, Cursor, and other MCP clients.
3
+ MCP server for [Cite42](https://cite42.dev) — AI search visibility, SEO keywords, and trend research tools for your AI agent.
4
4
 
5
- Cite42 gives your agent market-data tools for:
5
+ Once installed, your MCP client (Claude Code, Claude Desktop, Codex CLI, Cursor, Windsurf, etc.) can:
6
6
 
7
- - AI search answers and citations
8
- - brand rankings, comparisons, and sentiment
9
- - SEO keywords, CPC, competition, and trends
10
- - Reddit and YouTube research
11
- - content, competitor, prompt, and citation-gap workflows
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
- This package is a stdio MCP server. It needs a Cite42 API key.
13
+ ---
14
14
 
15
- ## Install
15
+ ## Requirements
16
16
 
17
- 1. Create a Cite42 API key at [cite42.dev/app/keys](https://cite42.dev/app/keys).
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)
18
19
 
19
- 2. Make sure you have Node.js 18 or newer.
20
+ ## Installation
20
21
 
21
- 3. Add the MCP server to your client.
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.
22
23
 
23
- ### Claude Code
24
+ ### Step 1 — Get your API key
25
+
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_...`)
29
+
30
+ ### Step 2 — Add the server to your client
31
+
32
+ Pick **one** of the clients below and replace `cite42_live_your_key_here` with your real key.
33
+
34
+ #### Claude Code
24
35
 
25
36
  ```bash
26
37
  claude mcp add cite42 -e CITE42_API_KEY=cite42_live_your_key_here -- npx -y @cite42/mcp
27
38
  ```
28
39
 
29
- ### Codex CLI
40
+ #### Codex CLI
30
41
 
31
42
  ```bash
32
43
  codex mcp add cite42 --env CITE42_API_KEY=cite42_live_your_key_here -- npx -y @cite42/mcp
33
44
  ```
34
45
 
35
- ### Cursor
46
+ #### Claude Desktop
36
47
 
37
- Add this to your MCP config:
48
+ Add this to `claude_desktop_config.json` (**Settings → Developer → Edit Config**):
38
49
 
39
50
  ```json
40
51
  {
@@ -50,62 +61,110 @@ Add this to your MCP config:
50
61
  }
51
62
  ```
52
63
 
53
- 4. Restart your MCP client.
64
+ #### Cursor / Windsurf / other JSON-config clients
54
65
 
55
- 5. Ask your agent to use Cite42, for example:
66
+ Use the same JSON block as Claude Desktop in your client's `mcpServers` config (Cursor: `~/.cursor/mcp.json` or **Settings → MCP**).
56
67
 
57
- ```text
58
- Use Cite42 to check which AI models cite competitors for "best customer support software".
59
- ```
68
+ ### Step 3 — Restart so the server loads
60
69
 
61
- ## Endpoints
70
+ MCP servers are started by the client, so the config is only picked up on a fresh start:
62
71
 
63
- These MCP tools call the matching Cite42 API endpoints.
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
64
74
 
65
- ### AI Search
75
+ ### Step 4 — Verify it's running
66
76
 
67
- - `cite42_search`: ask ChatGPT, Claude, Perplexity, Gemini, and Google AI Overview a query.
68
- - `cite42_citations`: see which URLs AI models cite for a query.
69
- - `cite42_rankings`: check where brands or domains appear in AI answers.
70
- - `cite42_compare`: compare your brand against competitors.
71
- - `cite42_sentiment`: measure how AI answers describe a brand.
77
+ - **Claude Code:** run `claude mcp list` — `cite42` should show 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.
72
80
 
73
- ### SEO And Trends
81
+ If it doesn't appear, see [Troubleshooting](#troubleshooting).
74
82
 
75
- - `cite42_keywords`: get search volume, CPC, competition, competition level, and keyword ideas.
76
- - `cite42_trends`: get Google Trends interest and rising queries.
77
- - `cite42_reddit_trends`: find Reddit questions, pain points, threads, and mentioned products.
78
- - `cite42_youtube_trends`: find YouTube videos, title patterns, creator angles, and opportunities.
83
+ ## Try it — example prompts
79
84
 
80
- ### Workflows
85
+ After restarting, just ask in plain language. Your agent picks the right Cite42 tool automatically.
81
86
 
82
- - `cite42_find_content_opportunities`: find content opportunities from AI, SEO, Reddit, YouTube, and trends.
83
- - `cite42_analyze_topic_demand`: analyze demand for a topic.
84
- - `cite42_map_ai_prompts`: map buyer prompts worth tracking.
85
- - `cite42_analyze_competitor_content`: analyze competitor visibility and content coverage.
86
- - `cite42_find_ai_citation_gaps`: find where competitors get cited but your brand does not.
87
- - `cite42_generate_content_brief`: generate brief-ready research data.
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'."*
88
92
 
89
- ## Configuration
93
+ ### Example: what a session looks like
90
94
 
91
- 1. Required API key:
95
+ **You ask:**
92
96
 
93
- ```bash
94
- CITE42_API_KEY=cite42_live_your_key_here
95
- ```
97
+ > Use Cite42 to find AI-cited competitors for "best invoicing software for freelancers".
96
98
 
97
- 2. Optional custom API base:
99
+ **Your agent calls** `cite42_citations` **and answers something like:**
98
100
 
99
- ```bash
100
- CITE42_API_BASE=https://api.cite42.dev/v1
101
- ```
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.
109
+
110
+ ## Available tools
111
+
112
+ ### AI search visibility
102
113
 
103
- You can also pass both as flags:
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 | — | 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:
104
150
 
105
151
  ```bash
106
152
  npx -y @cite42/mcp --api-key=cite42_live_your_key_here --api-base=https://api.cite42.dev/v1
107
153
  ```
108
154
 
109
- ## Pricing
155
+ ## Billing
156
+
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
 
111
- Tool calls use your Cite42 credits. Without an API key and available credits, calls will fail.
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.5",
4
- "description": "Stdio MCP server for Cite42 AI search, citations, SEO keywords, trends, and workflows.",
3
+ "version": "0.1.7",
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": {