MCP Java Decompiler Server

What is MCP Java Decompiler Server about?

Decompiles Java bytecode—whether supplied as a standalone .class file, a fully qualified package name, or a class inside a JAR—into human‑readable Java source code. It exposes the functionality via the Model Context Protocol (MCP) so AI assistants and other MCP‑aware tools can request decompilation programmatically.

How to use MCP Java Decompiler Server?

1. Run the server (recommended):

   npx -y @idachev/mcp-javadc
   

2. Configure your MCP client to point to the server command, e.g.:

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

3. Send JSON‑RPC requests using the three provided tools (decompile‑from‑path, decompile‑from‑package, decompile‑from‑jar).

Key Features of MCP Java Decompiler Server

• Decompile a .class file directly from a filesystem path.
• Decompile by fully qualified package name with optional classpath resolution.
• Decompile a specific class from a JAR archive, handling temporary extraction automatically.
• Full MCP‑compatible JSON‑RPC API.
• Stdio transport for simple integration.
• Clean error handling and automatic temporary file cleanup.
• No Java runtime required; uses a JavaScript port of the CFR decompiler.

Use Cases of MCP Java Decompiler Server

• AI coding assistants: Enable Claude, ChatGPT, or other models to view and reason about compiled Java libraries.
• Security analysis: Quickly inspect unknown .class or JAR files for suspicious code.
• Debugging: Retrieve source code for third‑party binaries when source is unavailable.
• Education: Demonstrate bytecode‑to‑source transformations in teaching environments.
• Automation pipelines: Integrate decompilation into CI/CD steps for verification of shipped binaries.

FAQ

Q: Do I need a Java JDK installed? A: No. The server uses a pure‑JavaScript implementation of CFR, so only Node.js (v16+) is required.

Q: How do I specify custom classpaths? A: Pass a classpath array in the decompile‑from‑package request or set the CLASSPATH environment variable when starting the server.

Q: What happens if the class file is corrupted? A: The server returns a clear error message describing the failure, allowing the client to handle it gracefully.

Q: Can I run multiple instances concurrently? A: Yes. Each instance is independent; just launch additional processes with the same npx command.

Q: How do I test the server interactively? A: Use the official MCP Inspector:

npx @modelcontextprotocol/inspector node ./index.js

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