@geogenio/mcp-server 1.0.1 → 1.0.2

package/Dockerfile

@@ -0,0 +1,8 @@
+FROM node:20-slim
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN npm install
+COPY . .
+RUN npm run build
+EXPOSE 3100
+CMD ["node", "build/index.js", "--http"]

package/build/api-client.js

@@ -54,6 +54,10 @@ export class GeoGenApiClient {
             body: JSON.stringify(body),
         });
     }
+    async getTrackingStatus(params) {
+        const query = this.buildQuery(params);
+        return this.request(`/v1/entities/tracking-status${query}`);
+    }
     async deletePrompt(promptId) {
         const query = this.buildQuery({ promptId });
         return this.request(`/v1/entities/deleteprompt${query}`, {
@@ -115,4 +119,21 @@ export class GeoGenApiClient {
         const query = this.buildQuery(params);
         return this.request(`/v1/query-fanouts${query}`);
     }
+    // ── Actions (Actionables + Tasks) ─────────────────────────────
+    async getEntityActions(params) {
+        const query = this.buildQuery(params);
+        return this.request(`/v1/entities/actions${query}`);
+    }
+    async dismissActionable(actionableId) {
+        return this.request("/v1/entities/actions/dismiss", {
+            method: "POST",
+            body: JSON.stringify({ actionableId }),
+        });
+    }
+    async updateTaskStatus(taskId, status) {
+        return this.request("/v1/entities/actions/update-status", {
+            method: "POST",
+            body: JSON.stringify({ taskId, status }),
+        });
+    }
 }

package/build/index.js

@@ -6,42 +6,138 @@
  * 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  - GeoGen API URL (required)
+ *   GEOGEN_API_KEY   - Your GeoGen workspace API key (required for stdio mode)
+ *   GEOGEN_BASE_URL  - GeoGen API URL (default: https://api.geogen.io)
+ *
+ * Transport modes:
+ *   --http           - Start as HTTP server with SSE transport (for OpenAI Agent Builder, remote clients)
+ *   --port <number>  - Port for HTTP mode (default: 3100)
+ *   (default)        - Stdio transport (for Claude Desktop, Cursor, etc.)
+ *
+ * In HTTP mode, clients pass their API key via the Authorization header on the
+ * initial GET /sse request. No server-side API key is needed.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.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 https://api.geogen.io");
-        process.exit(1);
-    }
-    // Create the API client
+import http from "node:http";
+const DEFAULT_BASE_URL = "https://api.geogen.io";
+function createServer(apiKey, baseUrl) {
     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
+    return server;
+}
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const httpMode = args.includes("--http");
+    const portIdx = args.indexOf("--port");
+    const port = portIdx !== -1 ? parseInt(args[portIdx + 1], 10) : 3100;
+    return { httpMode, port };
+}
+/** Extract Bearer token from Authorization header */
+function extractApiKey(req) {
+    const auth = req.headers.authorization;
+    if (!auth)
+        return null;
+    if (auth.startsWith("Bearer "))
+        return auth.slice(7);
+    return auth;
+}
+async function startStdio(apiKey, baseUrl) {
+    const server = createServer(apiKey, baseUrl);
     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);
+    await server.connect(transport);
+    console.error("GeoGen MCP Server running on stdio");
+}
+async function startHttp(baseUrl, port) {
+    // Track active SSE transports by session ID
+    const transports = new Map();
+    const httpServer = http.createServer(async (req, res) => {
+        // CORS headers for remote clients
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+        if (req.method === "OPTIONS") {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        const url = new URL(req.url || "/", `http://localhost:${port}`);
+        // GET /sse — establish SSE connection (client sends API key here)
+        if (req.method === "GET" && url.pathname === "/sse") {
+            const apiKey = extractApiKey(req);
+            if (!apiKey) {
+                res.writeHead(401, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Missing Authorization header. Pass your GeoGen API key as: Authorization: Bearer <key>" }));
+                return;
+            }
+            const server = createServer(apiKey, baseUrl);
+            const transport = new SSEServerTransport("/messages", res);
+            transports.set(transport.sessionId, transport);
+            transport.onclose = () => {
+                transports.delete(transport.sessionId);
+            };
+            await server.connect(transport);
+            return;
+        }
+        // POST /messages — receive messages from client
+        if (req.method === "POST" && url.pathname === "/messages") {
+            const sessionId = url.searchParams.get("sessionId");
+            if (!sessionId) {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Missing sessionId" }));
+                return;
+            }
+            const transport = transports.get(sessionId);
+            if (!transport) {
+                res.writeHead(404, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Session not found" }));
+                return;
+            }
+            await transport.handlePostMessage(req, res);
+            return;
+        }
+        // Health check
+        if (req.method === "GET" && url.pathname === "/") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ status: "ok", name: "geogen-mcp-server", transport: "sse" }));
+            return;
+        }
+        // 404 for anything else
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Not found" }));
+    });
+    httpServer.listen(port, () => {
+        console.error(`GeoGen MCP Server running on http://localhost:${port}`);
+        console.error(`  SSE endpoint: http://localhost:${port}/sse`);
+        console.error(`  Messages:     http://localhost:${port}/messages`);
     });
 }
