Aller au contenu principal

WebSearch

Le WebSearch permet à vos modèles et agents Clovis d'accéder au Web en temps réel pour enrichir leurs réponses avec des informations à jour.

Concrètement, votre modèle peut :​

  • lancer des recherches web,
  • extraire le contenu de pages précises,
  • cartographier et explorer des sites entiers,
  • analyser et synthétiser des contenus récents,
  • fournir des réponses fiables et contextualisées.

Le WebSearch est exposé sous forme de serveur MCP que votre application, votre agent ou votre orchestrateur peut appeler directement.

Pré-requis​

Une clé API Clovis valide (Bearer token)

La clé API doit avoir accès au WebSearch

Accès réseau à la gateway Clovis : https://llm-gateway.clovis-ai.fr

Endpoint MCP​

Le serveur MCP WebSearch est accessible à l'URL suivante :

URL du serveur MCP
https://llm-gateway.clovis-ai.fr/tools/websearch/mcp

Toutes les requêtes doivent inclure :

  • un header Authorization: Bearer <CLOVIS_API_KEY>
  • un header Content-Type: application/json
  • un header Accept: application/json, text/event-stream

Le serveur utilise le protocole MCP (JSON-RPC 2.0 sur HTTP avec Server-Sent Events).

Outils disponibles​

Le serveur MCP expose 5 outils couvrant l'ensemble de la chaîne d'exploitation du web : découvrir, lire, cartographier, explorer et surveiller.

Effectue une recherche web sécurisée via l'API Tavily, avec un pipeline de sanitisation utilisant ClovisLLM pour détecter les informations sensibles.

ParamètreTypeObligatoireDéfautDescription
querystring✔️—Requête de recherche
search_depthstring"basic"Profondeur : "basic", "advanced", "fast" ou "ultra-fast"
max_resultsinteger10Nombre maximum de résultats (1-20)
include_domainsarray<string>nullDomaines à inclure uniquement
exclude_domainsarray<string>nullDomaines à exclure
topicstring"general"Catégorie : "general" ou "news"
time_rangestringnullFiltre temporel : "day", "week", "month" ou "year"
start_datestringnullDate de début (YYYY-MM-DD). Remplace time_range
end_datestringnullDate de fin (YYYY-MM-DD). Remplace time_range
include_imagesbooleanfalseInclure des images dans les résultats
include_image_descriptionsbooleanfalseInclure des descriptions d'images (include_images requis)
include_raw_contentbooleanfalseInclure le contenu brut des pages
countrystringnullNom de pays pour orienter les résultats (ex : "france", "united states")
include_faviconbooleanfalseInclure les favicons
exact_matchbooleanfalseRetourner uniquement les résultats correspondant exactement

websearch-extract​

Extrait le contenu d'une ou plusieurs URL. Retourne le contenu au format markdown ou text. Le mode advanced permet de gérer les pages protégées ou complexes (LinkedIn, tableaux, contenu embarqué).

ParamètreTypeObligatoireDéfautDescription
urlsarray<string>✔️—Liste des URL à extraire
extract_depthstring"basic""basic" ou "advanced" pour les pages protégées/complexes
include_imagesbooleanfalseInclure les images des pages
formatstring"markdown"Format de sortie : "markdown" ou "text"
include_faviconbooleanfalseInclure les favicons
querystringnullRequête optionnelle pour reranker les chunks par pertinence

websearch-crawl​

Explore un site à partir d'une URL racine et suit les liens internes jusqu'à une profondeur et un nombre de pages définis.

ParamètreTypeObligatoireDéfautDescription
urlstring✔️—URL racine de l'exploration
max_depthinteger1Profondeur maximale depuis l'URL de base
max_breadthinteger20Nombre maximum de liens à suivre par page
limitinteger50Nombre total de pages à traiter
instructionsstringnullInstructions en langage naturel pour filtrer les pages
select_pathsarray<string>nullPatterns regex pour filtrer les chemins (ex : "/docs/.*")
select_domainsarray<string>nullPatterns regex pour restreindre à certains domaines
allow_externalbooleantrueSuivre les liens externes
extract_depthstring"basic""basic" ou "advanced" pour tableaux/contenu embarqué
formatstring"markdown"Format de sortie : "markdown" ou "text"
include_faviconbooleanfalseInclure les favicons

