ThaïS Server

Serveur MCP (Model Context Protocol) pour l'intégration de l'API Thaïs avec Claude Desktop. Ce projet permet à Claude d'interagir directement avec le système de réservation de l'hôtel Thaïs.

Description du projet

Ce serveur expose plusieurs outils (tools) MCP permettant de :

• Vérifier les disponibilités des chambres
• Lister les types de chambres disponibles
• Consulter les tarifs
• Créer des réservations avec confirmation par email

Le projet est structuré de manière modulaire pour faciliter la maintenance et l'évolution.

Architecture

thais-mcp-server/
├── src/
│   ├── config/
│   │   └── thais.config.js       # Configuration centralisée
│   ├── services/
│   │   ├── thais.service.js      # Communication avec l'API Thaïs
│   │   └── email.service.js      # Envoi d'emails de confirmation
│   ├── tools/
│   │   ├── availability.tool.js  # Tool de vérification des disponibilités
│   │   ├── room-types.tool.js    # Tool de liste des types de chambres
│   │   ├── prices.tool.js        # Tool de récupération des tarifs
│   │   └── reservation.tool.js   # Tool de création de réservation
│   ├── mcp-server.js             # Serveur MCP principal
│   └── index.js                  # Serveur Express (API REST)
├── .env                          # Variables d'environnement
├── .gitignore                    #
├── package.json                  # 
└── README.md                     # 

Description des fichiers

Configuration

src/config/thais.config.js

Fichier de configuration centralisé contenant :

• Les URLs et identifiants de l'API Thaïs
• Les paramètres de configuration email (SMTP)
• Le port du serveur Express

Les valeurs sont chargées depuis les variables d'environnement (process.env).

Services

src/services/thais.service.js

Service gérant toute la communication avec l'API Thaïs. Responsabilités :

• Authentification JWT avec cache de token (30 minutes)
• Récupération des disponibilités par période
• Récupération des types de chambres
• Récupération des tarifs par période et type de chambre
• Création de réservations (e-bookings)

Toutes les méthodes utilisent le token JWT pour l'authentification.

src/services/email.service.js

Service d'envoi d'emails utilisant Nodemailer. Fonctionnalités :

• Configuration du transporteur SMTP
• Envoi d'emails de confirmation de réservation au format HTML
• Gestion des erreurs d'envoi

Tools MCP

src/tools/availability.tool.js

Tool MCP pour vérifier les disponibilités. Paramètres :

• checkIn : Date d'arrivée (YYYY-MM-DD)
• checkOut : Date de départ (YYYY-MM-DD)
• adults : Nombre d'adultes

Le tool filtre automatiquement les chambres selon la capacité (nb_persons_min/max) et ne retourne que les chambres disponibles (availability > 0).

src/tools/room-types.tool.js

Tool MCP pour lister tous les types de chambres de l'hôtel. Ne prend aucun paramètre.

Retourne pour chaque type :

• ID et label
• Capacité minimum et maximum
• Description
• Statut public/privé

src/tools/prices.tool.js

Tool MCP pour récupérer les tarifs. Paramètres :

• checkIn : Date d'arrivée
• checkOut : Date de départ
• roomTypeIds : Liste optionnelle d'IDs de chambres

Le tool groupe les tarifs par type de chambre et calcule :

• Prix total du séjour
• Prix moyen par nuit
• Détail des prix par date

src/tools/reservation.tool.js

Tool MCP pour créer une réservation. Paramètres requis :

• Dates (checkIn, checkOut)
• Informations client (nom, prénom, email, téléphone, adresse, code postal, ville)
• Type de chambre (roomTypeId)
• Nombre de personnes (adults, children optionnel)
• Prix total

Le tool :

1. Crée la réservation via l'API Thaïs
2. Envoie un email de confirmation au client
3. Retourne les détails de la réservation

Serveurs

src/mcp-server.js

Serveur MCP principal utilisant le protocole stdio. Responsabilités :

• Enregistrement des tools MCP disponibles
• Routing des appels vers les handlers appropriés
• Communication avec Claude Desktop via stdio

Ce serveur est lancé automatiquement par Claude Desktop.

src/index.js

Serveur Express exposant une API REST pour tests. Endpoints :

• GET /health : Vérification de l'état du serveur
• GET /test-thais : Test de connexion à l'API Thaïs
• GET /availability : Vérification des disponibilités (query params: checkIn, checkOut, adults)

Ce serveur sert principalement pour les tests en développement.

Installation

Prérequis

• Node.js 18 ou supérieur
• Compte Gmail avec mot de passe d'application (pour l'envoi d'emails)
• Claude Desktop

Étapes d'installation

1. Cloner le projet :

git clone <url-du-repo>
cd thais-mcp-server

2. Installer les dépendances :

npm install

3. Créer le fichier .env à la racine :

THAIS_BASE_URL=https://demo.thais-hotel.com/hub/api/partner
THAIS_USERNAME=API_name
THAIS_PASSWORD=API_password
PORT=3000

EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_SECURE=false
[email protected]
EMAIL_PASS=votre-mot-de-passe-app
EMAIL_FROM=Hotel Thaïs <[email protected]>

4. Configurer Claude Desktop :

Créer/modifier le fichier de configuration Claude Desktop :

• Windows : %APPDATA%\Claude\claude_desktop_config.json

Contenu :

