# 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) pour mesurer l'effet de chaque changement sur le trafic.
- **Audit SEO complet** : sections collectées à la demande, rapports, scores, plan d'action priorisé avec gain estimé, suivi des actions.
- **Screaming Frog** : problèmes par catégorie, plan d'action, rapport par problème, problèmes d'une page.
- **Analyses** : suggestions de maillage interne, NavRank / ClickRank, mots-clés et analyse sémantique, cartographie sémantique du site.
- **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é.
- **Synchronisation CMS** : envoyer une page vers WordPress, 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) |

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://… »
- « 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. »
- « Quelles pages mériteraient des backlinks ce mois-ci ? Prépare une commande MyBack.link de 3 articles, je valide avant. »

## 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`.
- **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