Maven Decoder MCP

Servidor MCP para inspeccionar, buscar y descompilar JARs de Maven .m2 para agentes de codificación de IA en Java.

Documentación

Servidor MCP Maven Decoder

Tu agente adivina APIs de librerías que nunca ha leído. Esto hace que las lea.

Permite que los agentes de IA lean el código fuente real de cualquier dependencia de Maven: descompila archivos JAR de ~/.m2 o Maven Central, y compara versiones para detectar cambios incompatibles.

Demo: comparing jsoup 1.17.2 with 1.23.2

Pregúntale a un agente "Estoy actualizando org.jsoup:jsoup de 1.17.2 a 1.23.2 — ¿qué se rompe?" y sin una forma de leer los JAR responderá de memoria. Con este servidor, compare_versions lee ambos JAR e informa qué cambió realmente:

	1.17.2 → 1.23.2
Cambios incompatibles	45
Miembros eliminados	31
Miembros añadidos	150
Clases con cambios de API	47 de 115 comparadas

Los miembros se comparan tal como se declaran, por lo que uno que se movió a una superclase se informa como eliminado aunque aún pueda ser invocable. La herramienta lo indica en su propia salida.

También funciona con artefactos que no tienen JAR de fuentes: extract_class_info recurre a javap y devuelve campos, métodos y versión de bytecode analizados — que es exactamente el caso de los artefactos internos en un Nexus corporativo.

Pruébalo con un solo comando

npx skills add https://github.com/salitaba/maven-decoder-mcp --skill maven-code-search

Eso instala la habilidad de agente maven-code-search, que le indica a tu agente cuándo recurrir a estas herramientas. Para una configuración de servidor MCP pura, consulta Instalación.

🚀 Características

Funcionalidad Principal

Análisis de Archivos JAR: Inspección profunda de archivos JAR, incluyendo metadatos, manifiestos y estructura
Resolución de Dependencias: Análisis completo del árbol de dependencias con dependencias transitivas
Extracción de Código Fuente: Extrae código fuente de JAR de fuentes o descompila bytecode
Información de Clases: Firmas de clases detalladas, métodos, campos y anotaciones
Capacidades de Búsqueda: Encuentra clases, métodos y dependencias en todos los artefactos
Gestión de Versiones: Compara versiones, encuentra dependientes y rastrea conflictos de versiones

Soporte Maven en Línea

Búsqueda en Maven Central: Encuentra artefactos y clases que no están instalados localmente
Listado de Versiones Remotas: Ve cada versión publicada, no solo las que tienes
Descarga Bajo Demanda: Obtén cualquier artefacto (JAR, fuentes, POM) en una caché local
Repliegue Transparente: Cada herramienta de análisis descarga automáticamente un artefacto faltante, por lo que descompilar una dependencia que nunca instalaste simplemente funciona
Compatible con Espejos: Apúntalo a un Nexus/Artifactory corporativo, con credenciales opcionales
Modo Sin Conexión: Una sola variable de entorno restaura el comportamiento completamente local y sin red

Características Avanzadas

Soporte de Descompilación: Soporte integrado para múltiples descompiladores de Java (CFR, Fernflower, Procyon)
Análisis de Conflictos: Detecta y analiza conflictos de versiones de dependencias
Navegación de Repositorios: Explora y navega la estructura del repositorio Maven local
Análisis de Metadatos: Extrae y analiza archivos POM de Maven y metadatos
Descubrimiento de Servicios: Encuentra y analiza servicios Java e implementaciones SPI
Gestión de Respuestas: Paginación y resumen inteligentes para respuestas grandes
Extracción de Métodos: Extrae métodos específicos de clases Java grandes
Verificación de Integridad: Las descargas se verifican contra las sumas de verificación SHA-1 del repositorio

📦 Instalación

Requisitos Previos

Java 8+ (para funciones de descompilación)
Repositorio local de Maven (~/.m2/repository)
Uno de: Python 3.8+, Node.js 14+, o Docker

🚀 Instalación Rápida

Instalación de Una Línea (Recomendada)

curl -fsSL https://raw.githubusercontent.com/salitaba/maven-decoder-mcp/main/install.sh | bash

