OpenGrok Go MCP

opengrok-go-mcp

Inteligência de código-fonte para agentes, com tecnologia OpenGrok e Go.

Eu vi coisas que vocês, humanos, não grepariam. — Arquiteto Sênior, provavelmente.

Servidor MCP orientado a agentes para buscar, navegar e ler código através do OpenGrok.

Ele transforma o OpenGrok em uma superfície de inteligência de código mais segura para agentes LLM:

• ferramentas limitadas por capacidade que só aparecem quando o recurso OpenGrok subjacente funciona
• busca paginada e leitura de arquivos com cursores estáveis
• URLs de citação em resultados de código para que respostas possam apontar de volta para a fonte
• avisos para resultados amplos, heurísticos, truncados ou de melhor esforço (códigos warnings[] além de uma string warning legada)
• expansão automática de contexto em torno de resultados de busca com limites explícitos
• superfícies de ferramentas de gateway completas, compactas e experimentais para diferentes estilos de agente

Se você é um agente de IA lendo este repositório, comece com AGENTS.md para restrições do projeto e orientações de fluxo de trabalho do agente.

Nota pré-1.0: este servidor MCP ainda está em evolução. Algumas ferramentas, respostas e caminhos de configuração podem estar quebrados ou mudar antes de um lançamento estável 1.0. Por favor, relate problemas usando docs/reporting-issues.md.

Quando Usar

Use opengrok-go-mcp quando quiser que um agente investigue uma grande base de código indexada sem cloná-la localmente. Funciona melhor para encontrar símbolos, ler arquivos, rastrear referências, restringir buscas amplas e produzir respostas com citações de fonte.

Ele é intencionalmente honesto sobre os limites do OpenGrok. O OpenGrok fornece busca de texto completo além de definições ctags, não um grafo de chamadas semântico completo ou um mecanismo AST. Para questões estruturais, use este servidor para encontrar os arquivos e símbolos certos, depois verifique relacionamentos com ferramentas sensíveis à linguagem quando necessário.

Configuração do Cliente

Obrigatório: OPENGROK_MCP_BASE_URL — URL base da API OpenGrok terminando em /api/v1. Na inicialização, o servidor descobre projetos, testa capacidades e registra apenas ferramentas que funcionam. Uma instância típica atrás de proxy reverso não precisa de mais nada.

Copie um bloco abaixo, substitua a URL, reinicie o cliente.

O servidor usa como padrão OPENGROK_MCP_AGENT_PROFILE=economy (payloads enxutos, sem expansão automática de contexto). Defina OPENGROK_MCP_AGENT_PROFILE=rich quando quiser contexto de busca expandido por padrão. Diagnósticos internos de resposta ficam desativados por padrão; defina OPENGROK_MCP_DIAGNOSTICS=true apenas ao depurar contadores de paginação/busca. Veja docs/configuration.md para a referência completa de ambiente.

{
  "mcpServers": {
    "opengrok": {
      "command": "/path/to/opengrok-go-mcp",
      "env": {
        "OPENGROK_MCP_BASE_URL": "https://your-opengrok-host/source/api/v1"
      }
    }
  }
}

