Gemini CLI ve Go ile MCP Sunucusu Oluşturma

1. Giriş

Bu codelab'de, Gemini CLI'ın özelliklerini genişletmek için Model Context Protocol (MCP) sunucusu oluşturmayı ve dağıtmayı öğreneceksiniz. Bu laboratuvarda, Gemini CLI'yı genel amaçlı bir kodlama asistanından özel bir Go geliştirme uzmanına dönüştürerek Go geliştirme için özel araçlar sağlayan Go tabanlı bir sunucu olan godoctor'u oluşturacaksınız.

Bu codelab'de "istem odaklı" bir yaklaşım kullanılıyor. Teknik yönetici olarak hareket edecek ve yapay zeka asistanınıza (Gemini CLI) istemler sağlayacaksınız. Amacınız, proje gereksinimlerini etkili istemlere dönüştürmeyi öğrenmek ve uygulama ayrıntılarını yapay zekanın halletmesini sağlamak.

Bu projenin merkezinde Model Context Protocol (MCP) yer alır. MCP, Gemini gibi büyük dil modellerinin (LLM'ler) harici araçlar ve hizmetlerle nasıl iletişim kurduğunu standartlaştıran açık kaynaklı bir protokoldür. Bu araç, yapay zekanın gerçek dünyadaki bilgilere erişmesine ve yerleşik bilgilerinin ötesinde işlemler gerçekleştirmesine olanak tanıyan bir köprü görevi görür. MCP sunucusu oluşturarak Gemini CLI'nin keşfedip kullanabileceği özel bir eklenti oluşturursunuz. Bu eklenti, Gemini CLI'ye yeni beceriler öğretir.

Neler öğreneceksiniz?

• Gemini CLI'yı yükleme ve yapılandırma
• Yapay zeka asistanını yazılım geliştirmede yönlendirmek için etkili istemler oluşturma
• Yapay zeka asistanına bağlam ve yönergeler sağlama
• Gemini CLI özelliklerini artırmak için MCP sunucusu oluşturma ve yapılandırma
• Go uygulamasını container'a dönüştürme ve Google Cloud Run'a dağıtma

İhtiyacınız olanlar

Bu atölye çalışması, gerekli tüm bağımlılıklar (gcloud CLI, Go, Docker, Gemini CLI) önceden yüklenmiş olarak gelen Google Cloud Shell'de tamamen yapılabilir.

Alternatif olarak, kendi makinenizde çalışmayı tercih ederseniz aşağıdakilere ihtiyacınız olacaktır:

• Node.js 20 veya sonraki sürümler
• Google Cloud SDK'nın (gcloud KSA) yüklü ve başlatılmış olması
• Sisteminizde Go 1.24 veya sonraki bir sürümün yüklü olması gerekir.
• Sisteminizde Docker yüklü olmalıdır.

Önemli Teknolojiler

Kullanacağımız teknolojiler hakkında daha fazla bilgiyi burada bulabilirsiniz:

• Gemini CLI: Geliştireceğimiz yapay zeka destekli komut satırı arayüzü
• Model Context Protocol (MCP): Gemini CLI'nın özel aracımızla iletişim kurmasına olanak tanıyan açık kaynaklı protokol
• MCP için Go SDK'sı: MCP sunucumuzu uygulamak için kullanacağımız Go kitaplığı

Başarılı bir Codelab için ipuçları

Yapay zeka asistanıyla çalışmak, yazılım geliştirmenin yeni bir yoludur. Deneyiminizi sorunsuz ve başarılı hale getirmek için aşağıdaki ipuçlarından yararlanabilirsiniz:

1. ESC tuşuna basmaktan çekinmeyin. Yapay zeka bazen kabul etmediğiniz eylemler veya kodlar önerebilir. ESC tuşunu kullanarak önerilen işlemi iptal edin ve doğru yönde ilerlemesi için yeni bir istem girin. Pilot sizsiniz.
2. Araç kullanımını teşvik edin. Yapay zeka kaybolmuş gibi görünüyorsa veya bilgi uyduruyorsa mevcut araçlarını kullanmaya teşvik edin. "Bunu doğrulamak için Google Arama'yı kullanabilir misin?" veya "Değişiklik yapmadan önce mevcut kodu anlamak için read_file aracını kullan" gibi istemler çok etkili olabilir.
3. Manuel değişikliklere karşı koyun. Tüm işi yapay zekaya yaptırmaya çalışın. Bu, üzerinde çalıştığınız temel beceridir. Ancak manuel değişiklik yapmanız gerekiyorsa bunu yapmanızın ardından yapay zekaya bildirin. "README.md dosyasını manuel olarak güncelledim. Lütfen bilginizi tazelemek için tekrar okuyun." istemi, yapay zekanın projenizle senkronize kalmasını sağlar.
4. Kapatıp tekrar açmayı denediniz mi? Nadir durumlarda, yapay zeka komutunuza rağmen belirli bir yolu zorlamaya çalışabilir. Bunun nedeni, bağlam bozulması (bazen "bağlam çürümesi" olarak da adlandırılır) olabilir. Bu durumda, bağlam gürültüsünü azaltmak için Gemini CLI komutu "/compress"i kullanabilir veya uç durumlarda oturum geçmişinin tamamını temizlemek için "/clear" komutunu kullanabilirsiniz.

2. Ortam Kurulumu

Google Cloud kredileri için: Başlamanıza yardımcı olmak için bu bağlantıyı kullanarak ücretsiz Google Cloud kredilerinizi kullanın. Krediyi etkinleştirmek ve yeni bir proje oluşturmak için buradaki talimatları uygulayabilirsiniz.

Aşağıdaki seçeneklerden birini belirleyin: Bu

makinenizde çalıştırabilir veya bu codelab'i tamamen bulutta çalıştırmak istiyorsanız Cloud Shell'i başlatabilirsiniz.

Kendi hızınızda ortam kurulumu

1. Google Cloud Console'da oturum açın ve yeni bir proje oluşturun veya mevcut bir projeyi yeniden kullanın. Gmail veya Google Workspace hesabınız yoksa hesap oluşturmanız gerekir.

• Proje adı, bu projenin katılımcıları için görünen addır. Google API'leri tarafından kullanılmayan bir karakter dizesidir. Dilediğiniz zaman güncelleyebilirsiniz.
• Proje kimliği, tüm Google Cloud projelerinde benzersizdir ve sabittir (ayarlandıktan sonra değiştirilemez). Cloud Console, benzersiz bir dizeyi otomatik olarak oluşturur. Genellikle bu dizenin ne olduğuyla ilgilenmezsiniz. Çoğu codelab'de proje kimliğinize (genellikle PROJECT_ID olarak tanımlanır) başvurmanız gerekir. Oluşturulan kimliği beğenmezseniz başka bir rastgele kimlik oluşturabilirsiniz. Dilerseniz kendi adınızı deneyerek kullanılabilir olup olmadığını kontrol edebilirsiniz. Bu adım tamamlandıktan sonra değiştirilemez ve proje süresince geçerli kalır.
• Bazı API'lerin kullandığı üçüncü bir değer olan Proje Numarası da vardır. Bu üç değer hakkında daha fazla bilgiyi belgelerde bulabilirsiniz.

Dikkat: Proje kimliği genel olarak benzersizdir ve seçildikten sonra başka bir kullanıcı tarafından kullanılamaz. Bu kimliğin tek kullanıcısı sizsiniz. Proje silinse bile kimlik tekrar kullanılamaz.

Not: Gmail hesabı kullanıyorsanız varsayılan konumu Kuruluş yok olarak bırakabilirsiniz. Google Workspace hesabı kullanıyorsanız kuruluşunuz için uygun bir konum seçin.

2. Ardından, Cloud kaynaklarını/API'lerini kullanmak için Cloud Console'da faturalandırmayı etkinleştirmeniz gerekir. Bu codelab'i tamamlamak size çok fazla zaman kaybettirmez. Bu eğitimin ötesinde faturalandırılmayı önlemek için kaynakları kapatmak üzere oluşturduğunuz kaynakları veya projeyi silebilirsiniz. Yeni Google Cloud kullanıcıları 300 ABD doları değerinde ücretsiz deneme programından yararlanabilir.

Cloud Shell'i başlatma

Google Cloud, dizüstü bilgisayarınızdan uzaktan çalıştırılabilir. Ancak bu codelab'de, Cloud'da çalışan bir komut satırı ortamı olan Google Cloud Shell'i kullanacaksınız.

Google Cloud Console'da sağ üstteki araç çubuğunda Cloud Shell simgesini tıklayın:

Ortamın temel hazırlığı ve bağlanması yalnızca birkaç dakikanızı alır. İşlem tamamlandığında aşağıdakine benzer bir sonuç görürsünüz:

Bu sanal makine, ihtiyaç duyacağınız tüm geliştirme araçlarını içerir. 5 GB boyutunda kalıcı bir ana dizin sunar ve Google Cloud üzerinde çalışır. Bu sayede ağ performansı ve kimlik doğrulama önemli ölçüde güçlenir. Bu codelab'deki tüm çalışmalarınızı tarayıcıda yapabilirsiniz. Herhangi bir şey yüklemeniz gerekmez.

3. Gemini KSA'yı kullanmaya başlama

Bu bölümde, Gemini CLI'yı ortamınıza nasıl yükleyeceğiniz ve yapılandıracağınız da dahil olmak üzere Gemini CLI hakkında bilgi edineceksiniz.

Gemini CLI nedir?

Gemini CLI, çeşitli geliştirme görevlerinde size yardımcı olabilecek yapay zeka destekli bir komut satırı arayüzüdür. Projenizin bağlamını anlayabilir, soruları yanıtlayabilir, kod oluşturabilir ve yeteneklerini genişletmek için harici araçları kullanabilir.

Kurulum

Not: Google Cloud Shell kullanıyorsanız Gemini CLI zaten yüklüdür ve bir sonraki bölüme (Yapılandırma) geçebilirsiniz.

npm kullanarak Gemini CLI'yı genel olarak yükleyin.

npm install -g @google/gemini-cli

CLI'nın yüklendiğini doğrulamak için şu komutu çalıştırın:

gemini --version

Yapılandırma

Gemini CLI'nın davranışı, yapılandırma dosyaları ve ortam değişkenleri tarafından kontrol edilir. İki temel dosya vardır:

• GEMINI.md: Bu dosya, yapay zekaya yönergeler ve bağlam bilgisi sağlar. CLI, projenizin kodlama standartlarını ve kurallarını anlamak için bu dosyayı okur.
• .gemini/settings.json: Bu dosya, harici araçlara nasıl bağlanılacağı da dahil olmak üzere KSA'nın yapılandırmasını kontrol eder. Bu dosyayı daha sonra CLI'yı bu laboratuvarda oluşturduğumuz MCP sunucusunu kullanacak şekilde yapılandırmak için kullanacağız.

Önce ortamı ayarlayacağız, ardından GEMINI.md dosyasını oluşturacağız. settings.json dosyası sonraki bir adımda yapılandırılacaktır.

1. Proje dizini oluşturma ve başlatma:

mkdir godoctor && cd godoctor
go mod init godoctor

2. Google Cloud uygulama varsayılan kimlik bilgileriyle kimlik doğrulayın:

Not: Cloud Shell kullanıyorsanız kimlik doğrulama sizin için zaten yapılmıştır.

Bu codelab'de kullanacağınız GCP projesine erişimi olan bir hesaba giriş yapmanız gerekir:

• Google Cloud SDK'nın yüklendiğinden ve başlatıldığından emin olun.
• Uygulama Varsayılan Kimlik Bilgileri'ni ayarlamak için aşağıdaki komutu çalıştırın:

gcloud auth application-default login

4. Bağlam Dosyası (GEMINI.md)

Varsayılan adı GEMINI.md olan bağlam dosyaları, Gemini modeline talimat bağlamı sağlamak için kullanılır. Bu dosyaları kullanarak projeye özel talimatlar verebilir, bir karakter tanımlayabilir veya yapay zekanın yanıtlarını daha doğru ve ihtiyaçlarınıza göre uyarlanmış hale getirmek için kodlama stili kılavuzları sağlayabilirsiniz.

Yapay zeka asistanının yüksek kaliteli ve deyimsel Go kodu oluşturmasını sağlamak için Go geliştiricileriyle ilgili bazı yaygın en iyi uygulamaları içeren bir GEMINI.md dosyası yazacağız.

Amaç: Bu proje sırasında yapay zeka asistanı için kural grubu olarak kullanılacak bir GEMINI.md dosyası oluşturun.

Aşağıdaki içeriğe sahip GEMINI.md dosyasını oluşturmak için IDE'nizi açın. Cloud Shell kullanıyorsanız aşağıdaki komutu kullanarak bir düzenleyici açabilirsiniz:

cloudshell edit .

Görev: godoctor dizininizin kök dizininde GEMINI.md adlı bir dosya oluşturun ve aşağıdaki içeriği bu dosyaya yapıştırın.

# 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

Geliştirme ortamınız artık tamamen kuruldu.

5. İlk Derleme: Dokümantasyon Sunucusu

İlk hedefiniz, godoctor sunucusunun ilk sürümünü oluşturmaktır. Bu sürüm, Go dokümanlarına bakma olanağı sağlayan read_docs adlı tek bir araç sunan minimal bir uygulama olmalıdır.

Amaç: go doc komutunu kullanıma sunan, üretime hazır bir MCP sunucusu oluşturmak. Bu sayede bir LLM, Go belgelerini sorgulayabilir.

Kabukta Gemini CLI komutunu çalıştırın:

gemini

Önemli: Gemini CLI'yı Cloud Shell'e yüklemeniz veya güncellemeniz gerekiyorsa şu komutu kullanabilirsiniz: sudo env PATH=$PATH npm install -g @google/gemini-cli

CLI'yı ilk kez çalıştırdığınızda bir kimlik doğrulama modu ve tema seçmeniz istenir.

Bu codelab'i Cloud Shell'de çalıştırıyorsanız Use Cloud Shell user credentials (Cloud Shell kullanıcı kimlik bilgilerini kullan) seçeneğini belirleyin. Aksi takdirde, kişisel bir Google Hesabı ile oturum açmak için Google ile giriş yap'ı kullanabilirsiniz. Böylece Gemini CLI'ın cömert ücretsiz katmanından yararlanabilirsiniz. Kimlik doğrulama seçimi ekranı aşağıdaki gibi görünür:

Seçiminizi değiştirmeniz gerekirse /auth yazıp Enter tuşuna basarak bu menüyü tekrar açabilirsiniz.

Ardından bir tema seçmeniz istenir:

/auth parametresine benzer şekilde, temayı daha sonra /theme komutuyla da değiştirebilirsiniz.

Kimlik doğrulama yöntemini ve tercih ettiğiniz temayı seçtikten sonra komut istemine yönlendirilirsiniz. Burada komutlarınızı yazabilirsiniz. Örneğin:

Write a hello world application in Go

KSA, görevleri gerçekleştirmek için kendi muhakemesinin (Gemini Flash veya Gemini Pro gibi bir Gemini modeli aracılığıyla) ve araçların bir kombinasyonunu kullanır. Dosya sistemi veya API'ler, veritabanları gibi harici hizmetlerle etkileşim kurması gerektiğinde araçları kullanır. Kullanıma hazır olarak sunulan veya "dahili araçlar" olarak adlandırılan araçlara örnek olarak read_file, write_file, web_fetch ve google_search verilebilir. Geliştirdiğimiz MCP sunucusu da KSA'da kullanılabilecek bir araç haline gelecek.

Araç ilk kez çalıştırıldığında izniniz istenir. İsteğe tek seferlik izin verebilir (bir kez izin ver), oturumun geri kalanı için genel onay verebilir (her zaman izin ver) veya isteği reddedebilirsiniz. Dosya düzenleme işlemiyse bazı düzenlemeler yapmak istemeniz ihtimaline karşı dosyayı harici bir düzenleyici kullanarak düzenleme seçeneğini de görürsünüz. Örneğin, yukarıdaki istemin çıktısı, "Hello World" programı oluşturmak için şu şekildedir:

İstemlerin yanı sıra eğik çizgiyle başlayan komutları da kullanabilirsiniz. "/" yazarsanız CLI, otomatik tamamlama seçeneklerini otomatik olarak gösterir. Komutun tamamını yazmaya devam edebilir veya seçeneklerden birini belirleyebilirsiniz. Yukarıda bahsedilen /auth ve /theme komutları bu tür komutlardan birkaçıdır.

Arayüze alıştıktan sonra bu bölümün asıl görevi olan KSA'dan MCP sunucusunu bizim için yazmasını istemeye başlayabilirsiniz.

Hello World MCP sunucusu oluşturma

Modelin daha tutarlı bir şekilde içerik oluşturmasını sağlamanın en iyi yollarından biri, karmaşık görevleri artımlı adımlara ayırmaktır. Model, karmaşık bir görevi kendi başına çözebilse de doğru kurulum olmadan doğru uygulamayı bulması uzun zaman alır.

Daha tutarlı bir yaklaşım için, istediğimiz işlevi (Go dokümanlarını okuma) uygulamadan önce "Hello World" MCP sunucusu oluşturmasını isteyeceğiz.

Örnek bir istem aşağıda gösterilmektedir:

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!"

Yukarıdaki istemin üç ana segmentten oluştuğunu unutmayın:

1. Ne oluşturmak istediğimiz ve kısıtlamalar (ör. herhangi bir SDK yerine resmi SDK'yı, http yerine stdio aktarımını kullanma) dahil olmak üzere sorun spesifikasyonu
2. Yapılacak görevlerin (yapılacaklar) dökümü
3. Görev için kabul ölçütleri (temsilcinin görevin tamamlandığını bilmesi için test prosedürü olarak kullanılır)

Bu üç bileşenin bulunması, modelin istenen sonuçları daha tutarlı bir şekilde elde etmesine yardımcı olur.

Dikkat: Talimatlarımızda çok hassas davransak da model bazen yapmasını istediğimiz şeyden sapabilir. Bu nedenle, modelin çalışmasını doğrulamanız ve olası hata döngüleri ile halüsinasyonlara karşı dikkatli olmanız önemlidir. Model takılırsa lütfen bu bölümün sonundaki Faydalı İpuçları bölümünü inceleyin.

read_docs aracının uygulanması

Not: Aşağıdaki istem, standart kitaplığı kullanarak dokümanları alma kodu önemsiz olmadığı ve modelin bunu kendi başına anlaması biraz zaman alabileceği için modeli go doc kabuk komutunu kullanmaya açıkça teşvik eder. Yerleşik go doc derleyici aracını kullanmak çok zaman kazandırır ve MCP uygulamasını yapma gibi önemli konulara odaklanmamıza yardımcı olur.

Çalışan bir uygulama oluşturduktan sonra gerçek "read_docs" aracını uygulamaya geçebiliriz:

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

Not: Bu istemle denemeler yapabilir veya kendi isteminizi oluşturabilirsiniz.

Faydalı İpuçları

Not: LLM'lerle kodlama, deterministik olmayan bir deneyimdir. Bu nedenle, aynı ortamda iki özdeş istem çalıştırsanız bile her zaman tam olarak aynı sonuçları alacağınız garanti edilmez. Bu nedenle, LLM'nin döngüye takıldığını veya bağlamının bozulduğunu nasıl belirleyeceğinizi öğrenmeniz önemlidir. Kontrolün sizde olduğunu ve ESC tuşuna basarak istediğiniz zaman işlemi durdurabileceğinizi unutmayın.

MCP hâlâ yeni bir kavram olduğundan ve MCP için Go SDK'sı yeni bir kitaplık olduğundan bu adımda Gemini'ın doğru uygulamayı kendi başına keşfetmesi uzun zaman alabilir. Modelin doğru çözümü bulmasına yardımcı olmak için aşağıdakileri deneyebilirsiniz:

1. Model herhangi bir adımda dokümanları okumayı atladıysa ESC tuşuna basın ve dokümanları okumasını hatırlatın. Go'yu bilmiyorsanız "go doc" komutunu paket adıyla birlikte çalıştırmak ("go doc github.com/modelcontextprotocol/go-sdk/mcp") doğru dokümanı döndürür.
2. En üst düzey modül olan " github.com/modelcontextprotocol/go-sdk" herhangi bir dokümana sahip değil (Go kodu olmadığı için). Modele, tam yolu aramasını söylemeniz gerekiyor.
3. Bunun aksine, model var olmayan bir paket halüsinasyonu yaparsa (ör. "go doc github.com/modelcontextprotocol/go-sdk/mcp/server" yazarak yalnızca üst düzey pakete yönlendirin.

6. Gemini CLI için godoctor'u MCP sunucusu olarak yapılandırma

Yapay zeka asistanı hem istemci hem de sunucu için kodu oluşturduktan sonra, birkaç manuel test çalıştırmasını isteyebilirsiniz. Örneğin:

retrieve the documentation for the package net/http

Ayrıca, standart kitaplıkta olmayan harici bir bağımlılıkla da test ettiğinizden emin olun:

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

Sonuçlardan memnun kaldığınızda, bu projenin nasıl kullanılacağı ve geliştirileceğiyle ilgili talimatları içeren bir README.md dosyası yazmasını isteyin.

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

Şimdi sunucuyu, Gemini CLI'nın geliştirmenin bir sonraki aşamasında kullanabilmesi için yapılandıracağız.

1. CLI'dan, dokümanları okumak için tercih edilen yöntem olarak read_docs kullanılacak şekilde GEMINI.md dosyasını güncellemesini isteyin:

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. Şimdi MCP sunucusunu yapılandırmak için Gemini CLI'yı yeniden başlatmamız gerekiyor. Öncelikle, sohbet oturumunu kaydedelim. Böylece yeniden başlatıldıktan sonra kaldığınız yerden devam edebilirsiniz.

/chat save godoctor-workshop

3. Ctrl+D tuşlarına iki kez basarak veya /quit komutunu yazarak CLI'dan çıkın.
4. Önceki adımlarda aracı sizin için bir sunucu ikilisi derlemiş olmalıdır ancak kaynak kodunu değiştirdiğimizde etkilenmemesi için sunucuyu farklı bir adla tekrar derliyoruz:

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

5. Gemini CLI'yı yerel araç için yapılandırın: Projenizin kök dizininde bir .gemini/settings.json dosyası oluşturun ve derlenmiş sunucunuzu nasıl çalıştıracağını Gemini CLI'ya bildirmek için mcpServers bölümü ekleyin.

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

6. Şimdi, Cloud Shell Düzenleyici'yi veya en sevdiğiniz IDE'yi kullanarak yeni dosyaya aşağıdaki içeriği ekleyin.

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

7. gemini komutuyla Gemini CLI'yi başlatın
8. /mcp komutunu yazarak aracın yüklendiğini görebilirsiniz. /mcp desc simgesini kullanarak araçların tam açıklamasını da gösterebilirsiniz:

9. "Show me the documentation for the package net/http" (net/http paketiyle ilgili dokümanları göster) gibi bir istemle Gemini CLI'dan aracınızı kullanmasını isteyerek entegrasyonu test edin.

Aşağıdakine benzer bir tablo görürsünüz:

Not: Model, run_shell_command kullanarak dokümanları okumaya çalışırsa işlemi iptal edin ve modeli yeni geliştirdiğimiz aracı kullanmaya yönlendirin.

Araç düzgün çalışıyorsa araç çağrısı aracılığıyla alınan dokümanları görmeniz gerekir:

Tebrikler, bir MCP aracı oluşturdunuz. Ancak bu son değil. Bu sunucuyu biraz daha kullanışlı hale getirebiliriz.

7. Yapay zeka destekli kod incelemecisi ekleme

Şimdi daha gelişmiş, yapay zeka destekli bir özellik ekleyelim: Gemini API'yi kullanan bir kod inceleme aracı.

Artık /chat resume godoctor-workshop. komutuyla önceki sohbet oturumunu geri yükleyebilirsiniz. Bu işlem, oturum bağlamını read_docs geliştirme işlemini tamamladığımız noktaya kadar yükler. Böylece model, yeni aracı oluşturmak için gereken bilgiye sahip olur.

Bu aracın Vertex AI'ye erişmesi gerekeceğinden önce API'yi etkinleştirmemiz gerekir. Boş bir isteme ünlem işareti (!) yazarak Gemini CLI'dan ayrılmadan kabuk komutları çalıştırabilirsiniz. Bu işlem, Gemini CLI'yı kabuk moduna geçirir.

Vertex AI API'yi etkinleştirmek için kabuk modunda aşağıdaki komutu çalıştırın:

gcloud services enable aiplatform.googleapis.com

Komut tamamlandıktan sonra Escape tuşuna (Esc) basarak tekrar istem moduna geçebilirsiniz.

Önemli: go-genai SDK'sı, bu atölyenin kurulum adımında tanımladığımız ortam değişkenlerini kullanır: GOOGLE_GENAI_USE_VERTEXAI, GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION. Herhangi bir sorun yaşarsanız bu değişkenlerin ortamınızda doğru şekilde tanımlandığını kontrol edin.

Ortam değişkenlerini Gemini CLI kabuk modunda değiştiremezsiniz (değişiklikler kalıcı olmaz). Bu nedenle, CLI'dan çıkmanız, değişkenleri tanımlamanız ve CLI'yı tekrar başlatmanız gerekir.

Hedef: Mevcut projeye code_review adlı yeni bir araç ekleyin. Bu araç, Go kodunu analiz etmek ve geri bildirim sağlamak için Gemini API'yi kullanır.

Örnek İstem:

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

Faydalı İpuçları

1. Model üzerinde çalışmaya başladığında, read_docs paketinin dokümanlarına göz atmak için read_docs aracını çağırmak istediğini otomatik olarak görebilirsiniz.genai Aksi takdirde, işlemi her zaman Escape tuşuyla kesebilir ve artık read_docs aracını kullanabileceğini hatırlatabilirsiniz.
2. İstemde açık bir "izin verilmez" listesi olmasına rağmen yanlış üretken yapay zeka SDK'sını kullanmaya çalıştığını görürseniz doğru SDK'ya yönlendirin.

Kod İnceleyici'yi test etme

1. Sohbet oturumunu /chat save godoctor-workshop ile kaydedin ve ardından Ctrl+D tuşlarına iki kez basarak CLI'dan çıkın.
2. Sunucuyu yeni araç tanımıyla yeniden derleyin:

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

3. IDE'nizi kullanarak .gemini/settings.json dosyasını Vertex AI için ortam yapılandırmasını içerecek şekilde güncelleyin:

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

4. Gemini CLI'yı tekrar başlatın. /chat resume godoctor-workshop ile sohbet oturumunu geri yükleme
5. /mcp komutunu yazarak aracın etkinleştirildiğini onaylayın. Aşağıdakine benzer bir tablo görürsünüz:

6. Şimdi de aracın kaynak dosyalarından birini inceleyerek code_review aracını test edelim:

Use the code_review tool to review cmd/server/main.go

    You should see something like this:

Kod inceleme aracı çalışırken artık modele, bulduğu iyileştirmelerden bazılarını uygulamasını önerebilirsiniz. Böylece, tam bir "kendini geliştirme" iş akışı elde edebilirsiniz.

code-review aracının çalıştığını onaylamış oldunuz. Sonraki bölümde, bu işlevi buluta dağıtma üzerinde çalışacaksınız. /chat save godoctor-workshop ile mevcut oturumunuzu kaydedin ve CLI'dan çıkın.

8. Sunucunuzu buluta hazırlama

Şimdiye kadar geliştirdiğimiz MCP sunucusu yalnızca yerel makinede çalışır. Bu, kendi kullanımınız için araçlar geliştiriyorsanız sorun olmaz ancak kurumsal ortamlarda genellikle yüzlerce hatta binlerce geliştiricinin daha geniş kullanımı için araçlar dağıtmamız gerekir.

MCP sunucumuzu ölçeklendirmek için bu sunucuyu yalnızca standart G/Ç ile iletişim kuran bir sunucudan HTTP ile iletişim kurabilen bir sunucuya dönüştürmemiz ve farklı geliştiricilerin erişebileceği bir yere dağıtmamız gerekiyor. Bu amaçla, MCP spesifikasyonunda akışa uygun HTTP olarak tanımlanan bir aktarım modu kullanacağız ve dağıtım hedefimiz olarak Cloud Run'ı kullanacağız.

Hedef: godoctor sunucusunu, akışa alınabilir HTTP aktarımını kullanacak şekilde yeniden düzenleyin.

Örnek İstem:

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

Faydalı İpuçları

1. Model, bunun yerine HTTP+SSE'yi kullanmaya çalışabilir. Bu özellik kullanımdan kaldırılmıştır. Bu yolu izlediğini görürseniz akışa uygun HTTP'ye yönlendirin.
2. Gemini CLI'nin mevcut sürümü (0.26.0) işlemlerin arka planda çalıştırılmasını desteklemez (run_shell_command ile başlatılan tüm işlemler, araç çağrısı döndüğünde sonlandırılır). Bu nedenle, Gemini'dan bir komut dosyası kullanarak test sürecini otomatikleştirmesini istiyoruz. Bu özellik planlanmaktadır ve yakın gelecekte eklenerek test sürecini basitleştirebilir.

İsteğe bağlı: HTTP kullanarak MCP sunucusunu test etme

Gemini CLI'yı HTTP üzerinden sunucuyu kullanacak şekilde yapılandırmak istiyorsanız:

1. Oturumunuzu kaydedin ve CLI'dan çıkın
2. .gemini/settings.json dosyanızı düzenleyin ve yapılandırmayı yerel olarak çalışan sunucunuza yönlendirecek şekilde değiştirin.

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

3. İkinci bir terminalde, HTTP'nin etkinleştirildiği sunucuyu yerel olarak çalıştırın:

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

4. Gemini CLI'yı yeniden başlatın ve bağlantıyı test etmek için bir istem girin (ör. "fmt.Println ile ilgili dokümanları almak için godoctor aracını kullan."
5. Testi tamamladığınızda Ctrl+C tuşlarına basarak sunucuyu durdurun.

9. Uygulamayı Docker ile kapsülleme

Sunucumuz artık doğru aktarım protokolünü kullandığına göre dağıtım için kapsayabiliriz.

Amaç: godoctor sunucusunu taşınabilir ve üretime hazır bir container görüntüsüne paketlemek için bir Dockerfile oluşturun.

Örnek İstem:

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

İsteğe bağlı: Docker görüntüsünü manuel olarak test etme

Dockerfile oluşturulduktan sonra, doğru çalıştığından emin olmak için görüntüyü oluşturun ve çalıştırın.

1. Container'ı oluşturun:

docker build -t godoctor:latest .

2. Kapsayıcıyı yerel olarak çalıştırma:

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

3. Çalışan kapsayıcıyı test edin: Başka bir terminalde Gemini CLI'yı başlatın ve dokümanları getirmesini isteyin.
4. Testi tamamladığınızda Ctrl+C tuşlarına basarak sunucuyu durdurun.

10. Cloud Run'a dağıtma

Şimdi de kapsayıcımızı buluta dağıtma zamanı.

Amaç: Container'a alınmış godoctor sunucusunu Google Cloud Run'a dağıtın.

Örnek İstem:

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

Dikkat: Bu projede Cloud Run'ı ilk kez kullanıyorsanız Artifact Registry ve Cloud Run API'lerini etkinleştirmeniz istenir.

Dağıtım tamamlandıktan sonra Gemini CLI'yı, yeni dağıttığınız aracı kullanacak şekilde yapılandırırız.

MCP aracı yapılandırmasını dağıtılan hizmetinize işaret edecek şekilde değiştirmek için .gemini/settings.json dosyanızı güncelleyin veya Gemini CLI'dan bunu sizin için yapmasını isteyin:

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

Son mcpServers bölümü aşağıdaki gibi görünmelidir (yer tutucuyu gerçek Cloud Run uygulamanızın URL'siyle değiştirmeyi unutmayın):

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

Cloud Run dağıtımını test etme

Artık son uçtan uca teste hazırsınız.

Gemini CLI'yı son bir kez daha yeniden başlatın (bağlamınızı korumak istiyorsanız /chat save ve /chat resume komutlarını kullanın). Artık CLI, uzak MCP sunucusunu çağırabilir. Paketlerle ilgili doküman isteyin.

Kod inceleme aracını da test edebilirsiniz:

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

Temizleme

Dikkat: Bu oturumu sonlandırmadan önce Cloud Run dağıtımını sildiğinizden emin olun. Özellikle GCP faturalandırma hesabınızda beklenmedik ücretler oluşmasını önlemek için kimliği doğrulanmamış bir Cloud Run örneği kullanıyorsanız bu adımı atlamayın.

Testi tamamladığınızda ortamı temizlemeyi unutmayın. Gemini'a projenizi silmesini veya yalnızca CloudRun dağıtımını kaldırmasını söyleyebilirsiniz. Örnek istem:

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. Tebrikler!

Bir yapay zeka asistanına, gelişmiş ve yapay zeka destekli bir araç oluşturma, kapsülleme ve dağıtma konusunda başarıyla rehberlik ettiniz. Daha da önemlisi, modern yazılım geliştirmenin temel becerisi olan gereksinimleri etkili istemlere dönüştürme konusunda pratik yaptınız. Gemini CLI'ı özel bir MCP aracıyla başarıyla genişlettiniz. Böylece, daha güçlü ve uzmanlaşmış bir Go geliştirme asistanı elde ettiniz.

Referans belgeleri

• Gemini CLI duyuru blogu
• Gemini CLI ana sayfası
• Gemini CLI belgeleri
• Model Context Protocol spesifikasyonu
• MCP için Go SDK'sı
• Google Gen AI Go SDK'sı