mcp-gopls – Go için MCP sunucusu (gopls)

AI asistanlarının Go'nun LSP'sini (gopls) navigasyon, tanılamalar, testler, kapsama analizi ve daha fazlası için kullanmasına olanak tanıyan bir Model Context Protocol (MCP) sunucusu.

Özet: Claude / Cursor / Copilot'u Go ile kullanıyorsanız, mcp-gopls yapay zekaya tam LSP güçleri sağlar: tanıma gitme, referanslar, hover, tamamlama, go test, kapsama analizi, go mod tidy, govulncheck, vb.

Genel Bakış

Bu MCP sunucusu yapay zeka asistanlarına yardımcı olur:

• Go çalışma alanlarını analiz etmek için LSP kullanımı
• Tanımlara, referanslara ve çalışma alanı sembollerine gitme
• MCP'den çıkmadan kodu biçimlendirme, yeniden adlandırma ve kod eylemlerini inceleme
• Go testlerini, kapsama analizi, go mod tidy, govulncheck ve modül grafik komutlarını yapılandırılmış sonuçlarla çalıştırma
• Çalışma alanı kaynakları (genel bakış + go.mod) okuma ve küratörlü komut istemi kullanma

Durum: Aktif olarak geliştiriliyor – gerçek projelerde kullanılıyor.
Go 1.25.x ve gopls@latest ile test edilmiştir.

Mimari

Bu proje, Model Context Protocol'ü uygulamak için mark3labs/mcp-go kütüphanesini kullanır. MCP entegrasyonu, yapay zeka asistanları ile Go araçları arasında sorunsuz iletişim sağlar.

Sunucu, Language Server Protocol (LSP) aracılığıyla Go'nun resmi dil sunucusu olan gopls ile iletişim kurar.

Özellikler

