Aller au contenu principal

API Publique MCP de CWCloud

Ce document décrit l'API publique fournie par le paquet pkg/mcp, qui permet à d'autres projets Go de s'intégrer avec les services d'IA de CWCloud et de créer leurs propres serveurs MCP.

Installation​

go get github.com/cwloudtech/cwcloud-mcp/pkg/mcp

Démarrage Rapide​

package main

import (
    "log"
    "cwcloud-mcp/pkg/mcp"
)

func main() {
    // Créer un client CWCloud
    client := mcp.NewClient(
        mcp.DefaultAPIURL,
        "votre-cle-d-acces",
        "votre-cle-secrete", 
        mcp.LogLevelInfo,
    )
    
    // Générer du contenu IA
    response, err := client.GeneratePrompt(&mcp.PromptRequest{
        Adapter: mcp.AdapterGPT4o,
        Message: "Bonjour, le monde !",
        EnableHistory: true,
    })
    if err != nil {
        log.Fatal(err)
    }
    
    log.Printf("Réponse IA : %s", response.Response)
}

Composants Principaux​

Interface Client​

L'interface Client fournit un accès à tous les services d'IA et de gestion d'environnements de CWCloud :

type Client interface {
    // Services IA
    GeneratePrompt(req *PromptRequest) (*PromptResponse, error)
    ListConversations() (*ConversationList, error)
    GetConversation(id string) (*ConversationDetail, error)
    DeleteConversation(id string) error
    ListAdapters() (*AdapterList, error)
    GetUsageStats(params map[string]string) (*UsageStats, error)
    
    // Authentification
    ValidateAuth() error
    
    // Gestion des Environnements
    ListEnvironments() (*EnvironmentList, error)
    GetEnvironment(id string) (*EnvironmentDetail, error)
    ListAdminEnvironments() (*EnvironmentList, error)
    GetAdminEnvironment(id string) (*EnvironmentDetail, error)
    CreateEnvironment(req *EnvironmentRequest) (*EnvironmentDetail, error)
    UpdateEnvironment(id string, req *EnvironmentRequest) (*EnvironmentDetail, error)
    DeleteEnvironment(id string) error
    
    // Gestion des Projets
    ListProjects() ([]Project, error)
    GetProject(id string) (*Project, error)
    ListAdminProjects() ([]Project, error)
    GetAdminProject(id string) (*Project, error)
    
    // Gestion des Instances
    ListInstances() ([]Instance, error)
    GetInstance(provider, region, id string) (*Instance, error)
    
    // Gestion du Stockage
    ListBuckets() ([]Bucket, error)
    GetBucket(id string) (*Bucket, error)
    
    // Gestion des Registres
    ListRegistries() ([]Registry, error)
    GetRegistry(id string) (*Registry, error)
    
    // Gestion des Fonctions
    ListFunctions() ([]Function, error)
    GetFunction(id string) (*Function, error)
    
    // Gestion de la Surveillance
    ListMonitors() ([]Monitor, error)
    GetMonitor(id string) (*Monitor, error)
    
    // Gestion des Utilisateurs (NOUVEAU!)
    ListUsers() ([]User, error)
    GetUser(userID string) (*User, error)
    CreateUser(req *CreateUserRequest) (*User, error)
    
    // Gestion DNS (NOUVEAU!)
    ListDNSRecords() ([]DNSRecord, error)
    GetDNSRecord(recordID string) (*DNSRecord, error)
    CreateDNSRecord(req *CreateDNSRecordRequest) (*DNSRecord, error)
}

Fonction de Fabrique​

func NewClient(baseURL, accessKey, secretKey, logLevel string) Client

Crée un nouveau client API CWCloud. Utilisez mcp.DefaultAPIURL pour la production.

Adaptateurs IA Disponibles​

Utilisez ces constantes pour spécifier quel modèle d'IA utiliser :

const (
    AdapterGPT4o         = "gpt4o"
    AdapterGPT4oMini     = "gpt4o-mini"
    AdapterClaude3Sonnet = "claude3sonnet"
    AdapterClaude3Haiku  = "claude3haiku"
    AdapterGemini        = "gemini"
    AdapterGeminiPro     = "gemini-pro"
)

Création d'Outils MCP​

