Documentation

• 1: Tutoriels
• 1.1: Démarrage avec gomcptest
• 1.2: Building Your First OpenAI-Compatible Server
• 1.3: Utiliser l'Interface en Ligne de Commande cliGCP
• 2: Guides Pratiques
• 2.1: How to Create a Custom MCP Tool
• 2.2: How to Configure the OpenAI-Compatible Server
• 2.3: Comment Configurer l'Interface en Ligne de Commande cliGCP
• 2.4: Comment Utiliser le Serveur OpenAI avec big-AGI
• 3: Référence
• 3.1: Tools Reference
• 3.2: OpenAI-Compatible Server Reference
• 3.3: cliGCP Reference
• 4: Explication
• 4.1: Architecture de gomcptest
• 4.2: Understanding the Model Context Protocol (MCP)

1 - Tutoriels

Ces tutoriels vous aideront à vous familiariser avec gomcptest et ses composants.

1.1 - Démarrage avec gomcptest

Ce tutoriel vous guidera à travers la configuration du système gomcptest et la mise en place de l’authentification Google Cloud pour le projet.

Prérequis

• Go >= 1.21 installé sur votre système
• Compte Google Cloud avec accès à l’API Vertex AI
• Google Cloud CLI installé
• Familiarité de base avec le terminal/ligne de commande

Configuration de l’Authentification Google Cloud

Avant d’utiliser gomcptest avec les services de Google Cloud Platform comme Vertex AI, vous devez configurer votre authentification.

1. Initialiser le CLI Google Cloud

Si vous n’avez pas encore configuré le CLI Google Cloud, exécutez :

gcloud init

Cette commande interactive vous guidera à travers :

• La connexion à votre compte Google
• La sélection d’un projet Google Cloud
• La définition des configurations par défaut

2. Se connecter à Google Cloud

Authentifiez votre CLI gcloud avec votre compte Google :

gcloud auth login

Cela ouvrira une fenêtre de navigateur où vous pourrez vous connecter à votre compte Google.

3. Configurer les Identifiants par Défaut de l’Application (ADC)

Les Identifiants par Défaut de l’Application sont utilisés par les bibliothèques clientes pour trouver automatiquement les identifiants lors de la connexion aux services Google Cloud :

gcloud auth application-default login

Cette commande va :

1. Ouvrir une fenêtre de navigateur pour l’authentification
2. Stocker vos identifiants localement (généralement dans ~/.config/gcloud/application_default_credentials.json)
3. Configurer votre environnement pour utiliser ces identifiants lors de l’accès aux API Google Cloud

Ces identifiants seront utilisés par gomcptest lors de l’interaction avec les services Google Cloud.

Configuration du Projet

1. Cloner le dépôt :

   git clone https://github.com/owulveryck/gomcptest.git
   cd gomcptest
   

2. Construire les Outils : Compiler tous les outils compatibles MCP

   make tools
   

3. Choisir l’Interface :

   • Exécuter le serveur compatible OpenAI : Voir le Tutoriel du Serveur OpenAI
   • Utiliser le CLI directement : Voir le Tutoriel cliGCP

Prochaines Étapes

Après avoir terminé la configuration de base :

• Explorez les différents outils dans le répertoire tools
• Essayez de créer des tâches d’agent avec gomcptest
• Consultez les guides pratiques pour des cas d’utilisation spécifiques

1.2 - Building Your First OpenAI-Compatible Server

This tutorial will guide you step-by-step through running and configuring the OpenAI-compatible server in gomcptest. By the end, you’ll have a working server that can communicate with LLM models and execute MCP tools.

Prerequisites

• Go >= 1.21 installed
• Access to Google Cloud Platform with Vertex AI API enabled
• GCP authentication set up via gcloud auth login
• Basic familiarity with terminal commands
• The gomcptest repository cloned and tools built (see the Getting Started guide)

Step 1: Set Up Environment Variables

The OpenAI server requires several environment variables. Create a .envrc file in the host/openaiserver directory:

cd host/openaiserver
touch .envrc

Add the following content to the .envrc file, adjusting the values according to your setup:

# Server configuration
PORT=8080
LOG_LEVEL=INFO
IMAGE_DIR=/tmp/images

# GCP configuration
GCP_PROJECT=your-gcp-project-id
GCP_REGION=us-central1
GEMINI_MODELS=gemini-2.0-flash
IMAGEN_MODELS=imagen-3.0-generate-002

Ensure the image directory exists:

mkdir -p /tmp/images

Load the environment variables:

source .envrc

Step 2: Start the OpenAI Server

Now you can start the OpenAI-compatible server:

cd host/openaiserver
go run . -mcpservers "../bin/GlobTool;../bin/GrepTool;../bin/LS;../bin/View;../bin/Bash;../bin/Replace"

You should see output indicating that the server has started and registered the MCP tools.

Step 3: Test the Server with a Simple Request

Open a new terminal window and use curl to test the server:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [
      {
        "role": "user",
        "content": "Hello, what can you do?"
      }
    ]
  }'

You should receive a response from the model explaining its capabilities.

Step 4: Test Function Calling

Now let’s test function calling by asking the model to list files in a directory:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.0-flash",
    "messages": [
      {
        "role": "user",
        "content": "List the files in the current directory"
      }
    ]
  }'

The model should respond by calling the LS tool and returning the results.

What You’ve Learned

In this tutorial, you’ve:

1. Set up the environment for the OpenAI-compatible server
2. Built and registered MCP tools
3. Started the server
4. Tested basic chat completion
5. Demonstrated function calling capabilities

Next Steps

Now that you have a working OpenAI-compatible server, you can:

• Explore the API by sending different types of requests
• Add custom tools to expand the server’s capabilities
• Connect a client like the cliGCP to interact with the server
• Experiment with different Gemini models

Check out the How to Configure the OpenAI Server guide for more advanced configuration options.

1.3 - Utiliser l'Interface en Ligne de Commande cliGCP

Ce tutoriel vous guide à travers la configuration et l’utilisation de l’interface en ligne de commande cliGCP pour interagir avec les LLMs et les outils MCP. À la fin, vous serez capable d’exécuter le CLI et d’effectuer des tâches de base avec celui-ci.

Prérequis

Avant de commencer, assurez-vous que vous avez :

• Go 1.21 ou plus récent installé
• Un compte Google Cloud Platform avec l’API Vertex AI activée
• L’authentification Google Cloud configurée (voir le tutoriel de démarrage)
• Une installation gomcptest fonctionnelle avec les outils construits

Configuration de l’Environnement

