little-green-light-mcp

Ein schreibgeschützter MCP-Server für das Little Green Light Spender-CRM. Jeder stdio MCP-Client kann ihn verwenden, um Spender zu suchen, Spenden in einem Datumsbereich aufzulisten oder die Spendenhistorie einer Person abzurufen.

Der Servername ist lgl-mcp. Wie Sie ihn registrieren, hängt vom Host ab – siehe Einrichtung.

Schreibgeschützt von Grund auf

Dieser Server hat keine Erstellungs-, Aktualisierungs- oder Löschwerkzeuge – nicht deaktiviert, sondern nicht vorhanden. lgl.js stellt nur eine GET-Anforderungsfunktion bereit; es gibt keinen Codepfad in diesem Projekt, der einen Spendendatensatz ändern kann. Führen Sie nach jeder Änderung npm run audit:readonly aus, um dies mechanisch zu bestätigen.

Jeder zukünftige Schreibpfad (z. B. Synchronisierung von Spenden) gehört in LGLs eigene geprüfte Integrationswarteschlange, nicht hier.

Related MCP server: SQL Server MCP

Einrichtung

1. Holen Sie sich einen API-Schlüssel von LGL: Einstellungen → Integrationseinstellungen → LGL-API.

2. Legen Sie ihn in ~/.config/lgl-mcp/env ab (bereits erstellt, chmod 600):

   LGL_API_KEY=your-key-here

   Alternativ können Sie einen macOS-Schlüsselbund-Eintrag mit dem Namen lgl-api-key hinzufügen oder die Umgebungsvariable LGL_API_KEY für einen einmaligen Durchlauf setzen. Der Schlüssel wird niemals protokolliert, committet oder in Fehlermeldungen ausgegeben.

3. Abhängigkeiten installieren (bereits beim ersten Auschecken erledigt):

   npm install

4. Richten Sie einen stdio MCP-Host auf diesen Server aus. Der Befehl ist node; das Argument ist der absolute Pfad zu index.js:

   {
     "command": "node",
     "args": ["/absolute/path/to/little-green-light-mcp/index.js"]
   }

   Verpacken Sie dies in die Konfigurationsform Ihres Hosts (mcpServers, eine Serverzuordnung auf oberster Ebene usw.). Es sind keine zusätzlichen Umgebungsvariablen erforderlich, wenn der Schlüssel in ~/.config/lgl-mcp/env oder im Schlüsselbund liegt. Setzen Sie LGL_API_KEY nur für eine einmalige Überschreibung im env-Block des Hosts.

Werkzeuge

Jedes Werkzeug akzeptiert verbose: true, um das vollständige LGL-Objekt anstelle der gekürzten Zusammenfassung zu erhalten. Kompakte Spender enthalten Name, E-Mail, Telefon und Stadt/Bundesland. Spendedaten und Gesamtbetrag sind nur bei get_constituent enthalten. Kompakte Spenden enthalten Datum, Betrag, fund_id, Notiz und Spendername (wenn erweitert). Listenantworten, die begrenzt sind, enthalten ein note-Feld, das angibt, wie viele Ergebnisse ausgelassen wurden – nichts wird stillschweigend abgeschnitten.

Bestätigte Abfragesyntax

LGLs /constituents/search und /gifts/search verwenden q[]=field=value-Paare, keinen Freitext – dies war für mehrere Felder undokumentiert und wurde durch Tests mit einem Live-Konto bestätigt:

• Spender: name=<text> (LGLs eigenes dokumentiertes Beispiel) oder eaddr=<email> für eine genaue E-Mail-Übereinstimmung (undokumentiert; Vermutungen wie email=/email_address= wurden abgelehnt).

• Spenden: date_from=YYYY-MM-DD / date_to=YYYY-MM-DD (bestätigte echte Filter – ein Datum außerhalb des Bereichs setzt total_items auf null). Mehrere q[]-Einträge werden UND-verknüpft.

• Spenden haben an diesem Endpunkt keinen Fonds- oder Betragsfilter – fund_id, fund, fund_ids, campaign_id, amount_from, amount_to wurden alle getestet und als unbekannte Parameter abgelehnt. search_gifts stellt diese nicht bereit; filtern Sie Ergebnisse clientseitig nach fund_id / note, falls erforderlich.

• Der Spendername einer Spende erscheint nur, wenn die Anfrage expand=first_name,last_name,org_name enthält – LGL verschachtelt ansonsten kein Spenderobjekt in der Spendenantwort.

• Die Spendenbeträge von get_constituent (erstes/letztes Spendedatum, Gesamtbetrag) werden von LGL überhaupt nicht im Spenderobjekt zurückgegeben – sie werden hier aus der eigenen Spendenhistorie dieses Spenders berechnet, seitenweise bis zum Ende. Ein Spender ohne Spenden gibt lifetime_amount: 0 zurück. Es gilt weiterhin eine Sicherheitsgrenze (10.000 Spenden); die Antwort gibt dies an, wenn sie erreicht wird.

Entwicklung

npm run inspect          # MCP Inspector — exercise tools interactively
npm run audit:readonly   # mechanical check: no POST/PATCH/PUT/DELETE anywhere

Ratenbegrenzungen

LGL erlaubt 300 API-Aufrufe pro 5-Minuten-Fenster. lgl.js drosselt intern (gleitendes Fenster) und wiederholt bei 429/5xx mit Backoff, sodass eine breite Frage, die sich in viele Aufrufe aufteilt, sich elegant verschlechtert, anstatt einen Fehler zu verursachen.