• Yapılandırılabilir çalışma zamanı: --workspace, --gopls-path, --log-level, --rpc-timeout ve --shutdown-timeout bayrakları + ortam değişkenleri (MCP_GOPLS_*)
• Yapılandırılmış günlüğe kaydetme: slog ile metin/JSON günlüğü ve isteğe bağlı dosya çıktısı
• Genişletilmiş LSP yüzeyi: navigasyon, tanılamalar, biçimlendirme, yeniden adlandırma, kod eylemleri, hover, tamamlama, çalışma alanı sembolleri
• Test ve araç yardımcıları: kapsama analizi, go test, go mod tidy, govulncheck, go mod graph
• MCP ekstraları: kaynaklar (resource://workspace/overview, resource://workspace/go.mod) ve komut istemleri (summarize_diagnostics, refactor_plan)
• İlerleme akışı: uzun süreli komutlar, istemcilerin durum güncellemelerini gösterebilmesi için notifications/progress olayları gönderir

Özellik karşılaştırması: mcp-gopls vs yerleşik gopls MCP

gopls v0.20.0 itibariyle, yerleşik MCP sunucusu şu araçları sunar: go_context, go_diagnostics, go_file_context, go_file_diagnostics, go_file_metadata, go_package_api, go_references, go_rename_symbol, go_search, go_symbol_references, go_workspace, go_vulncheck.

Özellik / Kapasite	mcp-gopls (bu proje)	Yerleşik gopls MCP
Tanıma gitme	Evet (go_to_definition aracı)	Hayır (araç listesinde yok)
Referansları bulma	Evet (find_references)	Evet (go_references, go_symbol_references)
Tanılamalar (dosya / çalışma alanı)	Evet (check_diagnostics)	Evet (go_diagnostics, go_file_diagnostics)
Hover bilgisi	Evet (get_hover_info)	Hayır (araç listesinde yok)
Tamamlama	Evet (get_completion)	Hayır (araç listesinde yok)
Biçimlendirme	Evet (format_document)	Hayır (araç listesinde yok)
Sembolü yeniden adlandırma	Evet (rename_symbol)	Evet (go_rename_symbol)
Kod eylemleri	Evet (list_code_actions)	Hayır (araç listesinde yok)
Çalışma alanı sembol araması	Evet (search_workspace_symbols)	Evet (go_search)
Paket / çalışma alanı API/bağlam araçları	Yok	Evet (go_package_api, go_file_context, go_file_metadata, go_workspace, go_context)
go test çalıştırma	Evet (run_go_test)	Testler çalıştırmak için MCP aracı yok
Kapsama analizi	Evet (analyze_coverage)	Kapsama analizi için MCP aracı yok
go mod tidy	Evet (run_go_mod_tidy)	go mod tidy için MCP aracı yok
govulncheck	Evet (run_govulncheck)	Evet (go_vulncheck)
Modül grafı (go mod graph)	Evet (module_graph)	Modül grafı için MCP aracı yok
Ekstra MCP kaynakları	Evet (resource://workspace/overview, resource://workspace/go.mod)	MCP kaynakları olarak belgelenmiş değil
Özel MCP komut istemleri	Evet (summarize_diagnostics, refactor_plan)	MCP komut istemü olarak gösterilmiyor (sadece model talimatları)
Sunucuyla gönderilen model talimatları	Özel mekanizma yok (README/dokularda belgelenen)	Evet: gopls mcp -instructions kullanım akışlarını yazdırır

Tam LSP benzeri düzenlemeler + MCP'den araç kullanımı istiyorsanız (tanım, hover, tamamlama, biçim, yeniden adlandırma, kod eylemleri, go test, kapsama analizi, go mod tidy, modül grafı), mcp-gopls kesinlikle daha zengindir.

Çoğunlukla salt okunur/içgözlemci araçlar istiyorsanız (tanılamalar, sembol araması, referanslar, paket API, çalışma alanı/dosya bağlamı, vulncheck) ve ek ikili dosya istemiyorsanız, yerleşik gopls MCP yeterlidir.

Not: Yerleşik gopls MCP sunucusu hala deneysel olarak işaretlenmiş olup, araç seti zamanla değişebilir. Bu karşılaştırma gopls v0.20.x itibariyle doğrudur.

Proje Yapısı

.
├── cmd
│   └── mcp-gopls        # Uygulama giriş noktası
├── pkg
│   ├── lsp             # gopls ile iletişim için LSP istemcisi
│   │   ├── client      # LSP istemci uygulaması
│   │   └── protocol    # LSP protokolü türleri ve özellikleri
│   ├── server          # MCP sunucusu
│   └── tools           # LSP özelliklerini sunan MCP araçları

Kurulum

go install github.com/hloiseau/mcp-gopls/v2/cmd/mcp-gopls@latest

Hızlı Başlangıç

1. Sunucuyu kurun:

go install github.com/hloiseau/mcp-gopls/v2/cmd/mcp-gopls@latest

2. $PATH'ta olduğunu doğrulayın:

mcp-gopls --help

3. Yapay zeka istemcinizi yapılandırın (Cursor, Claude Desktop veya GitHub Copilot için örneklere aşağıda bakın).

---

Docker / MCP Gateway

mcp-gopls'i bir konteyner içinde çalıştırmayı tercih ederseniz (Docker MCP Gateway veya diğer konteynerleştirilmiş kurulumlar için), resmi görüntüyü kullanın.

Docker çalıştırma

docker run --rm -i \
  -v /absolute/path/to/your/go/project:/workspace \
  ghcr.io/hloiseau/mcp-gopls:latest \
  --workspace /workspace

docker-mcp.yaml

docs/docker-mcp.yaml'ı kopyalayın, bind mount yolunu güncelleyin, ardından bu dizinden çalıştırın:

docker mcp gateway run

Araçlar kataloğu meta verileri

MCP kataloğu araç takımınız bir toolsUrl gerektiriyorsa, docs/tools.json'ı statik bir araç listesi olarak kullanın.

Ayrıntılı İstemci Kurulumu

Not: Tüm istemciler aynı komuta işaret eder:
mcp-gopls --workspace /absolute/path/to/your/go/project
Yapılandırma biçimi istemciye göre biraz farklılık gösterir, ancak ikili dosya ve argümanlar aynı kalır.

1. Cursor'dan Bağlanma

1. Ayarlar → MCP Sunucuları → JSON Düzenle seçeneğini açın.
2. mcp-gopls girişini ekleyin veya güncelleyin:

{
  "mcpServers": {
    "mcp-gopls": {
      "command": "mcp-gopls",
      "args": ["--workspace", "/absolute/path/to/your/go/project"],
      "env": {
        "MCP_GOPLS_LOG_LEVEL": "info"
      }
    }
  }
}

3. Cursor'un yeniden bağlanması için Geliştirici: Pencereyi Yeniden Yükle seçeneğini çalıştırın.
4. Cursor Chat içinde Araçlar çekmecesini açın ve mcp-gopls'i etkinleştirin.

2. Araçları Çağırma

Araç / Komut İstemi	Cursor Chat içindeki örnek istek
go_to_definition	"go_to_definition'ı pkg/server/server.go:42 üzerinde kullanın."
find_references	"Araçtan ServeStdio referanslarını talep edin."
check_diagnostics	"cmd/mcp-gopls/main.go için tanılamalar isteyin."
get_hover_info	"get_hover_info'ı pkg/tools/workspace.go:88 üzerinde çağırın."
get_completion	"pkg/server/server.go:55 konumunda tamamlamaları tetikleyin."
format_document	"Biçimlendiriciyi pkg/tools/refactor.go üzerinde çalıştırın."
rename_symbol	"clientFactory'i aracı kullanarak newClientFactory'e yeniden adlandırın."
list_code_actions	"pkg/server/server.go:80-90 aralığı için kod eylemlerini listeleyin."
search_workspace_symbols	"NewWorkspaceConfig için çalışma alanı sembollerini arayın."
analyze_coverage	"analyze_coverage'ı ./pkg/... üzerinde işlev başına istatistiklerle çalıştırın."
run_go_test	"run_go_test'i ./cmd/... üzerinde çalıştırın."
run_go_mod_tidy	"run_go_mod_tidy'i çalıştırarak go.mod'u senkronize edin."
run_govulncheck	"run_govulncheck'i çalıştırın ve bulguları akışla."
module_graph	"Bağımlılıkları incelemek için module_graph'ı çağırın."
summarize_diagnostics	"Son tanılamalar üzerinde summarize_diagnostics komut istemini kullanın."
refactor_plan	"refactor_plan'a tanılamalar JSON'ını vererek düzeltme planı yapın."

İstemci Kurulum Örnekleri

Claude Desktop (macOS, Windows, Linux)

1. mcp-gopls'i kurun ve $PATH'ta olduğundan emin olun.
2. claude_desktop_config.json'ı oluşturun veya düzenleyin.
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. Sunucu girişini ekleyin:

{
  "mcpServers": {
    "mcp-gopls": {
      "command": "mcp-gopls",
      "args": ["--workspace", "/absolute/path/to/your/go/project"],
      "env": {
        "MCP_GOPLS_LOG_LEVEL": "info"
      }
    }
  }
}

Claude Desktop'u yeniden başlatın, bir sohbet açın ve sunucuya mcp-gopls aracıyla bağlanmasını isteyin (sunucu tespit edildiğinde Claude bir "Araçlar" sekmesi gösterecektir). Tipik komut istemlerine "cmd/api/server.go için tanılamalar listele" veya "userService'i accountService'e yeniden adlandır" dahildir.

Cursor IDE

Cursor'da Ayarlar → MCP Sunucuları → JSON Düzenle seçeneğini açın (~/.cursor/config.json veya proje yerel geçersiz kılmasına yazar). Ekleyin:

{
  "mcpServers": {
    "mcp-gopls": {
      "command": "mcp-gopls",
      "args": ["--workspace", "/absolute/path/to/your/go/project"]
    }
  }
}

Cursor'u yeniden yükleyin (veya Geliştirici: Pencereyi Yeniden Yükle komutunu çalıştırın) ve sunucu "Araçlar" çekmecesi içinde görünecektir. Artık Cursor Chat'e "go test ./pkg/server kapsama analizi ile çalıştır" veya "pkg/tools/tests.go:42 için hover bilgisi göster" gibi şeyler sorabilirsiniz.

GitHub Copilot (Agent Modu)

GitHub Copilot'un Agent Modu, VS Code, JetBrains IDE'leri, Eclipse ve Xcode arasında yerel MCP sunucularıyla konuşabilir (dokümanlar). VS Code'da mcp-gopls'i bağlamak için:

1. GitHub Copilot'u güncelleyin (VS Code 1.99+ gerektirir), Agent Modu'na seçin.
2. Çalışma alanınızda .vscode/mcp.json oluşturun (veya Copilot "Yapılandırmayı Düzenle" iletişim kutusunda gösterilen genel dosyayı düzenleyin).
3. Ekleyin:

{
  "servers": {
    "mcp-gopls": {
      "type": "stdio",
      "command": "mcp-gopls",
      "args": ["--workspace", "/absolute/path/to/your/go/project"],
      "env": {
        "MCP_GOPLS_LOG_LEVEL": "warn"
      }
    }
  }
}

4. Agent Modunu yeniden yükleyin (kapat/aç), Copilot yeni aracı keşfetsin; sohbet "Araçlar" seçicisi artık her MCP eylemini (run_go_test, run_govulncheck vb.) gösterecektir. JetBrains ve diğer IDE'ler Copilot ayarları paneli aracılığıyla aynı JSON şemasını paylaşır.

MCP Inspector / CLI testi

Hızlı denetim testleri veya demolar için mark3labs/mcp-inspector kullanabilirsiniz:

npx -y @mark3labs/mcp-inspector \
  --command mcp-gopls \
  --args "--workspace" "/absolute/path/to/your/go/project"

Inspector, her aracı/kaynağı/komut istemini manuel olarak çağırmanıza olanak tanır; bu, sunucu yapılandırmasında bir AI asistana bağlamadan önce hata ayıklamak için kullanışlıdır.

MCP Araçları

Araç	Açıklama
go_to_definition	Sembolün tanımına git
find_references	Bir sembol için tüm referansları listele
check_diagnostics	Bir dosya için önbelleğe alınmış tanılamalar al
get_hover_info	Bir sembol için hover markdown'ı döndür
get_completion	Bir konumdaki tamamlama etiketlerini döndür
format_document	Tüm bir belge için biçimlendirme düzenlemeleri döndür
rename_symbol	Yeniden adlandırma için çalışma alanı düzenlemeleri döndür
list_code_actions	Bir aralık için mevcut kod eylemlerini listele
search_workspace_symbols	Çalışma alanında sembol ara
analyze_coverage	go test kapsama analizi + isteğe bağlı işlev başına rapor ile çalıştır
run_go_test	Bir paket/desen için go test yürüt
run_go_mod_tidy	go mod tidy yürüt
run_govulncheck	govulncheck ./... yürüt
module_graph	go mod graph çıktısını döndür

İlerleme Bildirimleri

Uzun süreli araçlar, IDE'lerin zengin durum göstergelerini gösterebilmesi için yapılandırılmış notifications/progress olayları gönderir:

• Akış ilerleme (run_go_test, analyze_coverage, run_govulncheck, run_go_mod_tidy) artımlı günlük satırları ve yüzde güncellemeleri iletir. Cursor bunları canlı günlük olarak gösterir.
• Sadece başlangıç/tamamlama olayları (go_to_definition, find_references, rename_symbol vb.) hızlı bir "başladı" olayı gönderir; böylece kullanıcı arabirimi bir spinner gösterebilir; ardından nihai sonucu içeren bir tamamlama yükü gelir.
• Her ilerleme tokeni artık ad alanına ayrılmıştır (ör. run_go_test/<rand>) çeşitli araçlar eşzamanlı çalışırken "bilinmeyen token" hatalarını önlemek için.

Yeni araçlar entegre ederken, yalnızca temel LSP/golang komutu anlamlı ara çıktı üretiyorsa akış modunu seçin; aksi takdirde gürültüyü en aza indirmek için hafif başlangıç/tamamlama akışına devam edin.

Komut İstemi Talimatları

Her iki komut istemi, "Komut İstemleri" kataloğu aracılığıyla herhangi bir MCP farkında olan istemciden erişilebilir.

summarize_diagnostics

• Ne zaman kullanılır: check_diagnostics veya run_go_test sonrası ham tanılamaları işlem yapılabilir adımlara dönüştürmek için.
• Argümanlar: Yok. Sunucu, araçlar katmanı tarafından önbelleğe alınan son tanılamalar yükünü otomatik olarak okur.
• Tipik iş akışı: check_diagnostics → döndürülen dizisini komut istemi giriş alanına kopyala (Cursor'un kullanıcı arabirimi, "Son sonucu kullan"ı seçtiğinizde otomatik olarak yapıştırır).

refactor_plan

• Ne zaman kullanılır: Zaten bir tanılamalar JSON diziniz var ve kısa bir değişiklik kontrol listesi istiyorsunuz.
• Argümanlar: Ham Go tanılamalarını içeren bir diagnostics nesnesi gerekir (check_diagnostics tarafından döndürülen aynı yük).
• Örnek çağırma yükü:

{
  "diagnostics": [
    {
      "uri": "file:///path/to/pkg/tools/workspace.go",
      "range": {"start": {"line": 12, "character": 5}, "end": {"line": 12, "character": 25}},
      "severity": 1,
      "message": "unused variable testHelper"
    }
  ]
}

Komut istemi, numaralandırılmış düzeltme adımları artı önerilen doğrulama komutları (go test, analyze_coverage vb.) ile yanıt verir.

Yapılandırma

Sunucu, komut satırı bayrakları ve ortam değişkenleri aracılığıyla çeşitli yapılandırma seçeneklerini destekler:

Komut Satırı Bayrakları

Bayrak	Varsayılan	Açıklama
--workspace	.	Go proje kökünüze giden mutlak yol
--gopls-path	gopls	gopls ikili dosyasına giden yol
--log-level	info	Günlük seviyesi (debug, info, warn, error)
--rpc-timeout	30s	LSP çağrıları için RPC zaman aşımı
--shutdown-timeout	5s	Zarif kapatma için zaman aşımı

Ortam Değişkenleri

Tüm bayraklar MCP_GOPLS_ ön eki ile ortam değişkenleri aracılığıyla ayarlanabilir:

Ortam Değişkeni	Eşdeğer Bayrak	Açıklama
MCP_GOPLS_WORKSPACE	--workspace	Go proje kökünüze giden mutlak yol
MCP_GOPLS_GOPLS_PATH	--gopls-path	gopls ikili dosyasına giden yol
MCP_GOPLS_LOG_LEVEL	--log-level	Günlük seviyesi (debug, info, warn, error)
MCP_GOPLS_RPC_TIMEOUT	--rpc-timeout	LSP çağrıları için RPC zaman aşımı (ör. 30s, 1m)
MCP_GOPLS_SHUTDOWN_TIMEOUT	--shutdown-timeout	Zarif kapatma için zaman aşımı

Komut satırı bayrakları ortam değişkenlerine göre öncelik alır.

Sorun Giderme

• "column is beyond end of line" – gopls, sağlanan konumu eşleştiremedi. Dosyanın kaydedildiğini ve konumun sıfır tabanlı satırlar/karakterler kullandığını doğrulayın; sekmelerin ve boşlukların gopls beklentileriyle hizalanmasını sağlamak için go fmt çalıştırın.
• "no hover information available" – sembol, üretilen bir dosyaya veya yapılandırılmış çalışma alanı dışındaki bir modüle ait olabilir. --workspace bayrağının modül köküne işaret ettiğinden ve go list ./...'in başarılı olduğundan emin olun.
• "workspace not initialized" – sunucu ilk senkronizasyonını tamamlamadı. workspace initialized günlük satırı için bekleyin veya eski .gopls önbelleklerini sildikten sonra mcp-gopls'i yeniden başlatın.
• run_govulncheck eksik ikili dosya – araç artık go run golang.org/x/vuln/cmd/govulncheck@latest'a geri döner, ancak makine yine de giden ağ erişimine ihtiyaç duyar. Geri dönüş engellenmişse ikiliyi manuel olarak kurun.

Kullanım Örneği

Sunucuyu MCP destekleyen yapay zeka asistanlarıyla kullanma:

# Yapay zekaya kodla ilgili bilgi almak için sor
Bu projede `ServeStdio` işlevinin tanımını bulabilir misin?

# Tanılamalar iste
main.go dosyamda herhangi bir hata var mı?

# Bir sembol hakkında bilgi iste
Go'da Context.WithTimeout işlevi ne yapar?

Geliştirme

git clone https://github.com/hloiseau/mcp-gopls.git
cd mcp-gopls
go mod tidy
go test ./...
go build ./cmd/mcp-gopls

Tablo odaklı testler pkg/tools altında yer alır ve CI .github/workflows/ci.yml aracılığıyla çalışır.

Dokümantasyon

• docs/usage.md – hızlı başlangıç ve araç kataloğu incelemesi
• Çalışma alanı kaynakları resource://workspace/overview ve resource://workspace/go.mod sunar
• Komut istemlerine (summarize_diagnostics, refactor_plan) tutarlı çıktılar üretmesine yardımcı olur

Katkıda Bulunma

PR'ler ve sorunlar hoş geldiniz!

• Açık sorunları kontrol edin veya bir hata bulursanız veya bir özellik istiyorsanız yeni bir sorun dosyalayın.
• PR açmadan önce go test ./...'i çalıştırın.
• Daha büyük değişiklikler için (yeni ara