MCP LSP Go

Um servidor MCP que conecta assistentes de IA ao Language Server Protocol (LSP) do Go para análise avançada de código.

Documentação

mcp-gopls – Servidor MCP para Go (gopls)

Um servidor Model Context Protocol (MCP) que permite que assistentes de IA usem o LSP do Go (gopls) para navegação, diagnósticos, testes, cobertura e muito mais.

TL;DR: Se você usa Claude / Cursor / Copilot com Go, o mcp-gopls dá à IA todos os poderes do LSP: ir para definição, referências, hover, conclusão, go test, cobertura, go mod tidy, govulncheck, etc.

Demo Animation

Visão Geral

Este servidor MCP ajuda assistentes de IA a:

Usar LSP para analisar workspaces Go
Navegar para definições, referências e símbolos do workspace
Formatar, renomear e inspecionar ações de código sem sair do MCP
Executar testes Go, cobertura, go mod tidy, govulncheck e comandos de grafo de módulos com resultados estruturados
Ler recursos do workspace (visão geral + go.mod) e consumir prompts selecionados

Status: Em desenvolvimento ativo – usado em projetos reais.
Testado com Go 1.25.x e gopls@latest.

Arquitetura

Este projeto usa a biblioteca mark3labs/mcp-go para implementar o Model Context Protocol. A integração MCP permite comunicação perfeita entre assistentes de IA e ferramentas Go.

O servidor se comunica com gopls, o servidor de linguagem oficial para Go, via Language Server Protocol (LSP).

Recursos

