Java Decompiler

What is mcp-javadc?

mcp-javadc is a Model Context Protocol (MCP) server designed for decompiling Java class files. It allows AI assistants and other tools that implement the MCP protocol to convert Java bytecode back into human-readable source code. This project leverages a JavaScript port of the CFR decompiler, eliminating the need for a Java installation.

How to use mcp-javadc?

mcp-javadc can be used in several ways:

• Using npx (Recommended): npx -y @idachev/mcp-javadc
• Global Installation: Install globally with npm install -g @idachev/mcp-javadc, then run mcpjavadc.
• From Source: Clone the repository, install dependencies (npm install), and run npm start.

Once the server is running, it can be integrated with MCP clients (like Claude) by configuring the client to use the server's command. The server exposes three main tools via its MCP-compatible API:

• decompile-from-path: Decompiles a .class file from a given file path.
• decompile-from-package: Decompiles a Java class from a package name, with optional classpath specification.
• decompile-from-jar: Decompiles a Java class from a JAR file, requiring the JAR path and the class name to extract.

Key Features of mcp-javadc

• Decompiles Java .class files from file paths, package names, or JAR archives.
• Full MCP-compatible API for seamless integration with AI assistants and other tools.
• Stdio transport for easy integration.
• Clean error handling and temporary file management.
• No Java requirement, as it uses a JavaScript port of the CFR decompiler.

Use Cases of mcp-javadc

• AI Assistant Integration: Allows AI assistants to understand and work with Java bytecode by providing readable source code.
• Code Analysis: Useful for reverse engineering or understanding the functionality of compiled Java code when source code is unavailable.
• Debugging: Aids in debugging by providing insights into the compiled code's structure and logic.
• Educational Purposes: Helps in learning about Java bytecode and decompilation processes.

FAQ about mcp-javadc

Q: What are the prerequisites for running mcp-javadc? A: Node.js 16+ and npm are required. No Java installation is needed.

Q: What if I encounter issues with decompiling a specific class file? A: Ensure the class file is valid Java bytecode. You can try using decompile-from-package with an explicit classpath or decompile-from-jar with an explicit class name. Also, verify that the class names match the package structure within JARs.

Q: How can I test mcp-javadc interactively? A: You can use the official MCP Inspector tool by running npx @modelcontextprotocol/inspector node ./index.js. This provides a web interface to test the server's functionality.

Q: Does mcp-javadc support all Java versions? A: The underlying CFR decompiler (JavaScript port) is designed to work with modern Java features across all Java versions.

Q: How does mcp-javadc handle JAR files? A: When decompiling from JARs, the server creates a temporary directory, extracts the JAR contents, decompiles the specified class, and then cleans up the temporary directory.

MCP Java Decompiler Server (v1.2.4)

A Model Context Protocol (MCP) server for decompiling Java class files. This server allows AI assistants and tools that implement the MCP protocol to decompile Java bytecode into readable source code.

Features

• Decompile Java .class files from file path
• Decompile Java classes from package name (e.g., java.util.ArrayList)
• Decompile Java classes from JAR files
• Specify which class to extract from JAR files
• Full MCP-compatible API
• Stdio transport for seamless integration
• Clean error handling
• Temporary file management

Prerequisites

• Node.js 16+
• npm
• No Java requirement (using JavaScript port of CFR decompiler)

Installation

Option 1: Using npx (Recommended)

You can run the server directly with npx without installing:

# Run the server
npx -y @idachev/mcp-javadc

Option 2: Global Installation

# Install globally
npm install -g @idachev/mcp-javadc

# Run the server
mcpjavadc

Option 3: From Source

# Clone the repository
git clone https://github.com/idachev/mcp-javadc.git
cd mcp-javadc

# Install dependencies
npm install

# Run the server
npm start

Usage

Quick Start

The easiest way to run the server:

npm start

Integrating with MCP Clients

To use with an MCP client (like Claude or another MCP-compatible AI assistant):

# Configure the MCP client to use this server
npx some-mcp-client --server "node /path/to/mcp-javadc/index.js"

