mcp-generate

name	mcp-generate
description	Use when user says "mcp:generate", "generiere emails", "email generation", "MCP workflow", "generate emails for campaign", or triggers /mcp:generate.

MCP Generate — AI-Variablen-Generierung

Dieser Skill orchestriert die vollautomatische AI-Variablen-Generierung fuer Leads via MCP Business Tools. Claude generiert AI-Variablen basierend auf Research, Qualification und Screenshots, und speichert sie via save_lead_variables. Email-Body und Subject werden NICHT durch diesen Skill erzeugt — sie sind in der Email-Sequenz hardcoded und werden beim CSV-Export live mit den Variablen gerendert.

Hinweis zur Parallelisierung: Wenn dein Client parallele Subagents unterstuetzt (z.B. Claude Code), spawne pro Lead einen Subagent wie beschrieben. Andernfalls arbeite die Leads sequentiell mit exakt denselben Schritten ab — das Ergebnis ist identisch, nur langsamer.

Workflow-Uebersicht

1. list_campaigns -> Kampagne identifizieren (oder campaign_id aus Argument)
   |
2. list_leads(campaign_id, limit={batch_size})
   -> {batch_size} Leads mit Basisdaten (~0.5 KB/Lead)
   |
3. Fuer jeden Lead: Sub-Agent spawnen (parallel, bis zu {batch_size} gleichzeitig)
   -> Jeder Agent: get_lead_data() -> generiert Variablen -> save_lead_variables()
   |
4. Batch-Report: "Batch 1/N done, X/Y leads processed"
   |
5. Naechster Batch: list_leads erneut (remaining > 0?)
   |
6. Fertig: "Y Leads verarbeitet, Variablen bereit fuer Review"

Aufruf

Eingabe	Verhalten
/mcp:generate	Zeigt Kampagnen via list_campaigns, User waehlt
/mcp:generate 76	Startet direkt fuer Kampagne 76
generiere emails fuer kampagne 76	Startet direkt fuer Kampagne 76

Schritt-fuer-Schritt Anleitung

Phase 1: Kampagne bestimmen

Wenn KEINE campaign_id als Argument uebergeben wurde:

1. Rufe list_campaigns auf (MCP Tool)
2. Zeige dem User die Kampagnen mit leadCounts.needs_email_generation > 0
3. Frage: "Fuer welche Kampagne soll ich Variablen generieren?"
4. Merke dir die campaign_id

Wenn campaign_id als Argument uebergeben wurde: Direkt zur Batch-Groesse-Abfrage.

Batch-Groesse abfragen:

Frage den User: "Wie viele Leads pro Batch? (Default: 10)"

• 10 (Standard)
• 50 (Schneller, 50 parallele Agents)
• 100 (Aggressiv)
• 200 (Maximum)

Merke dir die Antwort als {batch_size}. Wenn der User einfach Enter drueckt oder nichts sagt: batch_size = 10.

Dann weiter zu Phase 2.

Phase 2: Leads laden (Batch)

Rufe auf:

list_leads(
  campaign_id = <ID>,
  limit = {batch_size}
)

Merke dir aus der Response:

• campaign.name und campaign.id
• total (Gesamtzahl zu verarbeitender Leads)
• remaining (verbleibend nach diesem Batch)
• Die leads[] mit IDs und Basisdaten

Wenn leads leer ist: "Keine Leads zur Verarbeitung. Alle Leads haben bereits generierte Variablen." -> STOP.

Phase 3: Sub-Agents spawnen (parallel)

Fuer JEDEN Lead im Batch einen Agent spawnen. Verwende das Agent-Tool mit:

• subagent_type: nicht gesetzt (general-purpose)
• mode: "bypassPermissions"
• run_in_background: true (fuer echte Parallelitaet)
• name: "gen-{lead.company}" (gekuerzt auf 20 Zeichen)
• description: "Generate variables for {lead.company}"

WICHTIG: Spawne ALLE Agents eines Batches in EINEM Message-Block, damit sie parallel laufen.

Sub-Agent Prompt Template

Fuer jeden Lead den folgenden Prompt zusammenbauen. Ersetze die Platzhalter mit den tatsaechlichen Daten aus der list_leads Response:

Du generierst AI-Variablen fuer einen Lead via MCP Tools.

KAMPAGNE: {campaign.name} (ID: {campaign.id})
LEAD: {lead.company} (ID: {lead.id})

## Schritte

