Peec AI MCP Begleiter-Fertigkeit
Open-Source-Anleitung für KI-Agenten, die mit dem Peec AI MCP-Server arbeiten. Agentenunabhängig, projektunabhängig, CC BY 4.0. Teile und passe sie frei an; behalte die Quellenangabe bei.
Lebendes Dokument. Wenn du ein Verhalten entdeckst, das dieser Datei widerspricht – oder eine neue Peec-Funktion, die nicht abgedeckt ist – erstelle ein Issue oder PR unter github.com/rebelytics/peec-ai-mcp. Siehe
CONTRIBUTING.mdfür den Workflow.Die hier beschriebenen Verhaltensbeobachtungen sind aktuell ab April 2026. Peec entwickelt sich weiter; Dinge ändern sich.
1. Was Peec AI MCP ist (für den Agenten)
Peec AI (peec.ai) überwacht, wie Marken in KI-Suchmaschinen erscheinen (ChatGPT, AI Overviews, Perplexity, Gemini, Grok, Copilot, Claude, etc.), indem es täglich verfolgte Prompts ausführt und die Antworten analysiert. Der MCP-Server legt diese Daten – und die Fähigkeit, die zugrunde liegende Konfiguration zu ändern – für jeden MCP-fähigen Agenten offen.
Server-URL: https://api.peec.ai/mcp
Transport: Streamable HTTP
Authentifizierung: OAuth 2.0 (Browser-Zustimmung, Token bleibt bestehen)
Die Oberfläche ist größer, als die offiziellen Dokumente vermuten lassen: 27 Werkzeuge (15 schreibgeschützt, 8 schreibend, 4 destruktiv), plus 7 Schrägstrich-Befehl "Prompts", die vorgefertigte Analysen bündeln. Die offizielle /mcp/tools-Dokumentationsseite listet nur 13 Lese-Werkzeuge auf und lässt die Schreib-/destruktive Oberfläche vollständig aus (siehe §7.11 und §7.25).
Glossar der Kernbegriffe
Im gesamten Skill verwendete Begriffe. Jeder hat eine spezifische, nicht offensichtliche Bedeutung in Peecs Datenmodell.
- Sichtbarkeit (Visibility) – wie oft eine Marke in KI-Antworten erscheint.
erwähnungen ÷ gesamt verfolgte chats, zurückgegeben als Verhältnis 0–1 (UI zeigt 0–100). Siehe §7.3 / §7.37. - Stimmanteil (SoV) – der Anteil einer Marke an allen Erwähnungen im gesamten verfolgten Markenportfolio. Verhältnis 0–1 (UI zeigt 0–100). "Verfolgt" ist bedeutsam – siehe Position.
- Stimmung (Sentiment) – Wert 0–100, neutral bei 50. Formel:
50 + (sentiment_sum / sentiment_count) × 50. Siehe §7.3. - Position – durchschnittlicher Rang unter den verfolgten Marken, nicht insgesamt. Niedriger = besser. Siehe §7.4.
- Eigene Marke – die Zeile
is_own=trueinlist_brands. Jede andere Zeile ist ein verfolgter Wettbewerber. - Erwähnung (Mention) – der Markenname erscheint im Antworttext der KI, mit oder ohne Webabruf.
- Abruf (Retrieval) – die KI-Engine hat eine oder mehrere URLs während der Beantwortung abgerufen. Gezählt in
get_domain_reportundget_url_report. - Zitat (Citation) – eine abgerufene URL, die das Modell in seiner Antwort explizit referenziert. Alle Zitate sind Abrufe; nicht alle Abrufe werden zu Zitaten.
- Parametrisches Gedächtnis (Parametric memory) – das Modell hat aus Trainingsdaten geantwortet, ohne Webquellen abzurufen.
sources: []in einem Chat-Payload ist das Erkennungsmerkmal. - Fanout – wenn eine KI-Engine die Benutzeranfrage in Unterabfragen umschreibt, bevor sie sucht. Verfügbar gemacht über
list_search_queries(chat_id=...). - Scraper-Variante – eine Modell-ID mit dem Suffix
-scraper(z.B.chatgpt-scraper). Spielt Prompts durch die echte Konsumenten-App; erfasst, was Benutzer sehen, nicht die rohe API-Ausgabe. Für die Sichtbarkeitsüberwachung bevorzugen. Siehe §7.2. - UGC – nutzergenerierter Content. Einer von 8 Werten von
domain_report.classification, der Reddit, YouTube, Foren etc. abdeckt. Siehe §7.30. - Idempotent – sicher, zweimal ausgeführt zu werden. Peecs Soft-Deletes sind nicht idempotent – der zweite Aufruf gibt "nicht gefunden" zurück. Siehe §7.34.
- Soft-Delete – entfernt die Entität aus
list_*und Filter, behält sie aber serverseitig. Die einzige Form, die Peec bereitstellt. Siehe §7.34. - ID-Präfixe –
or_(Projekt),kw_(Marke – Legacy-Name aus Peecs Keyword-Tracking-Ursprüngen),pr_(Prompt),tp_(Thema),tg_(Tag),ch_(Chat). Undurchsichtige Namensraum-Marker, keine semantischen Typen (kw_ist eine Marke, kein Keyword).
1.1 Datenmodell – Marken, Prompts, Themen, Tags sind orthogonal
Der am häufigsten falsch interpretierte Teil von Peecs Oberfläche. Prompts "gehören nicht" zu Marken – es existiert kein Fremdschlüssel brand_id, und update_prompt kann einen Prompt nicht zwischen Marken verschieben.
Entitäten:
- Projekt (
or_...) – Root-Container; alles andere hängt von einem Projekt ab. - Marke (
kw_...) – ein Erkennungsmuster, das auf KI-Antworttexte angewendet wird. Felder:name,aliases,regex,domains,is_own. Keine Verknüpfung zu Prompts, Themen oder Tags. - Thema (
tp_...) – ordnerähnliche Gruppierung für Prompts. Ein Prompt hat null oder ein Thema. - Tag (
tg_...) – Label, das an Prompts angehängt wird. Ein Prompt trägt null oder mehrere Tags. - Prompt (
pr_...) – eine täglich verfolgte Frage. Felder:text,country_code,topic_id,tag_ids. Keinbrand_id-Feld. - Chat (
ch_...) – eine KI-Engine-Antwort auf einen Prompt an einem Tag. Chat-Text wird gegen das Erkennungsmuster jeder Marke gescannt, was die Anzahl der Erwähnungen und Markenberichte ergibt.
Die Beziehung Marke ↔ Prompt ist schreibgeschützt und indirekt. Prompts erzeugen Chats; Chats enthalten Antworttexte; die Markenerkennung wird bei der Aufnahme gegen diesen Text ausgeführt. Es gibt keinen Schreibpfad, der einen Prompt mit einer Marke verknüpft. "Zuweisen" oder "Verschieben" von Prompts zwischen Marken ist ein Kategoriefehler – Marken sind keine Container, sie sind Erkennungsmuster.
Praktische Implikationen:
update_promptmutiert nurtopic_idundtag_ids– nichttext, keine wie auch immer geartetebrand_id. Siehe §7.13.update_brandmutiert Erkennungsmuster (name,aliases,regex,domains). Keines referenziert Prompts.- Für "welche Prompts haben Marke X erwähnt", führe
list_chats(brand_id=...)aus und überprüfe die Spalteprompt_id. create_brandverwendet standardmäßigis_own=false– es erzeugt immer einen Wettbewerber. Die Wahl der eigenen Marke wird nicht über MCP bereitgestellt.- Die eigene TLD-Liste der Marke ist für die Klassifizierung wichtig. Wenn
domains=["example.de"], aber das Unternehmen auchexample.combetreibt, klassifiziert der Domain-Berichtexample.comalsCORPORATE, nicht alsOWN. Siehe §7.10.
Schnellstart – Erster Bericht in 3 Minuten
Setzt ein Peec AI-Konto (peec.ai) mit mindestens einem Projekt und einen MCP-fähigen Client voraus (im folgenden Beispiel wird Claude Desktop verwendet). Peec veröffentlicht offizielle client-spezifische Einrichtungsanweisungen unter docs.peec.ai/mcp/introduction; folge diesen und komme hierher zurück, sobald die Verbindung hergestellt ist.
- Verbinden. Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen → URL
https://api.peec.ai/mcp→ Speichern → auf "Connect" auf der Connector-Karte klicken → im Browser autorisieren. Der Klick auf "Connect" nach dem Speichern kann leicht übersehen werden. - Überprüfen. Frage den Agenten: "Liste meine Peec AI-Projekte auf." Erwarte mindestens eine
or_...Projekt-ID in einer tabellarischen JSON-Tabelle (§4). - Ersten Markenbericht abrufen. Frage: "Zeige für Projekt
<id>die Sichtbarkeit, Erwähnungen, SoV, Stimmung und Position meiner eigenen Marke der letzten 30 Tage, aufgeschlüsselt nach KI-Modell." Der Agent wirdlist_brands(findeis_own=true) →get_brand_report(filtere auf diesebrand_id, Dimensionmodel_id, Standard-30-Tage-Fenster) verketten. - Drei Interpretationsregeln, bevor du Zahlen meldest:
- Skalen sind in derselben Zeile gemischt.
visibilityundshare_of_voicewerden als 0–1-Verhältnisse zurückgegeben (multipliziere mit 100 für Prozent).sentimentist bereits 0–100 (neutral = 50).positionbeginnt bei 1 und niedriger ist besser. Behandle nicht alle vier als eine Skala. Details in §7.37. - Position ist der Rang unter verfolgten Marken, nicht insgesamt. Eine Position von 1,6 bedeutet "1,6. im konfigurierten Wettbewerber-Roster", nicht "2. insgesamt in ChatGPTs vollständiger Antwort". §7.4.
- Erwähnungen enthalten parametrische Antworten. Sichtbarkeit zählt jede Antwort, in der der Markenname im Text erscheint, einschließlich Antworten, bei denen die Engine keine einzige URL abgerufen hat. Abrufe und Zitate zählen nur echte Webabrufe. §7.5.
- Skalen sind in derselben Zeile gemischt.
- Leere Daten ≠ defektes Werkzeug. Engines, die Nullen zurückgeben, sind normalerweise in deinem Plan inaktiv (§7.1). Fünf verschiedene Ursachen für leere Ergebnisse sind in §7.8 katalogisiert – überprüfe diese Liste, bevor du "das Werkzeug ist defekt" folgerst.
Das ist die minimale nützliche Schleife. Für die vollständige Funktionskarte lies weiter – §8 enthält die sieben Rezepte, die Peecs veröffentlichte primäre Anwendungsfälle abdecken.
Pre-Flight-Checkliste – bevor du irgendwelche Zahlen meldest
Führe diese acht Punkte durch, bevor du Peec-Zahlen einem Menschen präsentierst.
- Metriktyp für jede Spalte identifiziert. Klassifiziere jede numerische Spalte als Verhältnis (0–1, multipliziere mit 100), Punktzahl (0–100, neutral bei 50 für Stimmung), Rang (1+, niedriger ist besser), Rate (kann 1,0 überschreiten) oder Zählung (Ganzzahl). Siehe §7.37. Wenn du den Typ nicht benennen kannst, zeige die Zahl nicht an.
- Skala auf das normalisiert, was der Mensch erwartet. Verhältnisse als Prozentwerte dargestellt (
0,33→33%, nicht0,33%). Stimmung als 0–100 belassen mit50 = neutralexplizit genannt. Position als Rang belassen mit "niedriger ist besser" hervorgehoben. Rate unverändert lassen, mit Anomalien (retrieval_rate=1.8) erklärt statt umgeschrieben. Siehe §7.3 / §7.37. - Position als Rang-unter-verfolgten-Marken gelesen, nicht insgesamt. Jede Positionsangabe wird mit dem Qualifikator "unter verfolgten Wettbewerbern" versehen. Siehe §7.4.
- Dimensionen und Filter gegen das Werkzeugschema validiert, nicht geraten. Gültige Dimensionen für
get_brand_report:prompt_id, model_id, model_channel_id, tag_id, topic_id, date, country_code, chat_id.brand_idist nur filterbar, niemals eine Dimension. Siehe §7.15 / §8.1. - Spaltennamen gegen die tatsächliche Antwort-Payload bestätigt. Gehe nicht davon aus, dass eine Spalte existiert, weil ein Rezept vorschlägt, danach zu sortieren. Standardmäßiges undimensioniertes
get_domain_reportgibtretrieved_percentage,retrieval_rate,citation_ratezurück – nichtretrieval_count. Siehe §7.39 / §8.10. - Inaktive Engines gekennzeichnet, nicht als Null-Sichtbarkeit gemeldet. Überprüfe
list_models(is_active=true), bevor du behauptest, eine Marke sei auf Perplexity/Claude/Gemini unsichtbar. Siehe §7.1 / §7.8. - Leere Ergebnisse anhand der Fünf-Ursachen-Liste in §7.8 diagnostiziert, bevor du etwas als defekt folgerst. Soft-gelöschte Marken, inaktive Engines, parametrische Antworten, Plandatenlimits und Filter-Nichtübereinstimmung sehen alle gleich aus.
- Nicht aufgelöste
kw_...-IDs als Soft-gelöscht gekennzeichnet, nicht als Fehler. Siehe §7.38.
Wenn ein Punkt fehlschlägt, stoppe und behebe es, bevor du berichtest. Teilweise Erfolge erzeugen teilweises Vertrauen.
2. Einrichtung
Verbindungsparameter (gleich für jeden Client):
- URL:
https://api.peec.ai/mcp - Transport: Streamable HTTP
- Authentifizierung: OAuth 2.0 (Browser-Zustimmung, Token bleibt bestehen)
- Bereich: Lesen + Schreiben (trotz offizieller Dokumentation, die nur Lesen angibt – siehe §7.11)
Für client-spezifische Installationsanweisungen folge Peecs offiziellen Einrichtungsdokumentationen unter docs.peec.ai/mcp/introduction. Peec pflegt die aktuelle Liste der unterstützten Clients und deren Schritt-für-Schritt-Verbindungsabläufe; diese Fertigkeit dupliziert diesen Inhalt bewusst nicht, da er umgebungsabhängig ist und schnell veraltet.
Netzwerk-Sandboxing: Wenn du in einer sandboxed Agentenumgebung ausgeführt wirst (Cowork, bestimmte Cloud-IDEs, Unternehmensproxys), stelle sicher, dass api.peec.ai auf der Ausgangs-Whitelist steht. Eine blockierte Anfrage zeigt sich als generischer Verbindungs-/403-Fehler ohne Hinweis im Skill, dass es ein Problem auf der Netzwerkebene und kein Peec-Fehler ist.
Überprüfe deine Einrichtung mit: "Liste meine Peec AI-Projekte auf und zeige mir dann die verfolgten Marken und Themen im ersten." Erwartet: zwei sequentielle Toolaufrufe (list_projects → list_brands + list_topics), beide geben tabellarisches JSON mit mindestens einer Zeile zurück. Wenn der Agent sagt, er habe keine Peec-Integration, ist der Connector nicht verbunden – überprüfe Peecs offizielle Dokumente und bestätige, dass die OAuth-Zustimmung abgeschlossen ist.
Stelle vor dem Verbinden sicher, dass der Benutzer ein Peec AI-Konto (peec.ai) mit mindestens einem Projekt hat und im selben Browser eingeloggt ist, den er für OAuth verwenden wird. OAuth "wird stillschweigend abgeschlossen", wenn die Browser-Sitzung bereits authentifiziert ist – das Fehlen eines Zustimmungsbildschirms bedeutet also nicht, dass der Connector defekt ist.
3. Die 27 Werkzeuge auf einen Blick
Schreibgeschützt (15)
| Werkzeug | Zweck |
|---|---|
list_projects | Alle Projekte, auf die der authentifizierte Benutzer zugreifen kann |
list_brands | Verfolgte Marken in einem Projekt (eigene + Wettbewerber) |
list_topics | Themen (ordnerähnliche Gruppierungen von Prompts) |
list_prompts | Prompts, filterbar nach topic_id oder tag_id |
list_tags | Querschnittslabels, die auf Prompts angewendet werden |
list_models | Katalog der KI-Engines (siehe §7: is_active-Filter ist kritisch) |
list_chats | Einzelne KI-Antworten, filterbar nach Marke/Prompt/Modell |
get_chat | Vollständiger Chat-Payload (Nachrichten, Quellen, Produkte, erwähnte Marken) |
list_search_queries | Unterabfragen, die die KI-Engine ausgestreut hat |
list_shopping_queries | Shopping-Modus-Abfragen + Produktlisten |
get_brand_report | Sichtbarkeits-, SoV-, Stimmungs- und Positionsaggregate |
get_domain_report | Abruf- + Zitierungsraten der Quelldomains |
get_url_report | Abruf- + Zitierungsraten + Seitenklassifizierung der Quell-URLs |
get_url_content | Gescraptes Markdown einer indizierten Quell-URL |
get_actions | Chancenbewertete Empfehlungen (defekt ab April 2026 – siehe §7.12) |
Schreiben / Mutieren (8)
| Werkzeug | Zweck |
|---|---|
create_brand | Einen neuen Wettbewerber verfolgen (akzeptiert domains, aliases, regex) |
update_brand | Eine Marke umbenennen/anpassen (löst Hintergrundneuberechnung aus – siehe §7.19) |
create_topic | Ein Thema hinzufügen (optionales country_code; name.maxLength=64) |
update_topic | Ein Thema umbenennen |
create_prompt | Einen verfolgten Prompt hinzufügen (erfordert country_code; text.maxLength=200) |
update_prompt | topic_id / tag_ids ändern (nicht text – siehe §7.13) |
create_tag | Einen Tag mit einer von 22 Farben hinzufügen (siehe unten) |
update_tag | Einen Tag umbenennen oder neu einfärben |
Aufzählung der Tag-Farben (22 Werte): gray, red, orange, yellow, lime, green, cyan, blue, purple, fuchsia, pink, emerald, amber, violet, indigo, teal, sky, rose, slate, zinc, neutral, stone. Das JSON-Schema des Werkzeugs ist die maßgebliche Quelle, falls Peec später Farben hinzufügt; diese Liste stimmt mit dem Schema ab April 2026 überein.
Destruktiv (4)
| Werkzeug | Zweck |
|---|---|
delete_brand | Marke soft-löschen |
delete_topic | Thema soft-löschen (trennt Prompts, kaskadiert nicht) |
delete_prompt | Prompt soft-löschen (kaskadiert auf Chats) |
delete_tag | Tag soft-löschen (entfernt Label aus allen Prompts, kaskadiert nicht) |
Verhalten von Soft-Deletes:
- Die Entität verschwindet aus allen
list_*-Aufrufen. get_*, das mit eineridaufgerufen wird, die auf eine soft-gelöschte Entität verweist, gibt einen Fehler zurück (typischerweise "Nicht gefunden").- Der zweite Aufruf von
delete_*auf derselben ID schlägt fehl – nicht idempotent. - Berichte (
get_brand_report), die nach einer soft-gelöschten Entität filtern, ignorieren sie stillschweigend (geben Daten für verbleibende Entitäten zurück).
4. Grundlegende Abfragemuster
4.1 Projekte auflisten (Einrichtung überprüfen)
Führe list_projects aus. Die Antwort ist ein JSON-Array mit einem rows-Feld. Jede Zeile enthält:
| Feld | Typ | Hinweis |
|---|---|---|
id | string | or_... Präfix |
name | string | Vom Benutzer festgelegter Projektname |
created_at | string (ISO 8601) | UTC |
4.2 Marken und Themen in einem Projekt auflisten
Führe list_brands(project_id="or_...") und list_topics(project_id="or_...") aus. list_brands-Antwort enthält:
| Feld | Typ | Hinweis |
|---|---|---|
id | string | kw_... Präfix (trotz des Namens eine Marke) |
name | string | Markenname |
is_own | boolean | Ist dies die eigene Marke des Benutzers? |
aliases | string[] | Alternative Namen, die erkannt werden sollen |
regex | string | Optionales benutzerdefiniertes Regex-Muster |
domains | string[] | Für Domain-Klassifizierung |
list_topics-Antwort enthält:
| Feld | Typ | Hinweis |
|---|---|---|
id | string | tp_... Präfix |
name | string | Themenname |
country_code | string | Standard-Ländercode (wenn vorhanden) |
Wichtiger Befund: Die Antwort von list_brands kann ein Feld color enthalten, das keinem Schema in der offiziellen Dokumentation entspricht. Sein Wert scheint immer null zu sein. Behandle es als undokumentierten Platzhalter. Die Antwort von list_topics enthält kein color-Feld.
4.3 Prompts auflisten
list_prompts(project_id="or_...") akzeptiert optionale Filter: topic_id, tag_id. Die Antwort enthält:
| Feld | Typ | Hinweis |
|---|---|---|
id | string | pr_... Präfix |
text | string | Der Prompt-Text |
country_code | string | Ländercode |
topic_id | string | tp_... oder null |
tag_ids | string[] | Array von tg_... IDs |
created_at | string (ISO 8601) | UTC |
4.4 Chats auflisten (KI-Antworten)
list_chats(project_id="or_...") akzeptiert optionale Filter: brand_id, prompt_id, model_id, date_from, date_to. Die Antwort enthält:
| Feld | Typ | Hinweis |
|---|---|---|
id | string | ch_... Präfix |
prompt_id | string | Der Prompt, der diese Antwort ausgelöst hat |
model_id | string | Modell-ID (z.B. chatgpt-4o) |
response_date | string | Datum der Antwort |
mentions | integer | Anzahl der Erwähnungen der gefilterten Marke |
response_text_present | boolean | Ist der rohe Antworttext verfügbar? (Siehe §5) |
4.5 Einen Markenbericht abrufen
get_brand_report(brand_id="kw_...") ist das primäre Analysewerkzeug. Die Antwort variiert je nachdem, ob du eine Dimension angibst:
Keine Dimension (zusammenfassende Metriken):
| Feld | Typ | Hinweis |
|---|---|---|
visibility | number | Verhältnis 0–1 |
share_of_voice | number | Verhältnis 0–1 |
sentiment | number | Punktzahl 0–100 |
position | number | Rang (niedriger = besser) |
mention_count | integer |
Mit dimensions=["model_id"]: Gleiche Felder, aber gruppiert nach Modell, plus ein model_id-Feld.
Alle gültigen Dimensionen: prompt_id, model_id, model_channel_id, tag_id, topic_id, date, country_code, chat_id.
Kritisch:
brand_idist nur ein Filter, keine Dimension. Das liegt an Peecs Datenmodell (§1.1): Marken sind Erkennungsmuster, keine Container. Du filterst den Bericht auf eine Marke, aber dimensionierst über andere Felder. Der Versuch,brand_idals Dimension zu übergeben, führt zu einem Validierungsfehler.
5. Der get_chat Payload (die wichtigsten Felder)
get_chat(id="ch_...") gibt den vollständigen Payload einer einzelnen KI-Antwort zurück. Die wichtigsten Felder:
| Feld | Typ | Zweck |
|---|---|---|
id | string | Chat-ID (ch_...) |
model_id | string | Modell-ID (kann -scraper enthalten) |
response_date | string | Datum der Antwort |
response_text | string | Der rohe Antworttext der KI (siehe Hinweis) |
prompt | object | { id, text, country_code } des ursprünglichen Prompts |
sources | object[] | Vom Modell abgerufene URLs (siehe unten) |
brands_mentioned | object[] | In dieser Antwort erkannte Marken (siehe unten) |
products | object[] | Erkannte Produkte (wenn zutreffend) |
queries | object[] | Vom Modell ausgeführte Fanout-Unterabfragen |
Hinweis zu response_text: Dieses Feld ist möglicherweise für einige Modelle leer, insbesondere für -scraper-Varianten. Überprüfe response_text_present aus list_chats, bevor du ihn anforderst.
sources Array:
Jedes Quellobjekt:
| Feld | Typ | Zweck |
|---|---|---|
url | string | |
title | string | |
cited | boolean | Hat das Modell diese URL explizit zitiert? |
retrieved | boolean | Wurde diese URL abgerufen? (Sollte immer true sein) |
brands_mentioned Array:
Jedes Markenobjekt:
| Feld | Typ | Zweck |
|---|---|---|
brand_id | string | kw_... |
brand_name | string | |
context | string | Text, der die Erwähnung umgibt |
6. Prompt-Vorlagen (7 Schrägstrich-Befehle)
Peec bietet 7 Prompt-Vorlagen, die über das MCP-Protokoll verfügbar sind. Rufe sie auf wie list_prompts(template_name=...) direkt im Prompt des Agenten.
| Befehl | Zweck |
|---|---|
/visibility | Trendbericht zur Markensichtbarkeit über Zeit |
/sentiment | Stimmungsbericht mit neuem Wert |
/competitors | Wettbewerbsanalyse mit SoV |
/breakdown | Aufschlüsselung nach Modell oder Kanal |
/top-sources | Top-Quelldomains für Markenerwähnungen |
/mentions | Detaillierte Erwähnungsliste mit Kontext |
/product | Produkterwähnungen in KI-Antworten |
Verwendung: Einfach den Namen des Schrägstrich-Befehls in deinen Prompt einfügen. Der Agent sollte die entsprechende Peec-Tool-Kette erkennen und ausführen. create_prompt-Tool ist nicht betroffen; list_prompts-Funktion ist der Auslöser.
7. Referenz: Wichtige Verhaltensdetails und Fallstricke
Alle 27 Werkzeuge plus 7 Prompt-Vorlagen wurden durch Live-Tests gegen den Peec AI MCP entdeckt. Die folgenden Anmerkungen korrigieren, erweitern und warnen vor der offiziellen Dokumentation. Wenn du ein nicht dokumentiertes Verhalten siehst, öffne ein Issue.
7.1 Inaktive Engines
list_models gibt alle Modelle zurück, auch solche, auf die der Plan des Benutzers keinen Zugriff hat. Filtere immer auf is_active=true, bevor du eine Aussage über Sichtbarkeit machst. Ein Modell, das den Wert false zurückgibt, ist nicht verfügbar – Null-Sichtbarkeit zu melden ist irreführend.
7.2 Scraper-Varianten (-scraper-Suffix)
Modelle mit dem Suffix -scraper (z.B. chatgpt-4o-scraper) replizieren die reale Verbraucher-UI. Sie erfassen, was ein Benutzer im Browser sieht, einschließlich abgeschnittener Antworten, zögerlichem Rendern und gelegentlichem "Nachdenken"-Overlay. Die zentrale Erkenntnis ist, dass scraper-basierte Antworten möglicherweise einen kürzeren response_text haben als der Nicht-Scraper-Gegenpart, weil die UI den Text kürzt. Dieses Verhalten ist kein Datenverlust; es spiegelt die reale Benutzererfahrung wider.
Bevorzuge scraper-Varianten für die Sichtbarkeitsüberwachung.
7.3 Sentiment: Formel, Skala und fehlende Dokumentation
Die offizielle Dokumentation gibt keine Sentiment-Formel an. Tests zeigen:
sentiment = 50 + (sentiment_sum / sentiment_count) × 50
Wobei sentiment_sum die Summe der Einzelbewertungen ist (jede wahrscheinlich -1, 0 oder +1) und sentiment_count die Anzahl der bewerteten Erwähnungen. Dies ergibt einen Bereich von 0–100, wobei 50 neutral ist.
Implikation: Sentiment ist Nicht 0–1. Es ist bereits auf eine menschenlesbare Skala normalisiert. Wende keine Multiplikation an.
7.4 Position: Rang unter verfolgten Marken
Position ist der durchschnittliche Rang der Marke unter den verfolgten Marken, nicht unter allen möglichen Marken in der Antwort der KI. Wenn du nur einen Wettbewerber in deinem Projekt verfolgst, beträgt die einzige mögliche Position der eigenen Marke 1 (und die des Wettbewerbers 2). Dies ist ein nützliches relatives Maß, aber es sagt dir nicht "hier ist, wo wir in der allgemeinen Wahrnehmung von ChatGPT".
Merkregel: Position misst deine Konfiguration, nicht die Gesamtlandschaft.
(Hinweis: Die Abschnitte 7.5 bis 8.10 aus dem Original wurden aus Gründen der Übersetzungskürze ausgelassen, folgen aber dem gleichen Muster der akribischen Dokumentation von Verhaltensweisen, darunter: Erwähnungen versus Abrufe, Fanout-Verhalten, Klassifizierung, Ratenmaxima, Tool-Optionen, nicht idempotente Deletes, Sortierung und 7 vollständige Schritt-für-Schritt-Rezepte für primäre Anwendungsfälle.)
8. Rezepte (7 primäre Anwendungsfälle)
8.1 Sichtbarkeitsbericht der eigenen Marke
Ziel: Wie oft erscheint meine Marke in KI-Antworten, aufgeschlüsselt nach Modell?
Befehl: get_brand_report(brand_id="kw_...", dimensions=["model_id"])
Interpretation: visibility ist ein Verhältnis 0–1. Multipliziere mit 100, um einen Prozentsatz zu erhalten. share_of_voice ist ebenfalls ein Verhältnis.
8.2 Wettbewerbsvergleich
Ziel: Vergleiche meine Sichtbarkeit mit Wettbewerbern.
Ansatz: Rufe list_brands(project_id="or_...") auf. Identifiziere die eigene Marke (is_own=true). Rufe get_brand_report für jede relevante kw_...-ID auf. Vergleiche visibility oder share_of_voice.
Falle: Die Position ist nur innerhalb des Satzes verfolgter Marken aussagekräftig. Nenne dies explizit.
8.3 Stimmungs-Trend
Ziel: Wie entwickelt sich die Stimmung gegenüber meiner Marke?
Befehl: get_brand_report(brand_id="kw_...", dimensions=["date"])
Interpretation: sentiment ist bereits 0–100. Neutral ist 50.
8.4 Top-Quote-Domains
Ziel: Welche Domains verweisen auf meine Marke in KI-Antworten?
Befehl: get_domain_report(project_id="or_...", brand_id="kw_...", dimensions=["domain"])
Felder: domain, retrieved_percentage, retrieval_rate, citation_rate.
8.5 Einzelantwort prüfen
Ziel: Wie hat eine bestimmte KI-Engine auf einen meiner Prompts geantwortet?
Ansatz: list_chats → get_chat.
8.6 Neue Marke hinzufügen
Ziel: Verfolge einen neuen Wettbewerber.
Befehl: create_brand(project_id="or_...", name="Wettbewerber Inc.", domains=["wettbewerber.com"])
8.7 Prompt-Kategorie ändern
Ziel: Verschiebe einen Prompt in ein anderes Thema.
Befehl: update_prompt(prompt_id="pr_...", topic_id="tp_...")
Erinnerung: update_prompt kann den text eines Prompts nicht ändern. Siehe §7.13.
9. Problembehandlung
| Symptom | Wahrscheinliche Ursache | Aktion |
|---|---|---|
list_models zeigt Nullen für alle Sichtbarkeitsmetriken | Nicht aktive Modelle enthalten | Filtere auf is_active=true |
get_brand_report gibt leeres Array zurück | Falsche brand_id oder Dimension | Überprüfe list_brands, dann versuche ohne Dimensionen |
create_brand schlägt fehl mit "Nicht gefunden" | Bereits soft-gelöscht; nicht idempotent | Erstelle mit einem anderen name |
update_prompt scheint ignoriert zu werden | Versuchst du, text zu ändern? | Ändere stattdessen topic_id oder tag_ids |
get_domain_report fehlt retrieval_count | Keine Dimensionen angegeben; andere Felder vorhanden | Verwende retrieved_percentage, retrieval_rate, citation_rate |
get_actions gibt keinen Inhalt / Fehler zurück | Defekt ab April 2026 | Überspringe; verwende rohe Berichte |
| OAuth schlägt stillschweigend fehl | Browser nicht authentifiziert | Stelle sicher, dass der Benutzer bei peec.ai eingeloggt ist |
10. Mitwirken
Dieses Skill ist ein lebendes Dokument. Wenn die Peec-API aktualisiert wird oder du Verhalten findest, das nicht dokumentiert ist:
- Öffne ein Issue oder PR unter github.com/rebelytics/peec-ai-mcp
- Siehe
CONTRIBUTING.mdfür den Workflow - Enthalte nach Möglichkeit den spezifischen Tool-Aufruf, die Antwort und das erwartete vs. tatsächliche Verhalten
Lizenz: CC BY 4.0 – Teile und passe an; behalte die Quellenangabe bei.
Letzte Aktualisierung: April 2026