GlossaryAI — Serveur MCP

Serveur MCP (Model Context Protocol) pour GlossaryAI, un assistant IA spécialisé en vocabulaires, glossaires et textes juridiques/réglementaires. Il expose des outils de recherche vectorielle, de planification, de résolution de liens juridiques et de comparaison de concepts, alimentés par une base Qdrant et un LLM OpenAI-compatible.

---

Overview

Le serveur est construit avec FastMCP et exécuté via Uvicorn. Il est appelé par le client Streamlit AI4Semantics-MCP-client-fr pour :

1. Planifier la réponse à une question utilisateur (plan_workflow_with_tools).
2. Rechercher dans les documents indexés (retrieve_documents).
3. Lister les sources disponibles (get_available_tags).
4. Résoudre les liens juridiques et RDF mentionnés dans les chunks (resolve_links).
5. Comparer/converger plusieurs termes (compare_concepts).

---

Requirements

• Python 3.10 ou supérieur
• Docker (pour Qdrant via docker-compose.yml)
• Un GPU est recommandé pour le reranker local ; sinon le serveur bascule automatiquement sur ONNX CPU.
• Une clé API pour le LLM (LLM_API_KEY / URL_LLM_API) et éventuellement pour Albert (ALBERT_API_KEY) si le reranker API est activé.

---

Setup

1. Cloner le dépôt

git clone https://github.com/pwc-be-adv-tc-cd/AI4semantics
cd AI4semantics/AI4Semantics-MCP-server-fr

2. Créer et activer un environnement virtuel

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

3. Installer les dépendances

pip install -r requirements.txt

4. Configurer les variables d'environnement

Copier .env.sample vers .env et renseigner les valeurs :

cp .env.sample .env

Variable	Description
SERVER_HOST	Hôte Qdrant (qdrant en Docker, localhost en local)
SERVER_PORT	Port Qdrant (6333)
QDRANT_API_KEY	Clé API Qdrant (laisser vide si aucune)
URL_LLM_API	Endpoint OpenAI-compatible du LLM
LLM_API_KEY	Clé API du LLM
LLM_MODEL	Nom du modèle LLM
ALBERT_API_KEY	Clé pour le reranker Albert (si reranker_api.enabled: true)

5. Démarrer Qdrant

docker-compose up -d

Qdrant est alors accessible sur localhost:6333 avec un volume persistant dans ./data/qdrant.

6. Indexer les documents

Placer les documents dans tools/index_search/load_documents/documents/ puis lancer :

python tools/index_search/load_documents/load.py

Le script supporte de nombreux formats : PDF, HTML, TXT, CSV, JSON, XML/RDF/SKOS, Excel, Markdown, RTF, etc. Les fichiers HTML Eur-Lex (par exemple Data-Act.html) sont automatiquement découpés par articles/chapitres.

Pour tester la recherche :

python tools/index_search/load_documents/retrieve.py

7. Démarrer le serveur MCP

python -m server

Le serveur écoute par défaut sur 0.0.0.0:8001.

---

Tools

Tool	Fichier	Description
plan_workflow_with_tools	tools/planning_orchestrator/plan_workflow_with_tools.py	Planifie l'enchaînement des outils pour répondre à la question utilisateur.
retrieve_documents	tools/index_search/retrieve_documents.py	Recherche hybride dense/sparse dans Qdrant, reranking, retour de chunks et de fenêtres de documents.
get_available_tags	tools/index_search/get_available_tags.py	Liste les tags de sources présents dans la collection Qdrant.
resolve_links	tools/legal_link_resolver/resolve_links.py	Détecte les références à articles juridiques et les liens RDF/SKOS, puis remonte les chunks liés.
compare_concepts	tools/concept_comparator/compare_concepts.py	Compare plusieurs termes via recherche vectorielle et propose une définition convergente via LLM.

---

File Structure