📋 Métodos de Instalación

Método 1: uvx (Recomendado)

# Install uv (if not installed)
curl -Ls https://astral.sh/uv/install.sh | sh
# Ensure your shell PATH is updated (restart shell or eval as printed by installer)

# Run the server via uvx (isolated, fast, no venv needed)
uvx maven-decoder-mcp

# Optional: pick a specific Python
# uvx --python 3.12 maven-decoder-mcp

Método 2: Node.js/npm

# Install globally
npm install -g maven-decoder-mcp

# Or install locally
npm install maven-decoder-mcp

# Run the server
maven-decoder-mcp
# or if installed locally: npx maven-decoder-mcp

Método 3: Docker

# Pull and run
docker run --rm -it \
  -v ~/.m2:/home/mcpuser/.m2 \
  -v $(pwd):/workspace \
  ali79taba/maven-decoder-mcp:latest

Método 4: Desde el Código Fuente (Desarrollo)

# Clone repository
git clone https://github.com/salitaba/maven-decoder-mcp.git
cd maven-decoder-mcp

# Option A: Using Virtual Environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install "git+https://github.com/modelcontextprotocol/python-sdk.git"
./setup_decompilers.sh

# Option B: System-wide Installation (not recommended)
./setup_decompilers.sh

Windows

Para una copia del código fuente, usa Python 3.10 o más reciente y un JDK en PATH. Desde la raíz del repositorio, crea y activa un entorno virtual en PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

# Point to your existing local Maven repository (drive-letter paths are supported)
$env:MAVEN_REPOSITORY = 'F:\data\repository'
maven-decoder-mcp

En el Símbolo del Sistema (cmd.exe), actívalo con .venv\Scripts\activate.bat y establece el repositorio con set "MAVEN_REPOSITORY=F:\data\repository" en su lugar. Estos ajustes de entorno se aplican a los programas iniciados desde ese terminal; configúralos en el entorno de tu cliente MCP cuando inicie el servidor por separado.

Las descargas remotas usan una caché separada, resuelta en este orden (los valores vacíos se omiten):

MAVEN_DECODER_CACHE_DIR: el directorio de caché completo; no se añade ningún subdirectorio.
XDG_CACHE_HOME: añade maven-decoder-mcp\repository.
LOCALAPPDATA: añade maven-decoder-mcp\repository.
De lo contrario, ~/.cache/maven-decoder-mcp/repository en tu directorio de usuario.

En Windows, esto normalmente significa %LOCALAPPDATA%\maven-decoder-mcp\repository; XDG_CACHE_HOME aún tiene prioridad si está configurado. La caché usa la estructura de directorios de Maven pero permanece separada del repositorio local real para que las descargas no interfieran con las compilaciones de Maven. Configurar MAVEN_REPOSITORY no cambia la ubicación de la caché.

🔧 Configuración

Para el IDE Cursor

Añade a tu ~/.cursor/mcp_servers.json:

{
  "maven-decoder": {
    "command": "uvx",
    "args": ["maven-decoder-mcp"]
  }
}

Para Otros Clientes MCP

El servidor se ejecuta como un servidor MCP estándar y se puede integrar con cualquier cliente compatible con MCP.

🧠 Habilidad de Agente de IA

Este repositorio incluye una habilidad de agente maven-code-search que les indica a los agentes de codificación de IA cuándo y cómo usar este MCP para buscar código de paquetes Maven instalados.

npx skills add https://github.com/salitaba/maven-decoder-mcp --skill maven-code-search

La habilidad se encuentra en skills/maven-code-search y está lista para la indexación de skills.sh después de que se suba el repositorio.

🛠️ Herramientas Disponibles

Análisis Local