Adding to Claude Code

To add this tool to Claude Code:

claude mcp add javadc -s project -- npx -y @idachev/mcp-javadc

Example MCP client configuration:

{
  "mcpServers": {
    "javaDecompiler": {
      "command": "npx",
      "args": ["-y", "@idachev/mcp-javadc"],
      "env": {
        "CLASSPATH": "/path/to/java/classes"
      }
    }
  }
}

MCP Tools

The server provides three main tools:

1. decompile-from-path

Decompiles a Java .class file from a file path.

Parameters:

• classFilePath: Absolute path to the Java .class file

Example request:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "mcp.tool.execute",
  "params": {
    "tool": "decompile-from-path",
    "args": {
      "classFilePath": "/path/to/Example.class"
    }
  }
}

2. decompile-from-package

Decompiles a Java class from a package name.

Parameters:

• packageName: Fully qualified Java package and class name (e.g., java.util.ArrayList)
• classpath: (Optional) Array of classpath directories to search

Example request:

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "mcp.tool.execute",
  "params": {
    "tool": "decompile-from-package",
    "args": {
      "packageName": "java.util.ArrayList",
      "classpath": ["/path/to/rt.jar", "/path/to/classes"]
    }
  }
}

3. decompile-from-jar

Decompiles a Java class from a JAR file.

Parameters:

• jarFilePath: Absolute path to the JAR file (required)
• className: Fully qualified class name to extract from the JAR (required) (e.g., "com.example.MyClass")

Example request:

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "mcp.tool.execute",
  "params": {
    "tool": "decompile-from-jar",
    "args": {
      "jarFilePath": "/path/to/example.jar",
      "className": "com.example.MyClass"
    }
  }
}

Known Issues

Java Class Decompilation

The CFR decompiler (@run-slicer/cfr) is a JavaScript port of the popular CFR Java decompiler. It works well with:

1. Standard Java class files
2. Classes that are part of a known package structure
3. Modern Java features (all Java versions)
4. JAR files containing Java classes

If you encounter issues with a specific class file, try:

• Using the decompile-from-package tool with explicit classpath
• Using the decompile-from-jar tool with explicit class name
• Ensuring the class file is a valid Java bytecode file
• Checking for corrupt class files or JAR archives

Maven Repository Usage

When working with JAR files from Maven repositories:

• Use the find ~/.m2 -name "*dependency-name*jar" command to locate JAR files
• Filter out source and javadoc JARs using grep -v source | grep -v javadoc
• Use jar tf your-jar-file.jar | grep .class to list available classes in a JAR
• Check that class names match the package structure in the JAR

Configuration

Environment Variables

• CLASSPATH: Java classpath for finding class files (used when no classpath is specified)

Development

# Run in development mode
npm run dev

# Create test fixtures (creates sample Java class for testing)
npm run test:setup

# Run tests 
npm test

# Run linting
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

# Run with MCP Inspector for interactive testing
npx @modelcontextprotocol/inspector node ./index.js

Testing with MCP Inspector

You can use the official MCP Inspector tool to test the server functionality interactively:

# Install and run the MCP Inspector with the decompiler server
npx @modelcontextprotocol/inspector node ./index.js

The Inspector provides a user-friendly web interface that allows you to:

• List all available tools
• Execute the decompilation tools with custom parameters
• View and explore the decompiled output
• Test different inputs and error scenarios

This is especially useful for debugging and understanding the MCP server's capabilities before integrating it with other applications.

How It Works

1. The server uses the CFR decompiler (@run-slicer/cfr - a JavaScript port of the popular CFR Java decompiler)
2. When a decompile request is received, the server:
   • Reads the class file data directly or extracts it from a JAR file
   • Processes the class file with CFR decompiler
   • Returns the formatted source code
3. For JAR files, the server:
   • Creates a temporary directory for extraction
   • Extracts the JAR contents
   • Decompiles the specified class (or first class if none specified)
   • Cleans up the temporary directory

License

ISC