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 a eseguire il deployment di 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 Gemini CLI da assistente alla programmazione generico in 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à di Gemini CLI
• Come containerizzare ed eseguire il deployment di un'applicazione Go in Google Cloud Run

Che cosa ti serve

Questo workshop può essere svolto interamente in Google Cloud Shell, che include tutte le dipendenze necessarie (gcloud CLI, Go, Docker, Gemini CLI) preinstallate.

In alternativa, se preferisci lavorare sulla tua macchina, avrai bisogno di quanto segue:

• Node.js 20 o versioni successive
• 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:

• Gemini CLI: 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 fornisci 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 aggiornare 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

Per i crediti Google Cloud:per iniziare, riscatta i tuoi crediti Google Cloud senza costi utilizzando questo link. Puoi seguire le istruzioni qui per attivare il credito e creare un nuovo progetto.

Scegli una delle seguenti opzioni: Configurazione dell'ambiente autonomo se vuoi eseguire questa

codelab sulla tua macchina oppure avvia Cloud Shell se vuoi eseguire questo codelab interamente nel cloud.

Configurazione dell'ambiente autonoma

1. Accedi alla console Google Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai ancora 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 non ti piace l'ID generato, 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 altri 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

Anche se Google Cloud può 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 per sviluppatori di cui avrai bisogno. Offre una home directory permanente da 5 GB e viene eseguita su Google Cloud, migliorando notevolmente le prestazioni e l'autenticazione della rete. 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?

Gemini CLI è 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 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 in un secondo momento 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

2. Esegui l'autenticazione con le credenziali predefinite dell'applicazione Google Cloud:

Nota: se utilizzi Cloud Shell, l'autenticazione è già coperta.

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. File di contesto (GEMINI.md)

I file di contesto, che utilizzano il nome predefinito GEMINI.md, vengono utilizzati per fornire un contesto didattico al modello Gemini. Puoi utilizzare questi file per fornire istruzioni specifiche per il progetto, definire una persona o fornire guide di stile di programmazione per rendere le risposte dell'AI più accurate e personalizzate in base alle tue esigenze.

Per garantire che l'assistente AI generi codice Go idiomatico e di alta qualità, scriveremo un file GEMINI.md con alcune best practice comuni per gli sviluppatori Go.

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

Apri il tuo IDE per creare il file GEMINI.md con i contenuti riportati di seguito. Se utilizzi Cloud Shell, puoi aprire un editor utilizzando il comando riportato di seguito:

cloudshell edit .

Attività: crea un file denominato GEMINI.md nella directory radice di godoctor e incollaci 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*.

## 6. Project structure
- cmd/ contains source code for target binaries (e.g. server, client)
- internal/ contains source code for packages not meant to be exported (e.g. internal/tools/hello)
- bin/ contains the compiled binaries
- At the root place README.md, go.mod and go.sum

Ora l'ambiente di sviluppo è completamente configurato.

5. La build iniziale: un server di documentazione

Il tuo primo obiettivo è creare la versione iniziale del server godoctor. Questa versione deve essere un'applicazione minima che fornisce un singolo strumento chiamato read_docs 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

Importante: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.

Se esegui questo codelab in Cloud Shell, scegli l'opzione Utilizza le credenziali utente di Cloud Shell. In caso contrario, puoi utilizzare Accedi con Google per accedere con un Account Google personale e usufruire del generoso livello senza costi della CLI di Gemini. La schermata di selezione dell'autenticazione sarà 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 "strumenti 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 l'autorizzazione una tantum (Consenti una volta), un'approvazione generale per il resto della sessione (Consenti sempre) o rifiutare la richiesta. Se si tratta di un'operazione di modifica del 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, prima gli chiederemo di creare un server MCP "Hello World" prima di implementare la funzionalità che ci interessa (leggere la documentazione di Go).

Di seguito è riportato un esempio di prompt:

Create a Model Context Protocol (MCP) server that exposes a "hello_world" tool. This tool, when called, should return the message "Hello, MCP world!"

For the MCP implementation, you should use the official Go SDK for MCP (github.com/modelcontextprotocol/go-sdk/mcp) and use the stdio transport.

TODO:
- Download the dependency: `go get github.com/modelcontextprotocol/go-sdk/mcp`
- Inspect the documentation of the SDK: `go doc github.com/modelcontextprotocol/go-sdk/mcp`
- Build a `server` command that supports stdio transport only
- Build a `client` command that connects to the server over command transport to test the server

Acceptance Criteria:
- `./bin/client --list-tools` returns the list of server tools including "hello_world"
- `./bin/client --call-tool` "hello_world" returns the output "Hello, MCP world!"

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

