OpenGrok Go MCP

opengrok-go-mcp

Inteligencia de código fuente para agentes, impulsada por OpenGrok y Go.

He visto cosas que ustedes no grep-arían. — Arquitecto Senior, probablemente.

Servidor MCP orientado a agentes para buscar, navegar y leer código a través de OpenGrok.

Convierte OpenGrok en una superficie de inteligencia de código más segura para agentes LLM:

• herramientas limitadas por capacidades que solo aparecen cuando la función subyacente de OpenGrok funciona
• búsqueda paginada y lectura de archivos con cursores estables
• URLs de citación en resultados de código para que las respuestas puedan apuntar a la fuente
• advertencias para resultados amplios, heurísticos, truncados o de mejor esfuerzo (códigos warnings[] más una cadena warning heredada)
• expansión automática de contexto alrededor de coincidencias de búsqueda con límites explícitos
• superficies de herramientas de puerta de enlace completas, compactas y experimentales para diferentes estilos de agente

Si eres un agente de IA leyendo este repositorio, comienza con AGENTS.md para conocer las restricciones del proyecto y la guía de flujo de trabajo del agente.

Nota previa a 1.0: este servidor MCP aún está en evolución. Algunas herramientas, respuestas y rutas de configuración pueden estar rotas o cambiar antes de un lanzamiento estable 1.0. Por favor, reporta problemas usando docs/reporting-issues.md.

Cuándo Usarlo

Usa opengrok-go-mcp cuando quieras que un agente investigue una base de código indexada grande sin clonarla localmente. Funciona mejor para encontrar símbolos, leer archivos, rastrear referencias, acotar búsquedas amplias y producir respuestas con citas de fuente.

Es intencionalmente honesto sobre los límites de OpenGrok. OpenGrok proporciona búsqueda de texto completo más definiciones de ctags, no un grafo de llamadas semántico completo ni un motor AST. Para preguntas estructurales, usa este servidor para encontrar los archivos y símbolos correctos, luego verifica relaciones con herramientas conscientes del lenguaje cuando sea necesario.

Configuración del Cliente

Requerido: OPENGROK_MCP_BASE_URL — URL base de la API de OpenGrok que termina en /api/v1. Al iniciar, el servidor descubre proyectos, sondea capacidades y registra solo las herramientas que funcionan. Una instancia típica detrás de proxy inverso no necesita nada más.

Copia un bloque a continuación, reemplaza la URL, reinicia el cliente.

El servidor usa por defecto OPENGROK_MCP_AGENT_PROFILE=economy (cargas útiles ligeras, sin expansión automática de contexto). Establece OPENGROK_MCP_AGENT_PROFILE=rich cuando quieras contexto de búsqueda expandido por defecto. Los diagnósticos internos de respuesta están desactivados por defecto; establece OPENGROK_MCP_DIAGNOSTICS=true solo al depurar contadores de paginación/búsqueda. Consulta docs/configuration.md para la referencia completa de variables de entorno.

{
  "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.2"
      ],
      "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.2"
      ],
      "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.2"]

[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.2"
      ],
      "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

Variables de entorno comunes

Si las sondas de búsqueda devuelven 401/403 sin un token, el servidor aún se inicia y registra la remediación; las herramientas de búsqueda permanecen bloqueadas hasta que se establezca OPENGROK_MCP_API_TOKEN.

Seguridad

Evita pasar secretos como banderas de CLI. Usa OPENGROK_MCP_API_TOKEN para la autenticación de OpenGrok; el servidor nunca registra valores de tokens.

Advertencias operativas:

• El modo HTTP no agrega autenticación de cliente entrante. Mantén la dirección de enlace de loopback predeterminada o colócalo detrás de controles de red/autenticación de confianza.
• OPENGROK_MCP_INSECURE_SKIP_TLS_VERIFY=true es solo para instancias internas controladas con certificados rotos. No lo uses para hosts públicos o no confiables.
• El respaldo de archivo sin procesar usa OPENGROK_MCP_WEB_BASE_URL con las mismas credenciales configuradas. Trata esa URL como parte del límite de confianza de OpenGrok.
• Las herramientas de memoria son solo de superficie completa (stdio). Tienen ámbito de proceso, son efímeras y están deshabilitadas sobre HTTP porque la memoria no está aislada por sesión de cliente.
• Establece OPENGROK_MCP_CURSOR_SECRET para implementaciones compartidas si la integridad del cursor importa.

