maven-indexer-mcp

Un servidor del Protocolo de Contexto de Modelo (MCP) que indexa tu repositorio local de Maven (~/.m2/repository) y la caché de Gradle (~/.gradle/caches/modules-2/files-2.1) para proporcionar a los agentes de IA herramientas para buscar clases de Java, firmas de métodos y código fuente.

GitHub
22
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Maven Indexer

npm version Tests

Un servidor de Protocolo de Contexto de Modelo (MCP) que indexa tu repositorio Maven local (~/.m2/repository) y la caché de Gradle ( ~/.gradle/caches/modules-2/files-2.1) para proporcionar a los agentes de IA herramientas para buscar clases de Java, firmas de métodos y código fuente.

Caso de uso clave: Mientras que los modelos de IA conocen bien las bibliotecas públicas populares (como Spring, Apache Commons, Guava), a menudo tienen dificultades con:

  1. Paquetes internos de la empresa: Bibliotecas privadas que no son públicas.
  2. Paquetes públicos poco conocidos: Bibliotecas de código abierto de nicho o menos populares.

Este servidor cubre esa brecha al permitir que la IA "lea" tus dependencias locales, dándole efectivamente conocimiento de tus bibliotecas privadas y poco conocidas.

Características

  • Búsqueda semántica de clases: Busca clases por nombre o propósito.
  • Búsqueda de herencia: Encuentra todas las implementaciones de una interfaz o subclases de una clase.
  • Análisis bajo demanda: Extrae firmas de métodos y Javadocs directamente de los JARs.
  • Recuperación de código fuente: Proporciona el código fuente completo si está disponible.
  • Monitoreo en tiempo real: Actualiza automáticamente el índice cuando los repositorios cambian.

Maven Indexer MCP vs CLI de Maven Indexer

Este paquete proporciona una interfaz MCP para el índice de Maven/Gradle. Si estás usando un agente de codificación en la terminal, podrías beneficiarte de usar el CLI + SKILL en su lugar.

  • CLI: Los agentes de codificación modernos favorecen cada vez más los flujos de trabajo basados en CLI expuestos como SKILLs sobre MCP porque las invocaciones de CLI son más eficientes en tokens: evitan cargar grandes esquemas de herramientas en el contexto del modelo, permitiendo que los agentes actúen a través de comandos concisos y diseñados para un propósito. Esto hace que CLI + SKILLs sean más adecuados para agentes de codificación de alto rendimiento que deben equilibrar búsquedas de dependencias con grandes bases de código y razonamiento dentro de ventanas de contexto limitadas.
    Aprende más sobre CLI de Maven Indexer con SKILLS.

  • MCP: MCP sigue siendo la mejor opción para agentes integrados en IDE (Cursor, Kiro, Windsurf, etc.) que se benefician de indexación persistente en segundo plano, monitoreo automático de repositorios e invocación de herramientas sin configuración de CLI. El servidor MCP indexa tu repositorio en segundo plano y mantiene el índice actualizado automáticamente.

Primeros pasos

Agrega la siguiente configuración a tu cliente MCP:

{
  "mcpServers": {
    "maven-indexer": {
      "command": "npx",
      "args": [
        "-y",
        "maven-indexer-mcp@latest"
      ]
    }
  }
}

Esto descargará y ejecutará automáticamente la última versión del servidor. Detectará automáticamente la ubicación de tu repositorio Maven (generalmente ~/.m2/repository) y la caché de Gradle.

Configuración del cliente MCP

Cline

Sigue la guía de MCP de Cline y usa la configuración proporcionada arriba.

Codex

Sigue la guía de configuración de MCP usando la configuración estándar de arriba.

Cursor

Haz clic en el botón para instalar:

Cursor

O instala manualmente:

Ve a Cursor Settings -> MCP -> New MCP Server. Usa la configuración proporcionada arriba.

JetBrains AI Assistant y Junie

Ve a Settings | Tools | AI Assistant | Model Context Protocol (MCP) -> Add. Usa la configuración proporcionada arriba. De la misma manera, maven-indexer se puede configurar para JetBrains Junie en Settings | Tools | Junie | MCP Settings ->Add. Usa la configuración proporcionada arriba.

Kiro

En Configuración de Kiro, ve a Configure MCP > Open Workspace or User MCP Config > Usa el fragmento de configuración proporcionado arriba.

O, desde la Barra de actividades del IDE > Kiro > MCP Servers > Click Open MCP Config. Usa el fragmento de configuración proporcionado arriba.

Qoder

En Configuración de Qoder, ve a MCP Server > + Add > Usa el fragmento de configuración proporcionado arriba.

Alternativamente, sigue la guía de MCP y usa la configuración estándar de arriba.

Trae

Ve a Settings -> MCP -> + Add -> Add Manually para agregar un servidor MCP. Usa la configuración proporcionada arriba.

Windsurf

Sigue la guía de configuración de MCP usando la configuración estándar de arriba.

Tu primer prompt

Ingresa el siguiente prompt en tu cliente MCP para verificar que todo funcione:

Find the class `StringUtils` in my local maven repository and show me its methods.