Herramienta	Descripción
`list_artifacts`	Lista artefactos en el repositorio Maven con filtrado
`analyze_jar`	Analiza la estructura y el contenido de archivos JAR
`extract_class_info`	Obtén información detallada sobre clases Java
`get_dependencies`	Recupera dependencias de Maven de archivos POM
`search_classes`	Busca clases en todos los JAR, opcionalmente filtradas por anotación
`extract_source_code`	Descompila y extrae código fuente de Java
`extract_jar_resource`	Extrae recursos de texto como archivos `.proto`, servicios y metadatos
`compare_versions`	Compara dos versiones, incluyendo un diff de API pública y cambios incompatibles
`find_usage_examples`	Encuentra clases que referencian una clase o método dado
`get_dependency_tree`	Obtén el árbol de dependencias completo
`find_dependents`	Encuentra artefactos que dependen de un artefacto específico
`get_version_info`	Obtén las versiones instaladas de un artefacto (configura `include_remote` para añadir las publicadas)
`analyze_jar_structure`	Analiza la estructura general del JAR y los metadatos
`extract_method_info`	Extrae información de métodos específicos de clases Java

En Línea (Maven Central)

Herramienta	Descripción
`search_maven_central`	Busca en Maven Central artefactos por nombre, coordenadas o clase contenida
`get_remote_versions`	Lista cada versión publicada remotamente, marcando cuáles están instaladas
`download_artifact`	Descarga un artefacto (JAR/fuentes/POM) en la caché local; acepta `latest`

Parámetros de las herramientas