1. La specifica del problema, inclusi gli elementi da creare e i vincoli (ad es. utilizzare l'SDK ufficiale anziché qualsiasi SDK, trasporto stdio anziché http)
2. Suddivisione delle attività da svolgere (cose da fare)
3. Criteri di accettazione dell'attività, che fungono da procedura di test in modo che l'agente sappia quando è completata

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 prestare attenzione a potenziali loop di errori e allucinazioni. Se il modello si blocca, consulta la sezione Suggerimenti utili alla fine di questo capitolo.

Implementazione dello strumento read_docs

Nota:il prompt riportato di seguito 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.

Una volta che l'implementazione funziona, possiamo passare all'implementazione dello strumento "read_docs" vero e proprio:

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

TODO:
- create a package `./internal/tools/docs`
- register the tool with the MCP server
- update the client to support the "read_docs" tool by providing arguments to the tool call

Acceptance Criteria:
- `./bin/client --tools-list` show both hello_world and read_docs
- `./bin/client --tool-call read_docs fmt` returns the documentation for the `fmt` package
- `./bin/client --tool-call read_docs fmt.Println` returns the documentation for the `fmt.Println` function
- `./bin/client --tool-call read_docs github.com/modelcontextprotocol/go-sdk/mcp` returns documentation for the `mcp` package

Nota: non esitare a sperimentare con questo prompt o a provarne uno personalizzato.

Consigli 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 è importante imparare a identificare quando il modello LLM è bloccato in un loop o il contesto è degradato. Ricorda che hai il controllo e puoi interrompere l'operazione 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 da solo l'implementazione corretta. Per aiutare il modello a trovare la soluzione giusta, puoi provare quanto segue:

1. Se il modello ha saltato la lettura della documentazione in qualsiasi passaggio, premi ESC e ricordagli di farlo. Se non hai familiarità con Go, l'esecuzione di "go doc" più il nome del pacchetto "go doc github.com/modelcontextprotocol/go-sdk/mcp" restituirà la documentazione corretta.
2. Il modulo di primo livello " github.com/modelcontextprotocol/go-sdk" non ha alcuna documentazione (perché non ha codice Go), devi indicare al modello di cercare il percorso completo
3. Al contrario, se il modello allucina un pacchetto inesistente, ad esempio "go doc github.com/modelcontextprotocol/go-sdk/mcp/server", indirizzalo al pacchetto di primo livello.

6. Configurazione di godoctor come server MCP per la CLI 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 read_docs come metodo preferito per leggere la documentazione:

update the GEMINI.md file to include instructions to always use the read_docs tool to retrieve documentation about Go packages or symbols. This should be done whenever seeing an import for the first time in a session or after a new dependency is installed to the project (e.g. via `go get`)

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

/chat save godoctor-workshop

3. Esci dalla CLI premendo Ctrl+D due volte o digitando il comando /quit.
4. Nei passaggi precedenti, l'agente avrebbe dovuto compilare un binario del server, ma lo compiliamo di nuovo con un nome diverso in modo che non venga interessato quando modifichiamo il codice sorgente:

mkdir -p bin && go build -o ./bin/godoctor ./cmd/server

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 l'editor di Cloud Shell o il tuo IDE preferito.

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

7. Avviare Gemini CLI con il comando gemini
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 "Mostrami la documentazione del pacchetto net/http".

Il risultato dovrebbe essere simile a questo:

Nota:se il modello tenta di leggere la documentazione utilizzando run_shell_command, annulla e reindirizzalo all'utilizzo dello strumento che abbiamo appena sviluppato.

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 rendere questo server un po' più utile.

7. Aggiunta di un revisore del codice basato sull'AI

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

Ora puoi ripristinare la sessione di chat precedente con il comando /chat resume godoctor-workshop.. In questo modo, il contesto della sessione verrà caricato fino al punto in cui abbiamo terminato lo sviluppo di read_docs, quindi il modello avrà le conoscenze necessarie per creare il nuovo strumento.

Questo strumento dovrà accedere a Vertex AI, quindi dobbiamo prima abilitare l'API. Puoi eseguire comandi shell senza uscire da Gemini CLI digitando un punto esclamativo (!) in un prompt vuoto. In questo modo, l'interfaccia a riga di comando Gemini passerà alla modalità shell.

Esegui questo comando in modalità shell per abilitare l'API Vertex AI:

gcloud services enable aiplatform.googleapis.com

Una volta completato il comando, puoi tornare alla modalità Prompt digitando il tasto Esc.

Importante:l'SDK go-genai utilizzerà le variabili di ambiente che abbiamo definito nel passaggio di configurazione di questo workshop: GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION.. In caso di problemi, verifica che queste variabili siano definite correttamente nel tuo ambiente.

Non puoi modificare le variabili di ambiente dalla modalità shell di Gemini CLI (le modifiche non verranno mantenute), quindi dovrai uscire dalla CLI, definire le variabili e riavviarla.

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:

Add a new tool to my project called code_review. This tool should use the Gemini API on Vertex AI (with model id gemini-2.5-pro) to analyze Go code and provide a list of improvements 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".

The tool output should be text in Markdown format.

TODO:
- add the genai SDK dependency with `go get import google.golang.org/genai`
- create the tool code in ./internal/tools/code/review.go
- create a code review prompt to be used by the tool
- use go-genai with Vertex AI authentication to call gemini-2.5-pro
- register the tool with the server
- add a flag to the server to set the Google Cloud Project ID: --project
- add a flag to the server to set the Google Cloud Location: --location
- add support to the review tool in the client CLI

NOT TO DO:
- DO NOT use the package github.com/google/generative-ai-go/genai as it is DEPRECATED
- DO NOT use the package cloud.google.com/go/vertexai/genai as it has been superseded by google.golang.org/genai

Acceptance Criteria:
- `./bin/client --tools-list` show all tools including `code_review`
- `./bin/client --tool-call code_review internal/tools/code/review.go` returns the code review for the "review.go" file

Consigli utili

1. Una volta che il modello inizia a lavorarci, potresti notare automaticamente che richiede di chiamare lo strumento read_docs 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 read_docs.
2. Se vedi che tenta di utilizzare l'SDK GenAI sbagliato (anche se nel prompt è presente un elenco chiaro di "non consentito"), indirizzalo di nuovo su quello corretto.

Test del revisore del codice

1. Salva la sessione di chat con /chat save godoctor-workshop ed esci dalla CLI premendo due volte Ctrl+D.
2. Ricompila il server con la nuova definizione dello strumento:

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

3. Utilizzando il tuo IDE, aggiorna il file .gemini/settings.json per includere la configurazione dell'ambiente per Vertex AI:

{
  "mcpServers": {
    "godoctor": {
      "command": "./bin/godoctor",
      "env": {
        "GOOGLE_CLOUD_USE_VERTEXAI": "true",
        "GOOGLE_CLOUD_PROJECT": "<your-project-id>",
        "GOOGLE_CLOUD_LOCATION": "<your-preferred-region>"
      }
    }
  }
}

4. Avvia di nuovo Gemini CLI. Ripristina la sessione di chat con /chat resume godoctor-workshop
5. Verifica che lo strumento sia abilitato digitando il comando /mcp. Il risultato dovrebbe essere simile a questo:

6. Ora testiamo lo strumento code_review esaminando uno dei file di origine dello strumento:

Use the code_review tool to review cmd/server/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 godoctor-workshop 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 eseguire il deployment di 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 con 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 in streaming e Cloud Run come target 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 prepare it to be deployed to Cloud Run, so we need to add support to use the Streamable HTTP transport.

TODO:
- Update server to enable Streamable HTTP via the -http flag.
- An optional -listen flag can be specified to set the port to listen
- If no -http flag is specified, the server defaults to stdio transport and -listen is ignored
- Update client to use Streamable HTTP via the -addr flag
- If no flag is specified, the client defaults to command transport
- Create a shell script test_server.sh to support testing

NOT TO DO:
- DO NOT use the HTTP+SSE protocol as it has been deprecated by the MCP specification

Acceptance Criteria
- Create a shell script that:
  - Runs the server in the background;
  - Runs the client connecting over HTTP and call list tools
  - Kills the background process
- The shell script should run without failures

Consigli utili

1. Il modello potrebbe provare a utilizzare HTTP+SSE, che è stato ritirato. Se vedi che segue questo percorso, riportalo verso HTTP riproducibile in streaming.
2. La versione attuale di Gemini CLI (0.26.0) non supporta l'esecuzione di processi in background (qualsiasi processo avviato con run_shell_command viene interrotto al termine della chiamata allo strumento), pertanto chiediamo a Gemini di automatizzare la procedura di test utilizzando uno script. Questa funzionalità è pianificata e verrà aggiunta a breve, il che può semplificare il processo di test.

(Facoltativo) Test del server MCP tramite HTTP

Se vuoi configurare Gemini CLI in modo che utilizzi 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 rimandi al server locale in esecuzione.

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

3. In un secondo terminale, esegui il server abilitato per HTTP in locale:

go build -o ./bin/godoctor ./cmd/server && ./bin/godoctor -listen=:8080

4. Riavvia 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.25.6-alpine. The image should support the following environment variables:
- GOOGLE_CLOUD_USE_VERTEXAI
- GOOGLE_CLOUD_PROJECT
- GOOGLE_CLOUD_LOCATION

Acceptance Criteria:
- The image builds successfully
- Create a script test_docker.sh to launch the docker image in background and test the connectivity with the client:
    - Call list_tools on the client pointing to the server running on Docker
    - Call read_docs for fmt.Println
    - Stop the server
- The script should run without failures

(Facoltativo) Testare manualmente l'immagine Docker

Dopo aver creato Dockerfile, crea l'immagine ed eseguila per assicurarti che funzioni correttamente.

1. Crea il container:

docker build -t godoctor:latest .

2. Esegui il container in locale:

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.

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 following environment variables:
- GOOGLE_CLOUD_USE_VERTEXAI: true,
- GOOGLE_CLOUD_PROJECT: <your-project-id>
- GOOGLE_CLOUD_LOCATION: <your-preferred-region>

TODO:
- Run `docker build -t gcr.io/daniela-genai-sandbox/godoctor .`
- Run `gcloud run deploy godoctor --image` with the image created above

Acceptance Criteria:
- Call list-tools with the client pointing to the CloudRun endpoint

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 se vuoi conservare il contesto). Ora la CLI dovrebbe essere in grado di chiamare il server MCP remoto. Prova a chiedere la documentazione per qualsiasi pacchetto.

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 esercitato 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

• Blog dell'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