Aller au contenu principal

Creer votre premier connecteur MCP

Ce tutoriel vous guide dans la creation d'un connecteur MCP personnalise pour integrer un service externe a Chatbotaurus.

Prerequis​

  • Chatbotaurus installe et fonctionnel
  • Node.js 20.x et pnpm
  • Connaissance de base de TypeScript

Architecture d'un connecteur​

Un connecteur MCP dans Chatbotaurus est une classe TypeScript qui :

  1. Definit les outils disponibles (tools)
  2. Gere l'authentification vers le service cible
  3. Execute les appels API et retourne les resultats

Les connecteurs se trouvent dans packages/server/src/services/mcp-gateway/connectors/.

Etape 1 : Creer le fichier​

Creez packages/server/src/services/mcp-gateway/connectors/MonServiceConnector.ts :

import { BaseConnector, ConnectorConfig, ToolDefinition, ToolResult } from './BaseConnector'

export class MonServiceConnector extends BaseConnector {
  readonly name = 'mon-service'
  readonly description = 'Connecteur pour Mon Service EU'

  getTools(): ToolDefinition[] {
    return [
      {
        name: 'mon_service_list_items',
        description: 'Liste les elements de Mon Service',
        inputSchema: {
          type: 'object',
          properties: {
            limit: { type: 'number', description: 'Nombre max de resultats', default: 10 },
            offset: { type: 'number', description: 'Offset pour la pagination', default: 0 }
          }
        }
      },
      {
        name: 'mon_service_get_item',
        description: 'Recupere un element par son ID',
        inputSchema: {
          type: 'object',
          properties: {
            id: { type: 'number', description: 'ID de l element' }
          },
          required: ['id']
        }
      }
    ]
  }

  async executeTool(toolName: string, args: Record<string, unknown>): Promise<ToolResult> {
    switch (toolName) {
      case 'mon_service_list_items':
        return this.listItems(args.limit as number, args.offset as number)
      case 'mon_service_get_item':
        return this.getItem(args.id as number)
      default:
        throw new Error(`Outil inconnu: ${toolName}`)
    }
  }

  private async listItems(limit: number = 10, offset: number = 0): Promise<ToolResult> {
    const response = await this.httpClient.get('/api/items', {
      params: { limit, offset }
    })
    return { content: [{ type: 'text', text: JSON.stringify(response.data) }] }
  }

  private async getItem(id: number): Promise<ToolResult> {
    const response = await this.httpClient.get(`/api/items/${id}`)
    return { content: [{ type: 'text', text: JSON.stringify(response.data) }] }
  }
}

Etape 2 : Enregistrer le connecteur​

Ajoutez votre connecteur dans le registre des connecteurs pour qu'il soit disponible via le MCP Gateway.

Etape 3 : Configurer les credentials​

Stockez les credentials dans Vault :

sudo podman exec chatbotaurus-vault vault kv put \
  secret/mcp-servers/mon-service \
  api_url="https://mon-service.eu/api" \
  api_key="votre-cle-api"

Etape 4 : Tester​

# Test via curl
curl -X POST http://localhost:3000/api/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "mon_service_list_items",
      "arguments": { "limit": 5 }
    },
    "id": 1
  }'

Bonnes pratiques​

  • Utilisez HTTP keep-alive pour les connexions persistantes
  • Implementez un cache pour les requetes frequentes (TTL adapte au service)
  • Respectez les timeouts : 10s demo, 15s production, 30s operations lourdes
  • Ajoutez les metriques resolveMs, credentialsMs, executeMs
  • Ecrivez des tests property-based avec fast-check

Voir aussi​