Herramienta	Parámetro	Tipo	Predeterminado	Descripción
`list_artifacts`	`group_id`	string	—	Filtrar por ID de grupo (p. ej., 'org.springframework')
`list_artifacts`	`artifact_id`	string	—	Filtrar por ID de artefacto (p. ej., 'spring-core')
`list_artifacts`	`version`	string	—	Filtrar por versión (p. ej., '5.3.21')
`list_artifacts`	`sort_by`	string	name	Ordenar resultados por: 'name' (grupo/artefacto/versión ascendente, predeterminado), 'size' (primeros los JAR más grandes) o 'modified' (primeros los modificados más recientemente). Los valores desconocidos usan 'name'.
`list_artifacts`	`limit`	integer	50	Número máximo de artefactos a devolver
`list_artifacts`	`page`	integer	1	Número de página para la paginación
`list_artifacts`	`items_per_page`	integer	20	Elementos por página
`analyze_jar`	`group_id`*	string	—	ID de grupo de Maven
`analyze_jar`	`artifact_id`*	string	—	ID de artefacto de Maven
`analyze_jar`	`version`*	string	—	Versión de Maven
`analyze_jar`	`include_bytecode`	boolean	False	Incluir análisis de bytecode
`analyze_jar`	`include_manifest`	boolean	True	Incluir manifiesto del JAR
`analyze_jar`	`summarize_large_content`	boolean	True	Resumir contenido extenso automáticamente
`extract_class_info`	`group_id`*	string	—	ID de grupo de Maven
`extract_class_info`	`artifact_id`*	string	—	ID de artefacto de Maven
`extract_class_info`	`version`*	string	—	Versión de Maven
`extract_class_info`	`class_pattern`	string	—	Patrón para coincidir nombres de clase (admite expresiones regulares)
`extract_class_info`	`include_methods`	boolean	True	Incluir firmas de métodos
`extract_class_info`	`include_fields`	boolean	True	Incluir información de campos
`extract_class_info`	`include_bytecode`	boolean	False	Incluir salida detallada de bytecode javap para las clases coincidentes
`extract_class_info`	`page`	integer	1	Número de página para la paginación
`extract_class_info`	`items_per_page`	integer	20	Elementos por página
`extract_class_info`	`summarize_large_content`	boolean	True	Resumir contenido extenso automáticamente
`get_dependencies`	`group_id`*	string	—	ID de grupo de Maven
`get_dependencies`	`artifact_id`*	string	—	ID de artefacto de Maven
`get_dependencies`	`version`*	string	—	Versión de Maven
`get_dependencies`	`include_transitive`	boolean	False	Incluir dependencias transitivas
`get_dependencies`	`page`	integer	1	Número de página para la paginación
`get_dependencies`	`items_per_page`	integer	20	Elementos por página
`search_classes`	`class_name`	string	—	Nombre de clase a buscar (admite comodines)
`search_classes`	`package_pattern`	string	—	Patrón de paquete para filtrar
`search_classes`	`annotation`	string	—	Buscar clases con una anotación específica
`search_classes`	`case_sensitive`	boolean	True	Coincidir class_name y package_pattern distinguiendo mayúsculas. Establecer false para una búsqueda sin distinguir mayúsculas (p. ej., 'arraylist' coincide con 'ArrayList').
`search_classes`	`limit`	integer	100	Máximo de resultados a devolver
`search_classes`	`page`	integer	1	Número de página para la paginación
`search_classes`	`items_per_page`	integer	20	Elementos por página
`extract_source_code`	`group_id`*	string	—	ID de grupo de Maven
`extract_source_code`	`artifact_id`*	string	—	ID de artefacto de Maven
`extract_source_code`	`version`*	string	—	Versión de Maven
`extract_source_code`	`class_name`*	string	—	Nombre de clase totalmente calificado
`extract_source_code`	`prefer_sources`	boolean	True	Preferir el JAR de fuentes sobre la descompilación
`extract_source_code`	`summarize_large_content`	boolean	True	Resumir contenido extenso automáticamente
`extract_source_code`	`max_lines`	integer	500	Máximo de líneas a devolver (0 para todas)
`extract_jar_resource`	`group_id`*	string	—	ID de grupo de Maven
`extract_jar_resource`	`artifact_id`*	string	—	ID de artefacto de Maven
`extract_jar_resource`	`version`*	string	—	Versión de Maven
`extract_jar_resource`	`resource_path`	string	—	Ruta exacta del recurso dentro del JAR
`extract_jar_resource`	`resource_pattern`	string	—	Patrón de expresión regular para coincidir rutas de recursos
`extract_jar_resource`	`max_bytes`	integer	65536	Máximo de bytes a leer por recurso
`extract_jar_resource`	`limit`	integer	20	Máximo de recursos coincidentes a devolver
`compare_versions`	`group_id`*	string	—	ID de grupo de Maven
`compare_versions`	`artifact_id`*	string	—	ID de artefacto de Maven
`compare_versions`	`version1`*	string	—	Primera versión (más antigua) a comparar
`compare_versions`	`version2`*	string	—	Segunda versión (más nueva) a comparar
`compare_versions`	`compare_api`	boolean	True	Comparar la API pública: métodos y campos públicos y protegidos añadidos/eliminados, y cambios incompatibles
`compare_versions`	`resolve_inherited`	boolean	False	Reclasificar los miembros que desaparecieron de una clase pero que aún se declaran en un supertipo dentro del nuevo JAR en un grupo 'movido a supertipo' en lugar de contarlos como eliminaciones incompatibles. Predeterminado false (byte-idéntico a la comparación tal como se declara).
`compare_versions`	`summarize_large_content`	boolean	True	Resumir contenido extenso automáticamente
`find_usage_examples`	`class_name`*	string	—	Nombre de clase para encontrar su uso
`find_usage_examples`	`method_name`	string	—	Nombre de método para encontrar su uso
`find_usage_examples`	`search_tests`	boolean	True	Buscar en JAR de pruebas
`find_usage_examples`	`limit`	integer	50	Máximo de resultados a devolver
`find_usage_examples`	`page`	integer	1	Número de página para la paginación
`find_usage_examples`	`items_per_page`	integer	20	Elementos por página
`get_dependency_tree`	`group_id`*	string	—	ID de grupo de Maven
`get_dependency_tree`	`artifact_id`*	string	—	ID de artefacto de Maven
`get_dependency_tree`	`version`*	string	—	Versión de Maven
`get_dependency_tree`	`max_depth`	integer	3	Profundidad máxima a mostrar
`get_dependency_tree`	`summarize_large_content`	boolean	True	Resumir contenido extenso automáticamente
`find_dependents`	`group_id`*	string	—	ID de grupo de destino
`find_dependents`	`artifact_id`*	string	—	ID de artefacto de destino
`find_dependents`	`version`	string	—	Versión específica a buscar (opcional)
`find_dependents`	`limit`	integer	100	Máximo de resultados a devolver
`find_dependents`	`page`	integer	1	Número de página para la paginación
`find_dependents`	`items_per_page`	integer	20	Elementos por página
`get_version_info`	`group_id`*	string	—	ID de grupo de Maven
`get_version_info`	`artifact_id`*	string	—	ID de artefacto de Maven
`get_version_info`	`include_remote`	boolean	False	También listar versiones publicadas en el repositorio remoto (no solo las instaladas)
`get_version_info`	`limit`	integer	50	Máximo de versiones a devolver
`get_version_info`	`page`	integer	1	Número de página para la paginación
`get_version_info`	`items_per_page`	integer	20	Elementos por página
`analyze_jar_structure`	`group_id`*	string	—	ID de grupo de Maven
`analyze_jar_structure`	`artifact_id`*	string	—	ID de artefacto de Maven
`analyze_jar_structure`	`version`*	string	—	Versión de Maven
`analyze_jar_structure`	`summarize_large_content`	boolean	True	Resumir contenido extenso automáticamente
`extract_method_info`	`group_id`*	string	—	ID de grupo de Maven
`extract_method_info`	`artifact_id`*	string	—	ID de artefacto de Maven
`extract_method_info`	`version`*	string	—	Versión de Maven
`extract_method_info`	`class_name`*	string	—	Nombre de clase totalmente calificado
`extract_method_info`	`method_pattern`	string	—	Patrón para coincidir nombres de método (admite expresiones regulares)
`extract_method_info`	`include_bytecode`	boolean	False	Incluir análisis de bytecode
`extract_method_info`	`max_methods`	integer	10	Máximo de métodos a devolver
`search_maven_central`	`query`	string	—	Término de búsqueda de texto libre (p. ej., 'jackson databind')
`search_maven_central`	`group_id`	string	—	Filtro exacto de ID de grupo (p. ej., 'org.springframework')
`search_maven_central`	`artifact_id`	string	—	Filtro exacto de ID de artefacto (p. ej., 'spring-core')
`search_maven_central`	`class_name`	string	—	Nombre de clase simple para encontrar el artefacto que la contiene (p. ej., 'ObjectMapper')
`search_maven_central`	`fully_qualified_class`	string	—	Nombre de clase totalmente calificado (p. ej., 'com.fasterxml.jackson.databind.ObjectMapper')
`search_maven_central`	`packaging`	string	—	Filtro de empaquetado (p. ej., 'jar', 'pom')
`search_maven_central`	`all_versions`	boolean	False	Devolver cada versión publicada en lugar de solo la más reciente por artefacto
`search_maven_central`	`limit`	integer	20	Máximo de resultados a devolver (máx. 200)
`search_maven_central`	`page`	integer	1	Número de página para la paginación
`get_remote_versions`	`group_id`*	string	—	ID de grupo de Maven
`get_remote_versions`	`artifact_id`*	string	—	ID de artefacto de Maven
`get_remote_versions`	`include_snapshots`	boolean	True	Incluir versiones -SNAPSHOT. Establecer false para listar solo versiones publicadas.
`get_remote_versions`	`limit`	integer	100	Máximo de versiones a devolver
`download_artifact`	`group_id`*	string	—	ID de grupo de Maven
`download_artifact`	`artifact_id`*	string	—	ID de artefacto de Maven
`download_artifact`	`version`*	string	—	Versión a descargar, o 'latest' para la versión más reciente
`download_artifact`	`include_sources`	boolean	True	También descargar el JAR de fuentes cuando esté publicado
`download_artifact`	`include_javadoc`	boolean	False	También descargar el JAR de javadoc cuando esté publicado
`download_artifact`	`classifier`	string	—	Descargar un JAR clasificado específico en lugar del principal
`download_artifact`	`force`	boolean	False	Volver a descargar incluso cuando el archivo ya está en caché

