Rescuedogs MCP Server

1# rescuedogs-mcp-server
2 
3[![npm version](https://badge.fury.io/js/rescuedogs-mcp-server.svg)](https://www.npmjs.com/package/rescuedogs-mcp-server)
4[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5 
6### Search by lifestyle
7![Search demo](demo-1.png)
8 
9### Get detailed profiles
10![Detail demo](demo-2.png)
11 
12MCP server for discovering rescue dogs from European and UK organizations. Search, filter, and get detailed profiles of dogs available for adoption.
13 
14## Installation
15 
16```bash
17npm install -g rescuedogs-mcp-server
18```
19 
20## Claude Desktop Configuration
21 
22Add to `~/.config/claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
23 
24```json
25{
26  "mcpServers": {
27    "rescuedogs": {
28      "command": "npx",
29      "args": ["-y", "rescuedogs-mcp-server"]
30    }
31  }
32}
33```
34 
35## Available Tools
36 
37### rescuedogs_search_dogs
38 
39Search for rescue dogs with comprehensive filtering.
40 
41```
42"Find medium-sized dogs good for first-time owners"
43"Show me golden retrievers available to adopt in the UK"
44"Find low-energy dogs suitable for apartments"
45```
46 
47**Parameters:**
48- `query` - Free-text search
49- `breed` - Filter by breed name
50- `breed_group` - Filter by FCI group (Herding, Sporting, etc.)
51- `size` - Tiny, Small, Medium, Large, XLarge
52- `age_category` - puppy, young, adult, senior
53- `sex` - male, female
54- `energy_level` - low, medium, high, very_high
55- `experience_level` - first_time_ok, some_experience, experienced_only
56- `home_type` - apartment_ok, house_preferred, house_required
57- `adoptable_to_country` - ISO country code (GB, IE, FR, DE)
58- `include_images` - Include dog photos (default: false)
59 
60### rescuedogs_get_dog_details
61 
62Get full details for a specific dog including AI-generated personality profile.
63 
64```
65"Tell me about the dog with slug 'buddy-12345'"
66"Show me details for Max"
67```
68 
69**Parameters:**
70- `slug` - Dog's URL slug (required)
71- `include_image` - Include photo (default: true)
72 
73### rescuedogs_list_breeds
74 
75Get available breeds with counts and statistics.
76 
77```
78"What breeds are available?"
79"Show me herding breeds with at least 10 dogs"
80```
81 
82**Parameters:**
83- `breed_group` - Filter by FCI group
84- `min_count` - Minimum dogs available
85- `limit` - Number of breeds to return
86 
87### rescuedogs_get_statistics
88 
89Get overall platform statistics.
90 
91```
92"How many rescue dogs are available?"
93"Show me platform statistics"
94```
95 
96### rescuedogs_get_filter_counts
97 
98Get available filter options with counts based on current filters.
99 
100```
101"What filter options are available if I've selected Labrador breed?"
102"Show me available sizes for dogs in Spain"
103```
104 
105### rescuedogs_list_organizations
106 
107List rescue organizations with their statistics.
108 
109```
110"Which rescue organizations are in the UK?"
111"Show me all organizations"
112```
113 
114### rescuedogs_match_preferences
115 
116Find dogs matching your lifestyle preferences.
117 
118```
119"I live in an apartment, have moderate activity, and am a first-time dog owner"
120"Find dogs for an active family with a house and garden"
121```
122 
123**Parameters:**
124- `living_situation` - apartment, house_small_garden, house_large_garden, rural
125- `activity_level` - sedentary, moderate, active, very_active
126- `experience` - first_time, some, experienced
127- `has_children`, `has_other_dogs`, `has_cats` - boolean
128- `adoptable_to_country` - ISO country code
129 
130### rescuedogs_get_adoption_guide
131 
132Get information about the rescue dog adoption process.
133 
134```
135"How does rescue dog adoption work?"
136"Tell me about transport for adopting to the UK"
137"What fees should I expect?"
138```
139 
140**Parameters:**
141- `topic` - overview, transport, fees, requirements, timeline
142- `country` - ISO code for country-specific info
143 
144## Geographic Scope
145 
146This server covers **European and UK rescue organizations only**:
147 
148- United Kingdom
149- Ireland
150- Germany
151- France
152- Spain
153- Italy
154- Romania
155- Greece
156- Bulgaria
157- Cyprus
158- And more...
159 
160US, Canadian, and Australian rescues are not supported.
161 
162## Country Codes
163 
164Use these codes for the `adoptable_to_country` parameter:
165 
166| Code | Country |
167|------|---------|
168| GB | United Kingdom (UK also accepted) |
169| IE | Ireland |
170| DE | Germany |
171| FR | France |
172| ES | Spain |
173| IT | Italy |
174| NL | Netherlands |
175| BE | Belgium |
176| AT | Austria |
177| RO | Romania |
178| GR | Greece |
179| BG | Bulgaria |
180| CY | Cyprus |
181 
182Dogs can be adopted to countries where the rescue organization ships to. Use `rescuedogs_list_organizations` to see which countries each organization serves.
183 
184## Data Source
185 
186All data comes from [rescuedogs.me](https://www.rescuedogs.me), aggregating listings from vetted rescue organizations.
187 
188- 1,500+ available dogs
189- 12+ rescue organizations
190- 370+ breeds
191- 96% AI personality profile coverage
192 
193The platform is powered by the open-source [rescue-dog-aggregator](https://github.com/ssatama/rescue-dog-aggregator) project, which handles web scraping, data standardization, AI-powered personality extraction, and the public API.
194 
195## Docker
196 
197```bash
198docker build -t rescuedogs-mcp .
199docker run -i rescuedogs-mcp
200```
201 
202## Environment Variables
203 
204| Variable | Description | Default |
205|----------|-------------|---------|
206| `RESCUEDOGS_API_URL` | Base URL for the rescuedogs API | `https://api.rescuedogs.me` |
207| `RESCUEDOGS_IMAGE_URL` | Base URL for the image CDN | `https://images.rescuedogs.me` |
208 
209## Architecture
210 
211```
212src/
213├── index.ts              # Entry point — server setup and stdio transport
214├── constants.ts          # Shared constants (API URLs, cache TTLs, display limits)
215├── types.ts              # TypeScript type definitions for API responses
216├── schemas/
217│   └── index.ts          # Zod input schemas for all tools
218├── services/
219│   ├── api-client.ts     # Axios-based API client with retry logic
220│   ├── cache-service.ts  # In-memory cache with TTL support
221│   ├── formatters.ts     # Markdown formatters for API responses
222│   └── image-service.ts  # Image fetching and CDN transform URLs
223├── tools/
224│   ├── index.ts          # Tool registration barrel with logging wrapper
225│   ├── search-dogs.ts    # rescuedogs_search_dogs handler
226│   ├── get-dog-details.ts
227│   ├── list-breeds.ts
228│   ├── get-statistics.ts
229│   ├── get-filter-counts.ts
230│   ├── list-organizations.ts
231│   ├── match-preferences.ts
232│   └── get-adoption-guide.ts
233├── utils/
234│   └── mappings.ts       # Value mappings (age, sex, country, preferences)
235└── data/
236    └── adoption-guides.ts # Static adoption guide content
237```
238 
239## Development
240 
241```bash
242# Install dependencies
243npm install
244 
245# Run tests
246npm test
247 
248# Run tests with coverage
249npm run test:coverage
250 
251# Type check
252npm run typecheck
253 
254# Lint
255npm run lint
256 
257# Lint with auto-fix
258npm run lint:fix
259 
260# Build
261npm run build
262 
263# Development mode (tsx)
264npm run dev
265```
266 
267## Contributing
268 
269See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome!
270 
271## License
272 
273MIT
274