Tu cliente MCP debería leer la clase StringUtils de tu repositorio Maven local y mostrar sus métodos.

Configuración (Opcional)

Si la detección automática falla, o si quieres filtrar qué paquetes se indexan, puedes agregar variables de entorno a la configuración:

  • MAVEN_REPO: Ruta absoluta a tu repositorio Maven local (por ejemplo, /Users/yourname/.m2/repository). Usa esto si tu repositorio está en una ubicación no estándar.
  • GRADLE_REPO_PATH: Ruta absoluta a tu caché de Gradle (por ejemplo, /Users/yourname/.gradle/caches/modules-2/files-2.1).
  • INCLUDED_PACKAGES: Lista separada por comas de patrones de paquetes a indexar (por ejemplo, com.mycompany.*,org.example.*). El valor predeterminado es * (indexar todo).
  • MAVEN_INDEXER_CFR_PATH: (Opcional) Ruta absoluta a un JAR específico del descompilador CFR. Si no se proporciona, el servidor intentará usar su versión CFR incluida.
  • VERSION_RESOLUTION_STRATEGY: (Opcional) Estrategia para elegir la versión cuando se encuentran múltiples versiones de un artefacto y no se proporciona una coordenada específica.
    • semver: (Predeterminado) Prefiere la versión semántica más alta (por ejemplo, 1.2.0 > 1.1.9).
    • latest-published: Prefiere la versión con la hora de publicación más reciente (verifica *.pom.lastUpdated primero, luego la hora de modificación del archivo).
    • latest-used: Prefiere la versión importada/usada más recientemente por el usuario (basada en la hora de creación del archivo).

Ejemplo con configuración opcional:

{
  "mcpServers": {
    "maven-indexer": {
      "command": "npx",
      "args": [
        "-y",
        "maven-indexer-mcp@latest"
      ],
      "env": {
        "MAVEN_REPO": "/Users/yourname/.m2/repository",
        "GRADLE_REPO_PATH": "/Users/yourname/.gradle/caches/modules-2/files-2.1",
        "INCLUDED_PACKAGES": "com.mycompany.*",
        "MAVEN_INDEXER_CFR_PATH": "/path/to/cfr-0.152.jar",
        "VERSION_RESOLUTION_STRATEGY": "semver"
      }
    }
  }
}

Desarrollo local

Si prefieres ejecutar desde el código fuente:

  1. Clona el repositorio:

    git clone https://github.com/tangcent/maven-indexer-mcp.git
cd maven-indexer-mcp

  2. Instala las dependencias y compila:

    npm install
npm run build

  3. Usa la ruta absoluta en tu configuración:

    {
  "mcpServers": {
    "maven-indexer": {
      "command": "node",
      "args": ["/absolute/path/to/maven-indexer-mcp/build/index.js"]
    }
  }
}

Herramientas disponibles

  • search_classes: Busca clases de Java en el repositorio Maven local y las cachés de Gradle.

    • CUÁNDO USAR: 1. Código interno/privado: Necesitas encontrar una clase de una biblioteca interna de la empresa. 2. Bibliotecas poco conocidas: Estás usando una biblioteca pública menos común que la IA no conoce bien. 3. Verificación de versión: Necesitas verificar exactamente qué versión de una clase está presente localmente.

      • Nota: Para bibliotecas bien conocidas (por ejemplo, bibliotecas estándar de Java, Spring), la IA probablemente ya conoce la estructura de la clase, por lo que esta herramienta es menos crítica.

    • Ejemplos: "Muéstrame el código fuente de StringUtils", "¿Qué métodos están disponibles en DateTimeUtils?", "¿De dónde se importa esta clase?".

    • Entrada: className (por ejemplo, "StringUtils", "Analizador JSON")

    • Salida: Lista de clases coincidentes con sus artefactos.

  • get_class_details: Descompila y lee el código fuente de bibliotecas/dependencias externas. Usa esto en lugar de 'SearchCodebase' para clases que se importan pero están definidas en archivos JAR.
    • Valor clave: "No adivines qué hace la biblioteca interna—lee el código."
    • Consejo: Esencial para código interno/propietario donde la documentación es escasa o inexistente.
    • Entrada: className (obligatorio), artifactId (opcional), type ("signatures", "docs", "source")
    • Salida: Firmas de métodos, Javadocs o código fuente completo.
    • Nota: Si se omite artifactId, la herramienta selecciona automáticamente el mejor artefacto disponible (prefiriendo aquellos con código fuente adjunto).
  • search_artifacts: Busca artefactos en las cachés de Maven/Gradle por coordenada (groupId, artifactId).
  • search_implementations: Busca clases que implementen una interfaz específica o extiendan una clase específica. Útil para encontrar implementaciones de SPI en bibliotecas externas.
    • Entrada: className (por ejemplo, "java.util.List")
    • Salida: Lista de nombres de implementaciones/subclases y sus artefactos.
  • refresh_index: Activa un nuevo escaneo del repositorio Maven.

Desarrollo

  • Ejecutar pruebas: npm test
  • Modo de observación: npm run watch

Licencia

ISC