@mentionova/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,85 @@
+# Mentionova MCP Server
+
+Connect AI assistants to your [Mentionova](https://app.mentionova.com) data. Query workspaces, prompts, runs, citations, brand mentions, and more directly from Claude Code, Claude Desktop, or any MCP-compatible client.
+
+## Prerequisites
+
+- A Mentionova account on a **Scale plan or higher**
+- An API key (create one at Settings > API in the Mentionova dashboard)
+- Node.js 18+
+
+## Setup
+
+### Claude Code
+
+Add to your Claude Code settings (`~/.claude/settings.json` or project-level `.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "mentionova": {
+      "command": "npx",
+      "args": ["-y", "@mentionova/mcp-server"],
+      "env": {
+        "MENTIONOVA_API_KEY": "mn_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):
+
+```json
+{
+  "mcpServers": {
+    "mentionova": {
+      "command": "npx",
+      "args": ["-y", "@mentionova/mcp-server"],
+      "env": {
+        "MENTIONOVA_API_KEY": "mn_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+Then restart Claude Code or Claude Desktop.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `mentionova_list_workspaces` | List all workspaces in your organization |
+| `mentionova_get_workspace` | Get details for a specific workspace |
+| `mentionova_list_prompts` | List tracked prompts (search queries) in a workspace |
+| `mentionova_list_runs` | List prompt executions with status and channel results |
+| `mentionova_list_citations` | List URLs cited by AI engines, with filters |
+| `mentionova_list_mentions` | List verified brand mentions and recommendations |
+| `mentionova_list_pages` | List tracked pages from citations and GSC |
+| `mentionova_list_grids` | List content grids in a workspace |
+| `mentionova_list_alerts` | List notifications and alerts |
+| `mentionova_list_contacts` | List enriched contacts for cited domains |
+
+## Example Usage
+
+Once connected, just ask your AI assistant naturally:
+
+- "List my Mentionova workspaces"
+- "Show me the latest citations for workspace [name]"
+- "Which prompts are active in [workspace]?"
+- "Get all ChatGPT citations from the last 7 days"
+- "Show brand mentions for the most recent run"
+
+## API Key Permissions
+
+Your API key's permissions control which tools are available. Configure read/write access per resource in Settings > API in the Mentionova dashboard.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `MENTIONOVA_API_KEY` | Yes | Your Mentionova API key (`mn_live_...`) |
+| `MENTIONOVA_BASE_URL` | No | API base URL (default: `https://app.mentionova.com`) |

package/index.js

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const API_KEY = process.env.MENTIONOVA_API_KEY;
+const BASE_URL = process.env.MENTIONOVA_BASE_URL || "https://app.mentionova.com";
+
+if (!API_KEY) {
+  console.error("MENTIONOVA_API_KEY environment variable is required");
+  process.exit(1);
+}
+
+async function api(path, params = {}) {
+  const url = new URL(`/api/v1${path}`, BASE_URL);
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, String(v));
+  }
+
+  const res = await fetch(url.toString(), {
+    headers: { Authorization: `Bearer ${API_KEY}` },
+  });
+
+  const json = await res.json();
+  if (!res.ok) throw new Error(json.error || `API error ${res.status}`);
+  return json;
+}
+
+const server = new McpServer({
+  name: "mentionova",
+  version: "1.0.0",
+});
+
+// --- Workspaces ---
+
+server.tool(
+  "mentionova_list_workspaces",
+  "List all workspaces in your Mentionova organization",
+  {
+    limit: z.number().optional().describe("Results per page (1-100, default 50)"),
+    offset: z.number().optional().describe("Offset for pagination"),
+  },
+  async ({ limit, offset }) => {
+    const data = await api("/workspaces", { limit, offset });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+server.tool(
+  "mentionova_get_workspace",
+  "Get details for a specific workspace",
+  {
+    workspace_id: z.string().describe("Workspace UUID"),
+  },
+  async ({ workspace_id }) => {
+    const data = await api(`/workspaces/${workspace_id}`);
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// --- Prompts ---
+
+server.tool(
+  "mentionova_list_prompts",
+  "List prompts (search queries) tracked in a workspace. These are the questions being monitored across AI engines.",
+  {
+    workspace_id: z.string().describe("Workspace UUID"),
+    status: z.enum(["active", "paused", "archived"]).optional().describe("Filter by status"),
+    limit: z.number().optional().describe("Results per page (1-100, default 50)"),
+    offset: z.number().optional().describe("Offset for pagination"),
+  },
+  async ({ workspace_id, status, limit, offset }) => {
+    const data = await api(`/workspaces/${workspace_id}/prompts`, { status, limit, offset });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// --- Runs ---
+
+server.tool(
+  "mentionova_list_runs",
+  "List prompt runs (executions). Each run queries AI engines and captures their responses, citations, and mention data.",
+  {
+    workspace_id: z.string().describe("Workspace UUID"),
+    status: z.enum(["pending", "running", "completed", "failed", "partial"]).optional().describe("Filter by run status"),
+    prompt_id: z.string().optional().describe("Filter by prompt UUID"),
+    limit: z.number().optional().describe("Results per page (1-100, default 50)"),
+    offset: z.number().optional().describe("Offset for pagination"),
+  },
+  async ({ workspace_id, status, prompt_id, limit, offset }) => {
+    const data = await api(`/workspaces/${workspace_id}/runs`, { status, prompt_id, limit, offset });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// --- Citations ---
+
+server.tool(
+  "mentionova_list_citations",
+  "List citations (URLs referenced by AI engines in their responses). Filter by channel, date range, competitor status, etc.",
+  {
+    workspace_id: z.string().describe("Workspace UUID"),
+    channel: z.enum(["chatgpt", "claude", "perplexity", "gemini", "google", "reddit"]).optional().describe("Filter by AI engine"),
+    prompt_id: z.string().optional().describe("Filter by prompt UUID"),
+    run_id: z.string().optional().describe("Filter by run UUID"),
+    is_competitor: z.enum(["true", "false"]).optional().describe("Filter competitor citations"),
+    from: z.string().optional().describe("Start date (ISO 8601)"),
+    to: z.string().optional().describe("End date (ISO 8601)"),
+    limit: z.number().optional().describe("Results per page (1-100, default 50)"),
+    offset: z.number().optional().describe("Offset for pagination"),
+  },
+  async ({ workspace_id, channel, prompt_id, run_id, is_competitor, from, to, limit, offset }) => {
+    const data = await api(`/workspaces/${workspace_id}/citations`, {
+      channel, prompt_id, run_id, is_competitor, from, to, limit, offset,
+    });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// --- Verified Mentions ---
+
+server.tool(
+  "mentionova_list_mentions",
+  "List LLM-verified brand mentions and recommendations. Each entry shows whether the brand (and competitors) were mentioned or recommended in an AI engine response.",
+  {
+    workspace_id: z.string().describe("Workspace UUID"),
+    channel: z.enum(["chatgpt", "claude", "perplexity", "gemini", "google", "reddit"]).optional().describe("Filter by AI engine"),
+    run_id: z.string().optional().describe("Filter by run UUID"),
+    limit: z.number().optional().describe("Results per page (1-100, default 50)"),
+    offset: z.number().optional().describe("Offset for pagination"),
+  },
+  async ({ workspace_id, channel, run_id, limit, offset }) => {
+    const data = await api(`/workspaces/${workspace_id}/mentions`, { channel, run_id, limit, offset });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// --- Pages ---
+
+server.tool(
+  "mentionova_list_pages",
+  "List tracked pages (URLs from citations and GSC) for a workspace",
+  {
+    workspace_id: z.string().describe("Workspace UUID"),
+    limit: z.number().optional().describe("Results per page (1-100, default 50)"),
+    offset: z.number().optional().describe("Offset for pagination"),
+  },
+  async ({ workspace_id, limit, offset }) => {
+    const data = await api(`/workspaces/${workspace_id}/pages`, { limit, offset });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// --- Grids ---
+
+server.tool(
+  "mentionova_list_grids",
+  "List content grids (AI-powered spreadsheets) in a workspace",
+  {
+    workspace_id: z.string().describe("Workspace UUID"),
+    status: z.enum(["active", "archived"]).optional().describe("Filter by status (default: active)"),
+    limit: z.number().optional().describe("Results per page (1-100, default 50)"),
+    offset: z.number().optional().describe("Offset for pagination"),
+  },
+  async ({ workspace_id, status, limit, offset }) => {
+    const data = await api(`/workspaces/${workspace_id}/grids`, { status, limit, offset });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// --- Alerts ---
+
+server.tool(
+  "mentionova_list_alerts",
+  "List alerts and notifications for a workspace (run completions, failures, Reddit mentions, etc.)",
+  {
+    workspace_id: z.string().describe("Workspace UUID"),
+    limit: z.number().optional().describe("Results per page (1-100, default 50)"),
+    offset: z.number().optional().describe("Offset for pagination"),
+  },
+  async ({ workspace_id, limit, offset }) => {
+    const data = await api(`/workspaces/${workspace_id}/alerts`, { limit, offset });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// --- Contacts ---
+
+server.tool(
+  "mentionova_list_contacts",
+  "List enriched contacts for domains that appear in citations. Includes org info, employee count, and contact details from Apollo.",
+  {
+    workspace_id: z.string().describe("Workspace UUID"),
+    domain: z.string().optional().describe("Filter by specific domain"),
+    limit: z.number().optional().describe("Results per page (1-100, default 50)"),
+    offset: z.number().optional().describe("Offset for pagination"),
+  },
+  async ({ workspace_id, domain, limit, offset }) => {
+    const data = await api(`/workspaces/${workspace_id}/contacts`, { domain, limit, offset });
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+  }
+);
+
+// Start the server
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@mentionova/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for the Mentionova API - connect AI assistants to your AI search visibility data",
+  "type": "module",
+  "main": "index.js",
+  "bin": {
+    "mentionova-mcp": "index.js"
+  },
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "mentionova",
+    "ai-visibility",
+    "seo",
+    "citations",
+    "claude",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Loudspeaker-2025/mentionova-mcp"
+  },
+  "homepage": "https://mentionova.com/docs",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  }
+}