# satelia-mcp-lucca

Un serveur MCP (Model Context Protocol) qui permet a Claude d'interroger votre instance **Lucca** en langage naturel : lister les collaborateurs, les departements, consulter les absences et la consommation de conges par type.

> 🚀 **Vous installez le projet sur votre Mac ?** Suivez le guide pas a pas : **[SETUP.md](SETUP.md)**.

## C'est quoi ?

Un serveur MCP est un petit programme qui ajoute des « outils » a Claude. Une fois branche a Claude Desktop, vous pouvez demander a Claude d'utiliser ces outils pendant une conversation (ex. « Qui est absent la semaine prochaine dans l'equipe Sales ? »).

Ce serveur expose 4 outils, en lecture seule :

- **`lister-collaborateurs`** — liste / recherche les salaries (par prenom, nom ou email) et donne, pour chacun : identifiant, poste, departement, manager, date d'anciennete, fin de periode d'essai et fin de 2nde periode d'essai (renouvellement). Par defaut, les anciens collaborateurs (contrat termine) sont masques.
- **`lister-departements`** — liste les departements (services / equipes) avec leur identifiant et leur code.
- **`lister-absences`** — liste les absences (conges, RTT, etc.) sur une periode donnee, pour un collaborateur (via son id) ou un departement (via son id).
- **`consommation-conges`** — calcule les jours d'absence PRIS par type (conges payes, RTT, recuperation…) sur une periode, pour un collaborateur ou un departement. NB : c'est la consommation, pas le solde restant (l'API Lucca n'expose pas les soldes).

Enchainement typique : Claude appelle d'abord `lister-collaborateurs` pour trouver l'id d'une personne, puis `lister-absences` avec cet id.

## Prerequis

- Node.js version 18 ou superieure (`node --version`). Sinon : https://nodejs.org (version « LTS »).
- Un acces a l'API Lucca : le **sous-domaine** de votre instance et une **cle API**.

## Installation

```bash
npm install
npm run build
```

Si tout va bien, un dossier `build` apparait (`build/index.js`, `build/lucca.js`).

## Acces Lucca (important)

Le serveur ne contient **aucun** secret. Les acces sont lus dans des **variables d'environnement** :

| Variable | Role | Exemple |
|---|---|---|
| `LUCCA_INSTANCE` | le sous-domaine de votre instance : `https://<ICI>.ilucca.net` | `satelia` |
| `LUCCA_API_KEY` | votre cle API (Parametres Lucca → Cles API) | `xxxxxxxx-xxxx-...` |
| `LUCCA_BASE_URL` | (optionnel) URL complete, pour surcharger (ex. environnement de test) | `https://satelia.ilucca-test.net` |

Pour recuperer une cle API : dans Lucca, **Parametres → Cles API → creer une cle** (une cle dediee par integration, avec le role/perimetre minimal necessaire).

Pour un test rapide en local, copiez `.env.example` en `.env` (ignore par git) et remplissez vos acces.

## Connecter le serveur a Claude Desktop

Claude Desktop lit un fichier de configuration ou vous declarez vos serveurs MCP.

- macOS : `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows : `%APPDATA%\Claude\claude_desktop_config.json`

Ajoutez votre serveur dans `mcpServers` (remplacez le chemin et la cle). **La cle va dans le bloc `env`, jamais dans le code :**

```json
{
  "mcpServers": {
    "satelia-mcp-lucca": {
      "command": "node",
      "args": ["/chemin/absolu/vers/satelia-mcp-lucca/build/index.js"],
      "env": {
        "LUCCA_INSTANCE": "satelia",
        "LUCCA_API_KEY": "votre-cle-api"
      }
    }
  }
}
```

Pour obtenir le chemin absolu, lancez `pwd` dans le dossier du projet et ajoutez `/build/index.js`.

Fermez puis rouvrez Claude Desktop. Essayez : « Liste-moi les departements Lucca » ou « Qui est absent en juillet dans l'equipe Sales ? ».

Note : apres toute modification du code, relancez `npm run build` puis redemarrez Claude Desktop.

## Tester

Un smoke test verifie que le serveur demarre, expose les 3 outils, et — si les acces Lucca sont dans l'environnement — fait un vrai appel a l'API :

```bash
# sans acces : test structurel seulement
node test/smoke.mjs

# avec acces (charge le .env local) : test + vrais appels
set -a; . ./.env; set +a; node test/smoke.mjs
```

Pour explorer visuellement les outils :

```bash
npm run build
npx @modelcontextprotocol/inspector node build/index.js
```

## Ajouter votre propre outil

Tout se passe dans `src/index.ts`, dans le bloc bien visible :

```
// ====== AJOUTEZ VOTRE OUTIL ICI ======
```

Copiez un des outils existants (ex. `lister-departements`), adaptez le nom, la description (en francais), les champs d'entree (`inputSchema`) et l'appel `luccaFetch(...)`, puis relancez `npm run build`. Le client Lucca (`src/lucca.ts`) gere deja l'authentification et les erreurs.

## Commandes utiles

- `npm run build` : compile le projet dans `build`.
- `npm run start` : lance la version compilee.
- `npm run dev` : lance directement le code source (pratique en developpement).
- `node test/smoke.mjs` : smoke test.

## Licence

MIT. Voir le fichier `LICENSE`.