1. Définir les variables d’environnement :

   # Votre ID de projet GCP
   export GCP_PROJECT=votre-projet-id
   
   # Région Vertex AI (par défaut: us-central1)
   export GCP_REGION=us-central1
   
   # Modèles Gemini à utiliser 
   export GEMINI_MODELS=gemini-1.5-pro,gemini-2.0-flash
   
   # Répertoire pour stocker les images temporaires
   export IMAGE_DIR=/tmp/images
   

2. Créer le répertoire d’images :

   mkdir -p /tmp/images
   

Compilation et Exécution de cliGCP

1. Compiler cliGCP :

   cd /chemin/vers/gomcptest
   go build -o bin/cliGCP ./host/cliGCP
   

2. Exécuter cliGCP avec les outils de base :

   cd /chemin/vers/gomcptest
   bin/cliGCP -mcpservers "bin/GlobTool;bin/GrepTool;bin/LS;bin/View;bin/Bash"
   

Vous devriez voir une interface de chat interactive s’ouvrir, où vous pouvez interagir avec le modèle LLM.

Utilisation de cliGCP

Commandes de Base

Dans l’interface cliGCP, vous pouvez :

• Écrire des messages textuels pour interagir avec le LLM
• Utiliser /help pour afficher les commandes disponibles
• Utiliser /exit ou Ctrl+C pour quitter la session

Exemples d’Interactions

Essayez ces exemples pour tester les capacités de base du système :

1. Requête simple :

   Peux-tu m'expliquer le Protocole de Contexte de Modèle en termes simples ?
   

2. Utilisation de l’outil Bash :

   Affiche les 5 derniers fichiers modifiés dans le répertoire courant.
   

3. Recherche de fichiers :

   Trouve tous les fichiers Go dans ce projet.
   

4. Lecture et Explication de Code :

   Explique ce que fait le fichier main.go dans le répertoire cliGCP.
   

Utilisation d’Outils Avancés

Dispatch Agent

Pour utiliser l’outil dispatch_agent, qui permet de déléguer des tâches complexes :

bin/cliGCP -mcpservers "bin/GlobTool;bin/GrepTool;bin/LS;bin/View;bin/dispatch_agent -glob-path bin/GlobTool -grep-path bin/GrepTool -ls-path bin/LS -view-path bin/View;bin/Bash"

Maintenant, vous pouvez demander des choses comme :

Trouve tous les fichiers Go qui importent le paquet "context" et résume leur but.

Modification de Fichiers

Pour permettre la modification de fichiers, incluez les outils Edit et Replace :

bin/cliGCP -mcpservers "bin/GlobTool;bin/GrepTool;bin/LS;bin/View;bin/Bash;bin/Edit;bin/Replace"

Vous pouvez maintenant demander :

Crée un nouveau fichier README.md avec une description de base du projet.

Personnalisation de l’Expérience

Pour une expérience plus personnalisée, vous pouvez définir une instruction système spécifique :

export SYSTEM_INSTRUCTION="Tu es un assistant en programmation Go expert qui aide à analyser et améliorer le code."
bin/cliGCP -mcpservers "bin/GlobTool;bin/GrepTool;bin/LS;bin/View;bin/Bash"

Résolution des Problèmes Courants

Erreurs d’Authentification

Si vous rencontrez des erreurs d’authentification :

1. Vérifiez que vous avez exécuté gcloud auth application-default login
2. Assurez-vous que votre compte a accès au projet GCP et à l’API Vertex AI
3. Vérifiez que la variable d’environnement GCP_PROJECT est correctement définie

Erreurs d’Outil

Si les outils ne sont pas trouvés ou ne fonctionnent pas :

1. Vérifiez les chemins des outils dans la commande -mcpservers
2. Assurez-vous que tous les outils ont été compilés avec make tools
3. Vérifiez les permissions d’exécution sur les fichiers d’outils

Prochaines Étapes

Maintenant que vous avez configuré et utilisé l’interface cliGCP, vous pouvez :

• Explorer les différentes configurations avancées de cliGCP
• Créer des outils personnalisés pour étendre les fonctionnalités
• Créer des alias shell ou des scripts pour simplifier l’accès à vos configurations préférées

2 - Guides Pratiques

Ces guides vous aideront à résoudre des tâches spécifiques et à personnaliser gomcptest pour vos besoins.

2.1 - How to Create a Custom MCP Tool

This guide shows you how to create a new custom tool that’s compatible with the Model Context Protocol (MCP) in gomcptest.

Prerequisites

• A working installation of gomcptest
• Go programming knowledge
• Understanding of the MCP protocol basics

Steps to create a custom tool

1. Create the tool directory structure

mkdir -p tools/YourToolName/cmd

2. Create the README.md file

Create a README.md in the tool directory with documentation:

touch tools/YourToolName/README.md

Include the following sections:

• Tool description
• Parameters
• Usage notes
• Example

3. Create the main.go file

Create a main.go file in the cmd directory:

touch tools/YourToolName/cmd/main.go

4. Implement the tool functionality

Here’s a template to start with:

package main

import (
	"encoding/json"
	"fmt"
	"log"
	"os"

	"github.com/mark3labs/mcp-go"
)

// Define your tool's parameters structure
type Params struct {
	// Add your parameters here
	// Example:
	InputParam string `json:"input_param"`
}

func main() {
	server := mcp.NewServer()

	// Register your tool function
	server.RegisterFunction("YourToolName", func(params json.RawMessage) (any, error) {
		var p Params
		if err := json.Unmarshal(params, &p); err != nil {
			return nil, fmt.Errorf("failed to parse parameters: %w", err)
		}

		// Implement your tool's logic here
		result := doSomethingWithParams(p)

		return result, nil
	})

	if err := server.Run(os.Stdin, os.Stdout); err != nil {
		log.Fatalf("Server error: %v", err)
	}
}

func doSomethingWithParams(p Params) interface{} {
	// Your tool's core functionality
	// ...
	
	// Return the result
	return map[string]interface{}{
		"result": "Your processed result",
	}
}

5. Add the tool to the Makefile

Open the Makefile in the root directory and add your tool:

YourToolName:
	go build -o bin/YourToolName tools/YourToolName/cmd/main.go

Also add it to the all target.

6. Build your tool

make YourToolName

7. Test your tool

Test the tool directly:

echo '{"name":"YourToolName","params":{"input_param":"test"}}' | ./bin/YourToolName

8. Use with the CLI

Add your tool to the CLI command:

./bin/cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./YourToolName;./dispatch_agent;./Bash;./Replace"

Tips for effective tool development

• Focus on a single, well-defined purpose
• Provide clear error messages
• Include meaningful response formatting
• Implement proper parameter validation
• Handle edge cases gracefully
• Consider adding unit tests in a _test.go file

2.2 - How to Configure the OpenAI-Compatible Server

