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.

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

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 :

{
  "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 :

# 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 :

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.