# rhdata — Guide d'intégration MCP (pour l'app de paie)

Ce document explique comment un assistant IA (Claude Code, Claude Desktop, ou un
client MCP maison) se **connecte** au serveur **rhdata** et **utilise** ses outils
pour la rédaction de bulletins de paie français.

## 1. Connexion

| | |
|---|---|
| **Endpoint MCP** | `https://rhdata.bystep.cloud/mcp` |
| **Transport** | MCP **Streamable HTTP** |
| **Auth** | En-tête `Authorization: Bearer <MCP_AUTH_TOKEN>` |
| **Healthcheck** | `GET https://rhdata.bystep.cloud/healthz` → `ok` (public) |
| **Logo/favicon** | `https://rhdata.bystep.cloud/logo.png` · `https://rhdata.bystep.cloud/logo.svg` (public) |

### Claude Desktop / Claude Code (`claude_desktop_config.json` ou `.mcp.json`)

```json
{
  "mcpServers": {
    "rhdata": {
      "type": "http",
      "url": "https://rhdata.bystep.cloud/mcp",
      "headers": { "Authorization": "Bearer VOTRE_TOKEN" }
    }
  }
}
```

### Client MCP (SDK Python)

```python
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

async with streamablehttp_client(
    "https://rhdata.bystep.cloud/mcp",
    headers={"Authorization": "Bearer VOTRE_TOKEN"},
) as (read, write, _):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        res = await session.call_tool("get_article",
            {"code": "code du travail", "numero": "L3141-1"})
```

## 2. Contrat de sortie (à respecter par le LLM)

- **Chaque** résultat porte sa **provenance** : `source`, `url`, `ref_id`, `date_version`.
  → Toujours **citer** la source dans la réponse finale (« Légifrance, art. L3141-1,
  version au 2016-08-10 » / « BOSS, rubrique X, au JJ/MM/AAAA »).
- **Jamais de chiffre de paie inventé.** Les valeurs certifiées viennent
  **exclusivement** de `get_parametre` (table curée, validée à la main). Si la valeur
  n'existe pas, l'outil renvoie une **erreur explicite** — ne pas la deviner.
- Les erreurs sont renvoyées comme `{"error": "...", "detail": "..."}` — les traiter,
  ne pas halluciner de contenu de substitution.

## 3. Deux natures de données

- **Recherche LIVE** (API officielles, données à jour) : `search_legifrance`,
  `get_article`, `search_convention`, `get_etablissement`, `get_entreprise`,
  `search_entreprise`, `stats_urssaf`.
- **Base documentaire** (mise à jour quotidienne, stockée + versionnée) : doctrine
  **BOSS** en RAG sémantique (`search_boss`), articles Légifrance historisés,
  **paramètres certifiés** (`get_parametre` / `list_parametres`), veille
  (`list_maj_recentes`). `health()` donne la fraîcheur par source.

## 4. Les 12 outils

### Paramètres chiffrés certifiés (hors RAG)
- `get_parametre(cle, date?)` → valeur **certifiée** à une date (ex. `cle="pmss"`,
  `date="2026-01-15"`). Renvoie `valeur, unite, date_effet, date_fin, source, valide_par`.
  **La seule source autorisée pour les chiffres** (PMSS, SMIC, taux…).
- `list_parametres(date?)` → tous les paramètres en vigueur à une date.

### Textes légaux — Légifrance (live)
- `search_legifrance(query, code?, top_k=5)` → passages d'articles. `code` ∈
  {"code du travail", "code de la sécurité sociale", …} ou un `LEGITEXT…`.
- `get_article(code, numero, date?)` → texte intégral consolidé d'un article
  (ex. `numero="L3141-1"`). `date` optionnelle pour une version historique.

### Conventions collectives — KALI (live)
- `search_convention(query, idcc?, top_k=5)` → recherche dans les conventions.
  Avec `idcc` (ex. `"1486"`) : cible cette branche (minima, primes, classifications).

### Doctrine — BOSS (RAG sémantique, base quotidienne)
- `search_boss(query, top_k=5)` → passages de doctrine opposable (allègements,
  avantages en nature, frais pro, rescrits…) avec URL + date de version.

### Employeur — Insee Sirene (live)
- `get_etablissement(siret)` → dénomination, NAF, tranche d'effectifs, adresse.
- `get_entreprise(siren)` → unité légale.
- `search_entreprise(query, top_k=5)` → recherche par dénomination.

### Veille & contexte
- `list_maj_recentes(depuis)` → nouveautés ingérées depuis une date ISO.
- `stats_urssaf(query, top_k=5)` → **contexte macro** (ODbL). ⚠️ Statistiques
  agrégées, **jamais** des règles applicables à un bulletin.
- `health()` → fraîcheur (dernière ingestion réussie) par source.

## 5. Exemple de raisonnement pour un bulletin

1. `get_etablissement(siret)` → secteur/effectifs de l'employeur (contexte).
2. `search_convention(query="prime ancienneté", idcc="1486")` → éléments de branche.
3. `get_parametre("pmss", "2026-01")` + `get_parametre("smic_horaire", "2026-01")`
   → chiffres **certifiés** pour le calcul.
4. `search_boss("réduction générale coefficient")` → règle/doctrine applicable.
5. `get_article("code de la sécurité sociale", "L241-13")` → base légale.
6. Rédiger en **citant** chaque source (avec sa date de version).
```