* Obligatorio: el parámetro aparece en el array inputSchema required de la herramienta. Los parámetros sin * son opcionales y pueden omitirse.

💡 Ejemplos de uso

Encontrar dependencias

"Show me all dependencies of org.springframework:spring-core:5.3.21"

Descompilar clases

"Decompile the class com.example.MyService from my Maven repository"

Analizar conflictos

"Find all version conflicts in my Maven repository"

Comprobar si una actualización tiene cambios incompatibles

"Compare org.jsoup:jsoup 1.17.2 with 1.23.2 and tell me what would break"

compare_versions compara los miembros públicos y protegidos de cada clase que comparten las dos versiones, e informa de las eliminaciones por separado de las adiciones. Los miembros eliminados y las clases eliminadas se cuentan como cambios incompatibles. Los miembros se comparan tal como se declaran, por lo que uno que se movió a un supertipo se informa como eliminado aunque aún pueda ser invocable.

Explorar APIs

"Show me all public methods in the Jackson ObjectMapper class"

Encontrar llamadores reales

"Find classes that call ObjectMapper.readValue, including examples from test jars"

find_usage_examples escanea los grupos de constantes de las clases compiladas, por lo que encuentra llamadores reales en lugar de simples coincidencias de nombre. Pase method_name (como readValue) para acotar los resultados a los llamadores de un método específico. Los JAR de pruebas se incluyen de forma predeterminada y se clasifican primero porque suelen contener los ejemplos más claros; establezca search_tests en false para excluirlos. El escaneo se detiene después de MCP_USAGE_SCAN_LIMIT clases (predeterminado: 200000) para mantenerse receptivo en repositorios grandes.

