@geogenio/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,116 @@
+# GeoGen MCP Server
+
+MCP (Model Context Protocol) server for the GeoGen LLM SEO tracking platform. Lets AI assistants query your LLM visibility data, manage entities, and analyze trends via natural language.
+
+## Setup
+
+### 1. Install & Build
+
+```bash
+cd mcp-server
+npm install
+npm run build
+```
+
+### 2. Get Your API Key
+
+Go to your GeoGen workspace **Settings > API Keys** and create a new key.
+
+### 3. Configure Your AI Client
+
+#### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "geogen": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-server/build/index.js"],
+      "env": {
+        "GEOGEN_API_KEY": "your-api-key-here",
+        "GEOGEN_BASE_URL": "https://your-app.convex.site"
+      }
+    }
+  }
+}
+```
+
+#### Claude Code
+
+```bash
+claude mcp add geogen -- node /absolute/path/to/mcp-server/build/index.js
+```
+
+Then set the environment variables in your shell or `.env` file:
+```bash
+export GEOGEN_API_KEY="your-api-key-here"
+export GEOGEN_BASE_URL="https://your-app.convex.site"
+```
+
+#### Cursor / Windsurf
+
+Add to your MCP settings (see each IDE's documentation for the config location):
+
+```json
+{
+  "geogen": {
+    "command": "node",
+    "args": ["/absolute/path/to/mcp-server/build/index.js"],
+    "env": {
+      "GEOGEN_API_KEY": "your-api-key-here",
+      "GEOGEN_BASE_URL": "https://your-app.convex.site"
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Read Operations
+
+| Tool | Description |
+|------|-------------|
+| `get_entities` | List all tracked websites/entities |
+| `get_workspace` | Workspace usage, limits, credit balance |
+| `get_workspace_members` | List team members |
+| `get_workspace_tags` | List all tags |
+| `get_models` | Available LLM models |
+| `get_entity_prompts` | Prompts with stats for an entity |
+| `get_responses` | LLM responses with mention status |
+| `get_response_details` | Detailed response data (mentions, citations, fanouts) |
+| `get_citations` | Top cited domains for an entity |
+| `get_citation_details` | Detailed URLs for a cited domain |
+| `get_competitors` | Competitor visibility leaderboard |
+| `get_citations_trend` | Daily citation trend for top cited domains over time |
+| `get_visibility_trend` | Visibility trend over time |
+| `get_sentiment_trend` | Sentiment trend over time |
+| `get_query_fanouts` | Web search queries LLMs perform |
+
+### Write Operations
+
+| Tool | Description |
+|------|-------------|
+| `create_entity` | Create a new tracked entity (consumes credits) |
+| `add_prompts` | Add single or bulk prompts to an entity |
+| `delete_prompt` | Delete a prompt |
+
+## Example Queries
+
+Once configured, you can ask your AI assistant things like:
+
+- *"List all my tracked entities"*
+- *"What's the visibility trend for entity X over the last 30 days?"*
+- *"Show me the top competitors for my website"*
+- *"Which domains are LLMs citing when they talk about my brand?"*
+- *"What search queries are LLMs running about my entity?"*
+- *"Add a new tracking prompt: 'What is the best project management tool?'"*
+- *"Give me a full SEO report comparing my entity against competitors"*
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GEOGEN_API_KEY` | Yes | Your GeoGen workspace API key |
+| `GEOGEN_BASE_URL` | Yes | Your Convex site URL (e.g. `https://your-app.convex.site`) |

package/build/api-client.js

@@ -0,0 +1,118 @@
+/**
+ * GeoGen API Client
+ * Wraps all /v1 REST endpoints for use by MCP tool handlers.
+ */
+export class GeoGenApiClient {
+    baseUrl;
+    apiKey;
+    constructor(config) {
+        // Strip trailing slash from base URL
+        this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+        this.apiKey = config.apiKey;
+    }
+    async request(path, options) {
+        const url = `${this.baseUrl}${path}`;
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`,
+                ...options?.headers,
+            },
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            const errorMsg = data?.error || data?.message || `HTTP ${response.status}`;
+            throw new Error(errorMsg);
+        }
+        return data;
+    }
+    buildQuery(params) {
+        const entries = Object.entries(params).filter((entry) => entry[1] !== undefined && entry[1] !== "");
+        if (entries.length === 0)
+            return "";
+        return "?" + new URLSearchParams(entries).toString();
+    }
+    // ── Entities ──────────────────────────────────────────────
+    async getEntities() {
+        return this.request("/v1/entities");
+    }
+    async createEntity(body) {
+        return this.request("/v1/entities", {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    // ── Prompts ───────────────────────────────────────────────
+    async getEntityPrompts(params) {
+        const query = this.buildQuery(params);
+        return this.request(`/v1/entities/prompts${query}`);
+    }
+    async addPrompts(body) {
+        return this.request("/v1/entities/addprompt", {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    }
+    async deletePrompt(promptId) {
+        const query = this.buildQuery({ promptId });
+        return this.request(`/v1/entities/deleteprompt${query}`, {
+            method: "DELETE",
+        });
+    }
+    // ── Workspace ─────────────────────────────────────────────
+    async getWorkspace() {
+        return this.request("/v1/workspace");
+    }
+    async getWorkspaceMembers() {
+        return this.request("/v1/workspace/members");
+    }
+    async getWorkspaceTags() {
+        return this.request("/v1/workspace/tags");
+    }
+    // ── Models ────────────────────────────────────────────────
+    async getModels() {
+        return this.request("/v1/models");
+    }
+    // ── Responses ─────────────────────────────────────────────
+    async getResponses(params) {
+        const query = this.buildQuery(params);
+        return this.request(`/v1/responses${query}`);
+    }
+    async getResponseDetails(params) {
+        const query = this.buildQuery(params);
+        return this.request(`/v1/responses/details${query}`);
+    }
+    // ── Citations ─────────────────────────────────────────────
+    async getCitations(params) {
+        const query = this.buildQuery(params);
+        return this.request(`/v1/entities/citations${query}`);
+    }
+    async getCitationsTrend(params) {
+        const query = this.buildQuery(params);
+        return this.request(`/v1/trends/citations${query}`);
+    }
+    async getCitationDetails(params) {
+        const query = this.buildQuery(params);
+        return this.request(`/v1/entities/citations/details${query}`);
+    }
+    // ── Competitors ───────────────────────────────────────────
+    async getCompetitors(params) {
+        const query = this.buildQuery(params);
+        return this.request(`/v1/competitors${query}`);
+    }
+    // ── Trends ────────────────────────────────────────────────
+    async getVisibilityTrend(params) {
+        const query = this.buildQuery(params);
+        return this.request(`/v1/trends/visibility${query}`);
+    }
+    async getSentimentTrend(params) {
+        const query = this.buildQuery(params);
+        return this.request(`/v1/trends/sentiment${query}`);
+    }
+    // ── Query Fanouts ─────────────────────────────────────────
+    async getQueryFanouts(params) {
+        const query = this.buildQuery(params);
+        return this.request(`/v1/query-fanouts${query}`);
+    }
+}

package/build/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * GeoGen MCP Server
+ *
+ * Exposes the GeoGen LLM SEO tracking API as MCP tools
+ * for AI assistants (Claude Desktop, Cursor, Windsurf, Claude Code, etc.)
+ *
+ * Configuration via environment variables:
+ *   GEOGEN_API_KEY   - Your GeoGen workspace API key (required)
+ *   GEOGEN_BASE_URL  - Your Convex site URL (required)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { GeoGenApiClient } from "./api-client.js";
+import { registerTools } from "./tools.js";
+function main() {
+    const apiKey = process.env.GEOGEN_API_KEY;
+    const baseUrl = process.env.GEOGEN_BASE_URL;
+    if (!apiKey) {
+        console.error("Error: GEOGEN_API_KEY environment variable is required.");
+        console.error("Set it to your GeoGen workspace API key.");
+        process.exit(1);
+    }
+    if (!baseUrl) {
+        console.error("Error: GEOGEN_BASE_URL environment variable is required.");
+        console.error("Set it to your Convex site URL (e.g. https://your-app.convex.site).");
+        process.exit(1);
+    }
+    // Create the API client
+    const client = new GeoGenApiClient({ baseUrl, apiKey });
+    // Create the MCP server
+    const server = new McpServer({
+        name: "geogen",
+        version: "1.0.0",
+    });
+    // Register all tools
+    registerTools(server, client);
+    // Connect via stdio transport and start
+    const transport = new StdioServerTransport();
+    server.connect(transport).then(() => {
+        console.error("GeoGen MCP Server running on stdio");
+    }).catch((error) => {
+        console.error("Failed to start GeoGen MCP Server:", error);
+        process.exit(1);
+    });
+}
+main();

package/build/tools.js

@@ -0,0 +1,402 @@
+/**
+ * GeoGen MCP Tool Definitions
+ * Registers all tools on the MCP server, mapping to the /v1 REST API.
+ */
+import { z } from "zod";
+/** Helper: wrap API responses as MCP text content */
+function jsonContent(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+/** Helper: wrap errors as MCP text content */
+function errorContent(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+// Reusable schema fragments
+const periodSchema = z
+    .enum(["7d", "14d", "30d"])
+    .optional()
+    .describe("Time period: 7d, 14d, or 30d (default: 30d)");
+const startDateSchema = z
+    .string()
+    .optional()
+    .describe("Start date (ISO format, e.g. 2025-01-01). Use with endDate instead of period.");
+const endDateSchema = z
+    .string()
+    .optional()
+    .describe("End date (ISO format, e.g. 2025-01-31). Use with startDate instead of period.");
+const entityIdSchema = z.string().describe("The entity ID to query");
+const modelsSchema = z
+    .string()
+    .optional()
+    .describe("Comma-separated model UUIDs to filter by");
+const tagsSchema = z
+    .string()
+    .optional()
+    .describe("Comma-separated tag IDs to filter by");
+const promptIdsSchema = z
+    .string()
+    .optional()
+    .describe("Comma-separated prompt IDs to filter by");
+const limitSchema = z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe("Max number of results to return");
+const offsetSchema = z
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("Number of results to skip (for pagination)");
+export function registerTools(server, client) {
+    // ────────────────────────────────────────────────────────────
+    // 1. GET ENTITIES
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_entities", "List all tracked websites/entities in your GeoGen workspace", {}, async () => {
+        try {
+            return jsonContent(await client.getEntities());
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 2. CREATE ENTITY
+    // ────────────────────────────────────────────────────────────
+    server.tool("create_entity", "Create a new tracked entity (website/brand) with optional AI-generated prompts. This consumes credits.", {
+        name: z.string().describe("Display name for the entity (e.g. 'My Company')"),
+        domain: z.string().describe("Domain to track (e.g. 'example.com')"),
+        description: z.string().optional().describe("Description of the entity for context"),
+        language: z.string().optional().describe("Language code (e.g. 'en', 'fr')"),
+        geolocation: z.string().optional().describe("Geolocation code"),
+        models: z.array(z.string()).optional().describe("Array of model UUIDs to track against"),
+        generatePrompts: z
+            .boolean()
+            .optional()
+            .describe("Auto-generate tracking prompts with AI (costs credits, default: true)"),
+        startTracking: z
+            .boolean()
+            .optional()
+            .describe("Start tracking immediately (default: true)"),
+    }, async (args) => {
+        try {
+            return jsonContent(await client.createEntity(args));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 3. GET WORKSPACE
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_workspace", "Get workspace usage, subscription, limits, and credit balance", {}, async () => {
+        try {
+            return jsonContent(await client.getWorkspace());
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 4. GET WORKSPACE MEMBERS
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_workspace_members", "List all team members in the workspace", {}, async () => {
+        try {
+            return jsonContent(await client.getWorkspaceMembers());
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 5. GET WORKSPACE TAGS
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_workspace_tags", "List all tags in the workspace (used to filter prompts)", {}, async () => {
+        try {
+            return jsonContent(await client.getWorkspaceTags());
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 6. GET MODELS
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_models", "List all available LLM models that can be tracked (ChatGPT, Claude, Perplexity, etc.)", {}, async () => {
+        try {
+            return jsonContent(await client.getModels());
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 7. GET ENTITY PROMPTS
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_entity_prompts", "Get all tracking prompts for a specific entity, with stats (visibility, mention rate, sentiment)", {
+        entityId: entityIdSchema,
+        period: periodSchema,
+        startDate: startDateSchema,
+        endDate: endDateSchema,
+        tags: tagsSchema,
+    }, async (args) => {
+        try {
+            return jsonContent(await client.getEntityPrompts(args));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 8. ADD PROMPTS
+    // ────────────────────────────────────────────────────────────
+    server.tool("add_prompts", "Add one or more tracking prompts to an entity. Single: provide 'prompt'. Bulk: provide 'prompts' array.", {
+        entityId: entityIdSchema,
+        prompt: z.string().optional().describe("Single prompt text to add"),
+        prompts: z
+            .array(z.object({
+            prompt: z.string().describe("Prompt text"),
+            language: z.string().optional().describe("Language code"),
+            geolocation: z.string().optional().describe("Geolocation code"),
+        }))
+            .optional()
+            .describe("Array of prompts for bulk upload"),
+        language: z.string().optional().describe("Language for single prompt"),
+        geolocation: z.string().optional().describe("Geolocation for single prompt"),
+    }, async (args) => {
+        try {
+            return jsonContent(await client.addPrompts(args));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 9. DELETE PROMPT
+    // ────────────────────────────────────────────────────────────
+    server.tool("delete_prompt", "Delete a tracking prompt by its ID", {
+        promptId: z.string().describe("The prompt ID to delete"),
+    }, async ({ promptId }) => {
+        try {
+            return jsonContent(await client.deletePrompt(promptId));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 10. GET RESPONSES
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_responses", "Get LLM responses for an entity with mention status. Filter by period, models, tags, or mention status.", {
+        entityId: entityIdSchema,
+        period: periodSchema,
+        startDate: startDateSchema,
+        endDate: endDateSchema,
+        models: modelsSchema,
+        tags: tagsSchema,
+        promptIds: promptIdsSchema,
+        mentionStatus: z
+            .enum(["all", "mentioned", "not-mentioned"])
+            .optional()
+            .describe("Filter by mention status"),
+        limit: limitSchema,
+        offset: offsetSchema,
+    }, async (args) => {
+        try {
+            return jsonContent(await client.getResponses({
+                ...args,
+                limit: args.limit?.toString(),
+                offset: args.offset?.toString(),
+            }));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 11. GET RESPONSE DETAILS
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_response_details", "Get detailed data for a single LLM response, including mentions, citations, and query fanouts", {
+        responseId: z.string().describe("The response ID"),
+        entityId: entityIdSchema,
+    }, async (args) => {
+        try {
+            return jsonContent(await client.getResponseDetails(args));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 12. GET CITATIONS
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_citations", "Get top cited domains for an entity — shows which websites LLMs reference when responding about this entity", {
+        entityId: entityIdSchema,
+        period: periodSchema,
+        startDate: startDateSchema,
+        endDate: endDateSchema,
+        models: modelsSchema,
+        tags: tagsSchema,
+        promptIds: promptIdsSchema,
+        limit: limitSchema,
+        offset: offsetSchema,
+    }, async (args) => {
+        try {
+            return jsonContent(await client.getCitations({
+                ...args,
+                limit: args.limit?.toString(),
+                offset: args.offset?.toString(),
+            }));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 13. GET CITATIONS TREND
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_citations_trend", "Get daily citation trend for top cited domains over time — shows how citation counts change day by day", {
+        entityId: entityIdSchema,
+        period: periodSchema,
+        startDate: startDateSchema,
+        endDate: endDateSchema,
+        models: modelsSchema,
+        tags: tagsSchema,
+        promptIds: promptIdsSchema,
+        topN: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Number of top cited domains to include in the trend (default: all)"),
+    }, async (args) => {
+        try {
+            return jsonContent(await client.getCitationsTrend({
+                ...args,
+                topN: args.topN?.toString(),
+            }));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 14. GET CITATION DETAILS
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_citation_details", "Get detailed URLs for a specific cited domain — shows exactly which pages LLMs are linking to", {
+        entityId: entityIdSchema,
+        citedEntityUuid: z.string().describe("UUID of the cited domain to drill into"),
+        period: periodSchema,
+        startDate: startDateSchema,
+        endDate: endDateSchema,
+        models: modelsSchema,
+        limit: limitSchema,
+        offset: offsetSchema,
+    }, async (args) => {
+        try {
+            return jsonContent(await client.getCitationDetails({
+                ...args,
+                limit: args.limit?.toString(),
+                offset: args.offset?.toString(),
+            }));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 15. GET COMPETITORS
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_competitors", "Get competitor visibility leaderboard — see how your entity ranks against competitors in LLM mentions", {
+        entityId: entityIdSchema,
+        period: periodSchema,
+        startDate: startDateSchema,
+        endDate: endDateSchema,
+        models: modelsSchema,
+        competitorsOnly: z
+            .boolean()
+            .optional()
+            .describe("If true, only show competitors (exclude your entity)"),
+        limit: limitSchema,
+        offset: offsetSchema,
+    }, async (args) => {
+        try {
+            return jsonContent(await client.getCompetitors({
+                ...args,
+                competitorsOnly: args.competitorsOnly?.toString(),
+                limit: args.limit?.toString(),
+                offset: args.offset?.toString(),
+            }));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 16. GET VISIBILITY TREND
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_visibility_trend", "Get visibility trend over time — daily breakdown of mention rate, total responses, and visibility percentage", {
+        entityId: entityIdSchema,
+        period: periodSchema,
+        startDate: startDateSchema,
+        endDate: endDateSchema,
+        models: modelsSchema,
+        tags: tagsSchema,
+        promptIds: promptIdsSchema,
+    }, async (args) => {
+        try {
+            return jsonContent(await client.getVisibilityTrend(args));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 17. GET SENTIMENT TREND
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_sentiment_trend", "Get sentiment trend over time — daily breakdown of average sentiment score and mention count", {
+        entityId: entityIdSchema,
+        period: periodSchema,
+        startDate: startDateSchema,
+        endDate: endDateSchema,
+        models: modelsSchema,
+        tags: tagsSchema,
+    }, async (args) => {
+        try {
+            return jsonContent(await client.getSentimentTrend(args));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 18. GET QUERY FANOUTS
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_query_fanouts", "Get web search queries that LLMs performed while generating responses — shows what LLMs search for when answering about your entity", {
+        entityId: entityIdSchema,
+        period: periodSchema,
+        startDate: startDateSchema,
+        endDate: endDateSchema,
+        models: modelsSchema,
+        tags: tagsSchema,
+        limit: limitSchema,
+        offset: offsetSchema,
+        search: z.string().optional().describe("Full-text search filter on query text"),
+    }, async (args) => {
+        try {
+            return jsonContent(await client.getQueryFanouts({
+                ...args,
+                limit: args.limit?.toString(),
+                offset: args.offset?.toString(),
+            }));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+}