websearch-map​

Cartographie la structure d'un site. Retourne une liste d'URL découvertes sans extraire le contenu textuel.

ParamètreTypeObligatoireDéfautDescription
urlstring✔️—URL racine de la cartographie
max_depthinteger1Profondeur maximale d'exploration
max_breadthinteger20Nombre maximum de liens par page
limitinteger50Nombre total de pages à traiter
instructionsstringnullInstructions en langage naturel pour filtrer les pages
select_pathsarray<string>nullPatterns regex pour filtrer les chemins
select_domainsarray<string>nullPatterns regex pour le filtrage par domaine
allow_externalbooleantrueInclure les liens externes

websearch-search_status​

Vérifie le statut du serveur et des services dépendants (santé de Tavily, état des guardrails et de la sanitisation).

Exemples de code​

Initialiser la connexion MCP​

Initialize — curl
curl -X POST https://llm-gateway.clovis-ai.fr/tools/websearch/mcp \
-H "Authorization: Bearer $CLOVIS_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": { "name": "my-app", "version": "1.0.0" }
  }
}'

Lister les outils​

tools/list — curl
curl -X POST https://llm-gateway.clovis-ai.fr/tools/websearch/mcp \
-H "Authorization: Bearer $CLOVIS_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}'

Effectuer une recherche web​

websearch-search — curl
curl -X POST https://llm-gateway.clovis-ai.fr/tools/websearch/mcp \
-H "Authorization: Bearer $CLOVIS_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "websearch-search",
    "arguments": {
      "query": "Quelles sont les dernières actualités sur l'IA en France ?",
      "max_results": 5,
      "search_depth": "advanced",
      "topic": "news",
      "country": "france"
    }
  }
}'

Extraire le contenu d'une URL​

websearch-extract — curl
curl -X POST https://llm-gateway.clovis-ai.fr/tools/websearch/mcp \
-H "Authorization: Bearer $CLOVIS_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "websearch-extract",
    "arguments": {
      "urls": ["https://www.clovis-ai.fr"],
      "format": "markdown",
      "extract_depth": "basic"
    }
  }
}'
Réponse exemple
Réponse
{
"jsonrpc": "2.0",
"id": 4,
"result": {
  "content": [
    {
      "type": "text",
      "text": "{\"success\":true,\"data\":{\"results\":[{\"url\":\"https://www.clovis-ai.fr\",\"title\":\"Clovis - IA de confiance\",\"raw_content\":\"# Clovis, l'IA de confiance.\n\nVotre plateforme d'intelligence artificielle 100% française...\"
      }]}}"
    }
  ],
  "isError": false
}
}

Cartographier un site​

websearch-map — curl
curl -X POST https://llm-gateway.clovis-ai.fr/tools/websearch/mcp \
-H "Authorization: Bearer $CLOVIS_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "websearch-map",
    "arguments": {
      "url": "https://www.clovis-ai.fr",
      "max_depth": 1,
      "limit": 10
    }
  }
}'

Explorer un site (crawl)​

websearch-crawl — curl
curl -X POST https://llm-gateway.clovis-ai.fr/tools/websearch/mcp \
-H "Authorization: Bearer $CLOVIS_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "websearch-crawl",
    "arguments": {
      "url": "https://www.clovis-ai.fr",
      "max_depth": 1,
      "limit": 10,
      "format": "markdown"
    }
  }
}'

Vérifier le statut du service​

websearch-search_status — curl
curl -X POST https://llm-gateway.clovis-ai.fr/tools/websearch/mcp \
-H "Authorization: Bearer $CLOVIS_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "websearch-search_status",
    "arguments": {}
  }
}'
Réponse exemple
Réponse
{
"jsonrpc": "2.0",
"id": 7,
"result": {
  "content": [
    {
      "type": "text",
      "text": "{\"success\":true,\"data\":{\"server_version\":\"0.2.0\",\"tavily\":{\"healthy\":true,\"error\":null},\"guardrail\":{\"enabled\":true,\"status\":\"healthy\",\"endpoint\":\"https://llm-gateway.clovis-ai.fr/\",\"model\":\"ClovisLLM/gpt-oss-120b\"},\"sanitization\":{\"requests\":true,\"responses\":true}}}"
    }
  ],
  "isError": false
}
}