Runtime configurável: flags --workspace, --gopls-path, --log-level, --rpc-timeout e --shutdown-timeout + variáveis de ambiente (MCP_GOPLS_*)
Logging estruturado: logging em texto/JSON com slog e saída opcional para arquivo
Superfície LSP estendida: navegação, diagnósticos, formatação, renomeação, ações de código, hover, conclusão, símbolos do workspace
Auxiliares de teste e ferramentas: análise de cobertura, go test, go mod tidy, govulncheck, go mod graph
Extras MCP: recursos (resource://workspace/overview, resource://workspace/go.mod) e prompts (summarize_diagnostics, refactor_plan)
Streaming de progresso: comandos de longa duração emitem eventos notifications/progress para que os clientes possam exibir atualizações de status

Comparação de recursos: `mcp-gopls` vs MCP integrado do `gopls`

A partir do gopls v0.20.0, o servidor MCP integrado expõe estas ferramentas: 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.

Recurso / capacidade	`mcp-gopls` (este projeto)	MCP integrado do `gopls`
Ir para definição	Sim (ferramenta `go_to_definition`)	Sem ferramenta MCP dedicada (não está na lista de ferramentas)
Encontrar referências	Sim (`find_references`)	Sim (`go_references`, `go_symbol_references`)
Diagnósticos (arquivo / workspace)	Sim (`check_diagnostics`)	Sim (`go_diagnostics`, `go_file_diagnostics`)
Informações de hover	Sim (`get_hover_info`)	Sem ferramenta MCP dedicada (não está na lista de ferramentas)
Conclusão	Sim (`get_completion`)	Sem ferramenta MCP dedicada (não está na lista de ferramentas)
Formatação	Sim (`format_document`)	Sem ferramenta MCP dedicada (não está na lista de ferramentas)
Renomear símbolo	Sim (`rename_symbol`)	Sim (`go_rename_symbol`)
Ações de código	Sim (`list_code_actions`)	Sem ferramenta MCP dedicada (não está na lista de ferramentas)
Busca de símbolos no workspace	Sim (`search_workspace_symbols`)	Sim (`go_search`)
Ferramentas de API/contexto de pacote/workspace	Sem ferramenta MCP dedicada	Sim (`go_package_api`, `go_file_context`, `go_file_metadata`, `go_workspace`, `go_context`)
Executar `go test`	Sim (`run_go_test`)	Sem ferramenta MCP para executar testes
Análise de cobertura	Sim (`analyze_coverage`)	Sem ferramenta MCP para cobertura
`go mod tidy`	Sim (`run_go_mod_tidy`)	Sem ferramenta MCP para `go mod tidy`
`govulncheck`	Sim (`run_govulncheck`)	Sim (`go_vulncheck`)
Grafo de módulos (`go mod graph`)	Sim (`module_graph`)	Sem ferramenta MCP para grafo de módulos
Recursos MCP extras	Sim (`resource://workspace/overview`, `resource://workspace/go.mod`)	Não documentado como recursos MCP
Prompts MCP personalizados	Sim (`summarize_diagnostics`, `refactor_plan`)	Não expostos como prompts MCP (apenas instruções de modelo)
Instruções de modelo enviadas com o servidor	Sem mecanismo especial (documentado no README/docs)	Sim: `gopls mcp -instructions` imprime fluxos de trabalho de uso

Se você quiser edição completa estilo LSP + ferramentas via MCP (definição, hover, conclusão, formatação, renomeação, ações de código, go test, cobertura, go mod tidy, grafo de módulos), o mcp-gopls é estritamente mais rico.

Se você quiser principalmente ferramentas somente leitura/introspectivas (diagnósticos, busca de símbolos, referências, API de pacotes, contexto de workspace/arquivo, vulncheck) sem binário extra, o MCP integrado do gopls é suficiente.

Nota: O servidor MCP integrado do gopls ainda está marcado como experimental e seu conjunto de ferramentas pode mudar ao longo do tempo. Esta comparação é precisa a partir do gopls v0.20.x.

Estrutura do Projeto

.
├── cmd
│   └── mcp-gopls        # Application entry point
├── pkg
│   ├── lsp             # LSP client to communicate with gopls
│   │   ├── client      # LSP client implementation
│   │   └── protocol    # LSP protocol types and features
│   ├── server          # MCP server
│   └── tools           # MCP tools exposing LSP features

Instalação

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

Início Rápido

Instale o servidor:

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

Verifique se ele está no seu $PATH:

mcp-gopls --help

Configure seu cliente de IA (veja exemplos abaixo para Cursor, Claude Desktop ou GitHub Copilot).

Docker / MCP Gateway

Se você preferir executar o mcp-gopls em um contêiner (para Docker MCP Gateway ou outras configurações conteinerizadas), use a imagem oficial.

Execução com Docker

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

docker-mcp.yaml

Copie o docs/docker-mcp.yaml, atualize o caminho do bind mount e execute a partir desse diretório:

docker mcp gateway run

Metadados do catálogo de ferramentas

Se suas ferramentas de catálogo MCP exigirem um toolsUrl, use docs/tools.json como uma lista estática de ferramentas.

Configuração Detalhada do Cliente

Nota: Todos os clientes apontam para o mesmo comando:
mcp-gopls --workspace /absolute/path/to/your/go/project
O formato de configuração difere ligeiramente por cliente, mas o binário e os argumentos permanecem idênticos.

1. Conectar a partir do Cursor

Abra Configurações → Servidores MCP → Editar JSON.
Adicione ou atualize a entrada mcp-gopls:

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

Execute Developer: Reload Window para que o Cursor reconecte.
Abra a gaveta Ferramentas no Chat do Cursor e habilite mcp-gopls.

2. Invocar as ferramentas

Ferramenta / Prompt	Exemplo de solicitação no Chat do Cursor
`go_to_definition`	“Use `go_to_definition` em `pkg/server/server.go:42`.”
`find_references`	“Peça à ferramenta referências para `ServeStdio`.”
`check_diagnostics`	“Solicite diagnósticos para `cmd/mcp-gopls/main.go`.”
`get_hover_info`	“Chame `get_hover_info` em `pkg/tools/workspace.go:88`.”
`get_completion`	“Dispare conclusões em `pkg/server/server.go:55`.”
`format_document`	“Execute o formatador em `pkg/tools/refactor.go`.”
`rename_symbol`	“Renomeie `clientFactory` para `newClientFactory` via a ferramenta.”
`list_code_actions`	“Liste ações de código para `pkg/server/server.go:80-90`.”
`search_workspace_symbols`	“Pesquise símbolos do workspace para `NewWorkspaceConfig`.”
`analyze_coverage`	“Execute `analyze_coverage` para `./pkg/...` com estatísticas por função.”
`run_go_test`	“Execute `run_go_test` em `./cmd/...`.”
`run_go_mod_tidy`	“Invoque `run_go_mod_tidy` para sincronizar o go.mod.”
`run_govulncheck`	“Execute `run_govulncheck` e transmita os resultados.”
`module_graph`	“Chame `module_graph` para inspecionar dependências.”
`summarize_diagnostics`	“Use o prompt `summarize_diagnostics` nos diagnósticos mais recentes.”
`refactor_plan`	“Alimente `refactor_plan` com o JSON de diagnósticos para planejar correções.”

Exemplos de Configuração do Cliente

Claude Desktop (macOS, Windows, Linux)

Instale mcp-gopls e certifique-se de que ele esteja no seu $PATH.
Crie ou edite claude_desktop_config.json.
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Adicione a entrada do servidor:

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

Reinicie o Claude Desktop, abra um chat e peça para conectar à ferramenta mcp-gopls (o Claude mostrará uma aba “Ferramentas” assim que o servidor for detectado). Prompts típicos incluem “liste diagnósticos para cmd/api/server.go” ou “renomeie userService para accountService.”

Cursor IDE

No Cursor, abra Configurações → Servidores MCP → Editar JSON (isso grava em ~/.cursor/config.json ou na substituição local do projeto). Adicione:

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

Recarregue o Cursor (ou execute o comando Developer: Reload Window) e o servidor aparecerá na gaveta “Ferramentas”. Agora você pode pedir ao Chat do Cursor coisas como “execute go test ./pkg/server com cobertura” ou “mostre informações de hover para pkg/tools/tests.go:42.”

GitHub Copilot (Modo Agente)

O Modo Agente do GitHub Copilot pode conversar com servidores MCP locais no VS Code, IDEs JetBrains, Eclipse e Xcode (docs). Para conectar o mcp-gopls no VS Code:

Atualize o GitHub Copilot (requer VS Code 1.99+), opte pelo Modo Agente.
Crie .vscode/mcp.json no seu workspace (ou edite o arquivo global mostrado na caixa de diálogo “Editar configuração” do Copilot).
Adicione:

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

Recarregue o Modo Agente (desative/ative) para que o Copilot descubra a nova ferramenta; o seletor de “Ferramentas” do chat agora exporá cada ação MCP (run_go_test, run_govulncheck, etc.). JetBrains e outros IDEs compartilham o mesmo esquema JSON via painel de configurações do Copilot.

MCP Inspector / Teste via CLI

Para testes rápidos de fumaça ou demonstrações, você pode usar o mark3labs/mcp-inspector:

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

O inspector permite chamar cada ferramenta/recurso/prompt manualmente, o que é útil para depurar a configuração do servidor antes de conectá-lo a um assistente de IA.

Ferramentas MCP

Ferramenta	Descrição
`go_to_definition`	Navegar para a definição de um símbolo
`find_references`	Listar todas as referências de um símbolo
`check_diagnostics`	Buscar diagnósticos em cache para um arquivo
`get_hover_info`	Retornar markdown de hover para um símbolo
`get_completion`	Retornar rótulos de conclusão em uma posição
`format_document`	Retornar edições de formatação para um documento inteiro
`rename_symbol`	Retornar edições de workspace para uma renomeação
`list_code_actions`	Listar ações de código disponíveis para um intervalo
`search_workspace_symbols`	Pesquisar símbolos em todo o workspace
`analyze_coverage`	Executar `go test` com cobertura + relatório opcional por função
`run_go_test`	Executar `go test` para um pacote/padrão
`run_go_mod_tidy`	Executar `go mod tidy`
`run_govulncheck`	Executar `govulncheck ./...`
`module_graph`	Retornar saída de `go mod graph`

Notificações de Progresso

Ferramentas de longa duração emitem eventos estruturados de notifications/progress para que IDEs possam mostrar indicadores de status ricos:

Progresso em streaming (run_go_test, analyze_coverage, run_govulncheck, run_go_mod_tidy) encaminha linhas de log incrementais e atualizações percentuais. O Cursor exibe isso como um log ao vivo.
Eventos apenas de início/conclusão (go_to_definition, find_references, rename_symbol, etc.) disparam um evento rápido de “iniciado” para que a UI possa mostrar um spinner, seguido por um payload de conclusão com o resultado final.
Cada token de progresso agora tem namespace (por exemplo, run_go_test/<rand>) para evitar erros de “token desconhecido” quando várias ferramentas são executadas simultaneamente.

Ao integrar novas ferramentas, opte pelo modo de streaming apenas se o comando LSP/golang subjacente produzir saída intermediária significativa; caso contrário, mantenha o fluxo leve de início/conclusão para minimizar ruído.

Instruções de Prompt

Ambos os prompts são acessíveis de qualquer cliente compatível com MCP via catálogo “Prompts”.

`summarize_diagnostics`

Quando usar: Após check_diagnostics ou run_go_test para transformar diagnósticos brutos em etapas acionáveis.
Argumentos: Nenhum. O servidor lê automaticamente o último payload de diagnósticos armazenado em cache pela camada de ferramentas.
Fluxo de trabalho típico: check_diagnostics → copie o array retornado no campo de entrada do prompt (a UI do Cursor cola automaticamente quando você seleciona “Usar último resultado”).

`refactor_plan`

Quando usar: Você já tem um array JSON de diagnósticos e deseja uma lista de verificação concisa de alterações.
Argumentos: Requer um objeto diagnostics contendo os diagnósticos Go brutos (o mesmo payload retornado por check_diagnostics).
Exemplo de payload de invocação:

{
  "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"
    }
  ]
}

