<div align="center">

# PeopleLikeUs MCP

**MCP server for the [PeopleLikeUs](https://www.peoplelikeus.world) home-exchange platform — search homes, message members, manage your calendar and exchanges from your AI assistant.**

[![License: MIT](https://img.shields.io/github/license/manganate006/peoplelikeus-mcp)](LICENSE)
![Node](https://img.shields.io/badge/node-%E2%89%A518-brightgreen)
![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)
![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.26%2B-purple)

**[Installation](#installation) · [Tools](#tools) · [Examples](#examples) · [Limitations](#limitations) · [🇫🇷 Français](README.fr.md)**

</div>

## Overview

This [MCP](https://modelcontextprotocol.io) server exposes PeopleLikeUs as **26 tools** your assistant can call. Login is automatic from your email/password — **no manual token extraction** (no CAPTCHA, no Auth0). Ask in natural language:

> **You:** Search homes in Portugal, then add availability on my property 40646 from July 4 to August 29.
>
> **Assistant:** *(calls `plu_search_homes`, then `plu_add_availability`)*
> 12 homes in Portugal (Lisbon, Porto, Algarve…). Availability added on property 40646 for Jul 4 → Aug 29. ✅

## Requirements

- **Node.js ≥ 18**
- A **PeopleLikeUs** account (Premium recommended)
- Any **MCP client** — Claude Code, Claude Desktop, Cursor…

## Installation

```bash
git clone https://github.com/manganate006/peoplelikeus-mcp
cd peoplelikeus-mcp
npm install && npm run build
```

### Claude Code

```bash
claude mcp add peoplelikeus \
  --env PLU_EMAIL=your@email.com \
  --env PLU_PASSWORD=yourpassword \
  -- node /absolute/path/to/peoplelikeus-mcp/dist/index.js
```

### Claude Desktop / Cursor

Add to `claude_desktop_config.json` (or your client's MCP config):

```json
{
  "mcpServers": {
    "peoplelikeus": {
      "command": "node",
      "args": ["/absolute/path/to/peoplelikeus-mcp/dist/index.js"],
      "env": {
        "PLU_EMAIL": "your@email.com",
        "PLU_PASSWORD": "yourpassword"
      }
    }
  }
}
```

## Authentication

Set `PLU_EMAIL` + `PLU_PASSWORD` — the server handles login, CSRF and session automatically (cached at `~/.peoplelikeus-mcp-session.json`, 1 h TTL). Alternatives (browser cookies via `PLU_COOKIES`, runtime `plu_login`), rate-limit tuning and the full auth priority: **[docs/TOOLS.md](docs/TOOLS.md#configuration)**.

## Tools

26 tools, `plu_` prefix. Summary by domain — full parameters in **[docs/TOOLS.md](docs/TOOLS.md)**.

| Domain | Tools | Examples |
|---|---|---|
| 🔐 Auth | 3 | `plu_auth_status`, `plu_login`, `plu_set_cookies` |
| 🏠 Properties | 2 | `plu_get_property`, `plu_get_my_properties` |
| 📅 Calendar | 6 | `plu_add_availability`, `plu_delete_unavailability` |
| 💬 Conversations & messages | 5 | `plu_get_conversations`, `plu_send_message` |
| 🔄 Exchanges | 6 | `plu_create_exchange`, `plu_update_exchange_type`, `plu_cancel_exchange` |
| 🔍 Search | 2 | `plu_search_homes`, `plu_quick_search` |
| 🔔 Misc | 2 | `plu_get_notifications`, `plu_get_auth_user` |

## Examples

- "Search for homes in Portugal"
- "Show my conversations"
- "Message user 12345 about property 67890: \"Hello, we love your place…\""
- "Add availability for my property 40646 from July 4 to August 29"
- "Show my exchanges, then cancel exchange 22076"

## Limitations

- **HTML parsing** — some pages are Laravel Blade server-rendered; extraction depends on the HTML structure and can break if the site changes
- **No image upload** for property photos (multipart not implemented)
- **Read-only listings** — no property creation/editing
- **Search** uses `country_long`; location search needs coordinates (no server-side Google Places)
- **Rate limiting** — 1500 ms between requests by default (`PLU_REQUEST_DELAY`); auto retry/backoff on HTTP 429/503

## Development

```bash
npm run dev     # tsc watch
npm run build   # compile TypeScript
```

Full tool reference, configuration and architecture: **[docs/TOOLS.md](docs/TOOLS.md)**.

## License

[MIT](LICENSE)