Rescuegroups

@pipeworx/rescuegroups

RescueGroups.org 上由救援组织和收容所发布的可领养动物，以及这些组织本身的信息——名称、品种、年龄、性别、体型、性情标记、照片、领养费用，以及救援组织的联系方式、领养流程和服务区域。可按物种、邮政编码范围、品种和特征搜索。

属于 Pipeworx——一个将 AI agents 连接到 1683+ 个实时数据源的 MCP 网关。

工具

• rescuegroups_adoptable(species?, postalcode?, lat?, lon?, miles?, kilometers?, breed?, sex?, age_group?, size_group?, name?, good_with_kids?, good_with_dogs?, good_with_cats?, views?, org_id?, include_adopted?, sort?, limit?, page?, _apiKey) — 主要搜索工具。可回答“距 15206 邮编 50 英里内可领养的比格犬”、 “匹兹堡适合和孩子相处的猫”、“需要临时寄养的狗”等问题。返回 动物的完整属性集，包括品种、图片、物种，以及内联解析的发布组织信息。
• rescuegroups_animal(animal_id, _apiKey) — 返回一只动物的完整信息，包括所有 图片、颜色、花纹、状态和发布组织。
• rescuegroups_organizations(postalcode?, lat?, lon?, miles?, kilometers?, name?, state?, city?, type?, org_id?, sort?, limit?, page?, _apiKey) — 搜索救援组织和收容所。可回答“我附近 25 英里内的收容所”、“RescueGroups 组织 1234 是谁”。
• rescuegroups_species(limit?, page?, _apiKey) — 物种词汇表，也就是 rescuegroups_adoptable 的 species 参数所需的值。
• rescuegroups_breeds(species?, limit?, page?, _apiKey) — 按物种列出的品种， 用于构建精确的品种筛选条件。

身份验证

仅支持自带密钥。 Pipeworx 不持有 RescueGroups 密钥，此工具包也从不读取平台密钥——每个工具的输入架构都将 _apiKey 设为 required，因此网关的披露界面会在调用前告知调用者，而不是等到拒绝后才告知。

可通过 https://rescuegroups.org/services/request-an-api-key/ 申请免费的公共密钥。申请表很简短 （姓名、电子邮件、组织、网站 URL、需要查询哪些物种，以及是否需要全国范围搜索）。个人开发者也可以申请——“not incorporated”是可接受的公司注册状态，而且 API 文档明确说明，你不需要 RescueGroups 账户，只需要公共密钥。工作人员会审核表单并通过电子邮件发送密钥，因此不能即时自助获取；拒绝消息会说明这一点，而不会承诺点击一下即可获得密钥。

提醒阅读 docs/paid-upgrade-watchlist.md 的人：该文件中将 RescueGroups 归入“普通开发者无法获得注册资格——要求申请者是有兽医、收容所和安乐死政策的动物救援组织”的条目，描述的是 /partner-requirements-and-expectations/ 中的合作伙伴入驻流程，这是救援组织将动物发布出来的方式。公开的 API 密钥申请表则是另一回事，对所有人开放。该条目已更正。

数据源

• https://api.rescuegroups.org/v5 — RescueGroups.org v5 公共 API，通过 HTTPS 提供 JSON:API。 完整参考文档（无需身份验证，无密钥也可阅读）： https://api.rescuegroups.org/v5/public/docs

否则后来的人还得费劲才能重新发现的事项

无效密钥不会报错，而是静默返回零结果。 已于 2026-09-05 进行线上探测：

GET /v5/public/animals/search/available/dogs/?limit=1     (no Authorization)
  -> 401 application/vnd.api+json
     {"errors":[{"status":401,"source":{"header":"Authorization"},
       "title":"Missing authorization header",
       "detail":"Missing authorization header - apikey authentication required"}]}

GET /v5/public/animals/search/available/dogs/?limit=1     (Authorization: <junk>)
  -> 200 OK, Content-Length: 0, Content-Type: text/plain;charset=UTF-8

被拒绝的密钥会返回HTTP 200，且响应体完全为空，而不是 401—— 无论是否提供必需的 Content-Type 标头，结果都一样（两种情况都已检查；空的 200 响应并非因省略标头所致）。如果不加处理地传递，这会被理解为“你附近没有可领养的狗”，这不仅是错误的，用户也无法解决，因为没有任何提示指出他们的密钥有问题。因此，本工具包会将任何空的非 JSON 200 响应视为身份验证失败，并明确说明。请参阅 docs/silent-zero-policy.md。

因此，调用者可能遇到的三种状态会有意呈现为不同的结果：

状态	用户看到的内容
完全没有 _apiKey	“RescueGroups 需要 API 密钥，而 Pipeworx 未提供密钥。” + 申请方式
_apiKey 被上游拒绝	“你通过 _apiKey 传入的 API 密钥未被接受” + RescueGroups 如何表示这一情况 + 密钥范围限制说明
发送了密钥，但上游返回 401	“授权失败（HTTP 401）” + 上游提供的详细信息