O prompt responde com um conjunto numerado de etapas de refatoração, além de comandos de validação sugeridos (go test, analyze_coverage, etc.).

Configuração

O servidor suporta várias opções de configuração por meio de flags de linha de comando e variáveis de ambiente:

Flags de Linha de Comando

Flag	Padrão	Descrição
`--workspace`	`.`	Caminho absoluto para a raiz do seu projeto Go
`--gopls-path`	`gopls`	Caminho para o binário gopls
`--log-level`	`info`	Nível de log (`debug`, `info`, `warn`, `error`)
`--rpc-timeout`	`30s`	Timeout de RPC para chamadas LSP
`--shutdown-timeout`	`5s`	Timeout para desligamento gracioso

Variáveis de Ambiente

Todas as flags podem ser definidas por meio de variáveis de ambiente com o prefixo MCP_GOPLS_:

Variável de Ambiente	Flag Equivalente	Descrição
`MCP_GOPLS_WORKSPACE`	`--workspace`	Caminho absoluto para a raiz do seu projeto Go
`MCP_GOPLS_GOPLS_PATH`	`--gopls-path`	Caminho para o binário gopls
`MCP_GOPLS_LOG_LEVEL`	`--log-level`	Nível de log (`debug`, `info`, `warn`, `error`)
`MCP_GOPLS_RPC_TIMEOUT`	`--rpc-timeout`	Timeout de RPC para chamadas LSP (ex.: `30s`, `1m`)
`MCP_GOPLS_SHUTDOWN_TIMEOUT`	`--shutdown-timeout`	Timeout para desligamento gracioso