-main();
+async function main() {
+    const { httpMode, port } = parseArgs();
+    const baseUrl = process.env.GEOGEN_BASE_URL || DEFAULT_BASE_URL;
+    if (httpMode) {
+        // HTTP mode: no API key needed on server — clients pass their own
+        await startHttp(baseUrl, port);
+    }
+    else {
+        // Stdio mode: API key from env (local usage)
+        const apiKey = process.env.GEOGEN_API_KEY;
+        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);
+        }
+        await startStdio(apiKey, baseUrl);
+    }
+}
+main().catch((error) => {
+    console.error("Failed to start GeoGen MCP Server:", error);
+    process.exit(1);
+});

package/build/tools.js

@@ -190,7 +190,20 @@ export function registerTools(server, client) {
         }
     });
     // ────────────────────────────────────────────────────────────
-    // 10. GET RESPONSES
+    // 10. GET TRACKING STATUS
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_tracking_status", "Get the mention check status for an entity — when the last check completed, when the next is scheduled, and whether one is currently running", {
+        entityId: entityIdSchema,
+    }, async (args) => {
+        try {
+            return jsonContent(await client.getTrackingStatus(args));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 11. 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,
@@ -399,4 +412,50 @@ export function registerTools(server, client) {
             return errorContent(err);
         }
     });
