Come utilizzare MCP con l'API di OpenAI utilizzando Dolphin-MCP

Introduzione

Dolphin-MCP è un'implementazione open-source che estende il Model Context Protocol (MCP) di Anthropic per lavorare con vari modelli di linguaggio oltre Claude. Questa guida tecnica ti guiderà attraverso la configurazione e l'utilizzo di Dolphin-MCP specificamente con l'API di OpenAI, consentendoti di sfruttare i modelli GPT tramite l'architettura MCP.

Panoramica Tecnica

Dolphin-MCP funge da strato di traduzione tra la specifica MCP e varie API di LLM. Per l'integrazione con OpenAI, esso:

• Converte i messaggi del protocollo MCP nei formati delle API di OpenAI
• Gestisce le differenze di mapping dei token tra i modelli
• Gestisce lo stato della conversazione e la cronologia
• Fornisce capacità di esecuzione degli strumenti in modo indipendente dal modello

Prerequisiti

Prima di iniziare, assicurati di avere:

• Python 3.8+
• pip (gestore pacchetti)
• Chiave API di OpenAI
• Git installato
• Comprensione di base degli LLM e dei concetti API

Passaggi di Installazione

# Clona il repository Dolphin-MCP
git clone https://github.com/cognitivecomputations/dolphin-mcp.git
cd dolphin-mcp

# Crea un ambiente virtuale
python -m venv venv
source venv/bin/activate  # Su Windows: venv\Scripts\activate

# Installa le dipendenze
pip install -r requirements.txt

# Installa il pacchetto in modalità sviluppo
pip install -e .

Configurazione

1. Impostazione delle Variabili d'Ambiente

Crea un file .env nella radice del tuo progetto:

OPENAI_API_KEY=sk-la-tua-chiave-api-openai-qui
MCP_MODEL=gpt-4-0125-preview
MCP_PROVIDER=openai

2. Creazione di un File di Configurazione

Crea un file config.json:

{
  "provider": "openai",
  "model_settings": {
    "model": "gpt-4-0125-preview",
    "temperature": 0.7,
    "max_tokens": 2048
  },
  "api_config": {
    "api_key": "sk-la-tua-chiave-api-openai-qui",
    "base_url": "https://api.openai.com/v1",
    "timeout": 120
  }
}

Esempi di Utilizzo di Base

Esempio 1: Conversazione Semplice

from dolphin_mcp import DolphinMCP

# Inizializza il client
mcp_client = DolphinMCP.from_config("./config.json")

# Crea una conversazione
conversation = mcp_client.create_conversation()

# Aggiungi un messaggio di sistema
conversation.add_system_message("Sei un assistente AI utile specializzato nella programmazione Python.")

# Invia un messaggio utente e ottieni una risposta
response = conversation.add_user_message("Come implemento un albero di ricerca binario in Python?")

# Stampa la risposta
print(response.content)

Esempio 2: Utilizzare Strumenti con OpenAI

from dolphin_mcp import DolphinMCP
from dolphin_mcp.tools import WebSearchTool, CodeExecutionTool

# Inizializza client con strumenti
mcp_client = DolphinMCP.from_config("./config.json")

# Registra strumenti
mcp_client.register_tool(WebSearchTool(api_key="la-tua-chiave-api-di-ricerca"))
mcp_client.register_tool(CodeExecutionTool())

# Crea una conversazione con strumenti abilitati
conversation = mcp_client.create_conversation()

# Aggiungi istruzioni di sistema per gli strumenti
conversation.add_system_message("""
Sei un assistente AI con accesso ai seguenti strumenti:
- web_search: Cerca informazioni attuali su Internet
- code_execution: Esegui codice Python in sicurezza in una sandbox

Usa questi strumenti quando appropriato per fornire risposte accurate e utili.
""")

# Interrogazione dell'utente che richiede strumenti
response = conversation.add_user_message(
    "Qual è il meteo attuale a New York? Inoltre, puoi mostrarmi come calcolare il fattoriale di un numero in Python?"
)

# La risposta includerà automaticamente l'uso degli strumenti
print(response.content)
print("\nEsecuzioni degli strumenti:")
for tool_name, tool_result in response.tool_results.items():
    print(f"{tool_name}: {tool_result}")

Configurazione Avanzata

Utilizzo di Endpoint Compatibili con OpenAI

Se desideri utilizzare endpoint alternativi compatibili con OpenAI (come Azure OpenAI o modelli self-hosted), modifica la tua configurazione:

{
  "provider": "openai",
  "model_settings": {
    "model": "tuo-deployment-modello-personalizzato",
    "temperature": 0.7,
    "max_tokens": 2048
  },
  "api_config": {
    "api_key": "la-tua-chiave-api",
    "base_url": "https://il-tuo-endpoint-personalizzato.com/v1",
    "api_version": "2023-07-01-preview",  // Per Azure
    "api_type": "azure"  // Per Azure
  }
}

Implementazione di Strumenti Personalizzati

Dolphin-MCP ti consente di creare strumenti personalizzati per i modelli di OpenAI. Ecco come implementare uno strumento calcolatore personalizzato:

from dolphin_mcp.tools import BaseTool
import math

