Keap MCP Server

Ein leistungsstarker Model Context Protocol (MCP) Server für die Interaktion mit Keap CRM-Daten, mit erweiterten Funktionen wie HTTP/2-Unterstützung, umfassender Diagnose und Massenoperationen.

Funktionen

Kernverwaltung von Kontakten & Tags

• Umfassende Kontaktverwaltung - Auflisten, Suchen, Filtern und Abrufen detaillierter Kontaktinformationen

• Erweiterte Tag-Operationen - Vollständiges Lifecycle-Management von Tags, einschließlich Erstellung, Abfrage und Batch-Operationen

• Batch-Tag-Operationen - Effizientes Anwenden oder Entfernen mehrerer Tags bei mehreren Kontakten

• Benutzerdefinierte Feldoperationen - Suche nach Kontakten anhand benutzerdefinierter Feldwerte und Massenaktualisierung dieser Felder

• Komplexe logische Filterung - Unterstützung für AND-, OR-, NOT-Operatoren mit verschachtelten Bedingungen

Leistung & Optimierung

• HTTP/2-Unterstützung - Verbesserte Verbindungsleistung durch Connection Pooling

• Intelligentes Rate Limiting - Tägliche Anfragelimits mit adaptiven Backoff-Strategien

• Abfrageoptimierung - Intelligente serverseitige vs. clientseitige Filterung mit Leistungsanalysen

• Leistungsüberwachung - Echtzeit-Abfrageanalyse und Optimierungsvorschläge

• Persistentes Caching - SQLite-basiertes Caching zur Reduzierung von API-Aufrufen und Verbesserung der Leistung

Erweiterte Funktionen

• Umfassende Diagnose - API-Leistungskennzahlen, Systemüberwachung und Gesundheitsprüfungen

• Erweiterte Fehlerbehandlung - Robuste Wiederholungslogik mit exponentiellem Backoff für verschiedene Fehlertypen

• Massenaktualisierung benutzerdefinierter Felder - Effizientes Setzen von Werten für benutzerdefinierte Felder über mehrere Kontakte hinweg

• Erweiterte Filteroperatoren - Über 15 Operatoren, einschließlich BETWEEN, IN, SINCE, STARTS_WITH usw.

• ID-Listen-Operationen - Hilfsfunktionen für die Arbeit mit Mengen von Kontakt- und Tag-IDs

Related MCP server: claude-cli-mcp

Architektur

Der Keap MCP Server verwendet eine optimierte, hochleistungsfähige Architektur:

• API Client (src/api/client.py) - Verbesserte Keap API-Kommunikation mit HTTP/2, Rate Limiting und Diagnose

• MCP Tools (src/mcp/) - Umfassende MCP-Protokollimplementierung mit Optimierung

• Cache Manager (src/cache/) - SQLite-basiertes persistentes Caching mit intelligenter Invalidierung

• Optimization Engine (src/mcp/optimization/) - Abfrageoptimierung und Leistungsanalysen

• Schemas (src/schemas/) - Datenvalidierung und Modelle

• Utils (src/utils/) - Gemeinsame Hilfsprogramme für die Kontaktverarbeitung und Filterung

MCP Tools

Der Server stellt 17 umfassende MCP-Tools bereit:

Kontaktoperationen

1. list_contacts - Kontakte mit Filterung und Paginierung auflisten (jetzt optimiert)

2. search_contacts_by_email - Kontakte nach E-Mail-Adresse finden

3. search_contacts_by_name - Kontakte nach Namen finden

4. get_contact_details - Detaillierte Informationen zu einem bestimmten Kontakt abrufen

5. query_contacts_by_custom_field - Kontakte nach benutzerdefiniertem Feldwert abfragen

Tag-Operationen

6. get_tags - Tags mit optionaler Filterung abrufen

7. get_tag_details - Detaillierte Informationen zu einem bestimmten Tag abrufen

8. get_contacts_with_tag - Kontakte abrufen, die ein bestimmtes Tag haben

9. create_tag - Ein neues Tag erstellen

Tag-Verwaltung (Batch-Operationen)