1. Rufe get_lead_data(campaign_id={campaign.id}, lead_id={lead.id}) auf
2. Lies den emailGeneration.systemPrompt sorgfaeltig — er definiert Ton, Stil und Kontext
3. Analysiere Research, Qualification und Custom Attributes
4. Analysiere die Screenshots visuell (falls URLs vorhanden und dein Client Bilder laden kann)
5. Generiere fuer JEDE Variable in emailGeneration.variables[] den Text gemaess ihrem Prompt
6. REVIEW — Pruefe JEDE generierte Variable gegen diese Checkliste:
   - Umlaute korrekt geschrieben? (Ä/Ö/Ü/ä/ö/ü/ß — NIEMALS AE/OE/UE/ae/oe/ue/ss)
   - Keine internen Metriken erwaehnt? (SEO-Score, Overall-Score, Fit-Level, Need-Flags, Dimension-Scores, Opportunity Score, ranked Keyword)
   - Keine HTTPS/SSL-Behauptungen? ("ohne HTTPS", "kein SSL" etc.)
   - Kein harscher Deficit-Sprech? (ausbaufähig, nicht erreichbar, fehlerhaft, unzureichend, kaum nutzbar, schwach, schlecht)
   - Anrede konsistent ueber alle Variablen? (durchgehend formal ODER team-basiert, nie gemischt)
   - Kein "vorallem"? (korrekt: "vor allem")
   - Keine Leerzeilen am Anfang oder Ende einer Variable?
   - Jede Variable unter 10.000 Zeichen?
   Falls ein Kriterium verletzt: Korrigiere die Variable und pruefe erneut.
7. Speichere via save_lead_variables(campaign_id={campaign.id}, lead_id={lead.id}, variables=JSON-String)

WICHTIG: variables ist ein JSON-STRING. ALLE Variablen aus emailGeneration.expectedOutput muessen enthalten sein.

Phase 4: Screenshot-Handling

Screenshots sind in der lead.screenshots[] Liste als relative URLs enthalten (z.B. /api/research-artifacts/abc-123), Basis ist die ListM8-Server-URL.

Wenn dein Client Bilder von URLs laden und visuell analysieren kann: Screenshots laden und in die Generierung einbeziehen. Andernfalls: Screenshots ueberspringen und nur auf Basis von Research-Text, Qualification und Custom Attributes generieren — im Report vermerken: "Screenshots nicht einbezogen, Text-basierte Generierung."

Phase 5: Ergebnisse sammeln & Report

Warte bis ALLE Sub-Agents des Batches fertig sind (sie laufen im Background — du wirst benachrichtigt).

Zaehle:

• Erfolgreiche Generierungen (save_lead_variables returned status: "success")
• Fehler (save_lead_variables returned status: "error" oder Agent-Fehler)

Zeige Batch-Report:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Batch {batch_nr}/{total_batches} abgeschlossen
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Verarbeitet: {processed}/{total_leads} Leads
Erfolg: {success_count} | Fehler: {error_count}
Verbleibend: {remaining}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Phase 6: Naechster Batch oder Abschluss

Wenn remaining > 0: Zurueck zu Phase 2 (naechster list_leads Aufruf).

Wenn remaining == 0 oder keine Leads mehr: Zeige Abschluss-Report:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
MCP Generate abgeschlossen
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Kampagne: {campaign.name} (ID: {campaign.id})
Gesamt verarbeitet: {total_processed} Leads
Erfolg: {total_success} | Fehler: {total_errors}
Status: Verarbeitete Leads auf "pending_review" gesetzt
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Naechster Schritt: /mcp:verify — Variablen pruefen und freigeben
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

MCP Tool Reference

list_campaigns

Keine Parameter. Gibt alle Kampagnen des Users zurueck.

Response-Felder:

• campaigns[].id — Kampagnen-ID
• campaigns[].name — Name
• campaigns[].leadCounts.needs_email_generation — Anzahl Leads in der Generierungs-Queue
• campaigns[].leadCounts.pending_review — Anzahl Leads mit generierten, noch nicht freigegebenen Variablen
• campaigns[].leadCounts.approved / .rejected — Final-Status
• campaigns[].aiVariables[] — Konfigurierte AI-Variablen (Name + sortOrder)

list_leads

