little-green-light-mcp

Un servidor MCP de solo lectura para el CRM de donantes Little Green Light. Cualquier cliente MCP stdio puede usarlo para buscar donantes, listar donaciones en un rango de fechas u obtener el historial de donaciones de una persona.

El nombre del servidor es lgl-mcp. La forma de registrarlo depende del host — consulte Configuración.

Solo lectura por construcción

Este servidor no tiene herramientas de crear, actualizar o eliminar — no deshabilitadas, ausentes. lgl.js expone solo una función de solicitud GET; no hay ninguna ruta de código en este proyecto que pueda mutar un registro de donante. Ejecute npm run audit:readonly después de cualquier cambio para confirmarlo mecánicamente.

Cualquier ruta de escritura futura (por ejemplo, sincronizar donaciones) pertenece a la propia Cola de Integración revisada de LGL, no aquí.

Related MCP server: SQL Server MCP

Configuración

1. Obtenga una clave API de LGL: Settings → Integration Settings → LGL API.

2. Colóquela en ~/.config/lgl-mcp/env (ya creado, chmod 600):

   LGL_API_KEY=your-key-here

   Alternativamente, agregue un elemento de Llavero de macOS llamado lgl-api-key, o establezca la variable de entorno LGL_API_KEY para una ejecución única. La clave nunca se registra, confirma ni se muestra en mensajes de error.

3. Instale las dependencias (ya hecho en la primera descarga):

   npm install

4. Apunte un host MCP stdio a este servidor. El comando es node; el argumento es la ruta absoluta a index.js:

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

   Envuelva eso en la forma de configuración que use su host (mcpServers, un mapa de servidores de nivel superior, etc.). No se requieren variables de entorno adicionales si la clave está en ~/.config/lgl-mcp/env o en el Llavero. Establezca LGL_API_KEY en el bloque de entorno del host solo para una anulación única.

Herramientas

Cada herramienta acepta verbose: true para obtener el objeto LGL completo en lugar del resumen recortado. Los donantes compactos incluyen nombre, correo electrónico, teléfono y ciudad/estado. Las fechas de donación y el total de por vida solo están en get_constituent. Las donaciones compactas incluyen fecha, monto, fund_id, nota y nombre del donante (cuando se expande). Las respuestas de lista que están limitadas incluyen un campo note que indica cuántos resultados se omitieron — nada se trunca silenciosamente.

Sintaxis de consulta confirmada

Los endpoints /constituents/search y /gifts/search de LGL toman pares q[]=field=value, no texto libre — esto no estaba documentado para varios campos y se confirmó probando una cuenta real:

• Donantes: name=<text> (el ejemplo documentado de LGL) o eaddr=<email> para una coincidencia exacta de correo electrónico (no documentado; conjeturas como email=/email_address= fueron rechazadas).

• Donaciones: date_from=YYYY-MM-DD / date_to=YYYY-MM-DD (filtros reales confirmados — una fecha fuera de rango pone a cero total_items). Múltiples entradas q[] se combinan con AND.

• Las donaciones no tienen filtro de fondo o monto en este endpoint — fund_id, fund, fund_ids, campaign_id, amount_from, amount_to se probaron todos y fueron rechazados como parámetros desconocidos. search_gifts no los expone; filtre los resultados del lado del cliente por fund_id / note si es necesario.

• El nombre del donante de una donación solo aparece cuando la solicitud incluye expand=first_name,last_name,org_name — LGL no anida un objeto de donante en la respuesta de donación de otra manera.

• Los totales de donaciones de get_constituent (primera/última fecha de donación, monto de por vida) no son devueltos por LGL en el objeto del donante en absoluto — se calculan aquí a partir del historial de donaciones de ese donante, paginado hasta completar. Un donante sin donaciones devuelve lifetime_amount: 0. Aún se aplica un límite de seguridad (10,000 donaciones); la respuesta lo indica si se alcanza.

Desarrollo

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

Límites de tasa

LGL permite 300 llamadas API por ventana de 5 minutos. lgl.js limita internamente (ventana deslizante) y reintenta con retroceso en 429/5xx, por lo que una pregunta amplia que se ramifica en muchas llamadas se degrada gradualmente en lugar de dar error.