This guide shows you how to configure and customize the OpenAI-compatible server in gomcptest for different use cases.

Prerequisites

• A working installation of gomcptest
• Basic familiarity with the OpenAI server from the tutorial
• Understanding of environment variables and configuration

Environment Variables Configuration

Basic Server Configuration

The OpenAI server can be configured using the following environment variables:

# Server port (default: 8080)
export PORT=8080

# Log level: DEBUG, INFO, WARN, ERROR (default: INFO)
export LOG_LEVEL=INFO

# Directory to store images (required)
export IMAGE_DIR=/path/to/image/directory

GCP Configuration

Configure the Google Cloud Platform integration:

# GCP Project ID (required)
export GCP_PROJECT=your-gcp-project-id

# GCP Region (default: us-central1)
export GCP_REGION=us-central1

# Comma-separated list of Gemini models (default: gemini-1.5-pro,gemini-2.0-flash)
export GEMINI_MODELS=gemini-1.5-pro,gemini-2.0-flash

# Comma-separated list of Imagen models (optional)
export IMAGEN_MODELS=imagen-3.0-generate-002

Setting Up a Production Environment

For a production environment, create a proper systemd service file:

sudo nano /etc/systemd/system/gomcptest-openai.service

Add the following content:

[Unit]
Description=gomcptest OpenAI Server
After=network.target

[Service]
User=yourusername
WorkingDirectory=/path/to/gomcptest/host/openaiserver
ExecStart=/path/to/gomcptest/host/openaiserver/openaiserver -mcpservers "/path/to/gomcptest/bin/GlobTool;/path/to/gomcptest/bin/GrepTool;/path/to/gomcptest/bin/LS;/path/to/gomcptest/bin/View;/path/to/gomcptest/bin/Bash;/path/to/gomcptest/bin/Replace"
Environment=PORT=8080
Environment=LOG_LEVEL=INFO
Environment=IMAGE_DIR=/path/to/image/directory
Environment=GCP_PROJECT=your-gcp-project-id
Environment=GCP_REGION=us-central1
Environment=GEMINI_MODELS=gemini-1.5-pro,gemini-2.0-flash
Restart=on-failure

[Install]
WantedBy=multi-user.target

Then enable and start the service:

sudo systemctl enable gomcptest-openai
sudo systemctl start gomcptest-openai

Configuring MCP Tools

Adding Custom Tools

To add custom MCP tools to the server, include them in the -mcpservers parameter when starting the server:

go run . -mcpservers "../bin/GlobTool;../bin/GrepTool;../bin/LS;../bin/View;../bin/YourCustomTool;../bin/Bash;../bin/Replace"

Tool Parameters and Arguments

Some tools require additional parameters. You can specify these after the tool path:

go run . -mcpservers "../bin/GlobTool;../bin/dispatch_agent -glob-path ../bin/GlobTool -grep-path ../bin/GrepTool -ls-path ../bin/LS -view-path ../bin/View"

API Usage Configuration

Enabling CORS

For web applications, you may need to enable CORS. Add a middleware to the main.go file:

package main

import (
    "net/http"
    // other imports
)

// CORS middleware
func corsMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("Access-Control-Allow-Origin", "*")
        w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
        w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
        
        if r.Method == "OPTIONS" {
            w.WriteHeader(http.StatusOK)
            return
        }
        
        next.ServeHTTP(w, r)
    })
}

func main() {
    // existing code...
    
    http.Handle("/", corsMiddleware(openAIHandler))
    
    // existing code...
}

Setting Rate Limits

Add a simple rate limiting middleware:

package main

import (
    "net/http"
    "sync"
    "time"
    // other imports
)

type RateLimiter struct {
    requests     map[string][]time.Time
    maxRequests  int
    timeWindow   time.Duration
    mu           sync.Mutex
}

func NewRateLimiter(maxRequests int, timeWindow time.Duration) *RateLimiter {
    return &RateLimiter{
        requests:    make(map[string][]time.Time),
        maxRequests: maxRequests,
        timeWindow:  timeWindow,
    }
}

func (rl *RateLimiter) Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ip := r.RemoteAddr
        
        rl.mu.Lock()
        
        // Clean up old requests
        now := time.Now()
        if reqs, exists := rl.requests[ip]; exists {
            var validReqs []time.Time
            for _, req := range reqs {
                if now.Sub(req) <= rl.timeWindow {
                    validReqs = append(validReqs, req)
                }
            }
            rl.requests[ip] = validReqs
        }
        
        // Check if rate limit is exceeded
        if len(rl.requests[ip]) >= rl.maxRequests {
            rl.mu.Unlock()
            http.Error(w, "Rate limit exceeded", http.StatusTooManyRequests)
            return
        }
        
        // Add current request
        rl.requests[ip] = append(rl.requests[ip], now)
        rl.mu.Unlock()
        
        next.ServeHTTP(w, r)
    })
}

func main() {
    // existing code...
    
    rateLimiter := NewRateLimiter(10, time.Minute) // 10 requests per minute
    http.Handle("/", rateLimiter.Middleware(corsMiddleware(openAIHandler)))
    
    // existing code...
}

Performance Tuning

Adjusting Memory Usage

For high-load scenarios, adjust Go’s garbage collector:

export GOGC=100  # Default is 100, lower values lead to more frequent GC

Increasing Concurrency

If handling many concurrent requests, adjust the server’s concurrency limits:

package main

import (
    "net/http"
    // other imports
)

func main() {
    // existing code...
    
    server := &http.Server{
        Addr:         ":" + strconv.Itoa(cfg.Port),
        Handler:      openAIHandler,
        ReadTimeout:  30 * time.Second,
        WriteTimeout: 120 * time.Second,
        IdleTimeout:  120 * time.Second,
        MaxHeaderBytes: 1 << 20,
    }
    
    err = server.ListenAndServe()
    
    // existing code...
}

Troubleshooting Common Issues

Debugging Connection Problems

If you’re experiencing connection issues, set the log level to DEBUG:

export LOG_LEVEL=DEBUG

Common Error Messages

• Failed to create MCP client: Ensure the tool path is correct and the tool is executable
• Failed to load GCP config: Check your GCP environment variables
• Error in LLM request: Verify your GCP credentials and project access

Checking Tool Registration

To verify tools are registered correctly, look for log messages like:

INFO server0 Registering command=../bin/GlobTool
INFO server1 Registering command=../bin/GrepTool

2.3 - Comment Configurer l'Interface en Ligne de Commande cliGCP

Ce guide vous montre comment configurer et personnaliser l’interface en ligne de commande cliGCP pour divers cas d’utilisation.

Prérequis

• Une installation fonctionnelle de gomcptest
• Une familiarité de base avec l’outil cliGCP à partir du tutoriel
• Compréhension des variables d’environnement et de la configuration