class CalculatorTool(BaseTool):
    name = "calculator"
    description = "Esegue calcoli matematici"
    
    async def execute(self, expression: str):
        try:
            # Crea un ambiente sicuro con funzioni matematiche limitate
            safe_env = {
                "sqrt": math.sqrt,
                "sin": math.sin,
                "cos": math.cos,
                "tan": math.tan,
                "pi": math.pi,
                "e": math.e
            }
            
            # Valuta l'espressione nell'ambiente sicuro
            result = eval(expression, {"__builtins__": {}}, safe_env)
            return str(result)
        except Exception as e:
            return f"Errore nel calcolo: {str(e)}"
    
    @property
    def parameters(self):
        return {
            "type": "object",
            "properties": {
                "expression": {
                    "type": "string",
                    "description": "L'espressione matematica da valutare"
                }
            },
            "required": ["expression"]
        }

# Esempio di utilizzo
mcp_client = DolphinMCP.from_config("./config.json")
mcp_client.register_tool(CalculatorTool())

Gestione delle Risposte in Streaming

Per le applicazioni che richiedono risposte in tempo reale:

async def stream_response():
    mcp_client = DolphinMCP.from_config("./config.json")
    conversation = mcp_client.create_conversation()
    
    # Imposta la conversazione
    conversation.add_system_message("Sei un assistente AI utile.")
    
    # Stream della risposta
    async for chunk in conversation.add_user_message_streaming(
        "Spiega il calcolo quantistico in termini semplici."
    ):
        if chunk.type == "content":
            print(chunk.content, end="", flush=True)
        elif chunk.type == "tool_start":
            print(f"\n[Inizio utilizzo dello strumento: {chunk.tool_name}]")
        elif chunk.type == "tool_result":
            print(f"\n[Risultato dello strumento da {chunk.tool_name}]: {chunk.result}")
        elif chunk.type == "error":
            print(f"\nErrore: {chunk.error}")
    
    print("\nRisposta completata.")

# Esegui la funzione async
import asyncio
asyncio.run(stream_response())

Gestione degli Errori

Implementa una gestione degli errori robusta per gestire i problemi dell'API:

from dolphin_mcp.exceptions import MCPAPIError, MCPConfigError, MCPTimeoutError

try:
    mcp_client = DolphinMCP.from_config("./config.json")
    conversation = mcp_client.create_conversation()
    response = conversation.add_user_message("Genera una risposta complessa")
    
except MCPTimeoutError:
    print("La richiesta è scaduta. Controlla la tua connessione di rete o aumenta il valore di timeout.")
    
except MCPAPIError as e:
    print(f"Errore API: {e.status_code} - {e.message}")
    if e.status_code == 429:
        print("Limite di richiesta superato. Implementa un backoff esponenziale.")
    
except MCPConfigError as e:
    print(f"Errore di Configurazione: {e}")
    
except Exception as e:
    print(f"Errore imprevisto: {e}")

Ottimizzazione delle Prestazioni

Per gli ambienti di produzione, considera queste ottimizzazioni:

# Riutilizzo delle sessioni per il pooling delle connessioni
from dolphin_mcp import DolphinMCP
import aiohttp

async def optimized_mcp_usage():
    # Crea una sessione condivisa per il pooling delle connessioni
    async with aiohttp.ClientSession() as session:
        mcp_client = DolphinMCP.from_config(
            "./config.json",
            session=session,
            request_timeout=60,
            connection_pool_size=10
        )
        
        # Processa più conversazioni in modo efficiente
        tasks = []
        for i in range(5):
            conversation = mcp_client.create_conversation()
            conversation.add_system_message("Sei un assistente utile.")
            tasks.append(conversation.add_user_message_async(f"Domanda {i}: Cos'è il machine learning?"))
        
        # Raccogli tutte le risposte
        responses = await asyncio.gather(*tasks)
        
        for i, response in enumerate(responses):
            print(f"Risposta {i}: {response.content[:100]}...")

Integrazione con Applicazioni Web

Esempio di integrazione Flask:

from flask import Flask, request, jsonify
from dolphin_mcp import DolphinMCP

app = Flask(__name__)
mcp_client = DolphinMCP.from_config("./config.json")

@app.route("/chat", methods=["POST"])
def chat():
    data = request.json
    conversation_id = data.get("conversation_id")
    message = data.get("message")
    
    # Recupera o crea una conversazione
    if conversation_id and conversation_id in active_conversations:
        conversation = active_conversations[conversation_id]
    else:
        conversation = mcp_client.create_conversation()
        conversation_id = conversation.id
        active_conversations[conversation_id] = conversation
        conversation.add_system_message("Sei un assistente AI utile.")
    
    # Processa il messaggio
    response = conversation.add_user_message(message)
    
    return jsonify({
        "conversation_id": conversation_id,
        "response": response.content,
        "tool_results": response.tool_results
    })

if __name__ == "__main__":
    active_conversations = {}
    app.run(debug=True)

Risoluzione dei Problemi Comuni

Conclusione

Dolphin-MCP fornisce un modo flessibile e open-source per utilizzare i modelli di OpenAI con il protocollo MCP. Questa implementazione libera gli sviluppatori dai vincoli del fornitore mantenendo un'interfaccia coerente tra i diversi fornitori di LLM. Seguendo i passaggi in questa guida, puoi sfruttare la potenza dei modelli GPT attraverso l'architettura MCP standardizzata.

philschmid.de mostra integrazioni simili con altri LLM, e strumenti come mcpadapt possono aiutare ad estendere ulteriormente le capacità di Dolphin-MCP.