{
  "mcpServers": {
    "thais-hotel": {
      "command": "node",
      "args": [
        "CHEMIN_ABSOLU\\thais-mcp-server\\src\\mcp-server.js"
      ],
      "env": {
        "THAIS_BASE_URL": "https://demo.thais-hotel.com/hub/api/partner",
        "THAIS_USERNAME": "API_name",
        "THAIS_PASSWORD": "API_password",
        "EMAIL_HOST": "smtp.gmail.com",
        "EMAIL_PORT": "587",
        "EMAIL_SECURE": "false",
        "EMAIL_USER": "[email protected]",
        "EMAIL_PASS": "votre-mot-de-passe-app",
        "EMAIL_FROM": "Hotel Thaïs <[email protected]>"
      }
    }
  }
}

Remplacez CHEMIN_ABSOLU par le chemin complet vers votre projet.

Configuration de l'email Gmail

Pour envoyer des emails via Gmail :

1. Accéder à https://myaccount.google.com/apppasswords
2. Se connecter avec votre compte Gmail
3. Créer un mot de passe d'application :
   • Nom : "Thaïs MCP Server"
   • Copier le mot de passe généré (16 caractères)
4. Utiliser ce mot de passe dans EMAIL_PASS

Utilisation

Démarrage du serveur Express (développement)

npm start

Le serveur démarre sur http://localhost:3000

Utilisation avec Claude Desktop

1. Fermer complètement Claude Desktop
2. Relancer Claude Desktop
3. Le serveur MCP démarre automatiquement
4. Vérifier la présence du serveur "thais-hotel" dans l'interface

Exemples de requêtes :

• "Y a-t-il des chambres disponibles pour 2 personnes du 15 au 22 février ?"
• "Quels types de chambres proposez-vous ?"
• "Quels sont les tarifs du 15 au 22 février ?"
• "Je voudrais réserver une chambre double pour 2 adultes du 15 au 22 février. Nom: Dupont, Prénom: Marie, Email: [email protected], Téléphone: 0612345678, Adresse: 10 rue de Paris, Code postal: 75001, Ville: Paris"

API Thaïs

Le projet utilise l'API de démonstration Thaïs disponible sur : https://demo.thais-hotel.com/hub/doc/index.html

Endpoints utilisés

• POST /api/partner/login : Authentification JWT
• GET /api/partner/hotel/room-types : Liste des types de chambres
• GET /api/partner/hotel/apr/availabilities/currents : Disponibilités
• GET /api/partner/hotel/apr/prices/currents : Tarifs
• POST /api/partner/hotel/ebookings : Création de réservations

Authentification

L'API utilise JWT (JSON Web Token). Le service thais.service.js :

• Obtient un token via /api/partner/login
• Cache le token pendant 30 minutes
• Réutilise le token pour toutes les requêtes
• Régénère automatiquement un nouveau token après expiration

Dépendances principales

• express : Framework web pour l'API REST
• axios : Client HTTP pour les appels API
• nodemailer : Envoi d'emails
• @modelcontextprotocol/sdk : SDK pour le protocole MCP
• dotenv : Gestion des variables d'environnement

Scripts disponibles

npm start        # Démarre le serveur Express
npm run mcp      # Démarre le serveur MCP manuellement (non recommandé)

Note : Le serveur MCP est automatiquement démarré par Claude Desktop. Il ne faut PAS lancer npm run mcp manuellement en utilisation normale.

Sécurité

Variables sensibles

Les credentials et configurations sensibles sont gérés via :

• Fichier .env pour le développement (non commité)
• Variables d'environnement dans claude_desktop_config.json pour MCP

Le fichier .gitignore exclut :

• .env
• node_modules/
• Fichiers de log

Cache de token

Le token JWT est caché en mémoire pendant 30 minutes pour éviter les appels inutiles au endpoint de login.

Limitations connues

• Le serveur MCP ne peut pas être testé directement avec npm run mcp car il utilise stdio
• Les tokens JWT expirent après un certain temps (géré automatiquement par le cache)
• L'envoi d'emails nécessite un compte Gmail avec mot de passe d'application

Structure des données

Réservation

{
  checkin: "2026-02-15",
  checkout: "2026-02-22",
  customer_firstname: "Marie",
  customer_lastname: "Dupont",
  customer_email: "[email protected]",
  customer_phone: "0612345678",
  customer_address: "10 rue de Paris",
  customer_zipcode: "75001",
  customer_city: "Paris",
  customer_country: "FR",
  booking_rooms: [{
    room_type_id: 1,
    rate_id: 1,
    price: 434,
    nb_persons: {
      adults: 2,
      children: 0
    }
  }]
}

Disponibilité

{
  id: 84645,
  date: "2026-02-06",
  room_type_id: 1,
  availability: 12,  // Nombre de chambres disponibles
  source: "Thais"
}

Type de chambre

{
  id: 1,
  label: "Chambre double",
  nb_persons_min: 1,
  nb_persons_max: 5,
  public: true,
  description: "<p>Description HTML</p>"
}

Développement

Ajout d'un nouveau tool

1. Créer un fichier dans src/tools/
2. Définir le tool avec name, description, inputSchema et handler
3. Importer le tool dans src/mcp-server.js
4. Ajouter le tool au tableau tools

Exemple de structure :

export const monTool = {
  name: 'mon_tool',
  description: 'Description du tool',
  inputSchema: {
    type: 'object',
    properties: {
      param1: { type: 'string', description: 'Description' }
    },
    required: ['param1']
  },
  handler: async (params) => {
    // Logique du tool
    return {
      content: [{ type: 'text', text: 'Résultat' }]
    };
  }
};

Tests

Pour tester le serveur Express :

npm start
# Tester avec Postman ou curl
curl http://localhost:3000/health

Pour tester le serveur MCP :

• Utiliser Claude Desktop
• Vérifier les logs dans Developer Tools (Ctrl+Shift+I)

Auteur

Yousfi Abderrahmane.

Projet réalisé dans le cadre d'un test technique pour une alternance.

Licence

Ce projet est à usage éducatif et de démonstration.