@geogenio/mcp-server 1.0.0

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@geogenio/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for GeoGen LLM SEO tracking platform",
+  "type": "module",
+  "bin": {
+    "geogen-mcp": "./build/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/src/api-client.ts

@@ -0,0 +1,256 @@
+/**
+ * GeoGen API Client
+ * Wraps all /v1 REST endpoints for use by MCP tool handlers.
+ */
+
+export interface ApiClientConfig {
+  baseUrl: string;
+  apiKey: string;
+}
+
+export class GeoGenApiClient {
+  private baseUrl: string;
+  private apiKey: string;
+
+  constructor(config: ApiClientConfig) {
+    // Strip trailing slash from base URL
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+    this.apiKey = config.apiKey;
+  }
+
+  private async request(path: string, options?: RequestInit): Promise<any> {
+    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;
+  }
+
+  private buildQuery(params: Record<string, string | undefined>): string {
+    const entries = Object.entries(params).filter(
+      (entry): entry is [string, string] => entry[1] !== undefined && entry[1] !== ""
+    );
+    if (entries.length === 0) return "";
+    return "?" + new URLSearchParams(entries).toString();
+  }
+
+  // ── Entities ──────────────────────────────────────────────
+
+  async getEntities(): Promise<any> {
+    return this.request("/v1/entities");
+  }
+
+  async createEntity(body: {
+    name: string;
+    domain: string;
+    description?: string;
+    language?: string;
+    geolocation?: string;
+    models?: string[];
+    trackingType?: string;
+    generatePrompts?: boolean;
+    startTracking?: boolean;
+  }): Promise<any> {
+    return this.request("/v1/entities", {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  }
+
+  // ── Prompts ───────────────────────────────────────────────
+
+  async getEntityPrompts(params: {
+    entityId: string;
+    period?: string;
+    startDate?: string;
+    endDate?: string;
+    tags?: string;
+  }): Promise<any> {
+    const query = this.buildQuery(params);
+    return this.request(`/v1/entities/prompts${query}`);
+  }
+
+  async addPrompts(body: {
+    entityId: string;
+    prompt?: string;
+    prompts?: Array<{ prompt: string; language?: string; geolocation?: string }>;
+    language?: string;
+    geolocation?: string;
+  }): Promise<any> {
+    return this.request("/v1/entities/addprompt", {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  }
+
+  async deletePrompt(promptId: string): Promise<any> {
+    const query = this.buildQuery({ promptId });
+    return this.request(`/v1/entities/deleteprompt${query}`, {
+      method: "DELETE",
+    });
+  }
+
+  // ── Workspace ─────────────────────────────────────────────
+
+  async getWorkspace(): Promise<any> {
+    return this.request("/v1/workspace");
+  }
+
+  async getWorkspaceMembers(): Promise<any> {
+    return this.request("/v1/workspace/members");
+  }
+
+  async getWorkspaceTags(): Promise<any> {
+    return this.request("/v1/workspace/tags");
+  }
+
+  // ── Models ────────────────────────────────────────────────
+
+  async getModels(): Promise<any> {
+    return this.request("/v1/models");
+  }
+
+  // ── Responses ─────────────────────────────────────────────
+
+  async getResponses(params: {
+    entityId: string;
+    period?: string;
+    startDate?: string;
+    endDate?: string;
+    models?: string;
+    tags?: string;
+    promptIds?: string;
+    mentionStatus?: string;
+    limit?: string;
+    offset?: string;
+  }): Promise<any> {
+    const query = this.buildQuery(params);
+    return this.request(`/v1/responses${query}`);
+  }
+
+  async getResponseDetails(params: {
+    responseId: string;
+    entityId: string;
+  }): Promise<any> {
+    const query = this.buildQuery(params);
+    return this.request(`/v1/responses/details${query}`);
+  }
+
+  // ── Citations ─────────────────────────────────────────────
+
+  async getCitations(params: {
+    entityId: string;
+    period?: string;
+    startDate?: string;
+    endDate?: string;
+    models?: string;
+    tags?: string;
+    promptIds?: string;
+    limit?: string;
+    offset?: string;
+  }): Promise<any> {
+    const query = this.buildQuery(params);
+    return this.request(`/v1/entities/citations${query}`);
+  }
+
+  async getCitationsTrend(params: {
+    entityId: string;
+    period?: string;
+    startDate?: string;
+    endDate?: string;
+    models?: string;
+    tags?: string;
+    promptIds?: string;
+    topN?: string;
+  }): Promise<any> {
+    const query = this.buildQuery(params);
+    return this.request(`/v1/trends/citations${query}`);
+  }
+
+  async getCitationDetails(params: {
+    entityId: string;
+    citedEntityUuid: string;
+    period?: string;
+    startDate?: string;
+    endDate?: string;
+    models?: string;
+    limit?: string;
+    offset?: string;
+  }): Promise<any> {
+    const query = this.buildQuery(params);
+    return this.request(`/v1/entities/citations/details${query}`);
+  }
+
+  // ── Competitors ───────────────────────────────────────────
+
+  async getCompetitors(params: {
+    entityId: string;
+    period?: string;
+    startDate?: string;
+    endDate?: string;
+    models?: string;
+    competitorsOnly?: string;
+    limit?: string;
+    offset?: string;
+  }): Promise<any> {
+    const query = this.buildQuery(params);
+    return this.request(`/v1/competitors${query}`);
+  }
+
+  // ── Trends ────────────────────────────────────────────────
+
+  async getVisibilityTrend(params: {
+    entityId: string;
+    period?: string;
+    startDate?: string;
+    endDate?: string;
+    models?: string;
+    tags?: string;
+    promptIds?: string;
+  }): Promise<any> {
+    const query = this.buildQuery(params);
+    return this.request(`/v1/trends/visibility${query}`);
+  }
+
+  async getSentimentTrend(params: {
+    entityId: string;
+    period?: string;
+    startDate?: string;
+    endDate?: string;
+    models?: string;
+    tags?: string;
+  }): Promise<any> {
+    const query = this.buildQuery(params);
+    return this.request(`/v1/trends/sentiment${query}`);
+  }
+
+  // ── Query Fanouts ─────────────────────────────────────────
+
+  async getQueryFanouts(params: {
+    entityId: string;
+    period?: string;
+    startDate?: string;
+    endDate?: string;
+    models?: string;
+    tags?: string;
+    limit?: string;
+    offset?: string;
+    search?: string;
+  }): Promise<any> {
+    const query = this.buildQuery(params);
+    return this.request(`/v1/query-fanouts${query}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+#!/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();