+    // ────────────────────────────────────────────────────────────
+    // 19. GET ENTITY ACTIONS (Actionables + Tasks)
+    // ────────────────────────────────────────────────────────────
+    server.tool("get_entity_actions", "Get AI-generated actionable recommendations and their associated tasks for an entity. Actionables are SEO improvement suggestions; tasks are actionables that have been moved to the kanban board for tracking.", {
+        entityId: entityIdSchema,
+        status: z
+            .enum(["active", "dismissed", "in_task"])
+            .optional()
+            .describe("Filter actionables by status (default: all)"),
+    }, async (args) => {
+        try {
+            return jsonContent(await client.getEntityActions(args));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 20. DISMISS ACTIONABLE
+    // ────────────────────────────────────────────────────────────
+    server.tool("dismiss_actionable", "Dismiss an actionable recommendation so it no longer appears in the active feed. Dismissed actionables free up slots for new ones to be generated on the next mention check.", {
+        actionableId: z.string().describe("The actionable ID to dismiss"),
+    }, async (args) => {
+        try {
+            return jsonContent(await client.dismissActionable(args.actionableId));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 21. UPDATE TASK STATUS
+    // ────────────────────────────────────────────────────────────
+    server.tool("update_task_status", "Update the status of a task on the kanban board. Move tasks through the workflow: not_started → in_progress → in_review → done.", {
+        taskId: z.string().describe("The task ID to update"),
+        status: z
+            .enum(["not_started", "in_progress", "in_review", "done"])
+            .describe("New status for the task"),
+    }, async (args) => {
+        try {
+            return jsonContent(await client.updateTaskStatus(args.taskId, args.status));
+        }
+        catch (err) {
+            return errorContent(err);
+        }
+    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geogenio/mcp-server",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "MCP server for GeoGen LLM SEO tracking platform",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "scripts": {
     "build": "tsc",
     "start": "node build/index.js",
+    "start:http": "node build/index.js --http",
     "dev": "tsc --watch"
   },
   "dependencies": {

package/src/api-client.ts

@@ -96,6 +96,11 @@ export class GeoGenApiClient {
     });
   }
 
+  async getTrackingStatus(params: { entityId: string }): Promise<any> {
+    const query = this.buildQuery(params);
+    return this.request(`/v1/entities/tracking-status${query}`);
+  }
+
   async deletePrompt(promptId: string): Promise<any> {
     const query = this.buildQuery({ promptId });
     return this.request(`/v1/entities/deleteprompt${query}`, {
@@ -253,4 +258,28 @@ export class GeoGenApiClient {
     const query = this.buildQuery(params);
     return this.request(`/v1/query-fanouts${query}`);
   }
+
+  // ── Actions (Actionables + Tasks) ─────────────────────────────
+
+  async getEntityActions(params: {
+    entityId: string;
+    status?: string;
+  }): Promise<any> {
+    const query = this.buildQuery(params);
+    return this.request(`/v1/entities/actions${query}`);
+  }
+
+  async dismissActionable(actionableId: string): Promise<any> {
+    return this.request("/v1/entities/actions/dismiss", {
+      method: "POST",
+      body: JSON.stringify({ actionableId }),
+    });
+  }
+
+  async updateTaskStatus(taskId: string, status: string): Promise<any> {
+    return this.request("/v1/entities/actions/update-status", {
+      method: "POST",
+      body: JSON.stringify({ taskId, status }),
+    });
+  }
 }

package/src/index.ts

@@ -7,51 +7,158 @@
  * 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  - GeoGen API URL (required)
+ *   GEOGEN_API_KEY   - Your GeoGen workspace API key (required for stdio mode)
+ *   GEOGEN_BASE_URL  - GeoGen API URL (default: https://api.geogen.io)
+ *
+ * Transport modes:
+ *   --http           - Start as HTTP server with SSE transport (for OpenAI Agent Builder, remote clients)
+ *   --port <number>  - Port for HTTP mode (default: 3100)
+ *   (default)        - Stdio transport (for Claude Desktop, Cursor, etc.)
+ *
+ * In HTTP mode, clients pass their API key via the Authorization header on the
+ * initial GET /sse request. No server-side API key is needed.
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { GeoGenApiClient } from "./api-client.js";
 import { registerTools } from "./tools.js";
+import http from "node:http";
 
-function main() {
-  const apiKey = process.env.GEOGEN_API_KEY;
-  const baseUrl = process.env.GEOGEN_BASE_URL;
+const DEFAULT_BASE_URL = "https://api.geogen.io";
 
-  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 https://api.geogen.io");
-    process.exit(1);
-  }
-
-  // Create the API client
+function createServer(apiKey: string, baseUrl: string): McpServer {
   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);
+  return server;
+}
 
-  // Connect via stdio transport and start
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const httpMode = args.includes("--http");
+  const portIdx = args.indexOf("--port");
+  const port = portIdx !== -1 ? parseInt(args[portIdx + 1], 10) : 3100;
+  return { httpMode, port };
+}
+
+/** Extract Bearer token from Authorization header */
+function extractApiKey(req: http.IncomingMessage): string | null {
+  const auth = req.headers.authorization;
+  if (!auth) return null;
+  if (auth.startsWith("Bearer ")) return auth.slice(7);
+  return auth;
+}
+
+async function startStdio(apiKey: string, baseUrl: string) {
+  const server = createServer(apiKey, baseUrl);
   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);
+  await server.connect(transport);
+  console.error("GeoGen MCP Server running on stdio");
+}
+
+async function startHttp(baseUrl: string, port: number) {
+  // Track active SSE transports by session ID
+  const transports = new Map<string, SSEServerTransport>();
+
+  const httpServer = http.createServer(async (req, res) => {
+    // CORS headers for remote clients
+    res.setHeader("Access-Control-Allow-Origin", "*");
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+
+    if (req.method === "OPTIONS") {
+      res.writeHead(204);
+      res.end();
+      return;
+    }
+
+    const url = new URL(req.url || "/", `http://localhost:${port}`);
+
+    // GET /sse — establish SSE connection (client sends API key here)
+    if (req.method === "GET" && url.pathname === "/sse") {
+      const apiKey = extractApiKey(req);
+      if (!apiKey) {
+        res.writeHead(401, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Missing Authorization header. Pass your GeoGen API key as: Authorization: Bearer <key>" }));
+        return;
+      }
+
+      const server = createServer(apiKey, baseUrl);
+      const transport = new SSEServerTransport("/messages", res);
+      transports.set(transport.sessionId, transport);
+
+      transport.onclose = () => {
+        transports.delete(transport.sessionId);
+      };
+
+      await server.connect(transport);
+      return;
+    }
+
+    // POST /messages — receive messages from client
+    if (req.method === "POST" && url.pathname === "/messages") {
+      const sessionId = url.searchParams.get("sessionId");
+      if (!sessionId) {
+        res.writeHead(400, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Missing sessionId" }));
+        return;
+      }
+
+      const transport = transports.get(sessionId);
+      if (!transport) {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Session not found" }));
+        return;
+      }
+
+      await transport.handlePostMessage(req, res);
+      return;
+    }
+
+    // Health check
+    if (req.method === "GET" && url.pathname === "/") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "ok", name: "geogen-mcp-server", transport: "sse" }));
+      return;
+    }
+
+    // 404 for anything else
+    res.writeHead(404, { "Content-Type": "application/json" });
+    res.end(JSON.stringify({ error: "Not found" }));
+  });
+
+  httpServer.listen(port, () => {
+    console.error(`GeoGen MCP Server running on http://localhost:${port}`);
+    console.error(`  SSE endpoint: http://localhost:${port}/sse`);
+    console.error(`  Messages:     http://localhost:${port}/messages`);
   });
 }
 
-main();
+async function main() {
+  const { httpMode, port } = parseArgs();
+  const baseUrl = process.env.GEOGEN_BASE_URL || DEFAULT_BASE_URL;
+
+  if (httpMode) {
+    // HTTP mode: no API key needed on server — clients pass their own
+    await startHttp(baseUrl, port);
+  } else {
+    // Stdio mode: API key from env (local usage)
+    const apiKey = process.env.GEOGEN_API_KEY;
+    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);
+    }
+    await startStdio(apiKey, baseUrl);
+  }
+}
+
+main().catch((error) => {
+  console.error("Failed to start GeoGen MCP Server:", error);
+  process.exit(1);
+});

package/src/tools.ts

@@ -252,7 +252,25 @@ export function registerTools(server: McpServer, client: GeoGenApiClient) {
   );
 
   // ────────────────────────────────────────────────────────────
-  // 10. GET RESPONSES
+  // 10. GET TRACKING STATUS
+  // ────────────────────────────────────────────────────────────
+  server.tool(
+    "get_tracking_status",
+    "Get the mention check status for an entity — when the last check completed, when the next is scheduled, and whether one is currently running",
+    {
+      entityId: entityIdSchema,
+    },
+    async (args) => {
+      try {
+        return jsonContent(await client.getTrackingStatus(args));
+      } catch (err) {
+        return errorContent(err);
+      }
+    }
+  );
+
+  // ────────────────────────────────────────────────────────────
+  // 11. GET RESPONSES
   // ────────────────────────────────────────────────────────────
   server.tool(
     "get_responses",
@@ -517,4 +535,65 @@ export function registerTools(server: McpServer, client: GeoGenApiClient) {
       }
     }
   );
+
+  // ────────────────────────────────────────────────────────────
+  // 19. GET ENTITY ACTIONS (Actionables + Tasks)
+  // ────────────────────────────────────────────────────────────
+  server.tool(
+    "get_entity_actions",
+    "Get AI-generated actionable recommendations and their associated tasks for an entity. Actionables are SEO improvement suggestions; tasks are actionables that have been moved to the kanban board for tracking.",
+    {
+      entityId: entityIdSchema,
+      status: z
+        .enum(["active", "dismissed", "in_task"])
+        .optional()
+        .describe("Filter actionables by status (default: all)"),
+    },
+    async (args) => {
+      try {
+        return jsonContent(await client.getEntityActions(args));
+      } catch (err) {
+        return errorContent(err);
+      }
+    }
+  );
+
+  // ────────────────────────────────────────────────────────────
+  // 20. DISMISS ACTIONABLE
+  // ────────────────────────────────────────────────────────────
+  server.tool(
+    "dismiss_actionable",
+    "Dismiss an actionable recommendation so it no longer appears in the active feed. Dismissed actionables free up slots for new ones to be generated on the next mention check.",
+    {
+      actionableId: z.string().describe("The actionable ID to dismiss"),
+    },
+    async (args) => {
+      try {
+        return jsonContent(await client.dismissActionable(args.actionableId));
+      } catch (err) {
+        return errorContent(err);
+      }
+    }
+  );
+
+  // ────────────────────────────────────────────────────────────
+  // 21. UPDATE TASK STATUS
+  // ────────────────────────────────────────────────────────────
+  server.tool(
+    "update_task_status",
+    "Update the status of a task on the kanban board. Move tasks through the workflow: not_started → in_progress → in_review → done.",
+    {
+      taskId: z.string().describe("The task ID to update"),
+      status: z
+        .enum(["not_started", "in_progress", "in_review", "done"])
+        .describe("New status for the task"),
+    },
+    async (args) => {
+      try {
+        return jsonContent(await client.updateTaskStatus(args.taskId, args.status));
+      } catch (err) {
+        return errorContent(err);
+      }
+    }
+  );
 }