# Serveur MCP

Le serveur suit le [Model Context Protocol](https://modelcontextprotocol.io), transport Streamable HTTP. Il est sans session : chaque requête est indépendante, et il ne propose pas de flux de notifications.

```http
POST https://docs.hgdc.ch/mcp/<identifiant du projet>
Content-Type: application/json
```

- Les requêtes `POST` reçoivent une réponse JSON, jamais un flux.
- `GET` et `DELETE` répondent `405`.
- `OPTIONS` répond pour le préflight CORS : toute origine est acceptée.
- Un lot de requêtes JSON-RPC (un tableau) est refusé.

## Versions du protocole

`2025-11-25`, `2025-06-18` et `2025-03-26`. Si le client demande une autre version, le serveur répond avec la plus récente, `2025-11-25`.

## Méthodes

| Méthode      | Réponse                                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------- |
| `initialize` | Nom du serveur (`hgdc-docs`, avec le nom de la doc), capacités (`tools`) et consignes d’usage. |
| `ping`       | Objet vide.                                                                                    |
| `tools/list` | Les trois outils décrits ci-dessous.                                                           |
| `tools/call` | Le résultat de l’outil, en texte.                                                              |

Une notification, c’est-à-dire un message sans `id`, reçoit `202` sans corps. Une méthode inconnue reçoit une erreur JSON-RPC `-32601`.

## Outils

### `search_docs`

Cherche dans la doc et rend les passages les plus proches, chacun avec son titre, sa section, son adresse et son texte.

| Paramètre | Type   | Obligatoire | Règle                                          |
| --------- | ------ | ----------- | ---------------------------------------------- |
| `query`   | texte  | oui         | Question ou mots-clés, 500 caractères au plus. |
| `limit`   | entier | non         | De 1 à 10. Défaut : 5.                         |

### `get_page`

Rend une page complète en Markdown, précédée de son adresse.

| Paramètre | Type  | Obligatoire | Règle                                                                                               |
| --------- | ----- | ----------- | --------------------------------------------------------------------------------------------------- |
| `path`    | texte | oui         | Chemin de la page, tel que rendu par `search_docs` ou `list_pages`, par exemple `/guides/publier/`. |

### `list_pages`

Sans paramètre. Rend la liste des pages publiées, avec leur titre et leur chemin.

## Erreurs

Les erreurs suivent JSON-RPC, avec un `id` quand la requête en porte un.

| Code     | Message                                     | Cause                                                          |
| -------- | ------------------------------------------- | -------------------------------------------------------------- |
| `-32700` | Corps JSON invalide.                        | Le corps n’est pas du JSON.                                    |
| `-32600` | Requête JSON-RPC 2.0 attendue.              | Le message n’a pas la forme JSON-RPC 2.0.                      |
| `-32601` | Méthode non prise en charge.                | Méthode inconnue.                                              |
| `-32602` | Outil inconnu.                              | Nom d’outil inconnu dans `tools/call`.                         |
| `-32001` | Projet inconnu.                             | Identifiant absent, ou adresse qui n’est pas celle du serveur. |
| `-32029` | Trop de requêtes, réessaie dans une minute. | Limite par minute atteinte.                                    |

Un paramètre manquant dans un outil renvoie un résultat d’erreur de l’outil, comme `Paramètre path manquant.`, et non une erreur JSON-RPC.

## Limites

| Portée       | Limite                                   |
| ------------ | ---------------------------------------- |
| Par projet   | 300 requêtes par minute, 5 000 par jour. |
| Par visiteur | 60 requêtes par minute.                  |

Au-delà, le serveur répond avec le code `-32029`. Le détail des limites est dans [Limites](/docs/reference/limites/).

Le serveur ne donne accès qu’à ce que le site publie déjà. Il ne fait pas appel au modèle qui rédige les réponses de l’assistant.