Come creare un server MCP con l'interfaccia a riga di comando di Gemini e Go

1. Introduzione

In questo codelab imparerai a creare e implementare un server Model Context Protocol (MCP) per estendere le funzionalità della CLI Gemini. Creerai godoctor, un server basato su Go che fornisce strumenti personalizzati per lo sviluppo in Go, trasformando l'interfaccia a riga di comando di Gemini da assistente alla programmazione generico a esperto specializzato nello sviluppo in Go.

Questo codelab utilizza un approccio "basato sui prompt". Agirai in qualità di responsabile tecnico, fornendo prompt al tuo assistente AI (Gemini CLI). Il tuo obiettivo è imparare a tradurre i requisiti del progetto in prompt efficaci e lasciare che l'AI gestisca i dettagli di implementazione.

Al centro di questo progetto c'è il Model Context Protocol (MCP). MCP è un protocollo open source che standardizza il modo in cui i modelli linguistici di grandi dimensioni (LLM) come Gemini comunicano con strumenti e servizi esterni. Funge da ponte, consentendo all'AI di accedere a informazioni del mondo reale ed eseguire azioni al di là delle sue conoscenze integrate. Creando un server MCP, crei un plug-in personalizzato che Gemini CLI può rilevare e utilizzare, insegnandogli di fatto nuove competenze.

Obiettivi didattici

• Come installare e configurare Gemini CLI
• Come formulare prompt efficaci per guidare un assistente AI nello sviluppo software
• Come fornire contesto e linee guida a un assistente AI
• Come creare e configurare un server MCP per aumentare le funzionalità dell'interfaccia a riga di comando di Gemini
• Come containerizzare ed eseguire il deployment di un'applicazione Go in Google Cloud Run

Che cosa ti serve

Questo workshop può essere eseguito interamente in Google Cloud Shell, su cui sono preinstallate tutte le dipendenze necessarie (interfaccia a riga di comando gcloud, Go, Docker, interfaccia a riga di comando Gemini).

In alternativa, se preferisci lavorare sulla tua macchina, ti serviranno i seguenti elementi:

• Node.js 20 o versioni successive
• Un progetto Google Cloud con la fatturazione abilitata
• Google Cloud SDK (gcloud CLI) installato e inizializzato
• Go 1.24 o versioni successive installate sul sistema
• Docker installato sul sistema

Tecnologie chiave

Qui puoi trovare maggiori informazioni sulle tecnologie che utilizzeremo:

• Interfaccia a riga di comando di Gemini: l'interfaccia a riga di comando basata sull'AI che estenderemo
• Model Context Protocol (MCP): il protocollo open source che consente a Gemini CLI di comunicare con il nostro strumento personalizzato
• SDK Go per MCP: la libreria Go che utilizzeremo per implementare il nostro server MCP

Suggerimenti per un codelab efficace

Lavorare con un assistente AI è un nuovo modo di sviluppare software. Ecco alcuni suggerimenti per un'esperienza fluida e positiva:

1. Non aver paura di premere ESC. A volte l'AI propone azioni o codice con cui non sei d'accordo. Utilizza il tasto Esc per annullare l'azione proposta e fornire un nuovo prompt per guidarlo nella giusta direzione. Sei il pilota.
2. Incoraggia l'utilizzo degli strumenti. Se l'AI sembra persa o sta inventando informazioni, incoraggiala a utilizzare gli strumenti a sua disposizione. Prompt come "Puoi utilizzare la Ricerca Google per verificarlo?" o "Utilizza lo strumento read_file per comprendere il codice attuale prima di apportare modifiche" possono essere molto efficaci.
3. Resistere alle modifiche manuali. Cerca di far fare tutto il lavoro all'AI. Questa è l'abilità principale che stai praticando. Tuttavia, se devi apportare una modifica manuale, comunicala all'AI in un secondo momento. Un prompt come "Ho aggiornato manualmente il file README.md. Rileggilo per rinfrescare le tue conoscenze" assicurerà che l'AI rimanga sincronizzata con il tuo progetto.
4. Hai provato a spegnerlo e riaccenderlo? Nel raro caso in cui l'AI stia cercando di forzare un determinato percorso contro il tuo comando, il problema potrebbe essere dovuto al degrado del contesto (a volte chiamato anche "context rot"). In questo caso, puoi utilizzare il comando "/compress" di Gemini CLI per ridurre il rumore del contesto oppure, in casi estremi, puoi utilizzare il comando "/clear" per cancellare l'intera cronologia della sessione.

