Risoluzione dei Problemi

Questa pagina fornisce soluzioni ai problemi comuni che potresti incontrare quando usi PrestaShop MCP Server.

Errore OAuth: "OAuth non implementato"

Problema: Quando connetti la tua applicazione IA al tuo MCP Server, ricevi un messaggio di errore che indica "OAuth non implementato" o un errore simile relativo a OAuth.

Soluzione:

Questo errore si verifica generalmente quando il flusso di autenticazione OAuth non può essere completato. Verifica quanto segue:

1. Configurazione Cloudflare

Se stai usando Cloudflare, verifica che:

• Cloudflare consenta l'accesso alle route .well-known/*
• Queste route sono essenziali per il processo di scoperta OAuth
• Assicurati che Cloudflare non stia bloccando o memorizzando nella cache questi endpoint

2. Configurazione .htaccess e .htpasswd

Verifica il tuo file .htaccess per assicurarti che consenta l'intestazione Authorization:

# Consenti intestazione Authorization
SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

L'intestazione Authorization è richiesta per far funzionare correttamente l'autenticazione OAuth.

Se usi un .htpasswd, devi richiedere mcp con autenticazione di base nella tua URL.

Esempio: https://username:password@your_domain.com/mcp

3. Modalità Manutenzione PrestaShop

Assicurati che il tuo negozio PrestaShop non sia in modalità manutenzione:

• La modalità manutenzione blocca l'accesso esterno al tuo negozio
• Questo impedisce al flusso di autenticazione OAuth di completarsi
• Disabilita la modalità manutenzione prima di tentare di connettere la tua applicazione IA

Suggerimento: Dopo aver fatto queste modifiche, prova a riconnettere la tua applicazione IA al tuo MCP Server.

Errore di Configurazione della Connessione: "Si è verificato un errore durante la configurazione della connessione"

Problema: Quando tenti di connettere la tua applicazione IA, ricevi un messaggio di errore che indica "Si è verificato un errore durante la configurazione della connessione".

Soluzione:

Questo errore si verifica generalmente quando non sei connesso con l'account corretto autorizzato ad accedere al MCP Server.

Verifica il Tuo Account

1. Vai su accounts.distribution.prestashop.net
2. Verifica l'indirizzo email con cui sei connesso
3. Torna alla pagina di configurazione di PS MCP Server e naviga alla scheda "Membri"
4. Verifica di essere connesso con l'indirizzo email autorizzato a connettersi al MCP Server

Se Stai Usando l'Account Sbagliato

Se scopri che sei connesso con l'account sbagliato:

1. Disconnettiti dall'account attuale
2. Riconnettiti con l'indirizzo email autorizzato corretto
3. Prova a riconnettere la tua applicazione IA

Se hai un errore con Accounts

1. Devi reimpostare il modulo ps_accounts
2. Riprova il passaggio di onboarding degli account

Errore di Classe Non Trovata: "class psMcpTools/LanguagesTool not found"

Problema: Incontri un messaggio di errore che indica "class psMcpTools/LanguagesTool not found" o errori simili relativi alle classi del modulo ps_mcp_tools.

Soluzione:

Questo errore si verifica quando la cache di PrestaShop non è sincronizzata con la struttura del modulo. Per risolvere questo:

Reimposta il Modulo ps_mcp_tools

1. Vai al tuo back office PrestaShop
2. Naviga su Moduli > Gestore moduli
3. Cerca "ps_mcp_tools"
4. Fai clic sul menu a discesa accanto al modulo
5. Seleziona "Reimposta"
6. Conferma l'azione di reimpostazione

Questo reinizializzerà il modulo e cancellerà la cache interna di PrestaShop associata ad esso.

Problemi di connessione

Problema: Il tuo LLM non riesce a connettersi, a scoprire gli strumenti o non sembra trovare un server di autenticazione.

Soluzione:

Questo problema può verificarsi se il tuo server sta bloccando le richieste dagli LLM. Per risolvere questo problema, devi aggiungere i seguenti user-agent alla lista bianca del tuo server o firewall:

• Claude Desktop: "python-httpx/0.28.1" / "Claude-User"
• ChatGPT: "Python/3.12 aiohttp/3.11.18" / "openai-mcp/1.0.0 (ChatGPT)"
• Dust: "node" / "node"
• Gemini CL: "node" / "node"

Assicurati che la tua configurazione di sicurezza consenta le richieste con questi user-agent.

Errore durante la chiamata degli strumenti

Problema: Quando l'agente IA chiama uno strumento, riceve un errore come "Errore interno" o un messaggio di errore inaspettato, ma non sai cosa è andato storto.

Soluzione:

Quando sviluppi strumenti, risorse o prompt MCP, devi avvolgere la tua logica di business in gestori di eccezioni per restituire messaggi di errore significativi all'agente IA. PrestaShop MCP Server fornisce wrapper di eccezioni dedicati per questo scopo:

use PrestaShop\Module\PsMcpServer\Server\Exceptions\PsMcpToolCallException;

try {
    // la tua logica di business
} catch (\Exception $e) {
    throw new PsMcpToolCallException(
        'Impossibile elaborare: ' . $e->getMessage(),
        1
    );
}

Utilizza la classe di eccezione appropriata a seconda del tipo di elemento MCP:

Per esempi dettagliati, consulta la sezione Gestione degli errori nella documentazione.

Hai bisogno di aiuto?

Se incontri problemi che non sono coperti in questa guida alla risoluzione dei problemi, puoi contattare il nostro servizio di supporto al seguente URL:

https://care-center.prestashop.com/it/contattaci?form=support&subject=ps_mcp_server

Il nostro team di supporto sarà lieto di assisterti con qualsiasi problema tu possa riscontrare.