Arguments de Ligne de Commande

L’outil cliGCP accepte les arguments de ligne de commande suivants :

# Spécifier les serveurs MCP à utiliser (requis)
-mcpservers "outil1;outil2;outil3"

# Exemple avec des arguments d'outil
./cliGCP -mcpservers "./GlobTool;./GrepTool;./dispatch_agent -glob-path ./GlobTool -grep-path ./GrepTool -ls-path ./LS -view-path ./View;./Bash"

Configuration des Variables d’Environnement

Configuration GCP

Configurez l’intégration avec Google Cloud Platform avec ces variables d’environnement :

# ID du projet GCP (requis)
export GCP_PROJECT=votre-id-de-projet-gcp

# Région GCP (par défaut : us-central1)
export GCP_REGION=us-central1

# Liste de modèles Gemini séparés par des virgules (requis)
export GEMINI_MODELS=gemini-1.5-pro,gemini-2.0-flash

# Répertoire pour stocker les images (requis pour la génération d'images)
export IMAGE_DIR=/chemin/vers/repertoire/images

Configuration Avancée

Vous pouvez personnaliser le comportement de l’outil cliGCP avec ces variables d’environnement supplémentaires :

# Définir une instruction système personnalisée pour le modèle
export SYSTEM_INSTRUCTION="Vous êtes un assistant utile spécialisé dans la programmation Go."

# Ajuster la température du modèle (0.0-1.0, la valeur par défaut est 0.2)
# Les valeurs plus basses rendent la sortie plus déterministe, les valeurs plus élevées plus créatives
export MODEL_TEMPERATURE=0.3

# Définir une limite maximale de tokens pour les réponses
export MAX_OUTPUT_TOKENS=2048

Création d’Alias Shell

Pour simplifier l’utilisation, créez des alias shell dans votre .bashrc ou .zshrc :

# Ajouter à ~/.bashrc ou ~/.zshrc
alias gpt='cd /chemin/vers/gomcptest/bin && ./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./Bash;./Replace"'

# Créer des alias spécialisés pour différentes tâches
alias assistant-code='cd /chemin/vers/gomcptest/bin && GCP_PROJECT=votre-projet GEMINI_MODELS=gemini-2.0-flash ./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./Bash;./Replace"'

alias scanner-securite='cd /chemin/vers/gomcptest/bin && SYSTEM_INSTRUCTION="Vous êtes un expert en sécurité concentré sur la recherche de vulnérabilités dans le code" ./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./Bash"'

Personnalisation de l’Instruction Système

Pour modifier l’instruction système par défaut, éditez le fichier agent.go :

// Dans host/cliGCP/cmd/agent.go
genaimodels[model].SystemInstruction = &genai.Content{
    Role: "user",
    Parts: []genai.Part{
        genai.Text("Vous êtes un agent utile avec accès à des outils. " +
            "Votre travail est d'aider l'utilisateur en effectuant des tâches à l'aide de ces outils. " +
            "Vous ne devez pas inventer d'informations. " +
            "Si vous ne savez pas quelque chose, dites-le et expliquez ce que vous auriez besoin de savoir pour aider. " +
            "Si aucune indication, utilisez le répertoire de travail actuel qui est " + cwd),
    },
}

Création de Configurations Spécifiques aux Tâches

Pour différents cas d’utilisation, vous pouvez créer des scripts de configuration spécialisés :

Assistant de Revue de Code

Créez un fichier appelé reviseur-code.sh :

#!/bin/bash

export GCP_PROJECT=votre-id-de-projet-gcp
export GCP_REGION=us-central1
export GEMINI_MODELS=gemini-2.0-flash
export IMAGE_DIR=/tmp/images
export SYSTEM_INSTRUCTION="Vous êtes un expert en revue de code. Analysez le code pour détecter les bugs, les problèmes de sécurité et les domaines à améliorer. Concentrez-vous sur la fourniture de commentaires constructifs et d'explications détaillées."

cd /chemin/vers/gomcptest/bin
./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./Bash"

Rendez-le exécutable :

chmod +x reviseur-code.sh

Générateur de Documentation

Créez un fichier appelé generateur-doc.sh :

#!/bin/bash

export GCP_PROJECT=votre-id-de-projet-gcp
export GCP_REGION=us-central1
export GEMINI_MODELS=gemini-2.0-flash
export IMAGE_DIR=/tmp/images
export SYSTEM_INSTRUCTION="Vous êtes un spécialiste de la documentation. Votre tâche est d'aider à créer une documentation claire et complète pour le code. Analysez la structure du code et créez une documentation appropriée en suivant les meilleures pratiques."

cd /chemin/vers/gomcptest/bin
./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./Bash;./Replace"

Configurations Avancées d’Outils

Configuration de dispatch_agent

Lorsque vous utilisez l’outil dispatch_agent, vous pouvez configurer son comportement avec des arguments supplémentaires :

./cliGCP -mcpservers "./GlobTool;./GrepTool;./LS;./View;./dispatch_agent -glob-path ./GlobTool -grep-path ./GrepTool -ls-path ./LS -view-path ./View -timeout 30s;./Bash;./Replace"

Création de Combinaisons d’Outils

Vous pouvez créer des combinaisons d’outils spécialisées pour différentes tâches :

# Ensemble d'outils pour le développement web
./cliGCP -mcpservers "./GlobTool -include '*.{html,css,js}';./GrepTool;./LS;./View;./Bash;./Replace"

# Ensemble d'outils pour le développement Go
./cliGCP -mcpservers "./GlobTool -include '*.go';./GrepTool;./LS;./View;./Bash;./Replace"

Résolution des Problèmes Courants

Problèmes de Connexion au Modèle

Si vous rencontrez des difficultés pour vous connecter au modèle Gemini :

1. Vérifiez vos identifiants GCP :

gcloud auth application-default print-access-token

2. Vérifiez que l’API Vertex AI est activée :

gcloud services list --enabled | grep aiplatform

3. Vérifiez que votre projet a accès aux modèles que vous demandez

Échecs d’Exécution d’Outils

Si les outils échouent à s’exécuter :

1. Assurez-vous que les chemins des outils sont corrects
2. Vérifiez que les outils sont exécutables
3. Vérifiez les problèmes de permission dans les répertoires auxquels vous accédez

Optimisation des Performances

Pour de meilleures performances :

1. Utilisez des modèles d’outils plus spécifiques pour réduire la portée de la recherche
2. Envisagez de créer des agents spécialisés pour différentes tâches
3. Définissez une température plus basse pour des réponses plus déterministes

2.4 - Comment Utiliser le Serveur OpenAI avec big-AGI

