OpenGrok

31 ferramentas no total: 2–5 no Code Mode (opengrok_api + opengrok_execute, mais 3 ferramentas de memória quando OPENGROK_ENABLE_MEMORY_TOOLS=true) e 26 no modo padrão (OPENGROK_CODE_MODE=false).

Ferramentas Principais

Ferramentas Compostas

Estas mesclam múltiplas chamadas de API em uma única operação.

Ferramentas de Investigação

(Nota: as ferramentas de busca suportam filtragem por linguagem. Passe file_type usando o nome canônico do analisador — cxx para C++, golang para Go, sh para shell, javascript para JS. Aliases aceitos: cpp/c++→cxx, go→golang, bash/shell→sh, js→javascript, ts→typescript, cs→csharp, py→python, rb→ruby, rs→rust.)

Notas de fallback para defs/refs/symbol — buscas defs, refs e symbol exigem um escopo de projeto (passe projects ou defina OPENGROK_DEFAULT_PROJECT); sem isso, podem retornar muitos resultados entre projetos. Em instâncias onde o endpoint REST retorna erro ou resultados vazios para esses tipos, o cliente automaticamente recorre à análise da interface web para que o LLM ainda receba respostas. opengrok_call_graph precisa da API v2 e degrada para uma visão baseada em refs na v1.

Defina OPENGROK_CODE_MODE=true (o padrão). Chame opengrok_api uma vez no início da sessão para receber a especificação completa da API. Todas as operações subsequentes passam por opengrok_execute.

Todas as chamadas de API do sandbox são síncronas — globais planas (search(...)), sem await. A forma de objeto env.opengrok.* (env.opengrok.search(...)) é equivalente.

Busca e Descoberta

search() usa apenas nomes canônicos de tipos de arquivo (ex.: cxx, golang, sh) — veja a lista de aliases acima. Passe expandFunction: true para expandir resultados correspondentes ao corpo da função delimitadora (adiciona leituras no host, até 3 arquivos por chamada).

Paginação por cursor — Métodos que retornam um campo cursor (search, findFile, browseDir, getFileSymbols, getFileHistory, getFileDiff) suportam paginação. Passe o cursor de volta como opts.cursor na próxima chamada para buscar a próxima página. Se um cursor expirou (sessão reiniciada ou muito tempo decorrido), a resposta contém { _cursorExpired: true } — reinicie a paginação do início.

Leitura e Navegação

Histórico e Blame

Inteligência de Código

traceCallChain chamadores vêm da busca de referências; chamados vêm da análise AST do tree-sitter para linguagens suportadas (C/C++, Java, Go, Python, JS/TS, Rust e outras). Ambos os métodos de longa duração se distribuem por um cliente em segundo plano — uma conexão irmã sem limite de taxa com um orçamento curto por operação — para que travessias profundas não consumam a cota de limite de taxa em primeiro plano.

Sistema

Exemplo

// Example opengrok_execute code
const refs = env.opengrok.search("handleCrash", { searchType: "refs", maxResults: 5 });
const first = refs.results[0];
const content = env.opengrok.getFileContent(first.project, first.path, {
  startLine: first.matches[0].lineNumber - 5,
  endLine: first.matches[0].lineNumber + 10,
});
return { callerFile: first.path, code: content.content };

Quando search() retorna zero resultados e a amostragem está habilitada, _suggestions: string[] é automaticamente injetado no resultado — verifique-o antes de chamar sample() explicitamente.

Inteligência tree-sitter — leituras de intervalo e expandFunction expandem correspondências para corpos de função envolventes usando análise AST do tree-sitter (gramáticas WASM, sem necessidade de toolchain do host). Orçamentos de linhas por camada se aplicam: minimal 200 linhas, standard 400 linhas, generous 600 linhas. Substitua o diretório de gramáticas com OPENGROK_GRAMMAR_DIR; contribua com novas gramáticas via npm run copy-grammars (veja CONTRIBUTING.md).

Truncamento fitToBuffer — resultados de sandbox que excedem o buffer de ponte de 8 MB são aparados por fitToBuffer(), que mantém elementos de resultado completos em vez de truncar no meio do JSON. Resultados aparados carregam _truncated: true — restrinja a consulta ou pagine com cursor quando você o vir.

Elicitação (OPENGROK_ENABLE_ELICITATION=false para desabilitar, padrão: true)

Quando habilitada, opengrok_api solicita ao usuário que selecione um projeto de trabalho no início da sessão se nenhum OPENGROK_DEFAULT_PROJECT estiver configurado e mais de um projeto existir. O código do sandbox também pode chamar env.opengrok.elicit() para pedir ao usuário que escolha entre várias correspondências durante a execução. Requer um cliente que suporte MCP Elicitation — Claude Code v2.1.76+ suporta isso. Degrada graciosamente para { action: "cancel" } em outros clientes.