La bibliothèque fournit des aides pour créer des outils MCP :

Outil IA Simple​

tool := mcp.NewSimpleAITool(
    "resumer",
    "Résumer un texte en utilisant l'IA",
    client,
    mcp.AdapterGPT4o,
)

Outil de Gestion de Conversation​

tool := mcp.NewConversationTool(
    "lister_conversations",
    "Lister toutes les conversations IA",
    client,
)

Outils de Gestion d'Environnements​

// Outil de listage d'environnements
listTool := mcp.NewEnvironmentListTool(
    "lister_environnements",
    "Lister tous les environnements cloud",
    client,
)

// Outil de création d'environnements
createTool := mcp.NewEnvironmentCreateTool(
    "creer_environnement", 
    "Créer un nouvel environnement cloud",
    client,
)

// Outil de gestion d'environnements
manageTool := mcp.NewEnvironmentManageTool(
    "gerer_environnement",
    "Obtenir, mettre à jour ou supprimer un environnement",
    client,
)

Outils Personnalisés​

Implémentez l'interface MCPTool :

type MCPTool interface {
    GetName() string
    GetDescription() string
    GetInputSchema() map[string]interface{}
    Execute(ctx context.Context, params map[string]interface{}) (*MCPToolResult, error)
}

Types de Données​

PromptRequest​

type PromptRequest struct {
    Adapter       string            // Modèle d'IA à utiliser
    Message       string            // Texte de l'invite
    Settings      *PromptSettings   // Paramètres optionnels
    ListID        string            // ID de conversation (optionnel)
    EnableHistory bool              // Sauvegarder dans l'historique des conversations
}

PromptSettings​

type PromptSettings struct {
    MaxTokens   *int     // Nombre maximum de jetons à générer
    Temperature *float64 // Créativité (0.0 à 1.0)
    TopP        *int     // Échantillonnage Nucleus
    Model       *string  // Variante de modèle spécifique
}

PromptResponse​

type PromptResponse struct {
    Status   string     // Statut de la réponse
    Response string     // Texte généré par l'IA
    ListID   string     // ID de la conversation
    Usage    TokenUsage // Statistiques d'utilisation des jetons
}

Gestion des Environnements​

CreateEnvironmentRequest​

type CreateEnvironmentRequest struct {
    Name         string            // Nom de l'environnement
    Type         string            // Type d'environnement (vm, k8s, function, etc.)
    InstanceSize string            // Taille de l'instance (optionnel)
    Region       string            // Région cloud (optionnel)
    Environment  string            // Environnement (optionnel)
    Path         string            // Chemin du projet (optionnel)
}

UpdateEnvironmentRequest​

type UpdateEnvironmentRequest struct {
    Name         *string           // Nouveau nom (optionnel)
    InstanceSize *string           // Nouvelle taille d'instance (optionnel)
}

Environment​

type Environment struct {
    ID           string            // ID unique de l'environnement
    Name         string            // Nom de l'environnement
    Type         string            // Type d'environnement
    Status       string            // Statut actuel
    IP           string            // Adresse IP (si disponible)
    Credentials  *Credentials      // Informations d'accès
    CreatedAt    time.Time         // Date de création
    UpdatedAt    time.Time         // Date de dernière modification
}

Authentification​

Avant de faire des appels API, validez vos informations d'identification :

if err := client.ValidateAuth(); err != nil {
    log.Fatal("L'authentification a échoué :", err)
}

Gestion des Erreurs​

Toutes les méthodes retournent des erreurs Go standard. Vérifiez les échecs d'authentification, les problèmes de réseau et les erreurs API :

response, err := client.GeneratePrompt(req)
if err != nil {
    // Gérer l'erreur de manière appropriée
    log.Printf("L'appel API a échoué : %v", err)
    return
}

Gestion des Environnements​

Lister les Environnements​

// Lister tous les environnements
environments, err := client.ListEnvironments(nil)
if err != nil {
    return err
}

for _, env := range environments.Environments {
    fmt.Printf("ID: %s, Nom: %s, Type: %s, Statut: %s\n", 
        env.ID, env.Name, env.Type, env.Status)
}

// Avec filtrage
params := map[string]string{
    "name_filter": "production",
    "type_filter": "vm",
}
environments, err := client.ListEnvironments(params)