10. modify_tags - Tags bei Kontakten hinzufügen oder entfernen

11. apply_tags_to_contacts - Mehrere Tags auf mehrere Kontakte mittels Batch-Operationen anwenden

12. remove_tags_from_contacts - Mehrere Tags von mehreren Kontakten entfernen

Verwaltung benutzerdefinierter Felder

13. set_custom_field_values - Werte benutzerdefinierter Felder über mehrere Kontakte hinweg massenhaft aktualisieren

Erweiterte Abfrage- & Leistungsoperationen

14. query_contacts_optimized - Erweiterte Kontaktabfrage mit Optimierung und Leistungsanalyse

15. analyze_query_performance - Abfrageleistung und Optimierungspotenzial analysieren

Systemoperationen

16. get_api_diagnostics - Umfassende API-Diagnose und Leistungskennzahlen

Hilfsoperationen

17. intersect_id_lists - Schnittmenge mehrerer ID-Listen finden

Erste Schritte

Voraussetzungen

• Python 3.9 oder höher

• Keap API-Zugangsdaten

Installation

1. Repository klonen:

   git clone https://github.com/yourusername/keapmcp.git
   cd keapmcp

2. Abhängigkeiten installieren:

   pip install -r requirements.txt

3. Keap API-Zugangsdaten konfigurieren:

   • Die Anwendung verwendet eine .env-Datei zur Konfiguration

   • Der API-Schlüssel wurde von keapsync kopiert, kann aber bei Bedarf geändert werden

   • Die Konfiguration umfasst:

     KEAP_API_KEY=your_api_key_here
     KEAP_API_BASE_URL=https://api.infusionsoft.com/crm/rest/v1
     KEAP_MCP_HOST=127.0.0.1
     KEAP_MCP_PORT=5000
     KEAP_MCP_LOG_LEVEL=INFO
     KEAP_MCP_LOG_FILE=keap_mcp_server.log
     KEAP_MCP_CACHE_ENABLED=true
     KEAP_MCP_CACHE_TTL=3600

Server ausführen

python run.py --host 127.0.0.1 --port 5000

Befehlszeilenoptionen:

• --host - Zu bindender Host (Standard: 127.0.0.1)

• --port - Zu verwendender Port (Standard: 5000)

• --log-level - Protokollierungsebene (Standard: INFO)

• --log-file - Pfad zur Protokolldatei (Standard: keap_mcp_server.log)

• --no-console-log - Konsolenprotokollierung deaktivieren

Testen & Abdeckung

Der Keap MCP Server enthält eine umfassende Testsuite, um Zuverlässigkeit und korrekten Betrieb mit vollständiger CI/CD-Pipeline-Integration sicherzustellen.

Schnelles Testen

Verwenden Sie das Makefile für eine einfache Testausführung:

# Run all unit tests
make test

# Run tests with coverage reporting  
make coverage

# Generate HTML coverage report
make coverage-html

# Run service-specific tests
make test-services
make test-models

# Full development workflow
make dev-test

CI/CD-Integration

Das Projekt umfasst automatisierte Tests und Berichterstattung zur Testabdeckung:

• Continuous Integration: Tests laufen auf Python 3.9, 3.10 und 3.11

• Coverage Tracking: Mindestens 60 % Abdeckung erzwungen

• Pre-commit Checks: Code-Formatierung, Linting und Sicherheitsprüfungen

• Coverage Badges: Automatische Aktualisierung im Haupt-Branch

Testkategorien

• Unit Tests (tests/unit/) - Einzelkomponententests mit umfassendem Mocking

• Integration Tests (tests/integration/) - End-to-End-Funktionsüberprüfung

• Performance Tests (tests/performance/) - Last- und Optimierungsvalidierung

• API Validation - Überprüfung des Keap API-Antwortformats

Abdeckungsanforderungen

• Aktuelle Abdeckung: 55 % Integrationsabdeckung, variiert je nach Komponente

• API Client: Kernfunktionalität mit umfassendem Mocking getestet

• MCP Tools: Integrationstests mit Mock-Abhängigkeiten