Ce guide vous montre comment configurer le serveur compatible OpenAI de gomcptest pour fonctionner avec big-AGI, un client web open-source populaire pour les assistants IA.

Prérequis

• Une installation fonctionnelle de gomcptest
• Le serveur compatible OpenAI en cours d’exécution (voir le tutoriel du serveur OpenAI)
• Node.js (version 18.17.0 ou plus récente)
• Git

Pourquoi Utiliser big-AGI avec gomcptest ?

big-AGI fournit une interface web soignée et riche en fonctionnalités pour interagir avec des modèles d’IA. En le connectant au serveur compatible OpenAI de gomcptest, vous obtenez :

• Une interface web professionnelle pour vos interactions avec l’IA
• Support pour les outils/appels de fonction
• Gestion de l’historique des conversations
• Gestion des personas
• Capacités de génération d’images
• Support pour plusieurs utilisateurs

Configuration de big-AGI

1. Cloner le dépôt big-AGI :

   git clone https://github.com/enricoros/big-agi.git
   cd big-agi
   

2. Installer les dépendances :

   npm install
   

3. Créer un fichier .env.local pour la configuration :

   cp .env.example .env.local
   

4. Éditer le fichier .env.local pour configurer la connexion à votre serveur gomcptest :

   # Configuration big-AGI
   
   # URL de votre serveur compatible OpenAI gomcptest
   OPENAI_API_HOST=http://localhost:8080
   
   # Il peut s'agir de n'importe quelle chaîne car le serveur gomcptest n'utilise pas de clés API
   OPENAI_API_KEY=gomcptest-local-server
   
   # Définissez cette valeur sur true pour activer le fournisseur personnalisé
   OPENAI_API_ENABLE_CUSTOM_PROVIDER=true
   

5. Démarrer big-AGI :

   npm run dev
   

6. Ouvrez votre navigateur et accédez à http://localhost:3000 pour accéder à l’interface big-AGI.

Configuration de big-AGI pour Utiliser Vos Modèles

Le serveur compatible OpenAI de gomcptest expose les modèles Google Cloud via une API compatible OpenAI. Dans big-AGI, vous devrez configurer les modèles :

1. Ouvrez big-AGI dans votre navigateur
2. Cliquez sur l’icône Paramètres (engrenage) en haut à droite
3. Allez dans l’onglet Modèles
4. Sous “Modèles OpenAI” :
   • Cliquez sur “Ajouter des modèles”
   • Ajoutez vos modèles par ID (par exemple, gemini-1.5-pro, gemini-2.0-flash)
   • Définissez la longueur de contexte de manière appropriée (8K-32K selon le modèle)
   • Définissez la capacité d’appel de fonction sur true pour les modèles qui la prennent en charge

Activation de l’Appel de Fonction avec des Outils

Pour utiliser les outils MCP via l’interface d’appel de fonction de big-AGI :

1. Dans big-AGI, cliquez sur l’icône Paramètres
2. Allez dans l’onglet Avancé
3. Activez “Appel de fonction” dans la section “Fonctionnalités expérimentales”
4. Dans une nouvelle conversation, cliquez sur l’onglet “Fonctions” (icône de plugin) dans l’interface de chat
5. Les outils disponibles de votre serveur gomcptest devraient être listés

Configuration CORS pour big-AGI

Si vous exécutez big-AGI sur un domaine ou un port différent de celui de votre serveur gomcptest, vous devrez activer CORS côté serveur. Modifiez la configuration du serveur OpenAI :

1. Créez ou modifiez un middleware CORS pour le serveur OpenAI :

   // Middleware CORS avec autorisation d'origine spécifique
   func corsMiddleware(next http.Handler) http.Handler {
       return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
           // Autoriser les requêtes provenant de l'origine big-AGI
           w.Header().Set("Access-Control-Allow-Origin", "http://localhost:3000")
           w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
           w.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
   
           if r.Method == "OPTIONS" {
               w.WriteHeader(http.StatusOK)
               return
           }
   
           next.ServeHTTP(w, r)
       })
   }
   

2. Appliquez ce middleware à vos routes de serveur

Résolution des Problèmes Courants

Modèle Non Trouvé

Si big-AGI signale que les modèles ne peuvent pas être trouvés :

1. Vérifiez que votre serveur gomcptest est en cours d’exécution et accessible
2. Vérifiez les journaux du serveur pour vous assurer que les modèles sont correctement enregistrés
3. Assurez-vous que les ID de modèle dans big-AGI correspondent exactement à ceux fournis par votre serveur gomcptest

L’Appel de Fonction Ne Fonctionne Pas

Si les outils ne fonctionnent pas correctement :

1. Assurez-vous que les outils sont correctement enregistrés dans votre serveur gomcptest
2. Vérifiez que l’appel de fonction est activé dans les paramètres de big-AGI
3. Vérifiez que le modèle que vous utilisez prend en charge l’appel de fonction

Problèmes de Connexion

Si big-AGI ne peut pas se connecter à votre serveur :

1. Vérifiez la valeur OPENAI_API_HOST dans votre fichier .env.local
2. Recherchez des problèmes CORS dans la console de développement de votre navigateur
3. Assurez-vous que votre serveur est en cours d’exécution et accessible depuis le navigateur

Déploiement en Production

Pour une utilisation en production, considérez :

1. Sécurisation de votre API :

   • Ajoutez une authentification appropriée à votre serveur OpenAI gomcptest
   • Mettez à jour la OPENAI_API_KEY dans big-AGI en conséquence

2. Déploiement de big-AGI :

   • Suivez le guide de déploiement de big-AGI
   • Configurez les variables d’environnement pour pointer vers votre serveur gomcptest de production

3. Mise en place de HTTPS :

   • Pour la production, big-AGI et votre serveur gomcptest devraient utiliser HTTPS
   • Envisagez d’utiliser un proxy inverse comme Nginx avec des certificats Let’s Encrypt

Exemple : Interface de Chat Basique

Une fois que tout est configuré, vous pouvez utiliser l’interface de big-AGI pour interagir avec vos modèles d’IA :

1. Commencez une nouvelle conversation
2. Sélectionnez votre modèle dans le menu déroulant des modèles (par exemple, gemini-1.5-pro)
3. Activez l’appel de fonction si vous souhaitez utiliser des outils
4. Commencez à discuter avec votre assistant IA, propulsé par gomcptest

L’interface big-AGI offre une expérience beaucoup plus riche qu’une interface en ligne de commande, avec des fonctionnalités comme l’historique des conversations, le rendu markdown, la mise en évidence du code, et plus encore.

3 - Référence

Cette section fournit une documentation technique détaillée sur les composants, les API, les paramètres et les outils de gomcptest.

3.1 - Tools Reference