As flags de linha de comando têm precedência sobre as variáveis de ambiente.

Solução de Problemas

“column is beyond end of line” – o gopls não conseguiu mapear a posição fornecida. Confirme que o arquivo está salvo e que a posição usa linhas/colunas baseadas em zero; execute go fmt para garantir que tabs vs. espaços estejam alinhados com as expectativas do gopls.
“no hover information available” – o símbolo pode pertencer a um arquivo gerado ou a um módulo fora do workspace configurado. Garanta que a flag --workspace aponte para a raiz do módulo e que go list ./... seja executado com sucesso.
“workspace not initialized” – o servidor não concluiu sua sincronização inicial. Aguarde a linha de log workspace initialized ou reinicie o mcp-gopls após excluir os caches obsoletos de .gopls.
binário run_govulncheck ausente – a ferramenta agora usa go run golang.org/x/vuln/cmd/govulncheck@latest como fallback, mas a máquina ainda precisa de acesso de rede de saída. Instale o binário manualmente se o fallback estiver bloqueado.

Exemplo de Uso

Usando o servidor com assistentes de IA que suportam MCP:

# Ask the AI to get information about the code
Can you find the definition of the `ServeStdio` function in this project?

# Ask for diagnostics
Are there any errors in my main.go file?

# Ask for information about a symbol
What does the Context.WithTimeout function do in Go?