{
  "mcpServers": {
    "opengrok": {
      "command": "go",
      "args": [
        "run",
        "github.com/rokasklive/opengrok-go-mcp/cmd/opengrok-go-mcp@v0.6.0"
      ],
      "env": {
        "OPENGROK_MCP_BASE_URL": "https://your-opengrok-host/source/api/v1"
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opengrok": {
      "type": "local",
      "enabled": true,
      "command": [
        "go",
        "run",
        "github.com/rokasklive/opengrok-go-mcp/cmd/opengrok-go-mcp@v0.6.0"
      ],
      "environment": {
        "OPENGROK_MCP_BASE_URL": "https://your-opengrok-host/source/api/v1"
      }
    }
  }
}

[[mcp_servers]]
name = "opengrok"
command = ["go", "run", "github.com/rokasklive/opengrok-go-mcp/cmd/opengrok-go-mcp@v0.6.0"]

[mcp_servers.env]
OPENGROK_MCP_BASE_URL = "https://your-opengrok-host/source/api/v1"

{
  "mcpServers": {
    "opengrok": {
      "command": "go",
      "args": [
        "run",
        "github.com/rokasklive/opengrok-go-mcp/cmd/opengrok-go-mcp@v0.6.0"
      ],
      "env": {
        "OPENGROK_MCP_BASE_URL": "https://your-opengrok-host/source/api/v1"
      }
    }
  }
}

"command": "sh",
"args": [
  "-c",
  "cd /path/to/opengrok-go-mcp && go run ./cmd/opengrok-go-mcp --read-timeout=30s --write-timeout=30s"
]

OPENGROK_MCP_TRANSPORT=http \
OPENGROK_MCP_BASE_URL=https://your-opengrok-host/source/api/v1 \
go run ./cmd/opengrok-go-mcp

Variáveis de ambiente comuns

Se as sondagens de busca retornarem 401/403 sem token, o servidor ainda inicia e registra a correção; as ferramentas de busca permanecem bloqueadas até que OPENGROK_MCP_API_TOKEN seja definido.

Segurança

Evite passar segredos como flags de CLI. Use OPENGROK_MCP_API_TOKEN para autenticação OpenGrok; o servidor nunca registra valores de token em logs.

Ressalvas operacionais:

• O modo HTTP não adiciona autenticação de cliente de entrada. Mantenha o endereço de bind loopback padrão ou coloque-o atrás de controles de rede/autenticação confiáveis.
• OPENGROK_MCP_INSECURE_SKIP_TLS_VERIFY=true é apenas para instâncias internas controladas com certificados quebrados. Não use para hosts públicos ou não confiáveis.
• O fallback de arquivo bruto usa OPENGROK_MCP_WEB_BASE_URL com as mesmas credenciais configuradas. Trate essa URL como parte do limite confiável do OpenGrok.
• Ferramentas de memória são apenas superfície completa (stdio). Elas têm escopo de processo, são efêmeras e desativadas via HTTP porque a memória não é isolada por sessão de cliente.
• Defina OPENGROK_MCP_CURSOR_SECRET para implantações compartilhadas se a integridade do cursor for importante.

Avaliação

Avaliações stdio herméticas em evals/ — binário MCP real, backend OpenGrok falso, sem instância ativa. CI as executa em cada PR (ci.yml). Resumos do README e colunas Δ comparam com baselines confirmados em evals/baselines/. Atualize localmente com scripts/update-eval-results.sh; o hook opcional de pré-push (scripts/install-githooks.sh) executa testes e atualiza esses arquivos antes de você enviar.

go test ./evals/ -count=1                        # contract + token benchmark
go test ./evals/ -run TestEvalSuite -count=1      # MCP contract only
go test ./evals/ -run TestTokenBenchmark -count=1 # token economy only

Como ler as tabelas abaixo

• Avaliação de contrato — chamadas MCP herméticas contra um backend OpenGrok falso; verifica saídas, erros e campos de paginação. Δ é a mudança em relação ao baseline confirmado em evals/baselines/. cobertura@K é a fração de casos de avaliação exercitados.
• Benchmark de tokens — mesma estrutura, mas mede bytes UTF-8 cruzando o fio MCP (esquemas de ferramentas, requisições, respostas). Est. tokens = bytes ÷ 4 (heurística aproximada, não um tokenizador de modelo específico).
• Superfície — full (ferramentas granulares), compact (4 ferramentas consolidadas, padrão), ou gateway (descobrir + chamar experimental).
• ListTools — custo único quando o cliente carrega a lista de ferramentas e esquemas no início da sessão; geralmente o maior item de linha em full.
• Total aquecido — ListTools mais todas as chamadas de ferramenta em um cenário (bytes de requisição + resposta). Para gateway, aquecido exclui a chamada única de opengrok_discover; frio a inclui (apenas primeira sessão). Em full e compact, frio = aquecido.
• Mín–máx — intervalo entre os quatro cenários de replay (busca de símbolo, navegação de arquivo, busca de símbolo em várias etapas, buscar-e-ler). Detalhamento por cenário está na tabela recolhida.
• Δ em linhas de token — mudança em tokens estimados em relação ao último baseline confirmado (evals/baselines/token_report.json).

Avaliação de contrato

Última execução: 2026-06-25 · chamada direta · docs do harness →

10/10 aprovados · 100% (Δ ±0) · 100% cobertura@K — veja Como ler as tabelas para Δ e cobertura@K.

Benchmark de economia de tokens

Última execução: 2026-06-25 · replay determinístico · est. tokens = bytes÷4 (heurística, não exata do modelo)

ListTools domina o custo de sessão na superfície completa (18 ferramentas). Compact (4) e gateway (2) registram muito menos esquemas.

Aquecido = ListTools + tráfego de ferramentas do cenário. Gateway aquecido omite discover único; full/compact frio = aquecido. Exploração de arquivo compact ignora files.list (sem operação compact).

Δ vs. linha de base de 2026-06-24.

Desenvolvimento

Este projeto usa o GitHub Spec Kit para planejamento de funcionalidades não triviais.

Para mudanças de comportamento significativas, novas ferramentas MCP, mudanças de esquema, mudanças de configuração ou mudanças que afetem o comportamento voltado a agentes, os contribuidores devem começar pela constituição do projeto:

• .specify/memory/constitution.md

O trabalho de funcionalidades geralmente deve produzir:

• specs/FEATURE/spec.md
• specs/FEATURE/plan.md
• specs/FEATURE/tasks.md

Correções de bugs pequenas, edições de documentação, atualizações de dependências e refatorações mecânicas não exigem um fluxo completo do Spec Kit, a menos que afetem o contrato público do MCP.

Todas as mudanças devem preservar o contrato MCP, a semântica do OpenGrok, a postura de segurança, as expectativas de compatibilidade e os requisitos de documentação descritos na constituição.

Limitações Conhecidas

• A travessia de projetos grandes é limitada, e algumas operações de busca e descoberta são de melhor esforço, em vez de semântica de linguagem.
• O transporte HTTP é destinado a configurações locais ou internas controladas e não adiciona autenticação de cliente de entrada.

Consulte docs/limitations.md para a lista atual detalhada, impacto comportamental e mitigações.

Licença

opengrok-go-mcp é licenciado sob a Apache License 2.0 (Apache-2.0) para novos lançamentos a partir de v0.3.0-beta.2.

Lançamentos publicados anteriormente, até e incluindo v0.3.0-beta.1, foram lançados sob CC0-1.0 e permanecem disponíveis sob esses termos.