Bash

Executes bash commands in a persistent shell session.

Parameters

Response

The tool returns the command output as a string.

Banned Commands

For security reasons, the following commands are banned: alias, curl, curlie, wget, axel, aria2c, nc, telnet, lynx, w3m, links, httpie, xh, http-prompt, chrome, firefox, safari

Edit

Modifies file content by replacing specified text.

Parameters

Response

Confirmation message with the updated content.

GlobTool

Finds files matching glob patterns with metadata.

Parameters

Response

A list of matching files with metadata including path, size, modification time, and permissions.

GrepTool

Searches file contents using regular expressions.

Parameters

Response

A list of matches with file paths, line numbers, and matched content.

LS

Lists files and directories in a given path.

Parameters

Response

A list of files and directories with metadata.

Replace

Completely replaces a file’s contents.

Parameters

Response

Confirmation message with the content written.

View

Reads file contents with optional line range.

Parameters

Response

The file content with line numbers in cat -n format.

dispatch_agent

Launches a new agent with access to specific tools.

Parameters

Response

The result of the agent’s task execution.

Tool Response Format

Most tools return JSON responses with the following structure:

{
  "result": "...", // String result or
  "results": [...], // Array of results
  "error": "..." // Error message if applicable
}

Error Handling

All tools follow a consistent error reporting format:

{
  "error": "Error message",
  "code": "ERROR_CODE"
}

Common error codes include:

• INVALID_PARAMS: Parameters are missing or invalid
• EXECUTION_ERROR: Error executing the requested operation
• PERMISSION_DENIED: Permission issues
• TIMEOUT: Operation timed out

3.2 - OpenAI-Compatible Server Reference

Overview

The OpenAI-compatible server is a core component of the gomcptest system. It implements an API surface compatible with the OpenAI Chat Completions API while connecting to Google’s Vertex AI for model inference. The server acts as a bridge between clients (like the cliGCP tool) and the underlying LLM models, handling session management, function calling, and tool execution.

API Endpoints

POST /v1/chat/completions

The primary endpoint that mimics the OpenAI Chat Completions API.

Request

{
  "model": "gemini-pro",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello, world!"}
  ],
  "stream": true,
  "max_tokens": 1024,
  "temperature": 0.7,
  "functions": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          }
        },
        "required": ["location"]
      }
    }
  ]
}

Response (non-streamed)

{
  "id": "chatcmpl-123456789",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "gemini-pro",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop",
      "index": 0
    }
  ],
  "usage": {
    "prompt_tokens": 13,
    "completion_tokens": 7,
    "total_tokens": 20
  }
}

Response (streamed)

When stream is set to true, the server returns a stream of SSE (Server-Sent Events) with partial responses:

