kompa-mcp-server

Servidor MCP (Model Context Protocol) que expone los datos de social listening de Kompa — buzzes, desglose de sentimiento, línea de tendencia, temas candentes, autores únicos — como herramientas que cualquier cliente MCP puede llamar. Diseñado para que puedas conversar sobre los datos de Kompa directamente dentro de Claude (Desktop o Code) en lugar de una interfaz de chat independiente.

Este paquete es independiente de la aplicación kompa-chat de Next.js — solo reutiliza la misma API GraphQL de Kompa y el flujo de inicio de sesión, adaptados a un servidor MCP simple. Incluye dos puntos de entrada:

• build/index.js — transporte stdio, para clientes MCP locales que lanzan un proceso hijo (Claude Desktop/Code mediante configuración local).

• build/http.js — transporte HTTP Streamable, multitenant: una URL de conector alojada puede servir a muchos clientes. Consulta DEPLOY.md para la guía completa de despliegue en VPS (systemd + Caddy + incorporación de un cliente).

Configuración de cuenta y temas

No hay un sistema de claves API separado. Cada cliente ya tiene un nombre de usuario/contraseña de Kompa — eso es lo que usan aquí también, mediante una llamada a una herramienta:

configure_account({ username, password, topicIds: ["topic-id-1", ...] })

Haz la llamada una vez al inicio de una conversación (Claude lo hará automáticamente en cuanto menciones tus credenciales/temas, o puedes pedírselo explícitamente). El resto de herramientas reutilizan entonces esa cuenta y esos topic_ids hasta que vuelvas a llamar a configure_account — no es necesario repetirlos en cada llamada, aunque aún puedes pasar topicIds por llamada para sobrescribirlos.

Esto existe en lugar de la autenticación basada en cabeceras porque las cabeceras de solicitud personalizadas de Claude para conectores están actualmente en un despliegue beta restringido — consulta la nota "Auth model" en DEPLOY.md.

Para el punto de entrada stdio, puedes omitir por completo la llamada a la herramienta estableciendo las variables de entorno KOMPA_USERNAME/KOMPA_PASSWORD/KOMPA_DEFAULT_INDEXES — en ese caso, la cuenta queda preconfigurada al inicio.

Herramientas

Todas las herramientas de datos aceptan fromDate/toDate ("YYYY-MM-DD HH:mm:ss"), y opcionalmente types, query, sentiments y topicIds (si no se proporcionan, se usan los topicIds establecidos mediante configure_account).

Configuración

npm install
npm run build

Copia .env.example como referencia (solo relevante para el punto de entrada stdio — ver arriba).

Usarlo de forma independiente (antes de publicar)

Apunta cualquier cliente MCP directamente al archivo de entrada compilado:

{
  "mcpServers": {
    "kompa": {
      "command": "node",
      "args": ["/absolute/path/to/kompa-mcp-server/build/index.js"]
    }
  }
}

• Claude Desktop: coloca este bloque en claude_desktop_config.json (Settings → Developer → Edit Config).

• Claude Code: coloca el mismo bloque mcpServers en un .mcp.json en la raíz de tu proyecto, o ejecuta:

  claude mcp add kompa -- node /absolute/path/to/kompa-mcp-server/build/index.js

Reinicia el cliente después de editar la configuración y, a continuación, en el chat escribe algo como "Mi cuenta de Kompa es X/Y, ID de tema Z — ¿cuál es el desglose de sentimiento para la consulta 'foo' entre 2026-08-01 y 2026-08-21?" — Claude llama a configure_account y luego a la herramienta de datos.

Publicar en npm

Para que los usuarios puedan instalar mediante npx kompa-mcp-server en lugar de una ruta local:

npm login
npm publish --access public

Entonces la configuración de MCP queda así:

{
  "mcpServers": {
    "kompa": {
      "command": "npx",
      "args": ["-y", "kompa-mcp-server"]
    }
  }
}

Publicar en un marketplace de plugins de Claude Code

Tanto Claude Code como, para organizaciones Team/Enterprise, la propia claude.ai pueden añadir un marketplace de plugins directamente desde un repositorio git — aquí no hace falta publicar en npm, ya que marketplace-example/plugins/kompa-mcp/.claude-plugin/plugin.json apunta a tu conector HTTP alojado (consulta DEPLOY.md), no a un paquete local. Estructura:

marketplace-example/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── kompa-mcp/
        └── .claude-plugin/
            └── plugin.json      # edit the connector URL in here first

Como mantenedor:

1. Edita la url en marketplace-example/plugins/kompa-mcp/.claude-plugin/plugin.json para que apunte a tu dominio real desplegado (https://mcp.yourdomain.com/mcp).

2. Sube a GitHub un repositorio que contenga la estructura marketplace-example/ (renombra la carpeta como quieras que se llame la raíz del repositorio) — público, o privado si solo tu organización lo necesita (privado requiere que todos los que instalen tengan acceso al repositorio mediante sus credenciales de GitHub/git).

3. Comparte la URL del repositorio.

Como usuario de Claude Code que lo instala:

/plugin marketplace add https://github.com/<you>/<marketplace-repo>
/plugin install kompa-mcp-plugin@<marketplace-name>

Como organización Team/Enterprise de claude.ai (sin CLI, solo GUI):

1. Propietario de la organización: Organization settings → Connectors/Plugins → Add plugin marketplace → "Add from a repository" → pega la misma URL de GitHub.

2. Miembros: Customize → Plugins, buscad kompa-mcp-plugin en la lista de vuestro marketplace y haced clic en install/connect.

Para cuentas individuales Free/Pro/Max sin organización, esta vía de marketplace basada en repositorio no está disponible — usa en su lugar el flujo de carga de zip descrito en PLUGIN.md.

Notas / limitaciones

• El inicio de sesión usa el mismo flujo de nombre de usuario+contraseña que auth.ts de kompa-chat — sin OAuth, sin automatización de navegador.

• El token de acceso se almacena en caché dentro del proceso por nombre de usuario y se renueva 5 minutos antes de que expire.

• topicIds deben ser IDs de índice de proyecto de Kompa válidos a los que la cuenta tenga acceso — este servidor no los descubre ni los lista por ti.

• En modo HTTP, la configuración de cuenta/temas vive solo en la memoria de esa sesión de MCP — al cerrar la conversación/sesión se pierde, y la siguiente sesión debe llamar a configure_account de nuevo.