Rescuegroups

@pipeworx/rescuegroups

RescueGroups.org で保護団体やシェルターが掲載している譲渡可能な動物と、各団体の情報です。団体名、品種、年齢、性別、サイズ、性格に関するフラグ、写真、譲渡費用、保護団体の連絡先、譲渡の手続き、対応地域を確認できます。種、郵便番号からの距離、品種、特性で検索できます。

Pipeworx の一部です。AI エージェントを 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) — 1 頭の動物について、すべての 写真、色、模様、ステータス、掲載団体を含む全情報を返します。
• rescuegroups_organizations(postalcode?, lat?, lon?, miles?, kilometers?, name?, state?, city?, type?, org_id?, sort?, limit?, page?, _apiKey) — 保護団体とシェルターを検索します。「自分の近く 25 マイル以内のシェルター」 「RescueGroups の団体 ID 1234 はどこ」などの質問に答えます。
• rescuegroups_species(limit?, page?, _apiKey) — 種の一覧です。 rescuegroups_adoptable の species 引数には、この一覧の値を指定します。
• rescuegroups_breeds(species?, limit?, page?, _apiKey) — 種ごとの品種一覧です。 正確な品種フィルターを作成する際に使用します。

認証

BYO キーのみです。 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

拒否されたキーは 401 ではなく、HTTP 200 と完全に空の本文を返します。必須の Content-Type ヘッダーがある場合もない場合も同じです（両方を確認済み。空の 200 はヘッダーの省略が原因ではありません）。そのまま渡すと「近くに譲渡可能な犬はいません」と解釈されますが、これは誤りです。また、キーに問題があることを示す情報が何もないため、ユーザー側では修正できません。そのため、このパックでは JSON ではない空の 200 を認証エラーとして扱い、その旨を伝えます。docs/silent-zero-policy.md を参照してください。

そのため、呼び出し元が遭遇しうる 3 つの状態は、意図的に異なる形で表示されます。

状態	表示される内容
_apiKey がまったくない	「RescueGroups には API キーが必要ですが、Pipeworx からは提供されません。」＋キーの申請先
_apiKey が上流で拒否された	「_apiKey として渡された API キーは受け付けられませんでした」＋RescueGroups が拒否を通知する方法＋キーのスコープに関する注意
キーを送信した状態で上流が 401 を返した	「認証に失敗しました（HTTP 401）」＋上流独自の詳細

キーが Authorization ヘッダーから外に出ることはありません。 URL に含められることはありません（呼び出しが成功したかどうかにかかわらず、すべての中継地点で URL がログに記録されます）。また、ハンドラーの実行前に args から削除されるため、使用記録に残ることもありません。上流から中継されるすべての文字列は、まず秘匿情報の除去処理を通ります。そのため、仮に RescueGroups がエラーの detail にキーを含めるようになっても、呼び出し元に表示されるメッセージにキーが含まれることはありません。識別可能な秘密情報を埋め込み、URL、本文、結果、エラーのいずれにも現れないことを検証するテストで確認済みです。

キーのスコープは発行時に設定されます。 申請フォームでは、対象の種と、自分の組織のみを対象にするか全国検索を行うかを指定します。範囲を狭くして発行されたキーでは、スコープ外のクエリに対して返される行が少なくなるか、まったく返されないことがあります。これは実際に結果が空の場合と見分けがつきません。拒否されたキーに関するメッセージではこの可能性にも触れているため、適切に範囲を限定したキーを持つ呼び出し元が、誤ったキーが原因だと考えて調査することを避けられます。

ドキュメントに従い、GET を含むすべてのリクエストで Content-Type: application/vnd.api+json が必要です。 ここでは常に送信します。

ビューは URL パスに重ね、フィルターは POST 本文に指定します。 available、種（dogs）、特徴（haspic、urgent、isneedingfoster）は「ビュー」で、連結して指定します：/public/animals/search/available/dogs/haspic/。それ以外（犬種、性別、サイズ、郵便番号からの距離）は filters ／ filterRadius オブジェクトとして、同じ検索 URL に POST します。パックは、呼び出し元から本文が必要な項目が渡されたかどうかに基づいて、GET と POST を選択します。

距離検索には場所と半径の両方が必要です。 RescueGroups では半径のない場所を指定すると、フィルターが適用されていない結果を返すため、半分だけ指定された場合は送信せず、ローカルで拒否します。こうした結果は、半径が正しく適用されたように見えてしまいます。

type を指定しない組織検索には、2 回の呼び出しが必要です。 組織のビューは rescue と shelter のみです。フィルター付きの組織検索ではパスにビューが必要であり、2 つを重ねることはできません（AND 条件になり、結果が空になるためです）。type が指定されていない場合、パックは両方を検索して結果を統合し、その旨を note で示します。この場合、pages は意味を持たないため、ページ分割が必要なときは type を指定してください。

null の属性は null 値としてではなく、省略されます（v5 の変更履歴、2019-10-03）。また、フィールドセットは時間とともに増えていきます。レスポンスマッパーはフィールドを個別に列挙するのではなく、意図的に汎用的な実装にしています。JSON:API の attributes をまとめてフラット化し、relationships を included と照合して 1 階層分解決するため、新しい上流フィールドも黙って破棄されずに表示されます。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）が必要です。こちらでは API キーを用意していないため、キーなしで実行できる 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