# Glowe Pinterest MCP

Un downloader Pinterest public, utilisable de deux façons : une CLI pour les humains et un serveur MCP `stdio` pour les agents IA. Le cœur est unique : la CLI et le MCP obtiennent donc les mêmes résultats, appliquent les mêmes validations d’URL et téléchargent uniquement dans un dossier local configuré.

> Utiliser seulement les contenus pour lesquels vous détenez les droits nécessaires. Ce projet lit les données publiques rendues par Pinterest : ce n’est ni une API Pinterest officielle, ni une manière de contourner une connexion, un paywall ou une restriction de contenu.

## Ce que le projet fait

- Résout les liens de Pins Pinterest et les liens courts `pin.it`.
- Recherche des Pins publics par mots-clés.
- Extrait le titre, la description, l’URL du Pin et les médias image/GIF/vidéo exposés publiquement.
- Essaie l’image `originals`, puis les variantes `1200x`, `736x`, etc. si Pinterest ne sert pas la meilleure version.
- Télécharge de manière atomique : fichier `.part`, renommage final, sans écraser un fichier existant.
- Refuse les redirections et URLs médias hors de `pinterest.*`, `pin.it` et des CDN `*.pinimg.com` autorisés.

La recherche utilise la ressource publique structurée rendue par Pinterest, avec un fallback HTML transparent si elle devient indisponible. Pinterest peut ne rendre qu’une première tranche de résultats sans connexion : ce n’est pas une pagination garantie et il ne faut pas l’utiliser pour aspirer des tableaux complets.

## Installation locale

Node 20 ou plus récent est requis.

```bash
cd tools/pinterest-mcp
npm install
```

Choisissez explicitement le dossier de sortie :

```bash
export PINTEREST_MCP_DOWNLOAD_DIR="$PWD/downloads"
```

Les médias sont limités à 35 MiB par défaut. Ajuster seulement si nécessaire :

```bash
export PINTEREST_MCP_MAX_MEDIA_BYTES=52428800
```

## CLI — pour les humains

Toutes les commandes acceptent `--json` pour une sortie exploitable par script.

```bash
# Rechercher des références, sans écrire de fichier
npm run cli -- search "coiffure bob femme" --limit 8

# Charger la page suivante avec le nextCursor renvoyé par la recherche précédente
npm run cli -- search "coiffure bob femme" --limit 8 --cursor "CURSEUR_RENVOYÉ"

# Inspecter exactement ce qu’un Pin expose avant de télécharger
npm run cli -- inspect "https://pin.it/EXEMPLE" --json

# Télécharger un ou plusieurs Pins dans un dossier local contrôlé
npm run cli -- download "https://www.pinterest.com/pin/99360735500167749/" --output ./downloads

# Éviter les vidéos lorsque seules les images intéressent le workflow
npm run cli -- download "https://www.pinterest.com/pin/99360735500167749/" --no-video

# Recherche suivie d’un téléchargement : à employer seulement après validation du volume
npm run cli -- search-download "hairstyle editorial" --limit 5 --output ./downloads
```

Les commandes `download` et `search-download` ne prennent jamais un chemin de sortie depuis une URL ou une réponse distante. Les noms de fichiers sont normalisés et les collisions produisent un suffixe plutôt qu’un écrasement.

## MCP — pour les agents IA

Lancer le serveur directement :

```bash
PINTEREST_MCP_DOWNLOAD_DIR="$PWD/downloads" npm run mcp
```

Il utilise `stdio` : aucun port, aucune clé Pinterest et aucun journal applicatif sur `stdout`. Les erreurs et diagnostics de démarrage restent sur `stderr`, afin de ne pas corrompre le protocole MCP.

Exemple de configuration locale Codex (`~/.codex/config.toml`) :

```toml
[mcp_servers.glowe_pinterest]
command = "node"
args = ["/CHEMIN_ABSOLU/glowe/tools/pinterest-mcp/bin/mcp-server.mjs"]

[mcp_servers.glowe_pinterest.env]
PINTEREST_MCP_DOWNLOAD_DIR = "/CHEMIN_ABSOLU/pinterest-downloads"
PINTEREST_MCP_MAX_MEDIA_BYTES = "36700160"
```

Après modification de la configuration, redémarrer le client MCP/Codex afin qu’il relance le processus. Pour tout autre client MCP, utilisez la même commande `node`, le même argument absolu et les mêmes variables d’environnement.

### Contrat des outils MCP

| Outil | Écrit sur disque | Usage agent recommandé |
| --- | --- | --- |
| `pinterest_search` | Non | Chercher et présenter des références avant toute action ; réutiliser `nextCursor` pour la page suivante lorsqu’il est présent. |
| `pinterest_get_pin` | Non | Vérifier un lien `pinterest.com` ou `pin.it`, ses médias et ses métadonnées. |
| `pinterest_download` | Oui | Demander confirmation, puis télécharger 1 à 20 Pins fournis. |
| `pinterest_search_and_download` | Oui | Utiliser uniquement après confirmation explicite du nombre de résultats. |
| `pinterest_status` | Non | Vérifier le dossier local et les limites en vigueur. |

Les outils de lecture portent l’annotation MCP `readOnlyHint`. Les outils qui écrivent sur disque expliquent dans leur description qu’une confirmation de l’utilisateur est requise. Un agent doit toujours privilégier cette séquence : `pinterest_search` → montrer la sélection → `pinterest_get_pin` → confirmation → `pinterest_download`.

### Exemple de réponse MCP

`pinterest_get_pin` renvoie un JSON structuré contenant notamment :

```json
{
  "id": "99360735500167749",
  "pinUrl": "https://www.pinterest.com/pin/99360735500167749/",
  "title": "…",
  "media": [
    {
      "type": "image",
      "url": "https://i.pinimg.com/originals/...jpg",
      "alternatives": ["https://i.pinimg.com/1200x/...jpg"]
    }
  ]
}
```

L’agent ne doit pas inventer la disponibilité d’un média : il s’appuie sur `media`, puis rapporte séparément chaque téléchargement réussi ou échoué.

## Tests et contrôle qualité

```bash
# Tests déterministes : URLs, parsing SSR, repli qualité, écriture atomique, handshake MCP
npm test

# Vérification réseau explicite : recherche réelle, extraction d’un Pin, téléchargement CDN réel
npm run test:live
```

Le test réseau est volontairement séparé : Pinterest peut modifier son HTML public ou rendre un Pin indisponible. Il ne doit jamais être masqué par les tests unitaires.

## Inspirations et choix techniques

Le design s’inspire des projets MIT [pinterest-downloader](https://github.com/MohammadAliMehri/pinterest-downloader) (priorité `originals` et cascade de qualité) et [PinterestDownloader](https://github.com/x7007x/PinterestDownloader) (contrats structurés Pin/recherche). L’interface MCP s’inspire de [mcp-pinterest](https://github.com/terryso/mcp-pinterest), mais l’implémentation ici est autonome, sans navigateur headless, avec une surface de téléchargement volontairement plus restrictive.

Pour les Pins et boards appartenant au compte Pinterest connecté, préférer l’[API Pinterest officielle](https://developers.pinterest.com/docs/api/v5/pins-get/) et OAuth. Les conditions Pinterest et les droits d’auteur restent applicables à tout contenu téléchargé.