Inspeccionar artefactos solo compilados

"The sources jar is missing. Use extract_class_info for bytecode-backed fields and methods."
"Find and read .proto resources from com.example:protobuf-lib:1.0.0"

Cuando una dependencia no tiene un jar de fuentes, extract_class_info usa javap internamente y devuelve campos analizados, métodos, versión de bytecode y salida de bytecode verbose opcional. Los agentes deben usar analyze_jar, extract_class_info, extract_source_code y extract_jar_resource a través de este MCP en lugar de ejecutar jar o javap directamente.

Trabajando con Respuestas Grandes

"List all Spring classes with pagination (page 2, 10 items per page)"
"Extract source code for a large class with summarization"
"Get method information for specific patterns in a class"

Buscando en Maven Central (En línea)

"Which Maven artifact contains the class HikariDataSource?"
"Search Maven Central for retrofit"
"What is the newest published version of org.apache.commons:commons-lang3?"
"Download com.google.code.gson:gson:latest and show me the JsonParser class"

🌐 Soporte de Maven en Línea

El servidor funciona con el repositorio local y repositorios remotos. El acceso en línea está habilitado por defecto.

Cómo funciona

Cada herramienta primero busca en tu repositorio local (~/.m2/repository).
Si no se encuentra, el artefacto se descarga desde Maven Central a una caché (~/.cache/maven-decoder-mcp/repository) que utiliza la estructura estándar de Maven.
Todo el análisis existente (descompilación, información de clases, dependencias) se ejecuta entonces sobre el artefacto en caché exactamente igual que lo haría sobre uno instalado.

La caché está deliberadamente separada de ~/.m2 para que las descargas nunca interfieran con tus compilaciones de Maven o Gradle. Las respuestas incluyen un campo origin (local-repository o remote-cache) para que siempre sepas de dónde proviene un resultado.

Modo sin conexión

MAVEN_OFFLINE=true   # no network access at all; original local-only behavior
MAVEN_AUTO_DOWNLOAD=false   # keep online search, but never auto-download

Usando un espejo privado

MAVEN_REMOTE_REPOS="https://nexus.corp/repository/maven-public"
MAVEN_REMOTE_USERNAME=builder
MAVEN_REMOTE_PASSWORD=secret

Nota sobre el índice de búsqueda

Las descargas de artefactos usan repo1.maven.org, que es rápido y confiable. La búsqueda de artefactos usa search.maven.org, el único índice público que responde correctamente consultas a nivel de clase (c: / fc:). Ese índice limita la velocidad de ráfagas, por lo que las solicitudes se reintentan con retroceso; un período ocupado aún puede manifestarse como un tiempo de espera agotado. Las descargas y el listado de versiones no se ven afectados, porque leen maven-metadata.xml directamente del repositorio.

🔄 Gestión de Respuestas

Soporte de Paginación

El servidor maneja automáticamente respuestas grandes mediante paginación inteligente:

Detección Automática: Las respuestas que superan los 50KB se paginan automáticamente
Tamaño de Página Configurable: 20 elementos por página por defecto, personalizable por solicitud
Metadatos de Paginación: Cada respuesta incluye información de paginación
Herramientas Soportadas: list_artifacts, extract_class_info, search_classes, get_dependencies, find_dependents, get_version_info

Funciones de Resumen

El contenido de texto grande se resume automáticamente para mejorar la legibilidad:

Resumen Inteligente: Conserva partes importantes (declaraciones de paquete, firmas de métodos, llaves de cierre)
Límites Configurables: Límite de texto de 10KB por defecto, personalizable
Específico para Java: Optimizado para la estructura del código fuente de Java
Preservación de Metadatos: La estructura original y los metadatos se mantienen

Extracción de Métodos

Nueva herramienta para acceso específico a métodos concretos:

Coincidencia de Patrones: Usa patrones regex para encontrar métodos específicos
Resultados Limitados: Controla el número de métodos devueltos
Contexto Completo: Incluye firmas de métodos, cuerpos y números de línea
Procesamiento Eficiente: Solo extrae los métodos solicitados, no clases completas

🏗️ Arquitectura

El servidor está construido con una arquitectura modular:

MavenDecoderServer: Implementación principal del servidor MCP
ResponseManager: Maneja la paginación y el resumen
JavaDecompiler: Maneja múltiples estrategias de descompilación
MavenDependencyAnalyzer: Analiza dependencias y metadatos de Maven
MavenCentralClient: Búsqueda remota, listado de versiones y descargas de artefactos
Descompiladores: Integración de CFR, Procyon, Fernflower y javap

🧪 Desarrollo

Ejecutando Pruebas

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run specific test
python test_startup.py

Construyendo el Paquete

# Build distribution
python setup.py sdist bdist_wheel

# Install locally
pip install dist/maven_decoder_mcp-*.whl

Desarrollo con Docker

# Build Docker image
docker build -t maven-decoder-mcp .

# Run container
docker run --rm -it maven-decoder-mcp

📝 Opciones de Configuración

Variables de Entorno

Repositorio local

MAVEN_REPOSITORY / MAVEN_REPO: ruta directa al repositorio local de Maven (ej. F:\data\repository). Mayor precedencia.
MAVEN_HOME / M2_HOME: directorio de instalación de Maven o directorio del repositorio. Un subdirectorio repository/ anidado tiene prioridad cuando existe; conf/settings.xml <localRepository> se respetan.
~/.m2/settings.xml <localRepository> se respetan cuando no hay variable de entorno establecida. Respaldo: ~/.m2/repository.

Acceso en línea