Créer un Environnement​

req := &mcp.CreateEnvironmentRequest{
    Name:         "mon-serveur-web",
    Type:         "vm",
    InstanceSize: "medium",
    Region:       "eu-west-1",
}

env, err := client.CreateEnvironment(req)
if err != nil {
    return err
}

fmt.Printf("Environnement créé: %s (ID: %s)\n", env.Name, env.ID)

Obtenir des Détails d'Environnement​

env, err := client.GetEnvironment("environment-id-123")
if err != nil {
    return err
}

fmt.Printf("Nom: %s\n", env.Name)
fmt.Printf("Type: %s\n", env.Type)
fmt.Printf("Statut: %s\n", env.Status)
if env.IP != "" {
    fmt.Printf("IP: %s\n", env.IP)
}

Mettre à Jour un Environnement​

newName := "nouveau-nom-serveur"
req := &mcp.UpdateEnvironmentRequest{
    Name: &newName,
}

env, err := client.UpdateEnvironment("environment-id-123", req)
if err != nil {
    return err
}

fmt.Printf("Environnement mis à jour: %s\n", env.Name)

Supprimer un Environnement​

err := client.DeleteEnvironment("environment-id-123")
if err != nil {
    return err
}

## Gestion des Conversations

Démarrer une Conversation​

response, err := client.GeneratePrompt(&mcp.PromptRequest{
    Adapter:       mcp.AdapterGPT4o,
    Message:       "Bonjour, discutons !",
    EnableHistory: true, // Ceci crée une conversation
})
conversationID := response.ListID

Continuer une Conversation​

response, err := client.GeneratePrompt(&mcp.PromptRequest{
    Adapter: mcp.AdapterGPT4o,
    Message: "Dites-m'en plus à ce sujet.",
    ListID:  conversationID, // Continuer la conversation existante
})

Lister Toutes les Conversations​

conversations, err := client.ListConversations()
if err != nil {
    return err
}

for _, conv := range conversations.Conversations {
    fmt.Printf("ID : %s, Titre : %s\n", conv.ID, conv.Title)
}

Nouveaux Types (Gestion Utilisateurs & DNS)​

Gestion des Utilisateurs​

type User struct {
    ID        int     `json:"id"`
    Username  string  `json:"username"`
    Email     string  `json:"email"`
    FirstName string  `json:"first_name"`
    LastName  string  `json:"last_name"`
    IsActive  bool    `json:"is_active"`
    IsAdmin   bool    `json:"is_admin"`
    CreatedAt APITime `json:"created_at"`
    UpdatedAt APITime `json:"updated_at"`
}

type CreateUserRequest struct {
    Username  string `json:"username"`
    Email     string `json:"email"`
    Password  string `json:"password"`
    FirstName string `json:"first_name"`
    LastName  string `json:"last_name"`
    IsActive  bool   `json:"is_active"`
    IsAdmin   bool   `json:"is_admin"`
}

// Exemple d'utilisation
users, err := client.ListUsers()
if err != nil {
    return err
}

newUser, err := client.CreateUser(&mcp.CreateUserRequest{
    Username: "john.doe",
    Email:    "john@example.com",
    Password: "mot-de-passe-securise",
    IsActive: true,
})

Gestion DNS​

type DNSRecord struct {
    ID       int     `json:"id"`
    Name     string  `json:"name"`
    Type     string  `json:"type"`
    Content  string  `json:"content"`
    TTL      int     `json:"ttl"`
    Priority int     `json:"priority"`
    Zone     string  `json:"zone"`
    Status   string  `json:"status"`
    CreatedAt APITime `json:"created_at"`
    UpdatedAt APITime `json:"updated_at"`
}

type CreateDNSRecordRequest struct {
    Name     string `json:"name"`
    Type     string `json:"type"`
    Content  string `json:"content"`
    TTL      int    `json:"ttl"`
    Priority int    `json:"priority"`
    Zone     string `json:"zone"`
}

// Exemple d'utilisation
records, err := client.ListDNSRecords()
if err != nil {
    return err
}

newRecord, err := client.CreateDNSRecord(&mcp.CreateDNSRecordRequest{
    Name:    "api.example.com",
    Type:    "A",
    Content: "192.168.1.100",
    Zone:    "example.com",
    TTL:     300,
})