Amostragem (OPENGROK_ENABLE_SAMPLING=true, padrão: false)

Delega chamadas de LLM de volta ao cliente via MCP Sampling, usando a assinatura de modelo do cliente sem chaves de API separadas. Dispara automaticamente em três lugares: explicação de erro do sandbox, sumarização de grafos de dependência grandes (>10 nós) e reformulação de consulta com zero resultados (injeção de _suggestions). VS Code Copilot suporta amostragem; outros clientes variam. O servidor degrada graciosamente quando a amostragem não está disponível.

[!WARNING] Os gatilhos de amostragem são automáticos — não sob demanda. Uma única sessão de investigação pode gerar muitas chamadas de amostragem entre erros de sandbox, buscas com zero resultados e grafos de dependência grandes. Alguns clientes consomem solicitações premium por chamada após o primeiro prompt de confirmação. Habilite com isso em mente.

O Code Mode inclui 2 ferramentas por padrão (api + execute; 5 com OPENGROK_ENABLE_MEMORY_TOOLS=true). Dois arquivos persistem entre turnos e reinicializações de sessão:

A codificação delta retorna [unchanged] em leituras repetidas de conteúdo não modificado. O corte com pontuação de riqueza mantém as entradas de log de maior valor quando o espaço é limitado.

Núcleo

Code Mode e Desempenho

Memory Bank

Limite de Taxa

Cache de Resposta

Protocolo MCP

API OpenGrok

Segurança e Auditoria

Registro

Proxy

Usuários do VS Code podem definir opengrok-mcp.baseUrl, opengrok-mcp.codeMode, opengrok-mcp.contextBudget, opengrok-mcp.memoryBankDir, opengrok-mcp.defaultProject, opengrok-mcp.responseFormatOverride, opengrok-mcp.compileDbPaths, opengrok-mcp.enableObservationMasker e opengrok-mcp.observationMaskerTurns nas configurações do VS Code em vez disso. Valores secretos, como a senha, nunca são gravados nas configurações do VS Code.

Nota do SDK MCP: Esta versão usa @modelcontextprotocol/sdk v1.30.0 (linha v1).

Por padrão, o servidor se comunica via stdio. Para implantações compartilhadas em equipe, a camada de transporte HTTP está disponível como uma API de biblioteca (startHttpTransport() em src/server/transport/http-transport.ts), mas ainda não está conectada ao ponto de entrada da CLI — OPENGROK_HTTP_PORT está documentado abaixo, mas main.ts ainda não o lê para iniciar o servidor HTTP automaticamente. Use startHttpTransport() diretamente em implantações personalizadas.

Gerenciamento de Sessão

• Cada cliente HTTP recebe uma instância isolada de McpServer (padrão de fábrica por sessão)
• Sessões expiram após 30 minutos de inatividade; OPENGROK_HTTP_MAX_SESSIONS limita sessões concorrentes (padrão: 100)
• GET /mcp/sessions retorna JSON com contagem de sessões ativas e idade da sessão mais antiga

Autenticação

No modo de servidor de recursos, este servidor valida JWTs emitidos pelo seu próprio IdP — não há endpoint embutido de /token. Quando OPENGROK_JWT_ISSUER está definido, tokens de outros emissores são rejeitados. Metadados de recurso protegido RFC 9728 são servidos em /.well-known/oauth-protected-resource.

Funções RBAC

Tokens desconhecidos ou ausentes são rejeitados com 403 Forbidden. Quando nenhuma autenticação está configurada, solicitações não autenticadas recebem admin (modo de desenvolvimento local).

CORS

Clientes baseados em navegador são controlados por uma lista de permissões de origem (OPENGROK_ALLOWED_ORIGINS, separada por vírgulas). Sem autenticação configurada, origens de loopback (localhost, 127.0.0.1, [::1]) são permitidas para desenvolvimento local; uma vez que a autenticação esteja configurada (OPENGROK_HTTP_AUTH_TOKEN ou tokens RBAC), o loopback não é mais implícito — liste cada origem permitida explicitamente, incluindo as locais.

Para a arquitetura de segurança completa (modelo de ameaças, camadas de defesa, guia de endurecimento), consulte SECURITY.md.

Recomendação de confiança no sandbox: Ao configurar o OpenGrok MCP nas configurações de MCP do VS Code, você pode definir sandboxEnabled: true, que aprova automaticamente chamadas de ferramentas sem prompts de confirmação. Isso é seguro porque toda a execução de ferramentas ocorre dentro do sandbox QuickJS WASM sem acesso ao host — o LLM não pode executar comandos arbitrários do sistema através deste servidor.