Maven Decoder

Maven Decoder MCP Server

Your agent guesses at library APIs it has never read. This makes it read them.

Lets AI agents read the actual source of any Maven dependency — decompiles jars from ~/.m2 or Maven Central, and diffs versions for breaking changes.

Ask an agent *"I'm upgrading org.jsoup:jsoup from 1.17.2 to 1.23.2 — what breaks?"* and without a way to read the jars it will answer from memory. With this server, compare_versions reads both jars and reports what actually changed:

Members are compared as declared, so one that moved to a supertype is reported as removed even though it may still be callable. The tool states this in its own output.

It works on artifacts that have no sources jar too: extract_class_info falls back to javap and returns parsed fields, methods, and bytecode version — which is exactly the case for the internal artifacts in a corporate Nexus.

Try it in one command

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

That installs the maven-code-search agent skill, which tells your agent when to reach for these tools. For a raw MCP server setup instead, see Installation.

🚀 Features

Core Functionality

• Jar File Analysis: Deep inspection of jar files including metadata, manifests, and structure
• Dependency Resolution: Complete dependency tree analysis with transitive dependencies
• Source Code Extraction: Extract source code from source jars or decompile bytecode
• Class Information: Detailed class signatures, methods, fields, and annotations
• Search Capabilities: Find classes, methods, and dependencies across all artifacts
• Version Management: Compare versions, find dependents, and track version conflicts

Online Maven Support

• Maven Central Search: Find artifacts and classes that are not installed locally
• Remote Version Listing: See every published version, not just the ones you have
• On-Demand Download: Fetch any artifact (jar, sources, POM) into a local cache
• Transparent Fallback: Every analysis tool automatically downloads a missing artifact, so decompiling a dependency you never installed just works
• Mirror Friendly: Point it at a corporate Nexus/Artifactory, with optional credentials
• Offline Mode: A single env var restores fully local, network-free behavior

Advanced Features

• Decompilation Support: Integrated support for multiple Java decompilers (CFR, Fernflower, Procyon)
• Conflict Analysis: Detect and analyze dependency version conflicts
• Repository Navigation: Browse and explore the local Maven repository structure
• Metadata Parsing: Extract and parse Maven POM files and metadata
• Service Discovery: Find and analyze Java services and SPI implementations
• Response Management: Intelligent pagination and summarization for large responses
• Method Extraction: Extract specific methods from large Java classes
• Integrity Checking: Downloads are verified against the repository's SHA-1 checksums

📦 Installation

Prerequisites

• Java 8+ (for decompilation features)
• Maven local repository (~/.m2/repository)
• One of: Python 3.8+, Node.js 14+, or Docker

🚀 Quick Install

One-Line Install (Recommended)

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

📋 Installation Methods

Method 1: uvx (Recommended)

# 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

Method 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

Method 3: Docker

# Pull and run

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

Method 4: From Source (Development)

# 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

For a source checkout, use Python 3.10 or newer and a JDK on PATH. From the repository root, create and activate a virtual environment in 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

In Command Prompt (cmd.exe), activate with .venv\Scripts\activate.bat and set the repository with set "MAVEN_REPOSITORY=F:\data\repository" instead. These environment settings apply to programs launched from that terminal; set them in your MCP client's environment when it launches the server separately.

Remote downloads use a separate cache, resolved in this order (empty values are skipped):

1. MAVEN_DECODER_CACHE_DIR: the complete cache directory; no subdirectory is appended.
2. XDG_CACHE_HOME: append maven-decoder-mcp\repository.
3. LOCALAPPDATA: append maven-decoder-mcp\repository.
4. Otherwise, ~/.cache/maven-decoder-mcp/repository under your home directory.

On Windows, this usually means %LOCALAPPDATA%\maven-decoder-mcp\repository; XDG_CACHE_HOME still takes precedence if set. The cache uses Maven's directory layout but stays separate from the real local repository so downloads do not interfere with Maven builds. Setting MAVEN_REPOSITORY does not change the cache location.

🔧 Configuration

For Cursor IDE

Add to your ~/.cursor/mcp_servers.json:

{

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

For Other MCP Clients

The server runs as a standard MCP server and can be integrated with any MCP-compatible client.

🧠 AI Agent Skill

This repository includes a maven-code-search agent skill that tells AI coding agents when and how to use this MCP for searching installed Maven package code.

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

The skill is located at skills/maven-code-search and is ready for skills.sh indexing after the repository is pushed.

🛠️ Available Tools

Local Analysis

Online (Maven Central)

Tool parameters

| search_classes | limit | integer | 100 | Maximum