Evaluación

Evaluaciones stdio herméticas en evals/ — binario MCP real, backend OpenGrok falso, sin instancia en vivo. CI las ejecuta en cada PR (ci.yml). Los resúmenes del README y las columnas Δ comparan contra líneas base confirmadas en evals/baselines/. Actualiza localmente con scripts/update-eval-results.sh; el hook opcional de pre-push (scripts/install-githooks.sh) ejecuta pruebas y actualiza esos archivos antes de hacer push.

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

Cómo leer las tablas a continuación

• Evaluación de contrato — llamadas MCP herméticas contra un backend OpenGrok falso; verifica salidas, errores y campos de paginación. Δ es el cambio vs la línea base confirmada en evals/baselines/. cobertura@K es la fracción de casos de evaluación ejercitados.
• Benchmark de tokens — mismo arnés, pero mide bytes UTF-8 que cruzan el cable MCP (esquemas de herramientas, solicitudes, respuestas). Tokens est. = bytes ÷ 4 (heurística aproximada, no un tokenizador de modelo específico).
• Superficie — full (herramientas de grano fino), compact (4 herramientas consolidadas, predeterminado), o gateway (descubrir + llamar experimental).
• ListTools — costo único cuando el cliente carga la lista de herramientas y esquemas al inicio de la sesión; generalmente el elemento de línea más grande en full.
• Total cálido — ListTools más todas las llamadas de herramientas en un escenario (bytes de solicitud + respuesta). Para gateway, cálido excluye la llamada única a opengrok_discover; frío la incluye (solo primera sesión). En full y compact, frío = cálido.
• Mín–máx — rango entre los cuatro escenarios de reproducción (búsqueda de símbolo, navegación de archivo, búsqueda de símbolo en varios pasos, buscar-y-leer). El desglose por escenario está en la tabla colapsada.
• Δ en filas de tokens — cambio en tokens estimados vs la última línea base confirmada (evals/baselines/token_report.json).

Evaluación de contrato

Última ejecución: 2026-06-25 · llamada directa · docs del arnés →

10/10 aprobados · 100% (Δ ±0) · 100% cobertura@K — consulta Cómo leer las tablas para Δ y cobertura@K.

Benchmark de economía de tokens

Última ejecución: 2026-06-25 · reproducción determinista · tokens est. = bytes÷4 (heurística, no exacta al modelo)

ListTools domina el costo de sesión en la superficie completa (18 herramientas). Compact (4) y gateway (2) registran muchos menos esquemas.

Cálido = ListTools + tráfico de herramientas del escenario. Gateway cálido omite discover único; full/compact frío = cálido. La exploración de archivos compact omite files.list (sin operación compact).

Δ vs línea base del 2026-06-24.

Desarrollo

Este proyecto utiliza GitHub Spec Kit para la planificación de funcionalidades no triviales.

Para cambios de comportamiento significativos, nuevas herramientas MCP, cambios de esquema, cambios de configuración o cambios que afecten el comportamiento orientado a agentes, los contribuyentes deben partir de la constitución del proyecto:

• .specify/memory/constitution.md

El trabajo de funcionalidades generalmente debe producir:

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

Las correcciones menores de errores, ediciones de documentación, actualizaciones de dependencias y refactorizaciones mecánicas no requieren un flujo de trabajo completo de Spec Kit, a menos que afecten el contrato público de MCP.

Todos los cambios deben preservar el contrato MCP, la semántica de OpenGrok, la postura de seguridad, las expectativas de compatibilidad y los requisitos de documentación descritos en la constitución.

Limitaciones conocidas

• El recorrido de proyectos grandes está acotado, y algunas operaciones de búsqueda y descubrimiento son de mejor esfuerzo en lugar de semántica de lenguaje.
• El transporte HTTP está destinado a configuraciones locales o internas controladas y no agrega autenticación de clientes entrantes.

Consulta docs/limitations.md para obtener la lista detallada actual, el impacto de comportamiento y las mitigaciones.

Licencia

opengrok-go-mcp está licenciado bajo la Licencia Apache 2.0 (Apache-2.0) para nuevos lanzamientos a partir de v0.3.0-beta.2.

Las publicaciones anteriores hasta e incluyendo v0.3.0-beta.1 se publicaron bajo CC0-1.0 y permanecen disponibles bajo esos términos.