mcp-eprojet

Serveur MCP local (stdio) qui permet à un assistant IA (Claude Code, Claude Desktop…) de piloter E-Projet, une application web interne de gestion de tâches et de timesheet. Objectif : automatiser une saisie manuelle fastidieuse (créer des tâches, saisir ses heures, corriger des champs) en parlant à l'assistant.

Projet personnel et non officiel. Il se connecte avec votre propre compte, par la session web (form login Spring Security, cookie JSESSIONID) : E-Projet n'a pas d'API publique, les pages HTML et les endpoints internes sont donc lus et soumis comme le ferait un navigateur.

Il vise une instance précise d'E-Projet. Avant de l'utiliser, vérifiez que l'automatisation de votre saisie est autorisée dans votre organisation (et s'il existe une API officielle).

Principes

• Lecture et écriture, avec garde-fous : toute écriture est en dry_run par défaut (montre ce qui serait envoyé). Rien n'est envoyé sans confirmer: true, à ne passer qu'après accord explicite de l'utilisateur.

• Vérification : après chaque écriture, la donnée est relue (verifie, ecarts).

• Journal local : actions.log (date, outil, données), jamais de mot de passe ni de cookie.

• Session : login à la première requête, un seul login à la fois, reconnexion automatique avec un seul nouvel essai (pas de boucle qui bloquerait le compte).

• Rythme calme : pas de rafale ; les lots attendent 0,5 s entre deux envois.

Related MCP server: bort

Prérequis

• Node.js 24 ou plus récent (--env-file, fetch), pnpm

• Un compte E-Projet et l'URL de l'instance (ex. https://e-projet.example.com/EProjet-1)

Installation

pnpm install
cp .env.example .env      # puis renseigner les trois variables ci-dessous
pnpm build                # produit dist/

Brancher dans Claude Code

claude mcp add eprojet --scope user -- node --env-file=/chemin/vers/.env /chemin/vers/dist/index.js

Brancher dans Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "eprojet": {
      "command": "node",
      "args": ["--env-file=/chemin/vers/.env", "/chemin/vers/dist/index.js"]
    }
  }
}

Les identifiants restent dans .env : Node les charge avec --env-file, ils ne sont jamais copiés dans la configuration de Claude. Après chaque modification du code : pnpm build puis relancer le client.

Utilisation

Demandez en langage naturel ; l'assistant choisit les outils. Exemples :

• « Montre-moi mes tâches actives. » → lister_taches

• « Crée une tâche de formation de 1 h 30 demain sur le projet X. » → creer_tache (dry-run, puis confirmation de votre part)

• « J'ai passé 3 h sur PRJ-576-0417 aujourd'hui, 60 %. » → saisir_timesheet

• « Combien d'heures ai-je saisies cette semaine ? » → lire_timesheet

• « Corrige la durée prévue de ces cinq tâches. » → modifier_taches (un dry-run pour le lot)

Le cycle normal d'une écriture : dry-run → vous relisez → confirmer: true → relecture verifie.

Outils

Les dates sont au format AAAA-MM-JJ. Les listes sont limitées (20 par défaut, 100 au maximum).

Lecture

Écriture (dry-run par défaut)

Règles métier à connaître

• H. prév et Jour prév sont deux champs indépendants dans E-Projet (aucun lien imposé) :

  • duree_heures = H. prév, en heures décimales (0,5 = 30 min, 1,5 = 1 h 30), pas de 0,25, de 0,25 à 300 ;

  • jours_prev = Jour prév, en jours, pas de 0,25, minimum 0,25 (0,5 = demi-journée). Facultatif : par défaut, heures ÷ 8 arrondi au quart de jour supérieur, 0,25 minimum même sous 2 h.

• Statut Terminée ⇔ 100 %. Une tâche à 100 % est terminée ; pour la rouvrir, saisir_timesheet baisse le pourcentage. modifier_tache ne change pas le statut d'une tâche à 100 %.

• Rattrapage : une tâche terminée reste saisissable dans le timesheet pendant quelques jours (catégorie rattrapage).

• Libellés (type, statut, projet) : insensibles à la casse et aux accents ; un fragment unique est accepté. Un libellé inconnu ou ambigu renvoie la liste des valeurs permises.

Limites connues

• lire_timesheet ne voit pas les heures du jour des tâches terminées (rattrapage) : E-Projet ne les affiche pas.

• La suppression passe par un GET, comme le bouton de l'interface ; il n'existe aucun moyen de l'annuler.

• Le HTML d'E-Projet peut changer : les sélecteurs sont isolés (src/utils/parse.ts, activite.ts, timesheet/page.ts) pour qu'un changement ne demande qu'une adaptation locale.

Contribuer

Les contributions sont bienvenues (issue ou pull request).

1. pnpm install, puis un .env seulement si vous voulez tester contre une vraie instance.

2. Travaillez en TDD : un test d'abord, sur des fixtures HTML anonymisées (src/utils/__fixtures__/) et un faux api injecté (les tests ne touchent jamais le réseau).

3. Avant d'ouvrir une PR, tout doit passer :

   pnpm check          # tsc
   pnpm lint           # eslint
   pnpm format:check   # prettier (pnpm format pour corriger)
   pnpm test

4. Règles de code (CLAUDE.md) :

   • aucun fichier ne dépasse 200 lignes, sauf cas justifié : découpez par responsabilité ;

   • SOLID : un module = une responsabilité (client HTTP, session, parsing, service métier, outil MCP) ; ajouter un outil = ajouter des fichiers, sans modifier le code existant ; les outils reçoivent leurs dépendances (api, log) par injection ;

   • pas d'abstraction spéculative.

5. Sécurité :

   • stdout est réservé au protocole MCP : logs sur stderr uniquement ;

   • ne jamais committer de mot de passe, cookie, URL interne ni donnée réelle (noms, identifiants, projets) ; anonymisez les fixtures et les tests ;

   • toute nouvelle écriture doit être en dry_run par défaut, journalisée et relue après envoi.

6. Commits atomiques, un sujet par commit (feat(taches): …, fix(…), docs: …).

Ajouter un outil : un service dans src/services/<domaine>/ (logique + schéma zod), un handler dans src/tools/, l'enregistrement dans src/index.ts, une ligne dans docs/ARCHITECTURE.md et le tableau ci-dessus.

Structure

src/
  index.ts          démarre le serveur et enregistre les outils
  config.ts         variables d'environnement (zod)
  client/           session.ts (login, cookie, mutex) · http.ts (api(): relogin + 1 retry)
  services/         logique métier par domaine : taches/, timesheet/
  tools/            outils MCP : nom, description, validation, gestion d'erreur
  utils/            parse (HTML), dates, durées, lots, journal, logger
docs/               ARCHITECTURE.md et documents de conception

Architecture détaillée et décisions : docs/ARCHITECTURE.md.

Licence

MIT