.
├── server.py                       # Point d'entrée FastMCP + Uvicorn
├── config.py                       # Chargement centralisé de la configuration
├── config.yaml                     # Paramètres de chunking, recherche, reranker, comparateur
├── docker-compose.yml              # Service Qdrant
├── .env.sample                     # Variables d'environnement requises
├── requirements.txt                # Dépendances Python
│
└── tools/
    ├── __init__.py                 # Export des outils enregistrés dans le serveur
    │
    ├── concept_comparator/
    │   └── compare_concepts.py     # Comparaison/convergence de termes
    │
    ├── index_search/
    │   ├── retrieve_documents.py           # Wrapper de recherche pour le serveur
    │   ├── retrieve_search_documents.py    # Logique de recherche hybride et aggregation
    │   ├── get_available_tags.py           # Liste des tags indexés
    │   ├── init_qdrant_no_vocs.py          # (legacy) initialisation sans vocabulaires
    │   ├── init_qdrant_vocs.py             # (legacy) initialisation avec vocabulaires
    │   ├── old_init.py                     # (legacy)
    │   └── load_documents/
    │       ├── load.py             # Indexation complète (parse, chunk, embed, upsert)
    │       ├── retrieve.py         # Script de test de recherche
    │       ├── config.py           # Client Qdrant, modèle d'embedding, rerankers
    │       ├── config.yaml         # Configuration de Qdrant, chunking, reranker
    │       └── documents/          # Dossier contenant les documents à indexer
    │           ├── AGIT/
    │           ├── EU/
    │           ├── FranceTerme/
    │           ├── Legifrance/
    │           ├── OFB/
    │           └── OiEau/
    │
    ├── legal_link_resolver/
    │   └── resolve_links.py        # Résolution de liens juridiques et RDF
    │
    └── planning_orchestrator/
        ├── plan_workflow_with_tools.py  # Planner agent
        └── prompts.py                   # Prompt système du planner

---

Architecture de recherche

1. Parsing : load.py extrait le texte de nombreux formats.
2. Chunking : découpage par taille avec chevauchement. Les HTML Eur-Lex sont chunkés par articles/chapitres.
3. Embeddings : modèle BAAI/bge-m3 (dense + sparse via la même API de modèle).
4. Indexation : upsert dans Qdrant avec métadonnées (tag, filename, chunk_index, article, concept_uri, etc.).
5. Recherche : recherche hybride dense/sparse, reranking local (bge-reranker-v2-m3) ou via API Albert, agrégation par document, retour des meilleurs chunks avec possibilité de fenêtre.

Les paramètres de recherche sont centralisés dans tools/index_search/load_documents/config.yaml :

Paramètre	Description
search.limit	Nombre de résultats finaux retournés
search.min_candidates	Taille du pool initial de candidats
search.rerank_pool_size	Nombre de candidats rerankés
search.hybrid_dense_weight	Poids de la recherche dense vs sparse
search.max_chunks_per_document	Nombre de chunks maximum par document dans les résultats
chunking.chunk_size	Taille d'un chunk
chunking.chunk_overlap	Chevauchement entre chunks

---

Configuration

• config.yaml (racine) : paramètres pour le résolveur de liens (link_resolver) et le comparateur de concepts (concept_comparator).
• tools/index_search/load_documents/config.yaml : configuration Qdrant, modèles, chunking, reranker, recherche.
• .env : secrets et endpoints.

---

Démarrage rapide

# 1. Démarrer Qdrant
docker-compose up -d

# 2. Indexer les documents
python tools/index_search/load_documents/load.py

# 3. Lancer le serveur MCP
python -m server

Puis lancer le client Streamlit AI4Semantics-MCP-client-fr.

---

Notes importantes

• Le serveur utilise un ThreadPoolExecutor(max_workers=2) pour exécuter les recherches lourdes sans bloquer la boucle asyncio.
• TOKENIZERS_PARALLELISM est désactivé pour éviter les deadlocks du tokenizer HuggingFace.
• Le reranker local peut être remplacé par l'API Albert si reranker_api.enabled est à true dans config.yaml.

Pour plus de détails, consulter les commentaires dans chaque module.