little-green-light-mcp

一个用于 Little Green Light 捐赠者 CRM 的只读 MCP 服务器。任何 stdio MCP 客户端都可以使用它来查询捐赠者、按日期范围列出捐赠，或获取某人的捐赠历史。

服务器名称为 lgl-mcp。注册方式取决于宿主——参见设置。

构造上只读

此服务器没有创建、更新或删除工具——不是禁用，而是根本不存在。lgl.js 仅暴露一个 GET 请求函数；此项目中没有任何代码路径可以修改捐赠者记录。任何更改后运行 npm run audit:readonly 以机械方式确认。

任何未来的写入路径（例如同步捐款）都应属于 LGL 自身经过审查的集成队列，而非此处。

Related MCP server: SQL Server MCP

设置

1. 从 LGL 获取 API 密钥：设置 → 集成设置 → LGL API。

2. 将其放入 ~/.config/lgl-mcp/env（已创建，权限 600）：

   LGL_API_KEY=your-key-here

   或者，添加一个名为 lgl-api-key 的 macOS 钥匙串项目，或为一次性运行设置 LGL_API_KEY 环境变量。密钥永远不会被记录、提交或在错误消息中回显。

3. 安装依赖项（首次检出时已完成）：

   npm install

4. 将 stdio MCP 宿主指向此服务器。命令为 node；参数为 index.js 的绝对路径：

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

   根据宿主使用的配置格式（mcpServers、顶层服务器映射等）进行包装。如果密钥位于 ~/.config/lgl-mcp/env 或钥匙串中，则无需额外环境变量。仅在一次性覆盖时，在宿主的 env 块中设置 LGL_API_KEY。

工具

每个工具都接受 verbose: true 以获取完整的 LGL 对象而非精简摘要。紧凑的捐赠者信息包括姓名、电子邮件、电话和城市/州。捐赠日期和终身总额仅在 get_constituent 中提供。紧凑的捐赠信息包括日期、金额、fund_id、备注和捐赠者姓名（展开时）。有上限的列表响应会包含一个 note 字段，说明省略了多少结果——不会静默截断。

已确认的查询语法

LGL 的 /constituents/search 和 /gifts/search 接受 q[]=field=value 对，而非自由文本——这对某些字段来说未记录，并通过探测真实账户确认：

• 捐赠者：name=<文本>（LGL 自身记录的示例）或 eaddr=<电子邮件> 用于精确电子邮件匹配（未记录；类似 email=/email_address= 的猜测被拒绝）。

• 捐赠：date_from=YYYY-MM-DD / date_to=YYYY-MM-DD（已确认的真实过滤器——超出范围的日期会将 total_items 归零）。多个 q[] 条目以 AND 方式组合。

• 捐赠在此端点上没有基金或金额过滤器——fund_id、fund、fund_ids、campaign_id、amount_from、amount_to 均被尝试并作为未知参数拒绝。search_gifts 不暴露这些；如有需要，在客户端按 fund_id / note 过滤结果。

• 捐赠的捐赠者姓名仅在请求包含 expand=first_name,last_name,org_name 时出现——否则 LGL 不会在捐赠响应中嵌套捐赠者对象。

• get_constituent 的捐赠总额（首次/末次捐赠日期、终身金额）并非由 LGL 在捐赠者对象上返回——而是从此捐赠者自身的捐赠历史中计算得出，并分页完成。无捐赠的捐赠者返回 lifetime_amount: 0。仍适用安全上限（10,000 笔捐赠）；若达到上限，响应会说明。

开发

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

速率限制

LGL 允许每 5 分钟窗口内 300 次 API 调用。lgl.js 内部进行节流（滑动窗口）并在遇到 429/5xx 时带退避重试，因此一个需要多次调用的宽泛查询会优雅降级而非报错。