• Cache System: Umfassende Persistenz- und Leistungstests

• Utilities: Funktionalität der Kontaktverarbeitung und Filterung getestet

• Optimierung: Leistungsanalysen und Abfrageoptimierung abgedeckt

Spezifische Tests ausführen

# Run all tests
python -m pytest tests/ -v

# With coverage reporting
python -m pytest tests/ --cov=src --cov-fail-under=90

# Integration tests (requires running server)
python -m pytest tests/integration/ -v

Verwendung des MCP Servers

Beispiel: Kontakte auflisten (jetzt optimiert)

{
  "function": "list_contacts",
  "params": {
    "filters": [
      { "field": "email", "operator": "contains", "value": "@company.com" }
    ],
    "limit": 50,
    "include": ["id", "given_name", "family_name", "email"]
  }
}

Hinweis: list_contacts verwendet jetzt intern die Optimierungs-Engine für eine bessere Leistung. Für detaillierte Leistungskennzahlen verwenden Sie direkt query_contacts_optimized.

Beispiel: Suche nach E-Mail

{
  "function": "search_contacts_by_email",
  "params": {
    "email": "john.doe@company.com",
    "include": ["id", "given_name", "family_name", "email", "tags"]
  }
}

Beispiel: Tags abrufen

{
  "function": "get_tags",
  "params": {
    "include_categories": true,
    "limit": 100
  }
}

Beispiel: Batch-Tag-Operationen

{
  "function": "apply_tags_to_contacts",
  "params": {
    "tag_ids": ["123", "456"],
    "contact_ids": ["1001", "1002", "1003"]
  }
}

Beispiel: Abfrage benutzerdefinierter Felder

{
  "function": "query_contacts_by_custom_field",
  "params": {
    "field_id": "7",
    "field_value": "Engineering",
    "operator": "contains",
    "include": ["id", "given_name", "family_name", "email"]
  }
}

Beispiel: Neues Tag erstellen

{
  "function": "create_tag",
  "params": {
    "name": "VIP Customer",
    "description": "High-value customer segment",
    "category_id": "2"
  }
}

Beispiel: Massenaktualisierung benutzerdefinierter Felder

{
  "function": "set_custom_field_values",
  "params": {
    "field_id": "7",
    "contact_ids": ["1001", "1002", "1003"],
    "common_value": "VIP Customer"
  }
}

Oder mit individuellen Werten pro Kontakt:

{
  "function": "set_custom_field_values",
  "params": {
    "field_id": "7",
    "contact_values": {
      "1001": "Gold Tier",
      "1002": "Silver Tier", 
      "1003": "Bronze Tier"
    }
  }
}

Beispiel: API-Diagnose

{
  "function": "get_api_diagnostics",
  "params": {}
}

Beispiel: Schnittmenge von ID-Listen

{
  "function": "intersect_id_lists",
  "params": {
    "lists": [
      {"list_id": "active_contacts", "item_ids": ["1", "2", "3", "4"]},
      {"list_id": "newsletter_subscribers", "item_ids": ["2", "3", "5", "6"]}
    ],
    "id_field": "item_ids"
  }
}

Leistungsmerkmale

HTTP/2-Unterstützung

Der Server verwendet HTTP/2 für verbesserte Leistung mit Connection Pooling und Keepalive-Verbindungen.

Rate Limiting

• Tägliche Anfragelimits (standardmäßig 25.000 Anfragen/Tag)

• Intelligente Backoff-Strategien

• Überwachung und Diagnose von Ratenbegrenzungen

Caching-Strategie

• SQLite-basiertes persistentes Caching

• Intelligente Cache-Invalidierung

• TTL-basierte Ablaufsteuerung

• Nachverfolgung von Cache-Treffern/Fehlern

Fehlerbehandlung

• Exponentielles Backoff für Wiederholungsversuche

• Unterschiedliche Strategien für Timeout-, Netzwerk- und HTTP-Fehler

• Umfassende Fehlerverfolgung und Diagnose

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert - siehe die Datei LICENSE für Details.