OpenGrok

31 herramientas en total: 2–5 en Code Mode (opengrok_api + opengrok_execute, más 3 herramientas de memoria cuando OPENGROK_ENABLE_MEMORY_TOOLS=true) y 26 en modo estándar (OPENGROK_CODE_MODE=false).

Herramientas Principales

Herramientas Compuestas

Estas fusionan múltiples llamadas a la API en una sola operación.

Herramientas de Investigación

(Nota: las herramientas de búsqueda soportan filtrado por idioma. Pasa file_type usando el nombre de analizador canónico — cxx para C++, golang para Go, sh para shell, javascript para JS. Se aceptan alias: cpp/c++→cxx, go→golang, bash/shell→sh, js→javascript, ts→typescript, cs→csharp, py→python, rb→ruby, rs→rust.)

Notas de respaldo para defs/refs/symbol — las búsquedas de defs, refs y symbol requieren un ámbito de proyecto (pasa projects o establece OPENGROK_DEFAULT_PROJECT); sin uno pueden devolver demasiados resultados entre proyectos. En instancias donde el endpoint REST devuelve un error o resultados vacíos para estos tipos, el cliente automáticamente recurre al análisis de la interfaz web para que el LLM aún obtenga respuestas. opengrok_call_graph necesita la API v2 y se degrada a una vista basada en referencias en v1.

Establece OPENGROK_CODE_MODE=true (el valor predeterminado). Llama a opengrok_api una vez al inicio de la sesión para recibir la especificación completa de la API. Todas las operaciones posteriores pasan por opengrok_execute.

Todas las llamadas a la API del sandbox son síncronas — globales planos (search(...)), sin await. La forma de objeto env.opengrok.* (env.opengrok.search(...)) es equivalente.

Búsqueda y Descubrimiento

search() usa solo nombres de tipo de archivo canónicos (por ejemplo, cxx, golang, sh) — consulta la lista de alias anterior. Pasa expandFunction: true para expandir los resultados coincidentes a su cuerpo de función envolvente (añade lecturas en el host, hasta 3 archivos por llamada).

Paginación por cursor — Los métodos que devuelven un campo cursor (search, findFile, browseDir, getFileSymbols, getFileHistory, getFileDiff) soportan paginación. Pasa el cursor de vuelta como opts.cursor en la siguiente llamada para obtener la siguiente página. Si un cursor ha expirado (sesión reiniciada o demasiado tiempo transcurrido), la respuesta contiene { _cursorExpired: true } — reinicia la paginación desde el principio.

Lectura y Navegación

Historial y Blame

Inteligencia de Código

Los llamadores de traceCallChain provienen de la búsqueda de referencias; los llamados provienen del análisis AST de tree-sitter para lenguajes compatibles (C/C++, Java, Go, Python, JS/TS, Rust y más). Ambos métodos de larga duración se distribuyen a través de un cliente en segundo plano — una conexión hermana sin límite de velocidad con un presupuesto corto por operación — para que los recorridos profundos no consuman la cuota de límite de velocidad en primer plano.

Sistema

Ejemplo

// 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 };

Cuando search() devuelve cero resultados y el muestreo está habilitado, _suggestions: string[] se inyecta automáticamente en el resultado — verifícalo antes de llamar a sample() explícitamente.

Inteligencia de tree-sitter — las lecturas de rango y expandFunction expanden las coincidencias a los cuerpos de función envolventes mediante el análisis AST de tree-sitter (gramáticas WASM, sin necesidad de cadena de herramientas del host). Se aplican presupuestos de líneas por nivel: minimal 200 líneas, standard 400 líneas, generous 600 líneas. Anula el directorio de gramáticas con OPENGROK_GRAMMAR_DIR; contribuye nuevas gramáticas a través de npm run copy-grammars (consulta CONTRIBUTING.md).

Truncamiento fitToBuffer — los resultados del sandbox que superan el búfer de puente de 8 MB se recortan mediante fitToBuffer(), que conserva elementos de resultado completos en lugar de truncar a mitad de JSON. Los resultados recortados llevan _truncated: true — reduce la consulta o pagina con cursor cuando lo veas.

Elicitación (OPENGROK_ENABLE_ELICITATION=false para deshabilitar, predeterminado: true)

Cuando está habilitada, opengrok_api solicita al usuario que seleccione un proyecto de trabajo al inicio de la sesión si no hay OPENGROK_DEFAULT_PROJECT configurado y existe más de un proyecto. El código del sandbox también puede llamar a env.opengrok.elicit() para pedir al usuario que elija entre múltiples coincidencias durante la ejecución. Requiere un cliente que admita MCP Elicitation — Claude Code v2.1.76+ lo admite. Degrada correctamente a { action: "cancel" } en otros clientes.

