@cite42/mcp 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# @cite42/mcp
+
+MCP (Model Context Protocol) server for the [Cite42](https://cite42.dev) AI search data API,
+built on [Mastra](https://mastra.ai). Lets Claude Desktop, Cursor, and other MCP clients
+query competitor rankings, citations, and search results across ChatGPT, Claude, Perplexity,
+Gemini, and Google AI Overviews. Tools forward to the hosted Cite42 REST API using your API
+key, so billing and metering stay server-side.
+
+## Install
+
+You don't need to install — `npx` will fetch and run it on demand.
+
+## Configure Claude Desktop
+
+Open your Claude Desktop config:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Add the Cite42 MCP server:
+
+```json
+{
+  "mcpServers": {
+    "cite42": {
+      "command": "npx",
+      "args": ["-y", "@cite42/mcp"],
+      "env": {
+        "CITE42_API_KEY": "cite42_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Get your API key from [cite42.dev/app/keys](https://cite42.dev/app/keys).
+
+Restart Claude Desktop. You should see seven new tools available (see below).
+
+## Tools
+
+### `cite42_search`
+Run a search query against the AI models and get each model's answer plus the sources it cited.
+
+### `cite42_citations`
+Look up which sources the AI models cite for a query — useful for tracking which sites get referenced in AI answers. Optionally check whether a specific URL is cited.
+
+### `cite42_rankings`
+Check how a list of competitor domains/brands rank in AI-generated answers for a query (mention rate, average position, per-model breakdown).
+
+### `cite42_compare`
+Compare one brand head-to-head against a competitor set, with a co-mention graph of which brands the models name together.
+
+### `cite42_sentiment`
+Score how each model talks about a brand: a positive/neutral/negative split with the phrases driving the tone, plus an aggregate.
+
+### `cite42_keywords`
+Classic keyword data for a seed term: monthly search volume, CPC, competition, and (optionally) related keyword ideas.
+
+### `cite42_trends`
+Google Trends interest-over-time, related/rising queries, and a rising/falling/stable label for a term.
+
+## Environment variables
+
+- `CITE42_API_KEY` (required) — Your Cite42 API key (`cite42_live_...`)
+- `CITE42_API_BASE` (optional) — Override the API base URL. Defaults to `https://api.cite42.dev/v1`.
+
+## Pricing
+
+Each tool call consumes credits from your Cite42 balance. Top up at [cite42.dev/app/billing](https://cite42.dev/app/billing).

package/dist/stdio.cjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+"use strict";
+
+// src/stdio.ts
+var import_mcp = require("@mastra/mcp");
+
+// src/tools.ts
+var import_tools = require("@mastra/core/tools");
+var import_zod = require("zod");
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.cite42.dev/v1";
+function getApiKey() {
+  const key = process.env.CITE42_API_KEY;
+  if (!key) {
+    throw new Error(
+      "CITE42_API_KEY environment variable is required. Set it in your MCP client config (e.g., Claude Desktop)."
+    );
+  }
+  return key;
+}
+function getBaseUrl() {
+  return process.env.CITE42_API_BASE || DEFAULT_BASE_URL;
+}
+async function aivPost(path, body) {
+  const url = `${getBaseUrl()}${path.startsWith("/") ? path : `/${path}`}`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${getApiKey()}`
+    },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Cite42 API ${res.status} ${path}: ${text}`);
+  }
+  return res.json();
+}
+
+// src/tools.ts
+var modelEnum = import_zod.z.enum(["chatgpt", "claude", "perplexity", "gemini", "google_ai_overview"]);
+var aivSearch = (0, import_tools.createTool)({
+  id: "cite42_search",
+  description: "Run a query against AI models (ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews) and return each model's answer along with the sources it cited.",
+  inputSchema: import_zod.z.object({
+    query: import_zod.z.string().min(1).describe("The query to run against the AI models."),
+    models: import_zod.z.array(modelEnum).nonempty().optional().describe("Models to query. Defaults to all (chatgpt, claude, perplexity, gemini).")
+  }),
+  execute: async (input) => aivPost("/search", input)
+});
+var aivCitations = (0, import_tools.createTool)({
+  id: "cite42_citations",
+  description: "Find which sources AI models cite for a query. Aggregates cited URLs across models with per-model counts; optionally checks whether a specific URL is cited.",
+  inputSchema: import_zod.z.object({
+    query: import_zod.z.string().min(1).describe("The query to look up cited sources for."),
+    url: import_zod.z.string().optional().describe("Optional URL to check whether it was cited."),
+    models: import_zod.z.array(modelEnum).nonempty().optional().describe("Models to query. Defaults to all.")
+  }),
+  execute: async (input) => aivPost("/citations", input)
+});
+var aivRankings = (0, import_tools.createTool)({
+  id: "cite42_rankings",
+  description: "Measure how a set of brands/competitors rank in AI answers for a query: mention rate, average position, and a per-model breakdown across ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews.",
+  inputSchema: import_zod.z.object({
+    query: import_zod.z.string().min(1).describe("The query to measure brand/competitor visibility on."),
+    competitors: import_zod.z.array(import_zod.z.string().min(1)).nonempty().describe("Brand or domain names to track within the AI-generated answers."),
+    models: import_zod.z.array(modelEnum).nonempty().optional().describe("Models to query. Defaults to all.")
+  }),
+  execute: async (input) => aivPost("/rankings", input)
+});
+var aivCompare = (0, import_tools.createTool)({
+  id: "cite42_compare",
+  description: "Compare one primary brand head-to-head against a competitor set in AI answers: per-brand rankings plus a co-mention graph of which brands the models name together.",
+  inputSchema: import_zod.z.object({
+    query: import_zod.z.string().min(1).describe("The query to compare the brand and competitors on."),
+    brand: import_zod.z.string().min(1).describe("Your brand, ranked alongside the competitors."),
+    competitors: import_zod.z.array(import_zod.z.string().min(1)).nonempty().max(10).describe("Competitor brand/domain names (up to 10) to rank against your brand."),
+    models: import_zod.z.array(modelEnum).nonempty().optional().describe("Models to query. Defaults to all.")
+  }),
+  execute: async (input) => aivPost("/compare", input)
+});
+var aivSentiment = (0, import_tools.createTool)({
+  id: "cite42_sentiment",
+  description: "Score how each AI model talks about a brand for a query: a positive/neutral/negative split per model with the verbatim phrases driving the tone, plus an aggregate across models.",
+  inputSchema: import_zod.z.object({
+    query: import_zod.z.string().min(1).describe("The query whose answers are scored for brand sentiment."),
+    brand: import_zod.z.string().min(1).describe("The brand to score sentiment for in each model answer."),
+    models: import_zod.z.array(modelEnum).nonempty().optional().describe("Models to query. Defaults to all.")
+  }),
+  execute: async (input) => aivPost("/sentiment", input)
+});
+var aivKeywords = (0, import_tools.createTool)({
+  id: "cite42_keywords",
+  description: "Classic keyword data for a seed term: monthly search volume, CPC, competition, and (optionally) related keyword ideas. A flat-priced data tool, not an AI-model query.",
+  inputSchema: import_zod.z.object({
+    seed: import_zod.z.string().min(1).describe("Seed keyword to fetch search volume, CPC, and competition for."),
+    country: import_zod.z.string().optional().describe('ISO-2 country code for localized metrics. Defaults to "us".'),
+    ideas: import_zod.z.boolean().optional().describe("When true, also return related keyword ideas with their volumes.")
+  }),
+  execute: async (input) => aivPost("/keywords", input)
+});
+var aivTrends = (0, import_tools.createTool)({
+  id: "cite42_trends",
+  description: "Google Trends interest-over-time, related and rising queries, and a rising/falling/stable label for a term. A flat-priced data tool, not an AI-model query.",
+  inputSchema: import_zod.z.object({
+    term: import_zod.z.string().min(1).describe("Search term to pull Google Trends interest-over-time for."),
+    timeframe: import_zod.z.string().optional().describe('Trends window, e.g. "past_12_months", "past_30_days", "past_5_years".'),
+    geo: import_zod.z.string().optional().describe('Optional location name (e.g. "United States"). Worldwide when omitted.')
+  }),
+  execute: async (input) => aivPost("/trends", input)
+});
+
+// src/stdio.ts
+var server = new import_mcp.MCPServer({
+  id: "cite42",
+  name: "Cite42",
+  version: "0.1.0",
+  description: "AI search data API: query ChatGPT, Claude, Perplexity, and Gemini.",
+  tools: {
+    cite42_search: aivSearch,
+    cite42_rankings: aivRankings,
+    cite42_compare: aivCompare,
+    cite42_citations: aivCitations,
+    cite42_sentiment: aivSentiment,
+    cite42_keywords: aivKeywords,
+    cite42_trends: aivTrends
+  }
+});
+server.startStdio().catch((error) => {
+  console.error("[@cite42/mcp] Fatal error:", error);
+  process.exit(1);
+});

package/dist/stdio.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/stdio.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/stdio.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+// src/stdio.ts
+import { MCPServer } from "@mastra/mcp";
+
+// src/tools.ts
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.cite42.dev/v1";
+function getApiKey() {
+  const key = process.env.CITE42_API_KEY;
+  if (!key) {
+    throw new Error(
+      "CITE42_API_KEY environment variable is required. Set it in your MCP client config (e.g., Claude Desktop)."
+    );
+  }
+  return key;
+}
+function getBaseUrl() {
+  return process.env.CITE42_API_BASE || DEFAULT_BASE_URL;
+}
+async function aivPost(path, body) {
+  const url = `${getBaseUrl()}${path.startsWith("/") ? path : `/${path}`}`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${getApiKey()}`
+    },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Cite42 API ${res.status} ${path}: ${text}`);
+  }
+  return res.json();
+}
+
+// src/tools.ts
+var modelEnum = z.enum(["chatgpt", "claude", "perplexity", "gemini", "google_ai_overview"]);
+var aivSearch = createTool({
+  id: "cite42_search",
+  description: "Run a query against AI models (ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews) and return each model's answer along with the sources it cited.",
+  inputSchema: z.object({
+    query: z.string().min(1).describe("The query to run against the AI models."),
+    models: z.array(modelEnum).nonempty().optional().describe("Models to query. Defaults to all (chatgpt, claude, perplexity, gemini).")
+  }),
+  execute: async (input) => aivPost("/search", input)
+});
+var aivCitations = createTool({
+  id: "cite42_citations",
+  description: "Find which sources AI models cite for a query. Aggregates cited URLs across models with per-model counts; optionally checks whether a specific URL is cited.",
+  inputSchema: z.object({
+    query: z.string().min(1).describe("The query to look up cited sources for."),
+    url: z.string().optional().describe("Optional URL to check whether it was cited."),
+    models: z.array(modelEnum).nonempty().optional().describe("Models to query. Defaults to all.")
+  }),
+  execute: async (input) => aivPost("/citations", input)
+});
+var aivRankings = createTool({
+  id: "cite42_rankings",
+  description: "Measure how a set of brands/competitors rank in AI answers for a query: mention rate, average position, and a per-model breakdown across ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews.",
+  inputSchema: z.object({
+    query: z.string().min(1).describe("The query to measure brand/competitor visibility on."),
+    competitors: z.array(z.string().min(1)).nonempty().describe("Brand or domain names to track within the AI-generated answers."),
+    models: z.array(modelEnum).nonempty().optional().describe("Models to query. Defaults to all.")
+  }),
+  execute: async (input) => aivPost("/rankings", input)
+});
+var aivCompare = createTool({
+  id: "cite42_compare",
+  description: "Compare one primary brand head-to-head against a competitor set in AI answers: per-brand rankings plus a co-mention graph of which brands the models name together.",
+  inputSchema: z.object({
+    query: z.string().min(1).describe("The query to compare the brand and competitors on."),
+    brand: z.string().min(1).describe("Your brand, ranked alongside the competitors."),
+    competitors: z.array(z.string().min(1)).nonempty().max(10).describe("Competitor brand/domain names (up to 10) to rank against your brand."),
+    models: z.array(modelEnum).nonempty().optional().describe("Models to query. Defaults to all.")
+  }),
+  execute: async (input) => aivPost("/compare", input)
+});
+var aivSentiment = createTool({
+  id: "cite42_sentiment",
+  description: "Score how each AI model talks about a brand for a query: a positive/neutral/negative split per model with the verbatim phrases driving the tone, plus an aggregate across models.",
+  inputSchema: z.object({
+    query: z.string().min(1).describe("The query whose answers are scored for brand sentiment."),
+    brand: z.string().min(1).describe("The brand to score sentiment for in each model answer."),
+    models: z.array(modelEnum).nonempty().optional().describe("Models to query. Defaults to all.")
+  }),
+  execute: async (input) => aivPost("/sentiment", input)
+});
+var aivKeywords = createTool({
+  id: "cite42_keywords",
+  description: "Classic keyword data for a seed term: monthly search volume, CPC, competition, and (optionally) related keyword ideas. A flat-priced data tool, not an AI-model query.",
+  inputSchema: z.object({
+    seed: z.string().min(1).describe("Seed keyword to fetch search volume, CPC, and competition for."),
+    country: z.string().optional().describe('ISO-2 country code for localized metrics. Defaults to "us".'),
+    ideas: z.boolean().optional().describe("When true, also return related keyword ideas with their volumes.")
+  }),
+  execute: async (input) => aivPost("/keywords", input)
+});
+var aivTrends = createTool({
+  id: "cite42_trends",
+  description: "Google Trends interest-over-time, related and rising queries, and a rising/falling/stable label for a term. A flat-priced data tool, not an AI-model query.",
+  inputSchema: z.object({
+    term: z.string().min(1).describe("Search term to pull Google Trends interest-over-time for."),
+    timeframe: z.string().optional().describe('Trends window, e.g. "past_12_months", "past_30_days", "past_5_years".'),
+    geo: z.string().optional().describe('Optional location name (e.g. "United States"). Worldwide when omitted.')
+  }),
+  execute: async (input) => aivPost("/trends", input)
+});
+
+// src/stdio.ts
+var server = new MCPServer({
+  id: "cite42",
+  name: "Cite42",
+  version: "0.1.0",
+  description: "AI search data API: query ChatGPT, Claude, Perplexity, and Gemini.",
+  tools: {
+    cite42_search: aivSearch,
+    cite42_rankings: aivRankings,
+    cite42_compare: aivCompare,
+    cite42_citations: aivCitations,
+    cite42_sentiment: aivSentiment,
+    cite42_keywords: aivKeywords,
+    cite42_trends: aivTrends
+  }
+});
+server.startStdio().catch((error) => {
+  console.error("[@cite42/mcp] Fatal error:", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@cite42/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the Cite42 AI search data API. Use Claude Desktop and other LLM clients to query AI search engines.",
+  "license": "MIT",
+  "type": "module",
+  "bin": "dist/stdio.mjs",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup && chmod +x dist/stdio.mjs",
+    "dev": "tsup --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@mastra/core": "^1.35.0",
+    "@mastra/mcp": "^1.7.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.27",
+    "tsup": "^8.0.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": ["mcp", "model-context-protocol", "ai", "search", "llm", "claude"],
+  "engines": {
+    "node": ">=18"
+  }
+}