kompa-mcp-server

MCP (Model Context Protocol)-Server, der Kompa-Social-Listening-Daten — Buzzes, Sentiment-Aufschlüsselung, Trendlinie, heiße Themen, eindeutige Autoren — als Tools bereitstellt, die jeder MCP-Client aufrufen kann. Entwickelt, damit du direkt in Claude (Desktop oder Code) über Kompa-Daten chatten kannst, statt eine eigenständige Chat-Oberfläche zu nutzen.

Dieses Paket ist unabhängig von der kompa-chat Next.js-App – es verwendet nur dieselbe Kompa-GraphQL-API und denselben Anmeldevorgang, übertragen auf einen einfachen MCP-Server. Es bietet zwei Einstiegspunkte:

• build/index.js — Stdio-Transport, für lokale MCP-Clients, die einen untergeordneten Prozess starten (Claude Desktop/Code über lokale Konfiguration).

• build/http.js — Streamable-HTTP-Transport, mehrinstanzenfähig: Eine gehostete Connector-URL kann viele Kunden bedienen. Siehe DEPLOY.md für den vollständigen VPS-Bereitstellungsleitfaden (systemd + Caddy + Onboarding eines Kunden).

Konto- und Themenkonfiguration

Es gibt kein separates API-Schlüsselsystem. Jeder Kunde hat bereits einen Kompa-Benutzernamen/ein Passwort – das wird auch hier über einen Tool-Aufruf verwendet:

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

Ruf es einmal zu Beginn einer Konversation auf (Claude erledigt das automatisch, sobald du deine Anmeldedaten/Themen erwähnst, oder du kannst es explizit anfordern). Alle anderen Tools verwenden dann dieses Konto und die topic_ids, bis du configure_account erneut aufrufst – es ist nicht nötig, sie bei jedem Aufruf zu wiederholen, obwohl du weiterhin topicIds pro Aufruf übergeben kannst, um sie zu überschreiben.

Dies existiert anstelle einer Header-basierten Authentifizierung, weil Clades benutzerdefinierte Anfrage-Header für Connectors derzeit in einer eingeschränkten Beta-Phase sind – siehe den Hinweis „Auth model“ in DEPLOY.md.

Für den Stdio-Einstiegspunkt kannst du den Tool-Aufruf vollständig überspringen, indem du die Umgebungsvariablen KOMPA_USERNAME/KOMPA_PASSWORD/KOMPA_DEFAULT_INDEXES setzt – das Konto wird in diesem Fall beim Start vorkonfiguriert.

Tools

Alle Datentools akzeptieren fromDate/toDate ("YYYY-MM-DD HH:mm:ss"), optionale types, query, sentiments und optionale topicIds (Fallback auf die über configure_account gesetzten topicIds).

Setup

npm install
npm run build

Kopiere .env.example als Referenz (nur für den Stdio-Einstiegspunkt relevant – siehe oben).

Eigenständige Verwendung (vor der Veröffentlichung)

Zeige jeden MCP-Client direkt auf die gebaute Einstiegsdatei:

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

• Claude Desktop: Füge diesen Block in claude_desktop_config.json ein (Einstellungen → Entwickler → Konfiguration bearbeiten).

• Claude Code: Füge denselben mcpServers-Block in eine .mcp.json in deinem Projektstammverzeichnis ein oder führe aus:

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

Starte den Client nach der Konfigurationsänderung neu und sag dann im Chat etwa „Mein Kompa-Konto ist X/Y, Themen-ID Z – wie ist die Sentiment-Aufschlüsselung für die Abfrage 'foo' zwischen 2026-08-01 und 2026-08-21?" – Claude ruft configure_account auf und dann das Datentool.

Veröffentlichung auf npm

Damit Benutzer über npx kompa-mcp-server installieren können, statt einen lokalen Pfad zu verwenden:

npm login
npm publish --access public

Dann wird die MCP-Konfiguration zu:

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

Veröffentlichung in einem Claude-Code-Plugin-Marketplace

Sowohl Claude Code als auch, für Team/Enterprise-Organisationen, claude.ai selbst können ein Plugin-Marketplace direkt aus einem Git-Repository hinzufügen – kein npm-Publish nötig, da marketplace-example/plugins/kompa-mcp/.claude-plugin/plugin.json auf deinen gehosteten HTTP-Connector zeigt (siehe DEPLOY.md), nicht auf ein lokales Paket. Layout:

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

Als Maintainer:

1. Bearbeite die url in marketplace-example/plugins/kompa-mcp/.claude-plugin/plugin.json zu deiner tatsächlichen bereitgestellten Domain (https://mcp.yourdomain.com/mcp).

2. Pushe ein Repository mit dem marketplace-example/-Layout (benenne den Ordner um, was immer du als Repository-Stamm haben möchtest) zu GitHub – öffentlich, oder privat, wenn es nur deine Organisation benötigt (privat erfordert, dass alle Installierenden über ihre GitHub/Git-Anmeldedaten Repo-Zugriff haben).

3. Teile die Repository-URL.

Als Claude-Code-Benutzer, der es installiert:

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

Als claude.ai Team/Enterprise-Organisation (kein CLI, nur GUI):

1. Org-Besitzer: Organisationseinstellungen → Connectors/Plugins → Plugin-Marketplace hinzufügen → „Aus einem Repository hinzufügen“ → dieselbe GitHub-URL einfügen.

2. Mitglieder: Anpassen → Plugins, dort kompa-mcp-plugin aus deinem Marketplace finden, auf Installieren/Verbinden klicken.

Für einzelne Free/Pro/Max-Konten ohne Organisation steht dieser repo-basierte Marketplace-Pfad nicht zur Verfügung – verwende stattdessen den Zip-Upload-Ablauf in PLUGIN.md.

Hinweise / Einschränkungen

• Der Login verwendet denselben Benutzername+Passwort-Ablauf wie kompa-chat's auth.ts – kein OAuth, keine Browser-Automatisierung.

• Das Zugriffstoken wird pro Benutzername prozessintern zwischengespeichert und 5 Minuten vor Ablauf aktualisiert.

• topicIds müssen gültige Kompa-Projektindex-IDs sein, auf die das Konto Zugriff hat – dieser Server entdeckt oder listet sie nicht für dich.

• Im HTTP-Modus liegt die Konto-/Themenkonfiguration nur im Speicher dieser MCP-Sitzung – beim Schließen der Konversation/Sitzung gehen sie verloren, und die nächste Sitzung muss configure_account erneut aufrufen.