# Thaïs MCP 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 :
```bash
git clone <url-du-repo>
cd thais-mcp-server
```

2. Installer les dépendances :
```bash
npm install
```

3. Créer le fichier .env à la racine :
```env
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_USER=votre-email@gmail.com
EMAIL_PASS=votre-mot-de-passe-app
EMAIL_FROM=Hotel Thaïs <votre-email@gmail.com>
```

4. Configurer Claude Desktop :

Créer/modifier le fichier de configuration Claude Desktop :
- Windows : `%APPDATA%\Claude\claude_desktop_config.json`

Contenu :
```json
{
  "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": "votre-email@gmail.com",
        "EMAIL_PASS": "votre-mot-de-passe-app",
        "EMAIL_FROM": "Hotel Thaïs <votre-email@gmail.com>"
      }
    }
  }
}
```

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)

```bash
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: marie@test.com, 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

```bash
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

```javascript
{
  checkin: "2026-02-15",
  checkout: "2026-02-22",
  customer_firstname: "Marie",
  customer_lastname: "Dupont",
  customer_email: "marie@test.com",
  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é

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

### Type de chambre

```javascript
{
  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 :
```javascript
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 :
```bash
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.