2. Configurazione dell'ambiente

Configurazione dell'ambiente autonoma

1. Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai già un account Gmail o Google Workspace, devi crearne uno.

• Il nome del progetto è il nome visualizzato per i partecipanti a questo progetto. È una stringa di caratteri non utilizzata dalle API di Google. Puoi sempre aggiornarlo.
• L'ID progetto è univoco in tutti i progetti Google Cloud ed è immutabile (non può essere modificato dopo l'impostazione). La console Cloud genera automaticamente una stringa univoca, di solito non ti interessa di cosa si tratta. Nella maggior parte dei codelab, dovrai fare riferimento all'ID progetto (in genere identificato come PROJECT_ID). Se l'ID generato non ti piace, puoi generarne un altro casuale. In alternativa, puoi provare a crearne uno e vedere se è disponibile. Non può essere modificato dopo questo passaggio e rimane per tutta la durata del progetto.
• Per tua informazione, esiste un terzo valore, un numero di progetto, utilizzato da alcune API. Scopri di più su tutti e tre questi valori nella documentazione.

Attenzione:un ID progetto è univoco a livello globale e non può essere utilizzato da nessun altro dopo che lo hai selezionato. Sei l'unico utente di questo ID. Anche se un progetto viene eliminato, l'ID non può essere riutilizzato

Nota:se utilizzi un account Gmail, puoi lasciare la posizione predefinita impostata su Nessuna organizzazione. Se utilizzi un account Google Workspace, scegli una posizione adatta alla tua organizzazione.

2. Successivamente, devi abilitare la fatturazione in Cloud Console per utilizzare le risorse/API Cloud. Completare questo codelab non costa molto, se non nulla. Per arrestare le risorse ed evitare addebiti oltre a quelli previsti in questo tutorial, puoi eliminare le risorse che hai creato o il progetto. I nuovi utenti di Google Cloud possono usufruire del programma prova senza costi di 300$.

Avvia Cloud Shell

Sebbene Google Cloud possa essere gestito da remoto dal tuo laptop, in questo codelab utilizzerai Google Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.

Nella console Google Cloud, fai clic sull'icona di Cloud Shell nella barra degli strumenti in alto a destra:

Bastano pochi istanti per eseguire il provisioning e connettersi all'ambiente. Al termine, dovresti vedere un risultato simile a questo:

Questa macchina virtuale è caricata con tutti gli strumenti di sviluppo di cui avrai bisogno. Offre una home directory permanente da 5 GB e viene eseguita su Google Cloud, migliorando notevolmente le prestazioni di rete e l'autenticazione. Tutto il lavoro in questo codelab può essere svolto all'interno di un browser. Non devi installare nulla.

3. Guida introduttiva a Gemini CLI

In questa sezione imparerai a utilizzare Gemini CLI, inclusi l'installazione e la configurazione per il tuo ambiente.

Che cos'è Gemini CLI?

L'interfaccia a riga di comando di Gemini è un'interfaccia a riga di comando basata sull'AI che può aiutarti a svolgere un'ampia gamma di attività di sviluppo. Può comprendere il contesto del tuo progetto, rispondere a domande, generare codice e utilizzare strumenti esterni per estendere le sue funzionalità.

Installazione

Nota:se utilizzi Google Cloud Shell, Gemini CLI è già installata e puoi passare alla sezione successiva (Configurazione).

Installa Gemini CLI a livello globale utilizzando npm.

npm install -g @google/gemini-cli

Per verificare che la CLI sia installata, esegui:

gemini --version

Configurazione

Il comportamento della CLI Gemini è controllato da file di configurazione e variabili di ambiente. Esistono due file chiave:

• GEMINI.md: questo file fornisce linee guida e contesto in linguaggio naturale all'AI. L'interfaccia a riga di comando legge questo file per comprendere gli standard e le convenzioni di codifica del progetto.
• .gemini/settings.json: questo file controlla la configurazione della CLI, incluso come connettersi a strumenti esterni. Utilizzeremo questo file per configurare la CLI in modo che utilizzi il server MCP che stiamo creando in questo lab.

Innanzitutto, configureremo l'ambiente e poi procederemo a creare il file GEMINI.md. Il file settings.json verrà configurato in un passaggio successivo.

1. Crea e inizializza una directory di progetto:

mkdir godoctor
cd godoctor
go mod init godoctor

1. Autenticati con le credenziali predefinite dell'applicazione Google Cloud:

Se utilizzi Cloud Shell, questo passaggio è già stato eseguito. Puoi passare alla sezione successiva (Linee guida per lo sviluppo).

Dobbiamo accedere a un account che abbia accesso al progetto Google Cloud che utilizzerai per questo codelab:

• Assicurati di aver installato e inizializzato Google Cloud SDK.
• Esegui questo comando per configurare le credenziali predefinite dell'applicazione:

gcloud auth application-default login

4. Linee guida per lo sviluppo

Per garantire che l'assistente AI generi codice Go idiomatico e di alta qualità, è essenziale fornirgli linee guida chiare. Questa operazione viene eseguita nel file GEMINI.md.

Nota:GEMINI.md può avere molti altri utilizzi, ad esempio comunicare alla CLI la struttura del progetto, le pratiche di lavoro, i test e altro ancora.

Obiettivo: creare un file GEMINI.md che fungerà da insieme di regole per l'assistente AI durante questo progetto.

Attività: crea un file denominato GEMINI.md nella directory principale di godoctor e incolla i seguenti contenuti.

# Go Development Guidelines
All code contributed to this project must adhere to the following principles.

### 1. Formatting
All Go code **must** be formatted with `gofmt` before being submitted.

### 2. Naming Conventions
- **Packages:** Use short, concise, all-lowercase names.
- **Variables, Functions, and Methods:** Use `camelCase` for unexported identifiers and `PascalCase` for exported identifiers.
- **Interfaces:** Name interfaces for what they do (e.g., `io.Reader`), not with a prefix like `I`.

### 3. Error Handling
- Errors are values. Do not discard them.
- Handle errors explicitly using the `if err != nil` pattern.
- Provide context to errors using `fmt.Errorf("context: %w", err)`.

### 4. Simplicity and Clarity
- "Clear is better than clever." Write code that is easy to understand.
- Avoid unnecessary complexity and abstractions.
- Prefer returning concrete types, not interfaces.

### 5. Documentation
- All exported identifiers (`PascalCase`) **must** have a doc comment.
- Comments should explain the *why*, not the *what*.

# Agent Guidelines
- **Reading URLs:** ALWAYS read URLs provided by the user. They are not optional.

Ora l'ambiente di sviluppo è completamente configurato.

5. La build iniziale: un server godoc

Il tuo primo obiettivo è creare la versione iniziale del server godoctor. Questa versione deve essere un'applicazione minima e pronta per la produzione che fornisce un singolo strumento chiamato godoc che consente di cercare la documentazione di Go.

Obiettivo: creare un server MCP pronto per la produzione che esponga il comando go doc, consentendo a un LLM di eseguire query sulla documentazione di Go.

Esegui il comando Gemini CLI nella shell:

gemini

Nota:se devi installare o aggiornare Gemini CLI su Cloud Shell, puoi utilizzare questo comando: sudo env PATH=$PATH npm install -g @google/gemini-cli

Quando esegui la CLI per la prima volta, ti verrà chiesto di scegliere una modalità di autenticazione e un tema. Per la modalità di autenticazione, scegli "Accedi con Google" per accedere con un Account Google personale e usufruire del generoso livello senza costi dell'interfaccia a riga di comando di Gemini. Dovresti visualizzare un'opzione per selezionare la modalità di autenticazione simile a questa:

Se devi modificare la selezione, puoi digitare /auth e premere Invio per aprire di nuovo questo menu.

Successivamente, ti verrà chiesto di scegliere un tema:

Come per /auth, puoi anche cambiare il tema in un secondo momento con il comando /theme.

Dopo aver scelto il metodo di autenticazione e il tema che preferisci, verrà visualizzato il prompt dei comandi. Qui puoi digitare i comandi, ad esempio:

Write a hello world application in Go.

La CLI utilizza una combinazione di ragionamento proprio (tramite un modello Gemini come Gemini Flash o Gemini Pro) e strumenti per svolgere le attività. Utilizza gli strumenti ogni volta che deve interagire con il file system o con servizi esterni, come API, database e così via. Esempi di strumenti predefiniti, o "interni", sono read_file, write_file, web_fetch e google_search. Il server MCP che stiamo creando diventerà anche uno strumento disponibile per la CLI.

La prima volta che esegue uno strumento, ti chiederà l'autorizzazione. Puoi concedere un'autorizzazione una tantum, un'approvazione generale per il resto della sessione o rifiutare la richiesta. Se si tratta di un'operazione di modifica di un file, troverai anche l'opzione per modificare il file utilizzando un editor esterno, nel caso in cui tu voglia apportare alcune modifiche. Ad esempio, questo è l'output del prompt precedente, per creare un programma Hello World:

Oltre ai prompt, puoi utilizzare anche i comandi slash. Se digiti "/", la CLI mostrerà automaticamente le opzioni di completamento automatico. Puoi continuare a digitare il comando completo o selezionarne uno dalle opzioni. I comandi /auth e /theme menzionati sopra sono alcuni esempi.

Una volta acquisita familiarità con l'interfaccia, puoi iniziare l'attività principale di questa sezione, ovvero chiedere alla CLI di scrivere il server MCP per noi.

Creazione di un server MCP Hello World

Uno dei modi migliori per garantire che il modello crei contenuti in modo più coerente è suddividere le attività complesse in passaggi incrementali. Anche se il modello potrebbe essere in grado di risolvere un'attività complessa da solo, senza la configurazione corretta impiegherà molto tempo per scoprire l'implementazione giusta.

Per un approccio più coerente, inizieremo con la creazione di un server MCP "Hello World" prima di implementare la funzionalità che ci interessa (lettura della documentazione di Go).

Di seguito è riportato un esempio di prompt:

Your task is to create a Model Context Protocol (MCP) server to expose a "hello world" tool. For the MCP implementation, you should use the official Go SDK for MCP and use the stdio transport.

Read these references to gather information about the technology and project structure before writing any code:
- https://github.com/modelcontextprotocol/go-sdk/blob/main/README.md
- https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle
- https://go.dev/doc/modules/layout

To test the server, use shell commands like these:
(
  echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}';
  echo '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}';
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}';
) | ./bin/godoctor

Tieni presente che il prompt precedente è composto da tre segmenti principali:

1. La specifica del problema, inclusi gli obiettivi e i vincoli (ad es. utilizzare l'SDK ufficiale anziché qualsiasi SDK)
2. Documentazione di riferimento per il modello per aiutarlo a disambiguare la richiesta
3. Una procedura di test, che funge da criteri di accettazione per l'attività

Questi tre componenti aiutano il modello a ottenere i risultati desiderati in modo più coerente.

Attenzione:anche se siamo molto precisi nelle nostre istruzioni, a volte il modello può discostarsi da ciò che gli abbiamo detto di fare, quindi è importante verificare il suo lavoro e rimanere aggiornati su potenziali loop di errori e allucinazioni. Se il modello si blocca, consulta la sezione Risorse utili alla fine di questo capitolo.

Implementazione dello strumento di documentazione Go

Una volta che avrai un'implementazione funzionante, potremo passare all'implementazione dello strumento "go doc" vero e proprio:

Add a new tool to our MCP server called "godoc" that invokes the "go doc" shell command. The tool will take a mandatory "package" argument and an optional "symbol" argument.

Read the reference for the go doc command to understand its API: https://pkg.go.dev/golang.org/x/tools/cmd/godoc

Test it by executing the call with:
  echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name": "godoc", "arguments": {"package": "fmt"} } }'
 | ./bin/godoctor

Test it using both a standard library package and an external package like "github.com/modelcontextprotocol/go-sdk/mcp", both with and without symbols.

Non esitare a sperimentare con questo prompt o a crearne uno personalizzato.

Nota:il prompt riportato sopra incoraggia esplicitamente il modello a utilizzare il comando shell go doc perché il codice per recuperare la documentazione utilizzando la libreria standard non è banale e il modello potrebbe impiegare un po' di tempo per capirlo da solo. L'utilizzo dello strumento go doc integrato nel compilatore consente di risparmiare molto tempo e ci aiuta a concentrarci su ciò che è importante, ovvero l'implementazione di MCP.

Un'interfaccia a riga di comando utile

Una volta che hai scelto un'implementazione adatta, puoi chiedere al modello di creare una CLI godoctor utilizzando un client MCP. In questo modo, il test delle funzionalità verrà semplificato, in quanto non sarà necessario creare manualmente le chiamate JSON-RPC.

Prompt di esempio:

Now create a godoctor-cli component that will call the MCP server using command transport. This CLI will expose all tools using subcommands and allow us to test the MCP server implementation without needing to build the JSON-RPC calls manually.

Use the reference implementation at https://github.com/modelcontextprotocol/go-sdk/blob/main/README.md to build the client.

Test it by calling from the command line:
- the hello_world tool 
- the godoc tool with a local package
- the godoc tool with a local package and symbol
- the godoc tool with an external package
- the godoc tool with an external package and symbol

Ora che hai un insieme funzionante di client e server, nella sezione successiva configurerai Gemini CLI con il server MCP che hai appena creato per iniziare a sfruttarne i vantaggi nella prossima attività di programmazione.

Risorse utili

Nota:la codifica con gli LLM è un'esperienza non deterministica, quindi non è sempre garantito di ottenere gli stessi risultati esatti anche se esegui due prompt identici con lo stesso ambiente. Per questo motivo, identificare quando l'LLM è bloccato in un loop o il contesto è degradato è un'abilità importante da sviluppare. Ricorda che hai il controllo e puoi interromperlo in qualsiasi momento premendo ESC.

Poiché MCP è ancora un concetto nuovo e l'SDK Go per MCP è una nuova libreria, in questo passaggio Gemini potrebbe impiegare molto tempo per scoprire l'implementazione corretta. Per aiutare il modello a trovare la soluzione giusta, puoi fornirgli i seguenti riferimenti:

1. Puoi fornire al modello il seguente prompt in modo che rilevi l'API SDK in modo più coerente: "use the go doc shell command to discover the api for the go-sdk library" (utilizza il comando della shell go doc per scoprire l'API per la libreria go-sdk).
2. Se il modello tenta di esaminare il codice sorgente dell'SDK con lo strumento read_file, l'operazione non andrà a buon fine perché Gemini CLI non può leggere file al di fuori del suo ambito attuale. Puoi istruire l'app a utilizzare i comandi cat e ls tramite lo strumento run_shell_command.
3. Se il modello ha difficoltà a eseguire il debug dell'applicazione, chiedigli di aggiungere un logging più dettagliato e di migliorare le informazioni contestuali nei messaggi di errore.
4. Se tutto il resto non funziona, prova con un'implementazione di riferimento: https://github.com/danicat/godoctor

6. Configurazione di godoctor come server MCP per l'interfaccia a riga di comando Gemini

Dopo che l'assistente AI ha generato il codice sia per il client sia per il server, puoi chiedergli di eseguire alcuni test manuali. Ad esempio:

retrieve the documentation for the package net/http

Assicurati di testarlo anche con una dipendenza esterna (non nella libreria standard):

retrieve the documentation for the github.com/modelcontextprotocol/go-sdk/mcp package

Una volta che i risultati ti soddisfano, chiedi di scrivere un file README.md con le istruzioni su come utilizzare e sviluppare questo progetto.

