visibilia-mcp 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# visibilia-mcp — Brand Pulse MCP server
+
+Conecta cualquier cliente MCP (Claude Desktop, Cline, Cursor MCP) con tu cuenta de [VisibilIA](https://visibilia.app) para preguntar en lenguaje natural cómo aparece tu marca en los motores de IA.
+
+## Qué hace
+
+Expone 5 herramientas MCP que llaman a la API REST de VisibilIA con tu Bearer token:
+
+| Tool | Qué responde |
+|---|---|
+| `get_brand_visibility` | Scores de mention rate, share of voice, sentiment, citation y composite por LLM |
+| `list_intents` | Tus intents (topics) trackeados |
+| `list_top_cited_sources` | Top dominios que cita la IA sobre tu sector (últimos 30 días) |
+| `list_recent_mentions` | Menciones recientes con sentiment y posición |
+| `compare_with_competitor` | Tu share of voice vs un competidor concreto |
+
+## Setup en Claude Desktop
+
+1. Genera una API key en https://visibilia.app/app/settings/api (requiere plan Starter o Pro).
+2. Edita `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "visibilia": {
+      "command": "npx",
+      "args": ["-y", "visibilia-mcp"],
+      "env": {
+        "VISIBILIA_API_KEY": "vsk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
+      }
+    }
+  }
+}
+```
+
+3. Reinicia Claude Desktop. Verás un nuevo set de herramientas con prefijo `visibilia_*` en el selector de tools.
+
+Ejemplos de prompt en Claude Desktop una vez conectado:
+
+- "Resúmeme la visibilidad de mi marca esta semana"
+- "¿Qué dominios cita la IA más sobre mi sector?"
+- "Compara mi share of voice con [competidor X] estos últimos 7 días"
+
+## Setup en otros clientes
+
+El servidor habla MCP estándar sobre stdio. Cualquier cliente que soporte `command + args + env` lo puede usar.
+
+## Self-hosted / API base personalizada
+
+Si tienes una instalación on-prem de VisibilIA, pasa también `VISIBILIA_API_BASE`:
+
+```json
+"env": {
+  "VISIBILIA_API_KEY": "vsk_live_...",
+  "VISIBILIA_API_BASE": "https://visibilia.midominio.com"
+}
+```
+
+## Rate limits
+
+- Starter: 60 requests/minuto por API key
+- Pro: 240 requests/minuto por API key
+
+El servidor reporta el error de rate limit de vuelta al cliente MCP con un mensaje claro.
+
+## Desarrollo local
+
+```bash
+pnpm install
+pnpm dev   # tsx src/index.ts
+pnpm build # genera dist/
+```
+
+## Licencia
+
+MIT. Repo principal en https://github.com/JpegzaCreate/visibilia.

package/dist/index.js

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * VisibilIA MCP Server — Brand Pulse.
+ *
+ * Exposes 5 tools that any MCP client (Claude Desktop, Cline, Cursor MCP)
+ * can call to inspect your brand's visibility in AI generative engines:
+ *
+ *   - get_brand_visibility  — latest scores + share of voice
+ *   - list_intents          — your tracked search intents
+ *   - list_top_cited_sources — which URLs the LLMs cite about your sector
+ *   - list_recent_mentions  — last N mentions (with sentiment)
+ *   - compare_with_competitor — head-to-head SoV vs a named competitor
+ *
+ * Auth via Bearer token (the same API key you generate in
+ * /app/settings/api). Pass it via env var VISIBILIA_API_KEY.
+ *
+ * Transport: stdio. Configure in Claude Desktop:
+ *
+ *   {
+ *     "mcpServers": {
+ *       "visibilia": {
+ *         "command": "npx",
+ *         "args": ["-y", "@visibilia/mcp"],
+ *         "env": { "VISIBILIA_API_KEY": "vsk_live_..." }
+ *       }
+ *     }
+ *   }
+ */
+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.VISIBILIA_API_KEY;
+const API_BASE = process.env.VISIBILIA_API_BASE?.replace(/\/+$/, "") ??
+    "https://visibilia.app";
+if (!API_KEY) {
+    // Don't crash before the SDK handshake — log to stderr (stdio reserves
+    // stdout for protocol traffic) and continue. Tools will return a clear
+    // error on each call so the user sees it in Claude Desktop.
+    console.error("[visibilia-mcp] VISIBILIA_API_KEY not set. Generate one at https://visibilia.app/app/settings/api and re-launch.");
+}
+async function callApi(path, params = {}) {
+    if (!API_KEY) {
+        return {
+            error: "VISIBILIA_API_KEY no configurada. Genera una key en https://visibilia.app/app/settings/api y añádela al env del MCP server.",
+        };
+    }
+    const url = new URL(`${API_BASE}${path}`);
+    for (const [k, v] of Object.entries(params)) {
+        if (v)
+            url.searchParams.set(k, v);
+    }
+    try {
+        const res = await fetch(url, {
+            headers: { Authorization: `Bearer ${API_KEY}` },
+        });
+        if (res.status === 401) {
+            return {
+                error: "API key inválida o revocada. Revisa en /app/settings/api o regenera una nueva.",
+            };
+        }
+        if (res.status === 429) {
+            return {
+                error: "Rate limit excedido (60 req/min Starter, 240 req/min Pro). Espera un minuto y reintenta.",
+            };
+        }
+        if (!res.ok) {
+            return { error: `API error ${res.status}: ${(await res.text()).slice(0, 200)}` };
+        }
+        return (await res.json());
+    }
+    catch (err) {
+        return {
+            error: err instanceof Error
+                ? `Transport error: ${err.message}`
+                : "Transport error",
+        };
+    }
+}
+function asText(obj) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(obj, null, 2) }],
+    };
+}
+const server = new McpServer({
+    name: "visibilia",
+    version: "0.1.0",
+});
+server.tool("get_brand_visibility", "Latest visibility scores (mention_rate, share_of_voice, sentiment, citation, composite) per LLM provider for your active brand. Use this to answer questions like 'how visible is my brand in AI this week?'", {
+    intent_id: z
+        .string()
+        .uuid()
+        .optional()
+        .describe("Filter to a specific intent UUID. Omit for org-wide."),
+    from: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional()
+        .describe("ISO date (YYYY-MM-DD). Defaults to last 7 days."),
+    to: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional()
+        .describe("ISO date (YYYY-MM-DD). Defaults to today."),
+}, async (args) => {
+    const from = args.from ??
+        new Date(Date.now() - 7 * 24 * 60 * 60 * 1000)
+            .toISOString()
+            .slice(0, 10);
+    const params = { from, limit: "100" };
+    if (args.intent_id)
+        params.intent_id = args.intent_id;
+    if (args.to)
+        params.to = args.to;
+    const out = await callApi("/api/v1/scores", params);
+    return asText(out);
+});
+server.tool("list_intents", "List the search intents (topics) tracked for your active brand. Each intent has prompts that get scanned across LLMs.", {}, async () => {
+    const out = await callApi("/api/v1/intents", { limit: "100" });
+    return asText(out);
+});
+server.tool("list_top_cited_sources", "Top domains the LLMs cite when answering about your sector. Helpful to know where you need authority (e.g. 'Reddit and YouTube dominate, you should target them').", {
+    from: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional()
+        .describe("ISO date. Defaults to last 30 days."),
+}, async (args) => {
+    const from = args.from ??
+        new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)
+            .toISOString()
+            .slice(0, 10);
+    const out = await callApi("/api/v1/citations", {
+        from,
+        group_by: "domain",
+        limit: "20",
+    });
+    return asText(out);
+});
+server.tool("list_recent_mentions", "Recent brand mentions detected in LLM responses, with sentiment + position + citation URLs. Useful for 'what are people saying about us'.", {
+    intent_id: z.string().uuid().optional(),
+    limit: z.number().int().min(1).max(100).default(20),
+}, async (args) => {
+    const params = { limit: String(args.limit ?? 20) };
+    if (args.intent_id)
+        params.intent_id = args.intent_id;
+    const out = await callApi("/api/v1/mentions", params);
+    return asText(out);
+});
+server.tool("compare_with_competitor", "Compare your brand's share of voice against a specific competitor for the last 7 days, per LLM provider.", {
+    competitor_name: z.string().min(1).max(120),
+}, async (args) => {
+    // We don't have a dedicated comparison endpoint yet, so we approximate
+    // with two queries: get scores (your SoV) and get mentions filtered by
+    // competitor_id is not null. The Claude client can then reason over
+    // both JSON blobs. Future: dedicated /api/v1/competitors endpoint.
+    const from = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000)
+        .toISOString()
+        .slice(0, 10);
+    const [scores, mentions] = await Promise.all([
+        callApi("/api/v1/scores", { from, limit: "100" }),
+        callApi("/api/v1/mentions", { limit: "100" }),
+    ]);
+    return asText({
+        hint: `Filtra mentions por competitor_id no nulo y match_text que contenga "${args.competitor_name}" para calcular su share. Tu propia SoV está en scores.share_of_voice.`,
+        competitor_name: args.competitor_name,
+        from,
+        your_scores: scores,
+        raw_mentions: mentions,
+    });
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[visibilia-mcp] connected via stdio");
+}
+main().catch((err) => {
+    console.error("[visibilia-mcp] fatal:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "visibilia-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for VisibilIA — query your brand visibility in ChatGPT/Gemini/Perplexity/Claude from any MCP client (Claude Desktop, Cline, etc).",
+  "type": "module",
+  "bin": {
+    "visibilia-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "visibilia",
+    "geo",
+    "ai-visibility",
+    "llm",
+    "chatgpt",
+    "perplexity",
+    "gemini",
+    "claude"
+  ],
+  "author": "VisibilIA",
+  "license": "MIT",
+  "homepage": "https://visibilia.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JpegzaCreate/visibilia.git",
+    "directory": "mcp-server"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0",
+    "@types/node": "^20.0.0"
+  }
+}