{
  "markdown": "<!-- mcp-name: io.github.salitaba/maven-decoder-mcp -->\n\n# Maven Decoder MCP Server\n\n[![skills.sh](https://skills.sh/b/salitaba/maven-decoder-mcp)](https://skills.sh/salitaba/maven-decoder-mcp)\n\n**Your agent guesses at library APIs it has never read. This makes it read them.**\n\nLets AI agents read the actual source of any Maven dependency — decompiles jars from\n`~/.m2` or Maven Central, and diffs versions for breaking changes.\n\n![Demo: comparing jsoup 1.17.2 with 1.23.2](docs/demo.gif)\n\nAsk an agent *\"I'm upgrading `org.jsoup:jsoup` from 1.17.2 to 1.23.2 — what breaks?\"* and\nwithout a way to read the jars it will answer from memory. With this server,\n`compare_versions` reads both jars and reports what actually changed:\n\n| | 1.17.2 → 1.23.2 |\n|---|---|\n| Breaking changes | **45** |\n| Members removed | 31 |\n| Members added | 150 |\n| Classes with API changes | 47 of 115 compared |\n\nMembers are compared **as declared**, so one that moved to a supertype is reported as\nremoved even though it may still be callable. The tool states this in its own output.\n\nIt works on artifacts that have **no sources jar** too: `extract_class_info` falls back\nto `javap` and returns parsed fields, methods, and bytecode version — which is exactly\nthe case for the internal artifacts in a corporate Nexus.\n\n### Try it in one command\n\n```bash\nnpx skills add https://github.com/salitaba/maven-decoder-mcp --skill maven-code-search\n```\n\nThat installs the `maven-code-search` agent skill, which tells your agent when to reach\nfor these tools. For a raw MCP server setup instead, see [Installation](#-installation).\n\n## 🚀 Features\n\n### Core Functionality\n- **Jar File Analysis**: Deep inspection of jar files including metadata, manifests, and structure\n- **Dependency Resolution**: Complete dependency tree analysis with transitive dependencies\n- **Source Code Extraction**: Extract source code from source jars or decompile bytecode\n- **Class Information**: Detailed class signatures, methods, fields, and annotations\n- **Search Capabilities**: Find classes, methods, and dependencies across all artifacts\n- **Version Management**: Compare versions, find dependents, and track version conflicts\n\n### Online Maven Support\n- **Maven Central Search**: Find artifacts and classes that are **not installed locally**\n- **Remote Version Listing**: See every published version, not just the ones you have\n- **On-Demand Download**: Fetch any artifact (jar, sources, POM) into a local cache\n- **Transparent Fallback**: Every analysis tool automatically downloads a missing artifact, so decompiling a dependency you never installed just works\n- **Mirror Friendly**: Point it at a corporate Nexus/Artifactory, with optional credentials\n- **Offline Mode**: A single env var restores fully local, network-free behavior\n\n### Advanced Features\n- **Decompilation Support**: Integrated support for multiple Java decompilers (CFR, Fernflower, Procyon)\n- **Conflict Analysis**: Detect and analyze dependency version conflicts\n- **Repository Navigation**: Browse and explore the local Maven repository structure\n- **Metadata Parsing**: Extract and parse Maven POM files and metadata\n- **Service Discovery**: Find and analyze Java services and SPI implementations\n- **Response Management**: Intelligent pagination and summarization for large responses\n- **Method Extraction**: Extract specific methods from large Java classes\n- **Integrity Checking**: Downloads are verified against the repository's SHA-1 checksums\n\n## 📦 Installation\n\n### Prerequisites\n- Java 8+ (for decompilation features)\n- Maven local repository (`~/.m2/repository`)\n- One of: **Python 3.8+**, **Node.js 14+**, or **Docker**\n\n### 🚀 Quick Install\n\n#### One-Line Install (Recommended)\n```bash\ncurl -fsSL https://raw.githubusercontent.com/salitaba/maven-decoder-mcp/main/install.sh | bash\n```\n\n### 📋 Installation Methods\n\n#### Method 1: uvx (Recommended)\n```bash\n# Install uv (if not installed)\ncurl -Ls https://astral.sh/uv/install.sh | sh\n# Ensure your shell PATH is updated (restart shell or eval as printed by installer)\n\n# Run the server via uvx (isolated, fast, no venv needed)\nuvx maven-decoder-mcp\n\n# Optional: pick a specific Python\n# uvx --python 3.12 maven-decoder-mcp\n```\n\n#### Method 2: Node.js/npm\n```bash\n# Install globally\nnpm install -g maven-decoder-mcp\n\n# Or install locally\nnpm install maven-decoder-mcp\n\n# Run the server\nmaven-decoder-mcp\n# or if installed locally: npx maven-decoder-mcp\n```\n\n#### Method 3: Docker\n```bash\n# Pull and run\ndocker run --rm -it \\\n  -v ~/.m2:/home/mcpuser/.m2 \\\n  -v $(pwd):/workspace \\\n  ali79taba/maven-decoder-mcp:latest\n```\n\n#### Method 4: From Source (Development)\n```bash\n# Clone repository\ngit clone https://github.com/salitaba/maven-decoder-mcp.git\ncd maven-decoder-mcp\n\n# Option A: Using Virtual Environment\npython3 -m venv .venv\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\npip install -r requirements.txt\npip install \"git+https://github.com/modelcontextprotocol/python-sdk.git\"\n./setup_decompilers.sh\n\n# Option B: System-wide Installation (not recommended)\n./setup_decompilers.sh\n```\n\n### Windows\n\nFor a source checkout, use Python 3.10 or newer and a JDK on `PATH`. From the\nrepository root, create and activate a virtual environment in PowerShell:\n\n```powershell\npython -m venv .venv\n.\\.venv\\Scripts\\Activate.ps1\npython -m pip install -e \".[dev]\"\n\n# Point to your existing local Maven repository (drive-letter paths are supported)\n$env:MAVEN_REPOSITORY = 'F:\\data\\repository'\nmaven-decoder-mcp\n```\n\nIn Command Prompt (`cmd.exe`), activate with `.venv\\Scripts\\activate.bat` and set\nthe repository with `set \"MAVEN_REPOSITORY=F:\\data\\repository\"` instead. These\nenvironment settings apply to programs launched from that terminal; set them in\nyour MCP client's environment when it launches the server separately.\n\nRemote downloads use a separate cache, resolved in this order (empty values are\nskipped):\n\n1. `MAVEN_DECODER_CACHE_DIR`: the complete cache directory; no subdirectory is appended.\n2. `XDG_CACHE_HOME`: append `maven-decoder-mcp\\repository`.\n3. `LOCALAPPDATA`: append `maven-decoder-mcp\\repository`.\n4. Otherwise, `~/.cache/maven-decoder-mcp/repository` under your home directory.\n\nOn Windows, this usually means `%LOCALAPPDATA%\\maven-decoder-mcp\\repository`;\n`XDG_CACHE_HOME` still takes precedence if set. The cache uses Maven's directory\nlayout but stays separate from the real local repository so downloads do not\ninterfere with Maven builds. Setting `MAVEN_REPOSITORY` does not change the cache\nlocation.\n\n## 🔧 Configuration\n\n### For Cursor IDE\nAdd to your `~/.cursor/mcp_servers.json`:\n\n```json\n{\n  \"maven-decoder\": {\n    \"command\": \"uvx\",\n    \"args\": [\"maven-decoder-mcp\"]\n  }\n}\n```\n\n### For Other MCP Clients\nThe server runs as a standard MCP server and can be integrated with any MCP-compatible client.\n\n## 🧠 AI Agent Skill\n\nThis 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.\n\n```bash\nnpx skills add https://github.com/salitaba/maven-decoder-mcp --skill maven-code-search\n```\n\nThe skill is located at `skills/maven-code-search` and is ready for skills.sh indexing after the repository is pushed.\n\n## 🛠️ Available Tools\n\n### Local Analysis\n\n| Tool | Description |\n|------|-------------|\n| `list_artifacts` | List artifacts in Maven repository with filtering |\n| `analyze_jar` | Analyze jar file structure and contents |\n| `extract_class_info` | Get detailed information about Java classes |\n| `get_dependencies` | Retrieve Maven dependencies from POM files |\n| `search_classes` | Search for classes across all jars, optionally filtered by annotation |\n| `extract_source_code` | Decompile and extract Java source code |\n| `extract_jar_resource` | Extract text resources such as `.proto` files, services, and metadata |\n| `compare_versions` | Compare two versions, including a public API diff and breaking changes |\n| `find_usage_examples` | Find classes that reference a given class or method |\n| `get_dependency_tree` | Get complete dependency tree |\n| `find_dependents` | Find artifacts that depend on a specific artifact |\n| `get_version_info` | Get installed versions of an artifact (set `include_remote` to add published ones) |\n| `analyze_jar_structure` | Analyze overall jar structure and metadata |\n| `extract_method_info` | Extract specific method information from Java classes |\n\n### Online (Maven Central)\n\n| Tool | Description |\n|------|-------------|\n| `search_maven_central` | Search Maven Central for artifacts by name, coordinates, or contained class |\n| `get_remote_versions` | List every version published remotely, flagging which are installed |\n| `download_artifact` | Download an artifact (jar/sources/POM) into the local cache; accepts `latest` |\n\n## 💡 Usage Examples\n\n### Finding Dependencies\n```\n\"Show me all dependencies of org.springframework:spring-core:5.3.21\"\n```\n\n### Decompiling Classes\n```\n\"Decompile the class com.example.MyService from my Maven repository\"\n```\n\n### Analyzing Conflicts\n```\n\"Find all version conflicts in my Maven repository\"\n```\n\n### Checking an Upgrade for Breaking Changes\n```\n\"Compare org.jsoup:jsoup 1.17.2 with 1.23.2 and tell me what would break\"\n```\n`compare_versions` diffs the public and protected members of every class the\ntwo versions share, and reports removals separately from additions. Removed\nmembers and removed classes are counted as breaking changes. Members are\ncompared as *declared*, so one that moved to a supertype is reported as\nremoved even though it may still be callable.\n\n### Exploring APIs\n```\n\"Show me all public methods in the Jackson ObjectMapper class\"\n```\n\n### Inspecting Compiled-Only Artifacts\n```\n\"The sources jar is missing. Use extract_class_info for bytecode-backed fields and methods.\"\n\"Find and read .proto resources from com.example:protobuf-lib:1.0.0\"\n```\n\nWhen a dependency has no sources jar, `extract_class_info` uses `javap` internally and returns parsed fields, methods, bytecode version, and optional verbose bytecode output. Agents should use `analyze_jar`, `extract_class_info`, `extract_source_code`, and `extract_jar_resource` through this MCP instead of running `jar` or `javap` directly.\n\n### Working with Large Responses\n```\n\"List all Spring classes with pagination (page 2, 10 items per page)\"\n\"Extract source code for a large class with summarization\"\n\"Get method information for specific patterns in a class\"\n```\n\n### Searching Maven Central (Online)\n```\n\"Which Maven artifact contains the class HikariDataSource?\"\n\"Search Maven Central for retrofit\"\n\"What is the newest published version of org.apache.commons:commons-lang3?\"\n\"Download com.google.code.gson:gson:latest and show me the JsonParser class\"\n```\n\n## 🌐 Online Maven Support\n\nThe server works against the local repository **and** remote repositories. Online\naccess is enabled by default.\n\n### How it works\n\n1. Every tool first looks in your local repository (`~/.m2/repository`).\n2. On a miss, the artifact is downloaded from Maven Central into a cache\n   (`~/.cache/maven-decoder-mcp/repository`) that uses the standard Maven layout.\n3. All existing analysis (decompilation, class info, dependencies) then runs on\n   the cached artifact exactly as it would on an installed one.\n\nThe cache is deliberately **separate from `~/.m2`** so downloads never interfere\nwith your Maven or Gradle builds. Responses include an `origin` field\n(`local-repository` or `remote-cache`) so you always know where a result came from.\n\n### Going offline\n\n```bash\nMAVEN_OFFLINE=true   # no network access at all; original local-only behavior\nMAVEN_AUTO_DOWNLOAD=false   # keep online search, but never auto-download\n```\n\n### Using a private mirror\n\n```bash\nMAVEN_REMOTE_REPOS=\"https://nexus.corp/repository/maven-public\"\nMAVEN_REMOTE_USERNAME=builder\nMAVEN_REMOTE_PASSWORD=secret\n```\n\n### A note on the search index\n\nArtifact **downloads** use `repo1.maven.org`, which is fast and reliable.\nArtifact **search** uses `search.maven.org`, the only public index that answers\nclass-level (`c:` / `fc:`) queries correctly. That index rate-limits bursts, so\nrequests are retried with backoff; a busy period can still surface as a timeout.\nDownloads and version listing are unaffected, because they read\n`maven-metadata.xml` directly from the repository.\n\n## 🔄 Response Management\n\n### Pagination Support\nThe server automatically handles large responses through intelligent pagination:\n\n- **Automatic Detection**: Responses exceeding 50KB are automatically paginated\n- **Configurable Page Size**: Default 20 items per page, customizable per request\n- **Pagination Metadata**: Each response includes pagination information\n- **Supported Tools**: `list_artifacts`, `extract_class_info`, `search_classes`, `get_dependencies`, `find_dependents`, `get_version_info`\n\n### Summarization Features\nLarge text content is automatically summarized to improve readability:\n\n- **Smart Summarization**: Preserves important parts (package declarations, method signatures, closing braces)\n- **Configurable Limits**: Default 10KB text limit, customizable\n- **Java-Specific**: Optimized for Java source code structure\n- **Metadata Preservation**: Original structure and metadata are maintained\n\n### Method Extraction\nNew tool for targeted access to specific methods:\n\n- **Pattern Matching**: Use regex patterns to find specific methods\n- **Limited Results**: Control the number of methods returned\n- **Full Context**: Includes method signatures, bodies, and line numbers\n- **Efficient Processing**: Only extracts requested methods, not entire classes\n\n## 🏗️ Architecture\n\nThe server is built with a modular architecture:\n\n- **`MavenDecoderServer`**: Main MCP server implementation\n- **`ResponseManager`**: Handles pagination and summarization\n- **`JavaDecompiler`**: Handles multiple decompilation strategies\n- **`MavenDependencyAnalyzer`**: Analyzes Maven dependencies and metadata\n- **`MavenCentralClient`**: Remote search, version listing, and artifact downloads\n- **Decompilers**: CFR, Procyon, Fernflower, and javap integration\n\n## 🧪 Development\n\n### Running Tests\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run specific test\npython test_startup.py\n```\n\n### Building Package\n```bash\n# Build distribution\npython setup.py sdist bdist_wheel\n\n# Install locally\npip install dist/maven_decoder_mcp-*.whl\n```\n\n### Docker Development\n```bash\n# Build Docker image\ndocker build -t maven-decoder-mcp .\n\n# Run container\ndocker run --rm -it maven-decoder-mcp\n```\n\n## 📝 Configuration Options\n\n### Environment Variables\n\n#### Local repository\n- `MAVEN_REPOSITORY` / `MAVEN_REPO`: direct path to local Maven repository (e.g. `F:\\data\\repository`). Highest precedence.\n- `MAVEN_HOME` / `M2_HOME`: Maven install dir or repository dir. A nested `repository/` subdir wins when it exists; `conf/settings.xml` `<localRepository>` honored.\n- `~/.m2/settings.xml` `<localRepository>` honored when no env var set. Fallback: `~/.m2/repository`.\n\n#### Online access\n- `MAVEN_OFFLINE`: set to `true` to disable all network access (default: `false`)\n- `MAVEN_AUTO_DOWNLOAD`: auto-fetch artifacts missing locally (default: `true`)\n- `MAVEN_REMOTE_REPOS` / `MAVEN_REMOTE_REPO`: comma/space separated repository base URLs (default: `https://repo1.maven.org/maven2`)\n- `MAVEN_SEARCH_URL`: comma/space separated Solr search endpoints (default: `https://search.maven.org/solrsearch/select`)\n- `MAVEN_DECODER_CACHE_DIR`: where downloaded artifacts are cached (default: `~/.cache/maven-decoder-mcp/repository`)\n- `MAVEN_REMOTE_USERNAME` / `MAVEN_REMOTE_PASSWORD`: basic-auth credentials for a private mirror\n- `MAVEN_HTTP_TIMEOUT`: per-request timeout in seconds (default: 30)\n- `MAVEN_HTTP_RETRIES`: retries for transient network failures (default: 3)\n- `MAVEN_MAX_DOWNLOAD_SIZE`: maximum download size in bytes (default: 104857600)\n- `MAVEN_VERIFY_CHECKSUM`: verify downloads against published SHA-1 (default: `true`)\n\n#### Responses\n- `MCP_LOG_LEVEL`: Logging level (DEBUG, INFO, WARNING, ERROR)\n- `MCP_MAX_RESPONSE_SIZE`: Maximum response size in bytes (default: 50000)\n- `MCP_MAX_ITEMS_PER_PAGE`: Default items per page (default: 20)\n- `MCP_MAX_TEXT_LENGTH`: Maximum text length before summarization (default: 10000)\n- `MCP_MAX_LINES`: Maximum lines before summarization (default: 500)\n- `MCP_USAGE_SCAN_LIMIT`: Max classes scanned by `find_usage_examples` (default: 200000)\n- `MCP_API_DIFF_LIMIT`: Max classes compared by `compare_versions` (default: 2000)\n- `MAVEN_DECODER_DECOMPILER_DIR`: Directory holding `cfr.jar` / `procyon-decompiler.jar`\n\n### Advanced Configuration\nThe server automatically detects and configures:\n- Maven repository location\n- Available Java decompilers\n- System capabilities\n\n## 🔍 Troubleshooting\n\n### Common Issues\n\n**Server won't start**\n```bash\n# Check Python installation\npython --version\n\n# Check Maven repository\nls ~/.m2/repository\n\n# Check logs\nmaven-decoder-mcp --debug\n```\n\n\n\n**Decompilation fails**\n```bash\n# Check the environment: Java, repository, cache and available decompilers\nmaven-decoder-setup status\n\n# Install the optional CFR and Procyon decompilers\nmaven-decoder-setup decompilers\n```\nWithout CFR or Procyon the server still works, falling back to `javap` from\nthe JDK for signatures, fields and methods.\n\n**No artifacts found**\n```bash\n# Verify Maven repository location\nls ~/.m2/repository\n\n# Run a Maven build to populate repository\nmvn dependency:resolve\n```\n\n**Maven Central search times out**\n\nThe public search index rate-limits bursts of requests. Retries with backoff are\nbuilt in, but during heavy throttling a search can still fail. Workarounds:\n\n```bash\n# Wait a moment and retry, or raise the retry budget\nMAVEN_HTTP_RETRIES=5\n\n# Downloads and version listing do not use the search index, so these keep\n# working even while search is throttled:\n#   get_remote_versions, download_artifact\n```\n\n**Downloads fail behind a proxy or firewall**\n```bash\n# requests honors the standard proxy variables\nexport HTTPS_PROXY=http://proxy.corp:8080\n\n# Or point at an internal mirror\nexport MAVEN_REMOTE_REPOS=\"https://nexus.corp/repository/maven-public\"\n\n# Or turn the network off entirely\nexport MAVEN_OFFLINE=true\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Model Context Protocol](https://github.com/modelcontextprotocol) - The protocol that powers this server\n- [CFR](https://github.com/leibnitz27/cfr) - Java decompiler\n- [Procyon](https://github.com/mstrobel/procyon) - Java decompiler\n- [Maven](https://maven.apache.org/) - Dependency management\n\n## 📊 Stats\n\n![GitHub Stars](https://img.shields.io/github/stars/salitaba/maven-decoder-mcp)\n![GitHub Forks](https://img.shields.io/github/forks/salitaba/maven-decoder-mcp)\n![PyPI Downloads](https://img.shields.io/pypi/dm/maven-decoder-mcp)\n![npm Downloads](https://img.shields.io/npm/dm/maven-decoder-mcp)\n![Docker Pulls](https://img.shields.io/docker/pulls/ali79taba/maven-decoder-mcp)\n\n---\n\n**Made with ❤️ for the Java development community**\n",
  "bytes": 19417,
  "sha": "e28cddadb18520954c4dbe011d467143196591273184560afce1c3027ce65b21",
  "repo_slug": "salitaba/maven-decoder-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_salitaba_maven_decoder_mcp_546fb2a3/readme"
}