Now write a detailed README.md file explaining both from a user and a developer perspective how to use and to build this project.

Ora configureremo il server in modo che Gemini CLI possa utilizzarlo durante la fase successiva di sviluppo.

1. Chiedi alla CLI di aggiornare GEMINI.md in modo che utilizzi godoc come metodo preferito per leggere la documentazione:

update the GEMINI.md file to use the godoc tool to retrieve documentation about Go packages or symbols. Always prefer to use godoc over WebFetch and GoogleSearch, and only use those when godoc doesn't give a clear answer.

2. Ora dobbiamo riavviare Gemini CLI per configurarla. Innanzitutto, salviamo la sessione di chat in modo che tu possa riprenderla da dove l'avevi interrotta una volta riavviata.

/chat save workshop001

3. Esci dalla CLI premendo due volte Ctrl+D o digitando il comando /quit.
4. Compila il binario del server: crea una directory bin e compila il server godoctor al suo interno.

mkdir -p bin
go build -o ./bin/godoctor ./cmd/godoctor # adjust paths as needed

Nota: ti consigliamo di utilizzare una cartella diversa da quella utilizzata per la creazione del server durante lo sviluppo, in quanto vogliamo che questo binario sia stabile e disponibile per la CLI durante la fase successiva.

5. Configura Gemini CLI per lo strumento locale: crea un file .gemini/settings.json nella radice del progetto e aggiungi una sezione mcpServers per indicare a Gemini CLI come eseguire il server compilato.

mkdir -p .gemini
touch .gemini/settings.json

6. Ora aggiungi i seguenti contenuti al nuovo file utilizzando un editor della riga di comando come vim o nano:

{
  "mcpServers": {
    "godoctor": {
      "command": "./bin/godoctor"
    }
  }
}

7. Ora avvia Gemini CLI e ripristina la sessione di chat:

/chat resume workshop001

8. Dovresti essere in grado di vedere che lo strumento è caricato digitando il comando /mcp. Puoi anche mostrare la descrizione completa degli strumenti utilizzando /mcp desc:

9. Testa l'integrazione chiedendo a Gemini CLI di utilizzare il tuo strumento con un prompt come "Recupera la documentazione per net/http".

Il risultato dovrebbe essere simile a questo:

Nota: potrebbe succedere che il modello tenti di chiamare lo strumento tramite il comando shell. Se ciò accade, prova ad avviare una sessione senza il contesto della sessione precedente (ad es.non chiamare /chat resume).

Se lo strumento funziona correttamente, dovresti visualizzare la documentazione recuperata tramite la chiamata allo strumento:

Congratulazioni, hai creato uno strumento MCP. Ma non è finita qui, possiamo ancora renderla un po' più utile.

7. Aggiungere un revisore del codice basato sull'AI

Aggiungiamo una funzionalità più sofisticata basata sull'AI: un revisore del codice che utilizza l'API Gemini.

Obiettivo: aggiungi un nuovo strumento denominato code_review al progetto esistente. Questo strumento utilizzerà l'API Gemini per analizzare il codice Go e fornire feedback.

Prompt di esempio:

I want to add a new tool to my project called code_review. This tool should use the Gemini API on Vertex AI (with gemini-2.5-flash) to analyze Go code and provide a list of improvements in json format according to the best practices accepted by the Go community.

The tool should take the Go code content and an optional hint as input. The hint will be used to provide additional guidance for the AI reviewer, like "focus on security" or "help me simplify this code". Please update the server to include this new tool and modify the CLI client to add a review command to use it.

Use this SDK to call Gemini: https://github.com/googleapis/go-genai

Consigli utili

Una volta che il modello inizia a lavorarci, potresti notare che richiede automaticamente di chiamare lo strumento godoc per sfogliare la documentazione del pacchetto genai. In caso contrario, puoi sempre interrompere la procedura con il tasto Esc e ricordargli che ora ha a disposizione lo strumento godoc.

Test di Code Reviewer