Desenvolvimento

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

Testes orientados por tabela ficam em pkg/tools e o CI é executado via .github/workflows/ci.yml.

Documentação

docs/usage.md – guia de início rápido e passo a passo do catálogo de ferramentas
Os recursos do workspace expõem resource://workspace/overview e resource://workspace/go.mod
Os prompts (summarize_diagnostics, refactor_plan) ajudam os assistentes a produzir saídas consistentes

Contribuindo

PRs e issues são bem-vindos!

Verifique as issues abertas ou abra uma nova se encontrar um bug ou quiser um recurso.
Execute go test ./... antes de abrir um PR.
Para mudanças maiores (novas ferramentas, mudanças de protocolo), abra primeiro uma issue de design para que possamos discutir a abordagem.

Todas as contribuições devem manter a cobertura de testes e seguir as melhores práticas de Go. Consulte a seção Desenvolvimento para instruções de configuração.

Pré-requisitos

Go 1.25+ (testado com go1.25.4)
gopls instalado (go install golang.org/x/tools/gopls@latest)
Opcional: govulncheck (go install golang.org/x/vuln/cmd/govulncheck@latest)
O servidor força GOTOOLCHAIN=local para seu processo aninhado gopls. Se você precisar de um toolchain diferente, defina GOTOOLCHAIN no ambiente antes de iniciar o mcp-gopls.

Integração com Ollama

Este servidor MCP pode ser usado com qualquer ferramenta que suporte o protocolo MCP. Para integração com Ollama:

Certifique-se de que o Ollama esteja em execução
O servidor MCP é executado de forma independente e se comunica via stdin/stdout
Configure seu cliente para usar o servidor MCP como provedor de ferramentas

Licença

Apache License 2.0

MCP LSP Go

Documentação

mcp-gopls – Servidor MCP para Go (gopls)

Visão Geral

Arquitetura

Recursos

Comparação de recursos: mcp-gopls vs MCP integrado do gopls

Estrutura do Projeto

Instalação

Início Rápido

Docker / MCP Gateway

Execução com Docker

docker-mcp.yaml

Metadados do catálogo de ferramentas

Configuração Detalhada do Cliente

1. Conectar a partir do Cursor

2. Invocar as ferramentas

Exemplos de Configuração do Cliente

Claude Desktop (macOS, Windows, Linux)

Cursor IDE

GitHub Copilot (Modo Agente)

MCP Inspector / Teste via CLI

Ferramentas MCP

Notificações de Progresso

Instruções de Prompt

summarize_diagnostics

refactor_plan

Configuração

Flags de Linha de Comando

Variáveis de Ambiente

Solução de Problemas

Exemplo de Uso

Desenvolvimento

Documentação

Contribuindo

Pré-requisitos

Integração com Ollama

Licença

Comparação de recursos: `mcp-gopls` vs MCP integrado do `gopls`

`summarize_diagnostics`

`refactor_plan`