# rescuedogs-mcp-server

[![npm version](https://badge.fury.io/js/rescuedogs-mcp-server.svg)](https://www.npmjs.com/package/rescuedogs-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

### Search by lifestyle
![Search demo](demo-1.png)

### Get detailed profiles
![Detail demo](demo-2.png)

MCP server for discovering rescue dogs from European and UK organizations. Search, filter, and get detailed profiles of dogs available for adoption.

## Installation

```bash
npm install -g rescuedogs-mcp-server
```

## Claude Desktop Configuration

Add to `~/.config/claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "rescuedogs": {
      "command": "npx",
      "args": ["-y", "rescuedogs-mcp-server"]
    }
  }
}
```

## Available Tools

### rescuedogs_search_dogs

Search for rescue dogs with comprehensive filtering.

```
"Find medium-sized dogs good for first-time owners"
"Show me golden retrievers available to adopt in the UK"
"Find low-energy dogs suitable for apartments"
```

**Parameters:**
- `query` - Free-text search
- `breed` - Filter by breed name
- `breed_group` - Filter by FCI group (Herding, Sporting, etc.)
- `size` - Tiny, Small, Medium, Large, XLarge
- `age_category` - puppy, young, adult, senior
- `sex` - male, female
- `energy_level` - low, medium, high, very_high
- `experience_level` - first_time_ok, some_experience, experienced_only
- `home_type` - apartment_ok, house_preferred, house_required
- `adoptable_to_country` - ISO country code (GB, IE, FR, DE)
- `include_images` - Include dog photos (default: false)

### rescuedogs_get_dog_details

Get full details for a specific dog including AI-generated personality profile.

```
"Tell me about the dog with slug 'buddy-12345'"
"Show me details for Max"
```

**Parameters:**
- `slug` - Dog's URL slug (required)
- `include_image` - Include photo (default: true)

### rescuedogs_list_breeds

Get available breeds with counts and statistics.

```
"What breeds are available?"
"Show me herding breeds with at least 10 dogs"
```

**Parameters:**
- `breed_group` - Filter by FCI group
- `min_count` - Minimum dogs available
- `limit` - Number of breeds to return

### rescuedogs_get_statistics

Get overall platform statistics.

```
"How many rescue dogs are available?"
"Show me platform statistics"
```

### rescuedogs_get_filter_counts

Get available filter options with counts based on current filters.

```
"What filter options are available if I've selected Labrador breed?"
"Show me available sizes for dogs in Spain"
```

### rescuedogs_list_organizations

List rescue organizations with their statistics.

```
"Which rescue organizations are in the UK?"
"Show me all organizations"
```

### rescuedogs_match_preferences

Find dogs matching your lifestyle preferences.

```
"I live in an apartment, have moderate activity, and am a first-time dog owner"
"Find dogs for an active family with a house and garden"
```

**Parameters:**
- `living_situation` - apartment, house_small_garden, house_large_garden, rural
- `activity_level` - sedentary, moderate, active, very_active
- `experience` - first_time, some, experienced
- `has_children`, `has_other_dogs`, `has_cats` - boolean
- `adoptable_to_country` - ISO country code

### rescuedogs_get_adoption_guide

Get information about the rescue dog adoption process.

```
"How does rescue dog adoption work?"
"Tell me about transport for adopting to the UK"
"What fees should I expect?"
```

**Parameters:**
- `topic` - overview, transport, fees, requirements, timeline
- `country` - ISO code for country-specific info

## Geographic Scope

This server covers **European and UK rescue organizations only**:

- United Kingdom
- Ireland
- Germany
- France
- Spain
- Italy
- Romania
- Greece
- Bulgaria
- Cyprus
- And more...

US, Canadian, and Australian rescues are not supported.

## Country Codes

Use these codes for the `adoptable_to_country` parameter:

| Code | Country |
|------|---------|
| GB | United Kingdom (UK also accepted) |
| IE | Ireland |
| DE | Germany |
| FR | France |
| ES | Spain |
| IT | Italy |
| NL | Netherlands |
| BE | Belgium |
| AT | Austria |
| RO | Romania |
| GR | Greece |
| BG | Bulgaria |
| CY | Cyprus |

Dogs can be adopted to countries where the rescue organization ships to. Use `rescuedogs_list_organizations` to see which countries each organization serves.

## Data Source

All data comes from [rescuedogs.me](https://www.rescuedogs.me), aggregating listings from vetted rescue organizations.

- 1,500+ available dogs
- 12+ rescue organizations
- 370+ breeds
- 96% AI personality profile coverage

The 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.

## Docker

```bash
docker build -t rescuedogs-mcp .
docker run -i rescuedogs-mcp
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `RESCUEDOGS_API_URL` | Base URL for the rescuedogs API | `https://api.rescuedogs.me` |
| `RESCUEDOGS_IMAGE_URL` | Base URL for the image CDN | `https://images.rescuedogs.me` |

## Architecture

```
src/
├── index.ts              # Entry point — server setup and stdio transport
├── constants.ts          # Shared constants (API URLs, cache TTLs, display limits)
├── types.ts              # TypeScript type definitions for API responses
├── schemas/
│   └── index.ts          # Zod input schemas for all tools
├── services/
│   ├── api-client.ts     # Axios-based API client with retry logic
│   ├── cache-service.ts  # In-memory cache with TTL support
│   ├── formatters.ts     # Markdown formatters for API responses
│   └── image-service.ts  # Image fetching and CDN transform URLs
├── tools/
│   ├── index.ts          # Tool registration barrel with logging wrapper
│   ├── search-dogs.ts    # rescuedogs_search_dogs handler
│   ├── get-dog-details.ts
│   ├── list-breeds.ts
│   ├── get-statistics.ts
│   ├── get-filter-counts.ts
│   ├── list-organizations.ts
│   ├── match-preferences.ts
│   └── get-adoption-guide.ts
├── utils/
│   └── mappings.ts       # Value mappings (age, sex, country, preferences)
└── data/
    └── adoption-guides.ts # Static adoption guide content
```

## Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type check
npm run typecheck

# Lint
npm run lint

# Lint with auto-fix
npm run lint:fix

# Build
npm run build

# Development mode (tsx)
npm run dev
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Issues and PRs welcome!

## License

MIT