data: {"id":"chatcmpl-123456789","object":"chat.completion.chunk","created":1677858242,"model":"gemini-pro","choices":[{"delta":{"role":"assistant"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123456789","object":"chat.completion.chunk","created":1677858242,"model":"gemini-pro","choices":[{"delta":{"content":"Hello"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123456789","object":"chat.completion.chunk","created":1677858242,"model":"gemini-pro","choices":[{"delta":{"content":"!"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123456789","object":"chat.completion.chunk","created":1677858242,"model":"gemini-pro","choices":[{"delta":{"content":" How"},"index":0,"finish_reason":null}]}

data: {"id":"chatcmpl-123456789","object":"chat.completion.chunk","created":1677858242,"model":"gemini-pro","choices":[{"delta":{},"index":0,"finish_reason":"stop"}]}

data: [DONE]

Supported Features

Models

The server supports the following Vertex AI models:

• gemini-pro
• gemini-pro-vision

Parameters

Function Calling

The server supports function calling similar to the OpenAI API. When the model identifies that a function should be called, the server:

1. Parses the function call parameters
2. Locates the appropriate MCP tool
3. Executes the tool with the provided parameters
4. Returns the result to the model for further processing

Architecture

The server consists of these key components:

HTTP Server

A standard Go HTTP server that handles incoming requests and routes them to the appropriate handlers.

Session Manager

Maintains chat history and context for ongoing conversations. Ensures that the model has necessary context when generating responses.

Vertex AI Client

Communicates with Google’s Vertex AI API to:

• Send prompt templates to the model
• Receive completions from the model
• Stream partial responses back to the client

MCP Tool Manager

Manages the available MCP tools and handles:

• Tool registration and discovery
• Parameter validation
• Tool execution
• Response processing

Response Streamer

Handles streaming responses to clients in SSE format, ensuring low latency and progressive rendering.

Configuration

The server can be configured using environment variables:

Error Handling

The server implements consistent error handling with HTTP status codes:

Error responses follow this format:

{
  "error": {
    "message": "Detailed error message",
    "type": "error_type",
    "param": "parameter_name",
    "code": "error_code"
  }
}

Security Considerations

The server does not implement authentication or authorization by default. In production deployments, consider:

• Running behind a reverse proxy with authentication
• Using API keys or OAuth2
• Implementing rate limiting
• Setting up proper firewall rules

Examples

Basic Usage

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/credentials.json"
export GOOGLE_CLOUD_PROJECT="your-project-id"
./bin/openaiserver

With Custom Tools

export MCP_TOOLS_PATH="/path/to/tools"
./bin/openaiserver

Client Connection

curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-pro",
    "messages": [{"role": "user", "content": "Hello, world!"}]
  }'

Limitations

• Single chat session support only
• No persistent storage of conversations
• Limited authentication options
• Basic rate limiting
• Limited model parameter controls

Advanced Usage

Tool Registration

Tools are automatically registered when the server starts. To register custom tools:

1. Place executable files in the MCP_TOOLS_PATH directory
2. Ensure they follow the MCP protocol
3. Restart the server

Streaming with Function Calls

When using function calling with streaming, the stream will pause during tool execution and resume with the tool results included in the context.

3.3 - cliGCP Reference

Overview

The cliGCP (Command Line Interface for Google Cloud Platform) is a command-line tool that provides a chat interface similar to tools like “Claude Code” or “ChatGPT”. It connects to an OpenAI-compatible server and allows users to interact with LLMs and MCP tools through a conversational interface.

Command Structure

Basic Usage

./bin/cliGCP [flags]

Flags

Example

./bin/cliGCP -mcpservers "./bin/Bash;./bin/View;./bin/GlobTool;./bin/GrepTool;./bin/LS;./bin/Edit;./bin/Replace;./bin/dispatch_agent" -server "http://localhost:8080" -model "gemini-pro" -prompt "You are a helpful command-line assistant."

Components

Chat Interface

The chat interface provides:

• Text-based input for user messages
• Markdown rendering of AI responses
• Real-time streaming of responses
• Input history and navigation
• Multi-line input support

MCP Tool Manager

The tool manager:

• Loads and initializes MCP tools
• Registers tools with the OpenAI-compatible server
• Routes function calls to appropriate tools
• Processes tool results

Session Manager

The session manager:

• Maintains chat history within the session
• Handles context windowing for long conversations
• Optionally persists conversations to disk
• Provides conversation resume functionality

Interaction Patterns

Basic Chat

The most common interaction pattern is a simple turn-based chat:

1. User enters a message
2. Model generates and streams a response
3. Chat history is updated
4. User enters the next message

Function Calling

When the model determines a function should be called:

1. User enters a message requesting an action (e.g., “List files in /tmp”)
2. Model analyzes the request and generates a function call
3. cliGCP intercepts the function call and routes it to the appropriate tool
4. Tool executes and returns results
5. Results are injected back into the model’s context
6. Model continues generating a response that incorporates the tool results
7. The complete response is shown to the user

Multi-turn Function Calling

For complex tasks, the model may make multiple function calls:

1. User requests a complex task (e.g., “Find all Python files containing ’error’”)
2. Model makes a function call to list directories
3. Tool returns directory listing
4. Model makes additional function calls to search file contents
5. Each tool result is returned to the model
6. Model synthesizes the information and responds to the user

Technical Details

Message Format

Messages between cliGCP and the server follow the OpenAI Chat API format:

{
  "role": "user"|"assistant"|"system",
  "content": "Message text"
}

Function calls use this format:

{
  "role": "assistant",
  "content": null,
  "function_call": {
    "name": "function_name",
    "arguments": "{\"arg1\":\"value1\",\"arg2\":\"value2\"}"
  }
}

Tool Registration

Tools are registered with the server using JSONSchema:

{
  "name": "tool_name",
  "description": "Tool description",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "Parameter description"
      }
    },
    "required": ["param1"]
  }
}

Error Handling

The CLI implements robust error handling for:

• Connection issues with the server
• Tool execution failures
• Model errors
• Input validation

Error messages are displayed to the user with context and possible solutions.

Configuration

Environment Variables

Configuration File

You can create a ~/.cligcp.json configuration file with these settings:

{
  "server": "http://localhost:8080",
  "model": "gemini-pro",
  "prompt": "You are a helpful assistant.",
  "temperature": 0.7,
  "max_tokens": 1024,
  "tools": [
    "./bin/Bash",
    "./bin/View",
    "./bin/GlobTool"
  ]
}

Advanced Usage

Persistent History

To save and load chat history:

./bin/cliGCP -history ./chat_history.json

Custom System Prompt

To set a specific system prompt:

./bin/cliGCP -prompt "You are a Linux command-line expert that helps users with shell commands and filesystem operations."

Combining with Shell Scripts

You can use cliGCP in shell scripts by piping input and capturing output:

echo "Explain how to find large files in Linux" | ./bin/cliGCP -noninteractive

Limitations

• Single conversation per instance
• Limited rendering capabilities for complex markdown
• No built-in authentication management
• Limited offline functionality
• No multi-modal input support (e.g., images)

Troubleshooting

Common Issues

Diagnostic Mode

Run with the -verbose flag to enable detailed logging:

./bin/cliGCP -verbose

This will show all API requests, responses, and tool interactions, which can be helpful for debugging.

4 - Explication

Cette section fournit un contexte plus approfondi sur le fonctionnement de gomcptest, son architecture et les concepts qui le sous-tendent.

4.1 - Architecture de gomcptest

Vue d’Ensemble

Le projet gomcptest implémente un hôte personnalisé qui fournit une implémentation du Protocole de Contexte de Modèle (MCP). Il est conçu pour permettre les tests et l’expérimentation avec des systèmes d’agents sans nécessiter d’intégration directe avec des plateformes LLM commerciales.

Le système est construit avec ces principes clés à l’esprit :

• Modularité : Les composants sont conçus pour être interchangeables
• Compatibilité : L’API imite l’API OpenAI pour une intégration facile
• Extensibilité : De nouveaux outils peuvent être facilement ajoutés au système
• Test : L’architecture facilite le test d’applications basées sur des agents

Composants Principaux

Hôte (Serveur OpenAI)

L’hôte est le composant central, situé dans /host/openaiserver. Il présente une interface API compatible OpenAI et se connecte à Vertex AI de Google pour l’inférence de modèle. Cette couche de compatibilité facilite l’intégration avec des outils et bibliothèques existants conçus pour OpenAI.

L’hôte a plusieurs responsabilités clés :

1. Compatibilité API : Implémentation de l’API de complétion de chat OpenAI
2. Gestion des Sessions : Maintien de l’historique et du contexte des conversations
3. Intégration des Modèles : Connexion aux modèles Gemini de Vertex AI
4. Appel de Fonctions : Orchestration des appels de fonctions/outils basés sur les sorties du modèle
5. Streaming de Réponses : Support des réponses en streaming vers le client

Contrairement aux implémentations commerciales, cet hôte est conçu pour le développement et les tests locaux, privilégiant la flexibilité et l’observabilité aux fonctionnalités prêtes pour la production comme l’authentification ou la limitation de débit.

Outils MCP

Les outils sont des exécutables autonomes qui implémentent le Protocole de Contexte de Modèle. Chaque outil est conçu pour exécuter une fonction spécifique, comme l’exécution de commandes shell ou la manipulation de fichiers.

Les outils suivent un modèle cohérent :

• Ils communiquent via l’entrée/sortie standard en utilisant le protocole JSON-RPC MCP
• Ils exposent un ensemble spécifique de paramètres
• Ils gèrent leurs propres conditions d’erreur
• Ils renvoient les résultats dans un format standardisé

Cette approche permet aux outils d’être :

• Développés indépendamment
• Testés de manière isolée
• Utilisés dans différents environnements hôtes
• Chaînés ensemble dans des flux de travail complexes

CLI

L’interface en ligne de commande fournit une interface utilisateur similaire à des outils comme “Claude Code” ou “OpenAI ChatGPT”. Elle se connecte au serveur compatible OpenAI et offre un moyen d’interagir avec le LLM et les outils via une interface conversationnelle.

Flux de Données

1. L’utilisateur envoie une requête à l’interface CLI
2. Le CLI transmet cette requête au serveur compatible OpenAI
3. Le serveur envoie la requête au modèle Gemini de Vertex AI
4. Le modèle peut identifier des appels de fonction dans sa réponse
5. Le serveur exécute ces appels de fonction en invoquant les outils MCP appropriés
6. Les résultats sont fournis au modèle pour poursuivre sa réponse
7. La réponse finale est diffusée en streaming vers le CLI et présentée à l’utilisateur

Explications des Décisions de Conception

Pourquoi la Compatibilité avec l’API OpenAI ?

L’API OpenAI est devenue un standard de facto dans l’espace des LLM. En implémentant cette interface, gomcptest peut fonctionner avec une grande variété d’outils, de bibliothèques et d’interfaces existants avec une adaptation minimale.

Pourquoi Google Vertex AI ?

Vertex AI donne accès aux modèles Gemini de Google, qui possèdent de solides capacités d’appel de fonctions. L’implémentation pourrait être étendue pour prendre en charge d’autres fournisseurs de modèles si nécessaire.

Pourquoi des Outils Autonomes ?

En implémentant les outils comme des exécutables autonomes plutôt que des fonctions de bibliothèque, nous obtenons plusieurs avantages :

• Sécurité par isolation
• Agnosticisme linguistique (les outils peuvent être écrits dans n’importe quel langage)
• Capacité à distribuer les outils séparément de l’hôte
• Tests et développement plus faciles

Pourquoi MCP ?

Le Protocole de Contexte de Modèle fournit une manière standardisée pour les LLM d’interagir avec des outils externes. En adoptant ce protocole, gomcptest assure la compatibilité avec les outils développés pour d’autres hôtes compatibles MCP.

Limitations et Orientations Futures

L’implémentation actuelle présente plusieurs limitations :

• Une seule session de chat par instance
• Support limité pour l’authentification et l’autorisation
• Pas de persistance de l’historique des chats entre les redémarrages
• Pas de support intégré pour la limitation de débit ou les quotas

Les améliorations futures pourraient inclure :

• Support pour plusieurs sessions de chat
• Intégration avec des fournisseurs de modèles supplémentaires
• Fonctionnalités de sécurité améliorées
• Gestion des erreurs et journalisation améliorées
• Optimisations de performance pour les déploiements à grande échelle

Conclusion

L’architecture de gomcptest représente une approche flexible et extensible pour construire des hôtes MCP personnalisés. Elle privilégie la simplicité, la modularité et l’expérience développeur, ce qui en fait une excellente plateforme pour l’expérimentation avec des systèmes d’agents.

En comprenant cette architecture, les développeurs peuvent utiliser efficacement le système, l’étendre avec de nouveaux outils, et potentiellement l’adapter à leurs besoins spécifiques.

4.2 - Understanding the Model Context Protocol (MCP)

What is the Model Context Protocol?

The Model Context Protocol (MCP) is a standardized communication protocol that enables Large Language Models (LLMs) to interact with external tools and capabilities. It defines a structured way for models to request information or take actions in the real world, and for tools to provide responses back to the model.

MCP is designed to solve the problem of extending LLMs beyond their training data by giving them access to:

• Current information (e.g., via web search)
• Computational capabilities (e.g., calculators, code execution)
• External systems (e.g., databases, APIs)
• User environment (e.g., file system, terminal)

How MCP Works

At its core, MCP is a protocol based on JSON-RPC that enables bidirectional communication between LLMs and tools. The basic workflow is:

1. The LLM generates a call to a tool with specific parameters
2. The host intercepts this call and routes it to the appropriate tool
3. The tool executes the requested action and returns the result
4. The result is injected into the model’s context
5. The model continues generating a response incorporating the new information

The protocol specifies:

• How tools declare their capabilities and parameters
• How the model requests tool actions
• How tools return results or errors
• How multiple tools can be combined

MCP in gomcptest

In gomcptest, MCP is implemented using a set of independent executables that communicate over standard I/O. This approach has several advantages:

• Language-agnostic: Tools can be written in any programming language
• Process isolation: Each tool runs in its own process for security and stability
• Compatibility: The protocol works with various LLM providers
• Extensibility: New tools can be easily added to the system

Each tool in gomcptest follows a consistent pattern:

1. It receives a JSON request on stdin
2. It parses the parameters and performs its action
3. It formats the result as JSON and returns it on stdout

The Protocol Specification

The core MCP protocol in gomcptest follows this format:

Tool Registration

Tools register themselves with a schema that defines their capabilities:

{
  "name": "ToolName",
  "description": "Description of what the tool does",
  "parameters": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "Description of parameter 1"
      },
      "param2": {
        "type": "number",
        "description": "Description of parameter 2"
      }
    },
    "required": ["param1"]
  }
}

