Skip to content

🧠 Guide d'utilisation de l'API Cerveau Store

📋 Vue d'ensemble

Le Cerveau Store est votre catalogue universel d'outils MCP avec indexation intelligente et recherche sémantique. Il permet de :

  • 📚 Indexer tous vos outils MCP de manière centralisée
  • 🔍 Rechercher intelligemment avec scoring de pertinence
  • 📊 Analyser les performances et l'utilisation des outils
  • 🎯 Découvrir automatiquement les outils pertinents pour chaque tâche

🚀 Démarrage rapide

1. Vérifier que l'API fonctionne

curl -X GET http://localhost:8002/health

2. Explorer les outils existants

# Liste des outils
curl -X GET http://localhost:8002/tools?per_page=10

# Catégories disponibles
curl -X GET http://localhost:8002/tools/categories

3. Recherche intelligente

# Recherche sémantique
curl -X POST http://localhost:8002/search \
  -H "Content-Type: application/json" \
  -d '{"query":"connexion serveur distant","semantic":true,"limit":5}'

📝 Enregistrement d'outils MCP

Structure d'un outil MCP

{
  "name": "nom_de_votre_outil",
  "category": "automation",
  "description": "Description détaillée de l'outil",
  "parameters": {
    "param1": {
      "type": "string",
      "description": "Description du paramètre",
      "required": true
    },
    "param2": {
      "type": "integer",
      "description": "Paramètre optionnel",
      "default": 100,
      "required": false
    }
  },
  "llm_usage": "Instructions pour l'IA : quand et comment utiliser cet outil",
  "server_id": "votre_serveur_mcp",
  "metadata": {
    "version": "1.0.0",
    "author": "VotreNom",
    "tags": ["tag1", "tag2", "tag3"],
    "documentation": "https://docs.exemple.com"
  }
}

Catégories disponibles

  • network : Outils réseau (SSH, scan de ports, etc.)
  • database : Base de données (PostgreSQL, MongoDB, etc.)
  • file_management : Gestion de fichiers
  • web : Web scraping, APIs REST
  • development : Outils de développement (Docker, qualité code)
  • communication : Notifications (Slack, email)
  • security : Sécurité (mots de passe, cryptographie)
  • automation : Automatisation générale

Enregistrement via API

curl -X POST http://localhost:8002/tools/register \
  -H "Content-Type: application/json" \
  -d @votre_outil.json

Enregistrement via Python

import requests

def register_tool():
    tool_data = {
        "name": "mon_outil_mcp",
        "category": "automation",
        "description": "Mon outil personnalisé",
        "parameters": {
            "input": {"type": "string", "description": "Données d'entrée"}
        },
        "llm_usage": "Utilisez pour automatiser des tâches spécifiques",
        "server_id": "mon_serveur",
        "metadata": {
            "version": "1.0.0",
            "author": "Mon équipe"
        }
    }

    response = requests.post(
        "http://localhost:8002/tools/register",
        json=tool_data
    )

    return response.json()

🔍 Recherche intelligente

Types de recherche

1. Recherche textuelle simple

curl -X POST http://localhost:8002/search \
  -H "Content-Type: application/json" \
  -d '{"query":"ssh","limit":5}'

2. Recherche sémantique (recommandée)

curl -X POST http://localhost:8002/search \
  -H "Content-Type: application/json" \
  -d '{"query":"connexion serveur distant","semantic":true,"limit":5}'

3. Recherche par catégorie

curl -X GET "http://localhost:8002/tools?category=network&per_page=10"

4. Recherche avec filtres

curl -X POST http://localhost:8002/search \
  -H "Content-Type: application/json" \
  -d '{
    "query":"base de données",
    "semantic":true,
    "category":"database",
    "limit":10,
    "min_score":0.5
  }'

Interprétation des scores

  • 0.8 - 1.0 : Très pertinent, recommandé
  • 0.6 - 0.8 : Pertinent, bon candidat
  • 0.4 - 0.6 : Moyennement pertinent, à considérer
  • 0.0 - 0.4 : Peu pertinent, éviter

📊 Monitoring et métriques

Health check complet

curl -X GET http://localhost:8002/health

Statistiques du registry

curl -X GET http://localhost:8002/registry/stats

Métriques d'un outil spécifique

# Enregistrer une utilisation
curl -X POST "http://localhost:8002/tools/{tool_id}/metrics?success=true&latency=1000"

