@geogenio/mcp-server 1.0.0

package/src/tools.ts

@@ -0,0 +1,520 @@
+/**
+ * GeoGen MCP Tool Definitions
+ * Registers all tools on the MCP server, mapping to the /v1 REST API.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { GeoGenApiClient } from "./api-client.js";
+
+/** Helper: wrap API responses as MCP text content */
+function jsonContent(data: unknown) {
+  return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
+}
+
+/** Helper: wrap errors as MCP text content */
+function errorContent(err: unknown) {
+  const message = err instanceof Error ? err.message : String(err);
+  return {
+    content: [{ type: "text" as const, 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: McpServer, client: GeoGenApiClient) {
+  // ────────────────────────────────────────────────────────────
+  // 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);
+      }
+    }
+  );
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./build",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules"]
+}