Parameter	Typ	Default	Beschreibung
campaign_id	int	required	Kampagnen-ID
limit	int	10	Anzahl Leads (1-200)
fit_level	string	"qualified"	Qualification-Filter
research_status	string	"researched"	Research-Status-Filter
campaign_status	string	"processing"	Campaign-Status-Filter
qualification_status	string	''	Qualification-Status-Filter: '' (alle), 'pending' (inkl. nie qualifiziert), 'processing', 'completed', 'failed'

Gibt nur Basisdaten zurueck: id, email, company, website, city, phoneNumber, score, qualification (fitLevel, category, summary).

WICHTIG: Der Default campaign_status="processing" ist korrekt fuer den Generierungs-Workflow (= Leads mit Status "Ausstehend").

get_lead_data

Parameter	Typ	Default	Beschreibung
campaign_id	int	required	Kampagnen-ID
lead_id	int	required	Lead-ID

Gibt vollen Generierungs-Context zurueck:

• Stammdaten (email, company, website, city, phoneNumber, score)
• qualification (fitLevel, category, summary, snapshot)
• research (text, bestEmail, decisionMaker, contactRecommendation)
• screenshots[] (type, viewport, url, label)
• customAttributes (key-value Paare)
• emailGeneration.systemPrompt — Der aufgeloeste System-Prompt
• emailGeneration.variables[] — Variablen mit aufgeloesten Prompts
• emailGeneration.expectedOutput — JSON-Schema der erwarteten Ausgabe (Variablen-Namen)

save_lead_variables

Parameter	Typ	Default	Beschreibung
campaign_id	int	required	Kampagnen-ID
lead_id	int	required	Lead-ID
variables	string	required	JSON-String mit generierten Werten

variables-Format: "{\"hallo\": \"...\", \"intro\": \"...\"}"

Verhalten: Persistiert eine neue LeadAIVariableValue-Version pro Variable (vorherige Versionen bleiben als Historie erhalten). Setzt LeadCampaignStatus.status = pending_review. Beruehrt KEINE Email-Steps (Body/Subject werden beim CSV-Export live aus den Variablen gerendert).

Success-Response:

{
  "status": "success",
  "lead_id": 456,
  "campaign_id": 123,
  "version": 1,
  "variables_saved": 2,
  "campaign_status": "pending_review"
}

Error-Response bei fehlenden Variablen:

{
  "status": "error",
  "message": "Variable(s) missing from submission: 'intro'",
  "expected_variables": ["hallo", "intro"],
  "received_variables": ["hallo"]
}

Verification-Tools (siehe /mcp:verify)

Die folgenden Tools werden im Verification-Workflow verwendet, NICHT in der Generierung:

• get_lead_variables — laedt aktuelle Variablen-Werte (Name, Wert, Status, generatedAt) zur Pruefung
• approve_lead_variables — gibt Variablen frei (LeadCampaignStatus = approved, ready fuer CSV-Export)
• reject_lead_variables — lehnt Variablen ab mit reason (LeadCampaignStatus = rejected, vom CSV-Export ausgeschlossen)

Details: siehe /mcp:verify Skill.

Fehlerbehandlung

Fehler	Aktion
list_leads gibt leere leads[]	"Keine Leads in Queue" -> STOP
Sub-Agent save_lead_variables Error	Fehler notieren, weitermachen mit naechstem Lead
Sub-Agent Timeout/Crash	Als Fehler zaehlen, im Report erwaehnen
Alle Agents eines Batches fehlgeschlagen	Warnung ausgeben, User fragen ob fortfahren
Netzwerk/MCP-Verbindungsfehler	1x Retry, dann STOP mit Fehlermeldung

Kein automatischer Retry einzelner Leads — fehlgeschlagene Leads koennen spaeter mit /mcp:generate erneut verarbeitet werden (sie haben noch keinen pending_review-Status und tauchen wieder in list_leads auf).

Wichtige Hinweise

1. Voll autonom — Keine Rueckfragen waehrend der Generierung. Durchlaufen bis fertig.
2. {batch_size}er-Batches — {batch_size} Leads pro Batch (vom User gewaehlt, Default 10, Maximum 200).
3. Parallel — Alle Agents eines Batches gleichzeitig spawnen (ein Message-Block).
4. Idempotent — Leads mit bereits generierten Variablen tauchen nicht mehr in list_leads (default-filter campaign_status="processing") auf.
5. Versionierung — Jeder save_lead_variables-Aufruf erzeugt eine neue Version, aeltere Versionen bleiben als Historie erhalten.