1. Salva la sessione di chat con /chat save workshop002 ed esci dalla CLI premendo due volte Ctrl+D.
2. Lo strumento code_review deve accedere a Vertex AI, quindi dobbiamo prima abilitare l'API:

gcloud services enable aiplatform.googleapis.com

3. Crea un file .env con i contenuti riportati di seguito. Non dimenticare di sostituire la variabile GOOGLE_CLOUD_PROJECT con l'ID progetto effettivo del progetto che hai creato all'inizio di questo lab e GOOGLE_CLOUD_LOCATION con la località che preferisci (ad es. "us-central1").

export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='your-location'

4. Carica il file .env con il comando source:

source .env

5. Ricompila il server con la nuova definizione dello strumento:

go build -o ./bin/godoctor ./cmd/godoctor

6. Avvia di nuovo Gemini CLI. Ripristina la sessione di chat con /chat resume workshop002.
7. Verifica che lo strumento sia abilitato digitando il comando /mcp. Il risultato dovrebbe essere simile a questo:

8. Ora testiamo lo strumento code-review esaminando uno dei file di origine dello strumento:

"Utilizza lo strumento godoctor per esaminare il file cmd/godoctor/main.go."

    You should see something like this:

Ora che lo strumento di revisione del codice funziona, puoi suggerire al modello di applicare alcuni dei miglioramenti che ha trovato, per un flusso di lavoro completo di "auto-miglioramento".

Ora hai confermato che lo strumento code-review funziona. Nella prossima sezione lavorerai al deployment nel cloud. Salva la sessione corrente con /chat save workshop003 ed esci dalla CLI.

8. Preparare il server per il cloud

Il server MCP che abbiamo sviluppato finora viene eseguito solo nella macchina locale, il che va bene se stai sviluppando strumenti per uso personale, ma spesso negli ambienti aziendali dobbiamo implementare strumenti per un utilizzo più ampio da parte di centinaia o addirittura migliaia di sviluppatori.

Per scalare il nostro server MCP, dobbiamo convertirlo da un server che comunica solo con I/O standard a un server che può comunicare tramite HTTP e distribuirlo in un punto in cui possa essere accessibile a diversi sviluppatori. Per questo obiettivo utilizzeremo una modalità di trasporto definita nella specifica MCP come HTTP trasmissibile e Cloud Run come destinazione di deployment.

Obiettivo: refactoring del server godoctor per utilizzare il trasporto HTTP in streaming.

Prompt di esempio:

The godoctor server is currently using the stdio transport. I want to deploy it to Cloud Run, so I need to refactor it to use the streamable HTTP transport instead. Please modify the server to comply with the streamable HTTP specification.

Risorse utili

1. Se il modello ha difficoltà a implementare il trasporto HTTP trasmissibile, puoi fornirgli questo riferimento: https://github.com/modelcontextprotocol/go-sdk/blob/main/design/design.md
2. Il modello potrebbe provare a utilizzare HTTP+SSE, che è stato ritirato. Se vedi che segue questo percorso, riportalo verso HTTP riproducibile in streaming.

Test del server tramite HTTP

Chiedi al modello di aggiornare il client godoctor in modo che utilizzi anche HTTP in streaming per verificare che funzioni ancora.

Now update the client to use streamable HTTP and run a test by retrieving documentation from one package

(Facoltativo) Se vuoi configurare l'interfaccia a riga di comando di Gemini per utilizzare il server tramite HTTP:

1. Salva la sessione ed esci dalla CLI
2. Modifica il file .gemini/settings.json e cambia la configurazione in modo che punti al server locale in esecuzione.

"mcpServers": {
  "godoctor": {
    "httpUrl": "http://localhost:8080"
  }
}

3. Esegui il server sottoposto a refactoring localmente:

go run ./cmd/godoctor/main.go

