# MCP Google Maps Scraper (Apify)

Serveur **MCP** (Model Context Protocol) en Python qui expose l'Actor Apify
[**Google Maps Scraper**](https://apify.com/compass/crawler-google-places)
(ID : `nwua9Gu5YrADL7ZDj`) sous forme d'outils utilisables par un client MCP
(Claude, ChatGPT Apps, etc.).

- **SDK** : `mcp` (FastMCP inclus) + `apify-client` (client asynchrone)
- **Transport** : streamable HTTP (`/mcp`) — prêt pour un déploiement sur **Alpic AI**
- **Gestion des dépendances** : `uv`

## Outils exposés

| Outil | Description | Paramètres |
|-------|-------------|------------|
| `search_places` | Recherche de lieux par mots-clés + zone géographique | `search_terms`, `location`, `max_results=20`, `language="en"` |
| `get_place_details` | Fiche détaillée d'un lieu via son `placeId` ou une URL Google Maps | `place_id`, `language="en"` |

Chaque outil accepte un paramètre `ctx: Context | None = None` réservé à une
authentification/télémétrie future.

## Prérequis

- Python ≥ 3.11
- [`uv`](https://docs.astral.sh/uv/)
- Un jeton d'API Apify : https://console.apify.com/account/integrations

## Installation

```bash
uv sync
```

## Configuration

```bash
cp .env.example .env
# puis renseignez APIFY_TOKEN dans .env
```

| Variable | Obligatoire | Défaut | Rôle |
|----------|:-----------:|--------|------|
| `APIFY_TOKEN` | ✅ | — | Jeton d'API Apify |
| `HOST` | | `0.0.0.0` | Interface d'écoute |
| `PORT` | | `8000` | Port d'écoute (injecté par Alpic) |
| `MCP_PATH` | | `/mcp` | Chemin de l'endpoint MCP |
| `LOG_LEVEL` | | `INFO` | Niveau de log |
| `APIFY_MAX_RESULTS_CAP` | | `100` | Plafond de résultats par recherche |

## Lancement en local

```bash
export APIFY_TOKEN="votre_token"
uv run python main.py
```

Le serveur écoute alors sur `http://0.0.0.0:8000/mcp`.

### Tester avec l'inspecteur MCP

```bash
npx @modelcontextprotocol/inspector
# Transport : Streamable HTTP — URL : http://localhost:8000/mcp
```

## Déploiement sur Alpic AI

1. Poussez ce dépôt sur GitHub.
2. Connectez le dépôt dans Alpic et choisissez la branche de production.
3. Renseignez la variable d'environnement `APIFY_TOKEN`.
4. Les commandes de build/start sont décrites dans [`alpic.yaml`](./alpic.yaml).

Alpic déploie une nouvelle version à chaque push sur la branche sélectionnée.

## Structure

```
.
├── main.py           # Serveur MCP + outils Apify
├── pyproject.toml    # Dépendances (uv)
├── alpic.yaml        # Configuration de déploiement Alpic
├── .env.example      # Modèle de variables d'environnement
└── README.md
```