# Consulter les statistiques
curl -X GET "http://localhost:8002/tools/{tool_id}/stats"

🎯 Cas d'usage avancés

1. Découverte automatique d'outils

def find_best_tool_for_task(task_description):
    """Trouve le meilleur outil pour une tâche donnée"""

    search_result = requests.post(
        "http://localhost:8002/search",
        json={
            "query": task_description,
            "semantic": True,
            "limit": 3
        }
    ).json()

    if search_result["results"]:
        best_tool = search_result["results"][0]
        if best_tool["relevance_score"] > 0.7:
            return best_tool

    return None

# Exemple d'utilisation
task = "Je veux me connecter à un serveur distant de manière sécurisée"
best_tool = find_best_tool_for_task(task)
print(f"Outil recommandé: {best_tool['name']}")

2. Système de recommandation

def get_similar_tools(tool_id):
    """Trouve des outils similaires"""

    # Récupérer les détails de l'outil
    tool = requests.get(f"http://localhost:8002/tools/{tool_id}").json()

    # Rechercher des outils similaires
    similar = requests.post(
        "http://localhost:8002/search",
        json={
            "query": tool["description"],
            "semantic": True,
            "category": tool["category"],
            "limit": 5
        }
    ).json()

    # Exclure l'outil original
    return [t for t in similar["results"] if t["id"] != tool_id]

3. Validation et scoring personnalisé

def validate_tool_for_context(tool_id, context):
    """Valide qu'un outil convient pour un contexte donné"""

    tool = requests.get(f"http://localhost:8002/tools/{tool_id}").json()

    # Vérifier les prérequis
    required_params = [
        p for p, info in tool["parameters"].items() 
        if info.get("required", False)
    ]

    # Vérifier la disponibilité
    if not tool.get("available_on"):
        return False, "Outil non disponible"

    # Score personnalisé basé sur le contexte
    score = calculate_context_score(tool, context)

    return score > 0.6, f"Score: {score}"

🔧 Configuration avancée

Variables d'environnement importantes

# Port de l'API
CERVEAU_STORE_PORT=8002

# Base de données
CERVEAU_STORE_DB_URL=sqlite:///./cerveau_store.db

# Recherche sémantique
SENTENCE_TRANSFORMER_MODEL=all-MiniLM-L6-v2
SEARCH_CACHE_TTL_MINUTES=15

# Performance
MAX_SEARCH_RESULTS=100
BATCH_SIZE=50

Optimisation des performances

  1. Cache de recherche : Activé par défaut (15 min TTL)
  2. Indexation en lot : Utilisez /tools/register/batch pour plusieurs outils
  3. Pagination : Utilisez page et per_page pour les grandes listes
  4. Filtres : Combinez catégories et scores pour affiner les résultats

🧪 Scripts utiles

Script de sauvegarde

def backup_tools():
    """Sauvegarde tous les outils"""
    tools = requests.get("http://localhost:8002/tools?per_page=1000").json()

    with open("backup_tools.json", "w") as f:
        json.dump(tools, f, indent=2)

    print(f"✅ {len(tools['tools'])} outils sauvegardés")

Script de migration

def migrate_tools_from_config(config_file):
    """Migre des outils depuis un fichier de configuration"""

    with open(config_file) as f:
        config = json.load(f)

    for server_name, server_config in config["mcpServers"].items():
        # Convertir la configuration en format Cerveau Store
        tool_data = convert_mcp_config_to_tool(server_name, server_config)

        # Enregistrer l'outil
        response = requests.post(
            "http://localhost:8002/tools/register",
            json=tool_data
        )

        print(f"Migré: {server_name} - {response.status_code}")

📚 Documentation API complète

  • Swagger UI : http://localhost:8002/docs
  • ReDoc : http://localhost:8002/redoc
  • OpenAPI JSON : http://localhost:8002/openapi.json

🎉 Conclusion

Le Cerveau Store transforme votre écosystème MCP en un catalogue intelligent où :

  1. Tous vos outils sont indexés et documentés
  2. La recherche sémantique trouve les outils pertinents automatiquement
  3. Les métriques vous aident à optimiser l'utilisation
  4. L'API REST permet une intégration facile dans vos workflows

Votre système est maintenant prêt à gérer intelligemment tous vos outils MCP ! 🚀

Commentaires