Fonctions de Fabrique d'Outils MCP​

La bibliothèque fournit des fonctions de fabrique pour créer des outils compatibles MCP :

// Outils de gestion des utilisateurs
userTool := mcp.NewListUsersTool(
    "list_users",
    "Lister les Utilisateurs", 
    "Lister tous les utilisateurs système",
    client,
)

createUserTool := mcp.NewCreateUserTool(
    "create_user",
    "Créer un Utilisateur",
    "Créer un nouvel utilisateur système",
    client,
)

// Outils de gestion DNS
dnsTool := mcp.NewListDNSRecordsTool(
    "list_dns_records",
    "Lister les Enregistrements DNS",
    "Lister tous les enregistrements DNS",
    client,
)

createDNSTool := mcp.NewCreateDNSRecordTool(
    "create_dns_record",
    "Créer un Enregistrement DNS",
    "Créer un nouvel enregistrement DNS",
    client,
)

Statistiques d'Utilisation​

Suivez votre utilisation de l'IA et vos coûts :

stats, err := client.GetUsageStats(nil)
if err != nil {
    return err
}

fmt.Printf("Total des jetons : %d\n", stats.Usage.TotalTokens)
fmt.Printf("Coût total : $%.4f\n", stats.Usage.TotalCost)

// Utilisation par adaptateur
for adapter, usage := range stats.Usage.ByAdapter {
    fmt.Printf("%s : %d jetons, $%.4f\n", 
        adapter, usage.Tokens, usage.Cost)
}

Exemples​

Consultez le répertoire examples/ pour des exemples fonctionnels complets :

  • examples/usage.go - Exemples d'utilisation complets
  • Opérations de base du client
  • Création d'outils MCP personnalisés
  • Gestion des conversations
  • Statistiques d'utilisation
  • Gestion des utilisateurs et DNS

Sécurité des Threads​

Le client est sûr pour une utilisation concurrente à travers plusieurs goroutines.

Meilleures Pratiques​

  1. Réutiliser les Clients : Créez une seule instance de client et réutilisez-la dans votre application
  2. Gérer les Erreurs : Vérifiez toujours les erreurs, en particulier les échecs d'authentification
  3. Définir des Limites : Utilisez MaxTokens pour contrôler les coûts et la longueur des réponses
  4. Sauvegarder les Conversations : Utilisez EnableHistory: true pour les conversations à plusieurs tours
  5. Surveiller l'Utilisation : Vérifiez régulièrement les statistiques d'utilisation pour suivre les coûts
  6. Sécuriser les Identifiants : Stockez les clés API de manière sécurisée et ne les commitez jamais dans le contrôle de version
  7. Utiliser les Outils Admin avec Précaution : Les outils admin ont des privilèges élevés - utilisez avec prudence

Ensemble de Fonctionnalités Complet (119 Outils)​

La bibliothèque MCP CWCloud fournit maintenant 119 outils complets répartis en 10 catégories :

  • Services IA (3 outils) : Génération IA, conversations, adaptateurs
  • Gestion des Environnements (11 outils) : CRUD complet + opérations admin
  • Gestion des Projets (7 outils) : Cycle de vie complet des projets
  • Gestion des Instances (10 outils) : Opérations VM avec contrôles admin
  • Gestion du Stockage (10 outils) : Opérations de buckets avec contrôles admin
  • Gestion des Registres (10 outils) : Opérations de registres de conteneurs
  • Gestion des Fonctions (12 outils) : Serverless avec invocation
  • Gestion de la Surveillance (10 outils) : Surveillance d'endpoints
  • Gestion des Utilisateurs (10 outils) : Cycle de vie complet des utilisateurs
  • Gestion DNS (10 outils) : Gestion d'enregistrements DNS

Intégration avec les Serveurs MCP​

Cette bibliothèque est conçue pour être utilisée au sein des serveurs MCP. Les outils créés avec cette bibliothèque peuvent être facilement intégrés dans les implémentations du protocole MCP.

Pour un exemple complet d'un serveur MCP utilisant cette bibliothèque, consultez l'implémentation principale du serveur cwcloud-mcp à la racine du projet.