Function Call Request

When a model wants to use a tool, it generates a function call like:

{
  "name": "ToolName",
  "params": {
    "param1": "value1",
    "param2": 42
  }
}

Function Call Response

The tool executes the requested action and returns:

{
  "result": "Output of the tool's execution"
}

Or, in case of an error:

{
  "error": {
    "message": "Error message",
    "code": "ERROR_CODE"
  }
}

Design Decisions in MCP

Several key design decisions shape the MCP implementation in gomcptest:

Standard I/O Communication

By using stdin/stdout for communication, tools can be written in any language that can read from stdin and write to stdout. This makes it easy to integrate existing utilities and libraries.

JSON Schema for Tool Definition

Using JSON Schema for tool definitions provides a clear contract between the model and the tools. It enables:

• Validation of parameters
• Documentation of capabilities
• Potential for automatic code generation

Stateless Design

Tools are designed to be stateless, with each invocation being independent. This simplifies the protocol and makes tools easier to reason about and test.

Pass-through Authentication

The protocol doesn’t handle authentication directly; instead, it relies on the host to manage permissions and authentication. This separation of concerns keeps the protocol simple.

Comparison with Alternatives

vs. OpenAI Function Calling

MCP is similar to OpenAI’s function calling feature but with these key differences:

• MCP is designed to be provider-agnostic
• MCP tools run as separate processes
• MCP provides more detailed error handling

vs. LangChain Tools

Compared to LangChain:

• MCP is a lower-level protocol rather than a framework
• MCP focuses on interoperability rather than abstraction
• MCP allows for stronger process isolation

vs. Agent Protocols

Other agent protocols often focus on higher-level concepts like goals and planning, while MCP focuses specifically on the mechanics of tool invocation.

Future Directions

The MCP protocol in gomcptest could evolve in several ways:

• Enhanced security: More granular permissions and sand-boxing
• Streaming responses: Support for tools that produce incremental results
• Bidirectional communication: Supporting tools that can request clarification
• Tool composition: First-class support for chaining tools together
• State management: Optional session state for tools that need to maintain context

Conclusion

The Model Context Protocol as implemented in gomcptest represents a pragmatic approach to extending LLM capabilities through external tools. Its simplicity, extensibility, and focus on interoperability make it a solid foundation for building and experimenting with agentic systems.

By understanding the protocol, developers can create new tools that seamlessly integrate with the system, unlocking new capabilities for LLM applications.