密钥绝不会离开 Authorization 标头。 不会将其放入 URL 中（无论调用是否成功，每一跳都会记录 URL）；任何处理程序运行前都会先将其从 args 中删除，因此它不会进入使用记录；并且，所有从上游转发的字符串都会先经过脱敏处理——所以即使 RescueGroups 开始在错误 detail 中回显密钥，调用方看到的消息也不会包含它。我们通过一项测试验证了这一点：植入一个易于识别的密钥，并断言它不会出现在 URL、请求正文、结果或错误路径中。

密钥在签发时就限定了范围。 申请表会询问要查询哪些物种，以及只查询你自己的组织，还是进行全国范围的搜索。范围较窄的密钥对范围以外的查询会返回较少的记录，甚至不返回记录——这与结果确实为空的情况看起来完全相同。密钥被拒绝时显示的消息会指出这一可能性，避免使用范围较窄的有效密钥的调用方误以为密钥有问题。

根据文档，每个请求都必须携带 Content-Type: application/vnd.api+json，包括 GET 请求。 此处会无条件发送该标头。

视图位于 URL 路径中，筛选条件放在 POST 请求正文中。 available、物种（dogs）和特征（haspic、urgent、isneedingfoster）属于“视图”，会拼接成：/public/animals/search/available/dogs/haspic/。其他条件——品种、性别、体型、邮政编码范围——都属于 filters / filterRadius 对象，通过 POST 发送到同一个搜索 URL。该工具包会根据调用方是否提供了需要放入请求正文的内容来选择 GET 或 POST。

距离搜索需要同时提供位置和半径。 如果只提供其中一项，会在本地拒绝请求，而不会发送给上游，因为 RescueGroups 在没有半径时会静默返回未筛选的结果，让人误以为半径筛选已生效。

组织搜索未指定 type 时需要发起两次调用。 rescue 和 shelter 是仅有的组织视图；筛选组织搜索要求在路径中指定视图，而两个视图不能叠加（否则 AND 筛选的结果会为空）。未指定 type 时，该工具包会分别查询两种视图并合并结果，同时在 note 中说明这一点——在这种情况下，pages 没有意义；如果需要分页，请传入 type。

空属性会被省略，而不是设为 null（v5 更改日志，2019-10-03），并且字段集会随时间扩展。响应映射器刻意采用通用逻辑——整体展开 JSON:API 的 attributes，并根据 included 解析一层深度的 relationships——而不是逐一列出字段，因此上游新增字段时会一并显示，而不会被静默丢弃。raw 始终保留未经修改的请求正文。

速率限制未公开。 文档只说明 API 会在“请求数量异常”时返回 429，并建议调用方缓存参考数据。请缓存 rescuegroups_species 和 rescuegroups_breeds；它们很少变化。

提供了测试环境 test1-api.rescuegroups.org，路由相同，但也需要密钥；其数据可能已过时数周，并且不得用于生产环境。此处未接入该环境。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "rescuegroups": {
      "url": "https://gateway.pipeworx.io/rescuegroups/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/rescuegroups/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、discover_tools、search_within、remember/recall 和网关范围内的其他工具。因此，你看到的工具数量会多于此表所列：目前，单个工具包端点除了列出该工具包自有的工具外，还会列出大约 30 个共享工具。连接的 initialize 响应会说明其确切范围，是当天情况的权威依据。

这是有意设计的，并非意外的多路复用。元工具让限定范围的连接也能回答此工具包无法涵盖的问题——通过 ask_pipeworx 跨整个目录进行路由——因此你无需再添加第二个 MCP 服务。目前无法挂载不含这些工具的工具包端点；如果额外的模式消耗的上下文超过了路由带来的价值，请连接完整网关一次，而不是连接多个工具包端点。

或者，连接完整的 Pipeworx 网关，直接列出每个工具包的工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都会连接到同一个网关和同一组 1683+ 个数据源。唯一的区别是，哪个工具包的工具会被直接列出；无论连接哪一个，ask_pipeworx 都能访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

此工具包需要你提供自己的 API 密钥（_apiKey）——我们不会代为提供，因此这里没有无需密钥即可运行的 curl 命令。查看任意工具：GET https://gateway.pipeworx.io/v1/tools/rescuegroups_adoptable。查找工具：使用 {"query":"..."} 调用 POST https://gateway.pipeworx.io/v1/tools/search_packs。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需经过网关：

{
  "mcpServers": {
    "rescuegroups": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-rescuegroups"]
    }
  }
}

或者直接运行，以确认它可以启动：

npx -y @pipeworx/mcp-rescuegroups

它通过 stdin/stdout 使用 MCP 通信，并响应 initialize/tools/list/tools/call，但仅提供此工具包的工具——不包含上述网关连接额外提供的共享元工具。它使用相同的源码和工具，但不具备 ask_pipeworx 路由功能。

使用 ask_pipeworx

你可以用通俗英语提问，而不必直接调用工具——这在上面的工具包端点和完整网关上都适用：

ask_pipeworx({ question: "your question about Rescuegroups data" })

网关会选择合适的工具并自动填入参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT