Eseguire il debug di un server che non si avvia

A volte riavvia l'host e gli strumenti non sono semplicemente disponibili. Niente panico: gli errori di avvio seguono alcuni schemi prevedibili. 🛠️

La prima cosa da fare sono sempre i log. Claude Desktop scrive file di log separati per ogni server, che indicano esattamente perché un processo non è riuscito ad avviarsi.

La causa principale è un comando errato o un percorso relativo allo script. L'host non riesce a trovare Python o il file, quindi il processo non viene nemmeno avviato.

Esegua manualmente lo stesso comando della configurazione. Se va in crash nel terminale, andrà in crash anche per l'host, e l'errore sarà proprio lì.

Un ImportError significa che l'host ha avviato Python senza i Suoi pacchetti. Specifichi l'interprete oppure usi uv, così verrà utilizzato l'ambiente corretto.

Questo problema è facile da trascurare: qualsiasi print su stdout corrompe l'handshake, quindi il client rinuncia. Sposti ogni print su stderr e riprovi.

Una sola virgola finale rende claude_desktop_config.json non valido e l'host non carica alcun server. In caso di dubbio, convalidi il file.

La dimenticanza più semplice: ha modificato la configurazione, ma non ha mai riavviato. Chiuda completamente Claude, non solo la finestra, quindi lo riapra.

Il problema persiste? Avvii il server in Inspector. Se lì funziona ma non nell'host, il problema è nella configurazione, non nel codice.

Eviti di fare supposizioni. Il traceback nel Suo stderr indica la riga esatta e l'eccezione. Lo legga tutto prima di modificare qualsiasi cosa. 📋

Quando modifica qualcosa, cambi una sola cosa e poi esegua nuovamente il test. Modificare tre impostazioni contemporaneamente nasconde quale correzione abbia risolto davvero il problema.

Ha imparato a leggere i log, testare direttamente il comando, correggere percorsi, dipendenze e print indesiderati e isolare il problema con Inspector. Il Suo server è verificato! 🎉