# GPSEM MCP

Serveur [MCP](https://modelcontextprotocol.io) de [GPSEM](https://app.gpsem.io) : il donne à un assistant IA (Claude, ChatGPT, Cursor, Windsurf…) l'accès à votre compte GPSEM.

- **Pages, catégories, archives (CPT)** : lister, lire la fiche complète d'une page (SEO, indexation, scores, historique, problèmes de crawl), créer, modifier.
- **Historique des modifications** : lire et ajouter des événements (site, page, catégorie, archive), dont chaque lien interne avec sa page source et sa date, pour mesurer l’effet de chaque changement sur le crawl, l’indexation et le trafic.
- **Search Console, GA4, Bing Webmaster, Merchant Center, YouTube** : interrogés en direct avec les connexions déjà faites dans GPSEM, sans rien reconnecter. Search Console et GA4 acceptent des requêtes libres (dimensions, métriques, filtres, périodes).
- **Audit SEO** : sections collectées à la demande ; 14 types de rapports préréglés (express, résultats, visibilité, trafic, concurrence, indexation, contenus, maillage, performance, historique, cadrage, technique, complet, Knowledge Graph), en aperçu, PDF et PowerPoint ; scores, plan d’action priorisé avec gain estimé, suivi des actions.
- **Rapports mis en page** : rapports prêts à l'emploi (mensuel, direction, hebdomadaire, visibilité Google, audience, indexation, technique, contenus, e-commerce, IA, bilan annuel) calculés pour la période voulue, avec comparaison ; chiffres lisibles par l'assistant, composition d'un rapport sur mesure à partir d'une centaine de modules, et lien public (aperçu + PDF, sans connexion, période figée, révocable) à insérer dans un e-mail.
- **Outils GPSEM** : 57 tableaux et croisements (opportunités, concurrence Semrush, saisonnalité, motifs des non indexées, activité de Google, liens internes datés…) des écrans et de la boîte à outils, groupés par thème (indexation, contenus et pruning, mots-clés et Search Console, maillage, netlinking, analytics et conversions, planning éditorial).
- **Tableaux croisés e-commerce** : une cinquantaine de tableaux par fiche produit qui croisent catalogue, Search Console, Google Analytics 4, Merchant Center, crawl et tests d'indexation (position × ventes, ruptures qui coûtent, requêtes d'achat, fiches jumelles, liens internes × demande, qualité du flux, prix du marché, saisonnalité…). Modules `ecommerce_*` de `listReportModules`, lus avec `getReportData` (`modules=…`, et `settings` pour choisir la vue et le nombre de lignes) ; chaque ligne porte l'adresse de la page.
- **Recherche de différences** : pour quelques adresses (du site ou d'un concurrent), ce que la Wayback Machine en a gardé sur plusieurs périodes est lu et comparé — contenu refait, balise titre et meta description réécrites, fichiers CSS et JS, CMS, thème et outils installés ou retirés — avec la date des gros changements, cherchée en coupant la période en deux.
- **Screaming Frog** : lancer un crawl, problèmes par catégorie, plan d'action, rapport par problème (avec la documentation Google), problèmes d'une page, correction automatique des liens vers des 404, des redirections 301 et des boucles de redirection (une à la fois par site, avec son état).
- **Audit Opquast** : créer un audit, parcourir les 240 règles par catégorie, y répondre (conforme / non conforme) avec un commentaire argumenté à partir du crawl et des pages, marquer les catégories hors périmètre, rédiger la synthèse de chaque catégorie.
- **Analyses** : suggestions de maillage interne, NavRank / ClickRank, mots-clés et analyse sémantique, cartographie sémantique du site.
- **Veille et tendances** : sujets en hausse pour le site, analyse d’une page externe (concurrent, actualité) pour savoir si elle a du sens pour le site, ajout en idée ou rédaction, topics surveillés et leurs insights.
- **Rédaction** : idées de contenu, rédaction automatique depuis une expression, une ou plusieurs URL (réécriture d'une page concurrente), un mot-clé.
- **Éditeurs de contenu** : l'assistant sait dans quel éditeur est chaque page (éditeur classique, blocs Gutenberg, Elementor sur WordPress, Creative Elements sur PrestaShop) et écrit dans le bon format : il conserve les blocs d'une page Gutenberg, lit et modifie la structure et les widgets d'une page Elementor, connaît les widgets disponibles sur le site et leurs réglages, et peut régler l'éditeur par défaut du site ou d'un type de contenu.
- **Synchronisation CMS** : envoyer une page vers le CMS du site, réimporter une page, synchroniser tout le site.
- **Backlinks (MyBack.link)** : crédit, coût des options, ancres déjà utilisées, historique des commandes, commande de backlinks vers vos pages. L'achat via le MCP est désactivé par défaut : il s'active dans GPSEM, paramètres MyBack.link de l'entreprise, avec un plafond mensuel et un nombre maximal d'articles par commande.
- **Compte** : ajout de site (dans la limite de l'abonnement), coordonnées de l'entreprise, paramètres du site, mentions légales.

Les outils sont générés au démarrage depuis la spécification OpenAPI de l'API GPSEM : toute nouvelle route de l'API devient un outil, sans mise à jour du paquet.

## Installation

Il faut Node.js 18 ou plus et un **token API GPSEM** : dans GPSEM, menu utilisateur → *API & MCP*, ou fiche entreprise → onglet *API GPSEM* → *Créer un token*. Le token n'est affiché qu'une fois.

### Claude Code

```bash
claude mcp add gpsem -e GPSEM_API_TOKEN=gpsem_votre_token -- npx -y github:puples/gpsem-mcp
```

### Claude Desktop, Cursor, Windsurf et autres clients MCP

Dans le fichier de configuration MCP du client (`claude_desktop_config.json`, `.cursor/mcp.json`…) :

```json
{
  "mcpServers": {
    "gpsem": {
      "command": "npx",
      "args": ["-y", "github:puples/gpsem-mcp"],
      "env": { "GPSEM_API_TOKEN": "gpsem_votre_token" }
    }
  }
}
```

### Variables d'environnement

| Variable | | Rôle |
|---|---|---|
| `GPSEM_API_TOKEN` | obligatoire | Token `gpsem_…` de l'entreprise |
| `GPSEM_SITE_ID` | facultatif | Site par défaut (ID encodé) : plus besoin de préciser `siteId` |
| `GPSEM_API_URL` | facultatif | Défaut `https://app.gpsem.io/api/v1/external` |
| `GPSEM_MAX_CHARS` | facultatif | Taille maximale d'une réponse transmise à l'assistant (défaut 60 000 caractères) |
| `GPSEM_EXPORT_DIR` | facultatif | Dossier où l'assistant peut enregistrer les réponses complètes en fichier (voir *Export en fichier*). Absent : pas d'export en fichier |
| `GPSEM_EXPORT_MAX_PAGES` | facultatif | Nombre maximal de pages enchaînées par `toutes_les_pages` (défaut 200) |

Le token reste sur votre poste : le serveur MCP appelle directement l'API GPSEM, sans intermédiaire.

## Exemples de demandes

- « Quels sont les 10 chantiers SEO prioritaires de mon site, avec leur gain estimé ? »
- « Liste les pages qui ont beaucoup d'impressions mais un click rank faible et propose de nouvelles balises title. »
- « Corrige la meta description des pages sans meta, envoie-les sur WordPress et note-le dans l'historique. »
- « Quelles pages sont hors sujet d'après la cartographie sémantique ? »
- « Rédige un article à partir de cette page concurrente : https://… »
- « Sur la page Elementor /services, remplace le texte du deuxième bloc et ajoute un bouton vers /contact, sans toucher à la mise en page. »
- « Les mentions légales de mon site sont-elles complètes ? Complète l'hébergeur et le directeur de la publication. »
- « Crée un nouveau site pour https://exemple.fr si mon abonnement le permet. »
- « Lance un crawl Screaming Frog, puis fais l'audit Opquast du site à partir du crawl, avec un commentaire pour chaque règle. »
- « Quelles pages mériteraient des backlinks ce mois-ci ? Prépare une commande MyBack.link de 3 articles, je valide avant. »

## Catalogue des rapports

À la connexion, le serveur envoie à l'assistant la liste de tous les rapports disponibles, dans ses consignes : chaque section / question de l'audit complet (par chapitre), Screaming Frog, NavRank / ClickRank, Opquast, sources de données, analyses, avec l'outil et les arguments à utiliser. Avec `GPSEM_SITE_ID`, la liste est celle du site : rapports indisponibles signalés (source non connectée, pas de crawl…) et problèmes Screaming Frog relevés au dernier crawl.

Le catalogue complet est aussi exposé :
- en outils : `listReports` (général) et `listReportsForSite` ;
- en ressources MCP : `gpsem://rapports` et `gpsem://sites/{siteId}/rapports`.

## Export en fichier

Pour exporter une grosse liste (pages, mots-clés, tableau d'un outil GPSEM…), l'assistant n'a pas à la lire tranche par tranche dans la conversation : avec `GPSEM_EXPORT_DIR`, le serveur écrit lui-même la réponse dans un fichier de ce dossier.

```json
"env": { "GPSEM_API_TOKEN": "gpsem_votre_token", "GPSEM_EXPORT_DIR": "C:\\Users\\moi\\exports-gpsem" }
```

Chaque outil de lecture reçoit alors deux arguments de plus :

| Argument | | Rôle |
|---|---|---|
| `enregistrer_sous` | texte | Nom de fichier relatif au dossier d'export, ex. `pages-site.json` ou `2026-10/mots-cles.csv` (les sous-dossiers sont créés). Extensions admises : `.json`, `.jsonl`, `.csv`. Un chemin absolu ou contenant `..` est refusé |
| `toutes_les_pages` | vrai / faux (défaut faux) | Si la réponse est paginée (`limit` / `page`, ou `offset`), enchaîne les pages jusqu'au bout et réunit tout dans le même fichier, dans la limite de `GPSEM_EXPORT_MAX_PAGES` |

La réponse **complète** est écrite dans le fichier, sans la troncature de `GPSEM_MAX_CHARS`. L'assistant ne reçoit qu'un accusé : chemin du fichier, taille, nombre de lignes, `meta.total`, noms des colonnes et les 3 premières lignes en aperçu.

- `.json` : la réponse telle que reçue ; avec `toutes_les_pages`, `{ meta, data: [...] }` avec toutes les lignes.
- `.jsonl` : une ligne par élément de la liste.
- `.csv` : une ligne par élément, colonnes = toutes les clés de premier niveau, valeurs imbriquées en JSON, séparateur `;`, UTF-8 avec BOM (s'ouvre directement dans Excel).

`.jsonl` et `.csv` demandent une réponse en liste ; une réponse qui n'en est pas une s'enregistre en `.json`. Si une erreur survient en cours de pagination, les pages déjà lues restent dans le fichier et l'accusé dit où reprendre. Un fichier du même nom est remplacé. Les outils qui modifient des données n'ont pas ces arguments, et le token n'est jamais écrit dans un fichier.

## Bonnes pratiques intégrées

- **Données par étapes** : les grosses réponses sont résumées ou paginées (sections d'audit : `data_index` puis `data=` / `bloc=` ; cartographie : `cluster=`, `q=`, `page_id=` ; listes : `limit`, `page`). Au-delà de `GPSEM_MAX_CHARS`, la réponse est tronquée avec une indication pour affiner la demande.
- **Historique** : l'assistant lit `getHistoriqueCodes` et choisit le code le plus précis, ou le code générique de la cible (`100-09-001` site, `300-09-001` page, `310-09-001` catégorie, `320-09-001` archive). Les événements ajoutés par le MCP portent la source `mcp`.
- **Éditeurs de contenu** : avant de modifier un contenu, l'assistant lit l'éditeur de la page (`getPage`, champ `editor`). Page en blocs : les délimiteurs de blocs sont conservés. Page Elementor : il modifie la structure (`elementor_data`) en gardant identifiants et réglages de style ; un contenu qui ne correspond plus à la structure est refusé plutôt que d'écraser la mise en page. Les widgets et leurs réglages viennent de `getContentEditors`.
- **Actions à effet réel** (publication CMS, rédaction automatique, création de site, génération d'audit, modification du compte) : signalées aux clients MCP comme non en lecture seule ; l'assistant est invité à demander confirmation.

## Vérifier l'installation

```bash
npx -y github:puples/gpsem-mcp --list-tools
```

Affiche la liste des outils (ne nécessite pas de token).

Documentation de l'API : [app.gpsem.io/api/v1/external/docs](https://app.gpsem.io/api/v1/external/docs).

## Licence

MIT