Muestreo (OPENGROK_ENABLE_SAMPLING=true, predeterminado: false)

Delega las llamadas de LLM de vuelta al cliente mediante MCP Sampling, usando la suscripción de modelo del cliente sin claves API separadas. Se activa automáticamente en tres lugares: explicación de errores del sandbox, resumen de grafos de dependencias grandes (>10 nodos) y reformulación de consultas con cero resultados (inyección de _suggestions). VS Code Copilot admite el muestreo; otros clientes varían. El servidor degrada correctamente cuando el muestreo no está disponible.

[!ADVERTENCIA] Los disparadores de muestreo son automáticos — no bajo demanda. Una sola sesión de investigación puede generar muchas llamadas de muestreo entre errores del sandbox, búsquedas con cero resultados y grafos de dependencias grandes. Algunos clientes consumen solicitudes premium por llamada después del primer mensaje de confirmación. Habilítalo teniendo esto en cuenta.

Code Mode incluye 2 herramientas por defecto (api + execute; 5 con OPENGROK_ENABLE_MEMORY_TOOLS=true). Dos archivos persisten entre turnos y reinicios de sesión:

La codificación delta devuelve [unchanged] en lecturas repetidas de contenido sin modificar. El recorte con puntuación de riqueza mantiene las entradas de registro de mayor valor cuando el espacio es limitado.

Núcleo

Code Mode y Rendimiento

Memory Bank

Limitación de velocidad

Caché de respuestas

Protocolo MCP

API de OpenGrok

Seguridad y Auditoría

Registro

Proxy

Los usuarios de VS Code pueden establecer opengrok-mcp.baseUrl, opengrok-mcp.codeMode, opengrok-mcp.contextBudget, opengrok-mcp.memoryBankDir, opengrok-mcp.defaultProject, opengrok-mcp.responseFormatOverride, opengrok-mcp.compileDbPaths, opengrok-mcp.enableObservationMasker y opengrok-mcp.observationMaskerTurns en la configuración de VS Code en su lugar. Los valores secretos como la contraseña nunca se escriben en la configuración de VS Code.

Nota del SDK de MCP: Esta versión usa @modelcontextprotocol/sdk v1.30.0 (línea v1).

Por defecto, el servidor se comunica a través de stdio. Para implementaciones compartidas en equipo, la capa de transporte HTTP está disponible como API de biblioteca (startHttpTransport() en src/server/transport/http-transport.ts) pero aún no está conectada al punto de entrada de CLI — OPENGROK_HTTP_PORT se documenta a continuación pero main.ts aún no lo lee para iniciar el servidor HTTP automáticamente. Usa startHttpTransport() directamente en implementaciones personalizadas.

Gestión de sesiones

• Cada cliente HTTP recibe una instancia aislada de McpServer (patrón de fábrica por sesión)
• Las sesiones expiran después de 30 minutos de inactividad; OPENGROK_HTTP_MAX_SESSIONS limita las sesiones concurrentes (predeterminado: 100)
• GET /mcp/sessions devuelve JSON con el número de sesiones activas y la antigüedad de la sesión más antigua

Autenticación

En el modo de servidor de recursos, este servidor valida JWT emitidos por tu propio IdP — no hay un punto final integrado de /token. Cuando se establece OPENGROK_JWT_ISSUER, se rechazan tokens de otros emisores. Los metadatos de recursos protegidos RFC 9728 se sirven en /.well-known/oauth-protected-resource.

Roles RBAC

Los tokens desconocidos o faltantes se rechazan con 403 Forbidden. Cuando no hay autenticación configurada, las solicitudes no autenticadas reciben admin (modo de desarrollo local).

CORS

Los clientes basados en navegador están controlados por una lista de permitidos de orígenes (OPENGROK_ALLOWED_ORIGINS, separados por comas). Sin autenticación configurada, los orígenes de bucle local (localhost, 127.0.0.1, [::1]) están permitidos para desarrollo local; una vez que la autenticación está configurada (OPENGROK_HTTP_AUTH_TOKEN o tokens RBAC), el bucle local ya no es implícito — liste cada origen permitido explícitamente, incluidos los locales.

Para la arquitectura de seguridad completa (modelo de amenazas, capas de defensa, guía de endurecimiento), consulte SECURITY.md.

Recomendación de confianza del sandbox: Al configurar OpenGrok MCP en la configuración MCP de VS Code, puede establecer sandboxEnabled: true que aprueba automáticamente las llamadas a herramientas sin solicitudes de confirmación. Esto es seguro porque toda la ejecución de herramientas ocurre dentro del sandbox QuickJS WASM sin acceso al host — el LLM no puede ejecutar comandos arbitrarios del sistema a través de este servidor.