4. In un nuovo terminale (poiché l'operazione precedente è bloccante), avvia Gemini CLI e fornisci un prompt per testare la connessione, ad esempio: "Utilizza lo strumento godoctor per ottenere la documentazione per fmt.Println."
5. Arresta il server con Ctrl+C al termine del test.

9. Containerizzare l'applicazione con Docker

Ora che il nostro server utilizza il protocollo di trasporto corretto, possiamo inserirlo in un container per il deployment.

Obiettivo: creare un Dockerfile per inserire il server godoctor in un'immagine container portatile e pronta per la produzione.

Prompt di esempio:

Please create a multi-stage Dockerfile that compiles the Go binary and copies it into a minimal golang image like golang:1.24-alpine.

Test dell'immagine Docker

Dopo aver creato Dockerfile, crea l'immagine ed eseguila per assicurarti che funzioni correttamente. Puoi chiedere a Gemini di farlo per te:

build the image and test the connectivity to the server using the godoctor client

(Facoltativo) Se vuoi eseguire il test manualmente:

1. Crea il container:

docker build -t godoctor:latest .

2. Esegui il container localmente:

docker run -p 8080:8080 -e PORT=8080 godoctor:latest

3. Testa il container in esecuzione: in un altro terminale, avvia Gemini CLI e chiedi di recuperare la documentazione.
4. Arresta il server con Ctrl+C al termine del test.

10. Deployment in Cloud Run

Ora è il momento di eseguire il deployment del nostro container nel cloud.

Obiettivo: eseguire il deployment del server godoctor containerizzato in Google Cloud Run.

Guida ai prompt: chiedi all'assistente AI di fornire i comandi gcloud per eseguire il deployment del container.

Prompt di esempio:

Now please deploy this image to Cloud Run and return me an URL I can use to call the MCP tool. Configure Cloud Run to use the environment variables in the .env file.

Attenzione:se è la prima volta che utilizzi Cloud Run in questo progetto, ti verrà chiesto di abilitare le API Artifact Registry e Cloud Run.

Al termine del deployment, configureremo Gemini CLI per utilizzare lo strumento appena eseguito.

Aggiorna il file .gemini/settings.json per modificare la configurazione dello strumento MCP in modo che punti al servizio di cui è stato eseguito il deployment oppure chiedi a Gemini CLI di farlo per te:

now update the .gemini/settings.json file to use this URL for the godoctor server

La sezione mcpServers finale dovrebbe avere questo aspetto (ricordati di sostituire il segnaposto con l'URL effettivo dell'app Cloud Run):

"mcpServers": {
  "godoctor": {
    "httpUrl": "https://<your-cloud-run-id>.us-central1.run.app"
  }
}

Test del deployment di Cloud Run

Ora puoi eseguire il test end-to-end finale.

Riavvia l'interfaccia a riga di comando di Gemini un'ultima volta (utilizzando /chat save e /chat resume per conservare il contesto). Ora la CLI dovrebbe essere in grado di chiamare il server MCP remoto. Prova a chiedere la documentazione per eventuali pacchetti.

Puoi anche testare lo strumento di revisione del codice:

Use the godoctor tool to review the cmd/godoctor/main.go file

Pulizia

Attenzione:assicurati di eliminare il deployment di Cloud Run prima di concludere questa sessione, soprattutto se utilizzi un'istanza Cloud Run non autenticata per evitare addebiti imprevisti al tuo account di fatturazione GCP.

Al termine del test, ricordati di pulire l'ambiente. Puoi chiedere a Gemini di eliminare il progetto o solo il deployment di Cloud Run. Prompt di esempio:

I'm done with my tests on the CloudRun server, please delete this deployment for me and revert my .gemini/settings.json to use the local version.

11. Complimenti!

Hai guidato correttamente un assistente AI nella creazione, nella containerizzazione e nel deployment di uno strumento sofisticato basato sull'AI. Ancora più importante, hai acquisito la competenza essenziale dello sviluppo di software moderno: tradurre i requisiti in prompt efficaci. Hai esteso correttamente Gemini CLI con uno strumento MCP personalizzato, rendendolo un assistente allo sviluppo Go più potente e specializzato.

Documenti di riferimento

• Post del blog sull'annuncio di Gemini CLI
• Home page di Gemini CLI
• Documentazione di Gemini CLI
• Specifica del Model Context Protocol
• SDK Go per MCP
• SDK Google Gen AI per Go