MAVEN_OFFLINE: establece en true para deshabilitar todo acceso a la red (por defecto: false)
MAVEN_AUTO_DOWNLOAD: obtiene automáticamente artefactos que faltan localmente (por defecto: true)
MAVEN_REMOTE_REPOS / MAVEN_REMOTE_REPO: URLs base del repositorio separadas por comas/espacios (por defecto: https://repo1.maven.org/maven2)
MAVEN_SEARCH_URL: endpoints de búsqueda Solr separados por comas/espacios (por defecto: https://search.maven.org/solrsearch/select)
MAVEN_DECODER_CACHE_DIR: dónde se almacenan en caché los artefactos descargados (por defecto: ~/.cache/maven-decoder-mcp/repository)
MAVEN_REMOTE_USERNAME / MAVEN_REMOTE_PASSWORD: credenciales de autenticación básica para un espejo privado
MAVEN_HTTP_TIMEOUT: tiempo de espera por solicitud en segundos (por defecto: 30)
MAVEN_HTTP_RETRIES: reintentos para fallos de red transitorios (por defecto: 3)
MAVEN_MAX_DOWNLOAD_SIZE: tamaño máximo de descarga en bytes (por defecto: 104857600)
MAVEN_VERIFY_CHECKSUM: verifica las descargas contra el SHA-1 publicado (por defecto: true)

Respuestas

MCP_LOG_LEVEL: Nivel de registro (DEBUG, INFO, WARNING, ERROR)
MCP_MAX_RESPONSE_SIZE: Tamaño máximo de respuesta en bytes (por defecto: 50000)
MCP_MAX_ITEMS_PER_PAGE: Elementos por página por defecto (por defecto: 20)
MCP_MAX_TEXT_LENGTH: Longitud máxima de texto antes del resumen (por defecto: 10000)
MCP_MAX_LINES: Máximo de líneas antes del resumen (por defecto: 500)
MCP_USAGE_SCAN_LIMIT: Máximo de clases escaneadas por find_usage_examples (por defecto: 200000)
MCP_API_DIFF_LIMIT: Máximo de clases comparadas por compare_versions (por defecto: 2000)
MAVEN_DECODER_DECOMPILER_DIR: Directorio que contiene cfr.jar / procyon-decompiler.jar

Configuración Avanzada

El servidor detecta y configura automáticamente:

Ubicación del repositorio de Maven
Descompiladores de Java disponibles
Capacidades del sistema

🔍 Solución de Problemas

Problemas Comunes

El servidor no se inicia

# Check Python installation
python --version

# Check Maven repository
ls ~/.m2/repository

# Check logs
maven-decoder-mcp --debug

La descompilación falla

# Check the environment: Java, repository, cache and available decompilers
maven-decoder-setup status

# Install the optional CFR and Procyon decompilers
maven-decoder-setup decompilers

Desde un checkout del código fuente puedes ejecutar ./setup_decompilers.sh, que descarga CFR y Procyon en un directorio decompilers/ junto al script, como decompilers/cfr.jar y decompilers/procyon-decompiler.jar.

Si maven-decoder-setup status informa que no hay descompiladores aunque tengas los jars, están en un lugar donde el servidor no busca. Busca en estas raíces en orden, tomando la primera coincidencia:

$MAVEN_DECODER_DECOMPILER_DIR, si está establecido
decompilers/ dentro del paquete instalado
decompilers/ junto al paquete — la estructura del checkout del código fuente
~/.cache/maven-decoder-mcp/decompilers
decompilers/ en el directorio de trabajo actual
el directorio de trabajo actual en sí mismo

Tu cliente MCP inicia el servidor desde un directorio de trabajo arbitrario, por lo que los últimos dos son poco confiables en la práctica. Si tus jars están en cualquier otro lugar, apunta a ellos explícitamente:

export MAVEN_DECODER_DECOMPILER_DIR=~/tools/decompilers

El directorio debe contener los jars con los nombres exactos cfr.jar y procyon-decompiler.jar. El valor expande ~ y variables de entorno.

Sin CFR o Procyon el servidor sigue funcionando, recurriendo a javap del JDK para firmas, campos y métodos.

No se encuentran artefactos

# Verify Maven repository location
ls ~/.m2/repository

# Run a Maven build to populate repository
mvn dependency:resolve

La búsqueda en Maven Central agota el tiempo de espera

El índice de búsqueda público limita la velocidad de ráfagas de solicitudes. Los reintentos con retroceso están integrados, pero durante una limitación intensa una búsqueda aún puede fallar. Soluciones alternativas:

# Wait a moment and retry, or raise the retry budget
MAVEN_HTTP_RETRIES=5

# Downloads and version listing do not use the search index, so these keep
# working even while search is throttled:
#   get_remote_versions, download_artifact

Las descargas fallan detrás de un proxy o firewall

# requests honors the standard proxy variables
export HTTPS_PROXY=http://proxy.corp:8080

# Or point at an internal mirror
export MAVEN_REMOTE_REPOS="https://nexus.corp/repository/maven-public"

# Or turn the network off entirely
export MAVEN_OFFLINE=true

🤝 Contribuciones

Haz un fork del repositorio
Crea una rama de características (git checkout -b feature/amazing-feature)
Haz commit de tus cambios (git commit -m 'Add amazing feature')
Haz push a la rama (git push origin feature/amazing-feature)
Abre una Solicitud de Extracción (Pull Request)

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

🙏 Agradecimientos

Model Context Protocol - El protocolo que impulsa este servidor
CFR - Descompilador de Java
Procyon - Descompilador de Java
Maven - Gestión de dependencias

📊 Estadísticas

GitHub Stars GitHub Forks PyPI Downloads npm Downloads Docker Pulls

Hecho con ❤️ para la comunidad de desarrollo de Java