# mcp-java-decompile

**Repository Path**: kdyzm/mcp-java-decompile

## Basic Information

- **Project Name**: mcp-java-decompile
- **Description**: 一款反编译jar包的mcp，支持java8/java21和cfr/Vineflower反编译器
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-14
- **Last Updated**: 2026-06-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Java Decompile MCP Server

[![Node.js](https://img.shields.io/badge/Node.js-24.x-339933?logo=node.js)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript)](https://www.typescriptlang.org/)
[![MCP SDK](https://img.shields.io/badge/MCP_SDK-1.29+-blue)](https://github.com/modelcontextprotocol/typescript-sdk)

一个 Model Context Protocol (MCP) 服务器，用于反编译 Java JAR 文件中的类。专为 Claude Code 设计，使其在编写 Java 代码时能够直接查看第三方 JAR 包中的类定义、方法签名和源码实现。

## 功能

| 工具 | 描述 |
|------|------|
| `list_jar_contents` | 列出 JAR 文件中所有类和资源 |
| `decompile_class` | 反编译指定类的源码 |
| `search_classes` | 按名称模式搜索类（支持 `*` 通配符） |
| `decompile_package` | 反编译整个包的所有类 |
| `get_backend_info` | 查看当前反编译器后端状态 |

## 工作原理

```
┌─────────────────┐     ┌───────────────────┐     ┌──────────────────┐
│   Claude Code   │◄───►│  java-decompile   │◄───►│  Decompiler JAR  │
│   (MCP Client)  │     │  MCP Server       │     │  (Vineflower/CFR)│
└─────────────────┘     └────────┬──────────┘     └──────────────────┘
                                 │
                        ┌────────▼──────────┐
                        │   adm-zip (JS)    │
                        │  JAR 文件解析     │
                        └───────────────────┘
```

- JAR 内容浏览（列表、搜索）由 Node.js `adm-zip` 库直接处理，无需 Java 运行时
- 类反编译通过 Java 子进程执行 Vineflower/CFR JAR 完成
- 支持两种反编译器后端，可通过环境变量切换

## 环境要求

| 依赖 | 版本要求 | 说明 |
|------|---------|------|
| [Node.js](https://nodejs.org/) | ≥ 18.x | 推荐 24.x |
| [npm](https://www.npmjs.com/) | ≥ 9.x | 随 Node.js 一起安装 |
| [JDK](https://adoptium.net/) | ≥ 17 (Vineflower) / ≥ 8 (CFR) | 仅用于运行反编译器 JAR |

## 安装

### 1. 克隆或创建项目

```bash
# 在已有目录中（如果尚未初始化）
cd D:\gitRepository\projects\mcp\java-decompile

# 或者从 GitHub 克隆（如果已推送到远程）
# git clone <repo-url>
# cd java-decompile
```

### 2. 安装 Node.js 依赖

```bash
npm install
```

### 3. 下载反编译器

```bash
npm run setup
```

此命令从 Maven Central 下载两个反编译器 JAR：

| 反编译器 | 版本 | 文件 |
|----------|------|------|
| **Vineflower**（默认） | 1.12.0 | `bin/vineflower-1.12.0.jar` |
| **CFR**（备用） | 0.152 | `bin/cfr-0.152.jar` |

> 如果下载失败，可以手动从以下地址下载并放入 `bin/` 目录：
> - Vineflower: https://github.com/Vineflower/vineflower/releases
> - CFR: https://github.com/leibnitz27/cfr/releases

### 4. 编译 TypeScript

```bash
npm run build
```

编译产物在 `build/` 目录中。

### 5. 验证安装

```bash
# 下载测试 JAR
curl -sL -o D:/test.jar "https://repo1.maven.org/maven2/org/apache/commons/commons-lang3/3.14.0/commons-lang3-3.14.0.jar"

# 测试列出 JAR 内容
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_jar_contents","arguments":{"jarPath":"D:/test.jar"}}}' | node build/index.js

# 测试反编译类
export JAVA_DECOMPILE_HOME="D:/ProgramFiles/Java/jdk-21.0.11+10"
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"decompile_class","arguments":{"jarPath":"D:/test.jar","className":"org.apache.commons.lang3.StringUtils"}}}' | node build/index.js

# 清理测试文件
rm D:/test.jar
```

## 集成到 Claude Code

### 方式一：项目级配置（推荐）

在项目根目录的 `.claude/settings.json` 中添加：

```json
{
  "mcpServers": {
    "java-decompile": {
      "command": "node",
      "args": ["D:/gitRepository/projects/mcp/java-decompile/build/index.js"],
      "env": {
        "JAVA_DECOMPILE_HOME": "D:/ProgramFiles/Java/jdk-21.0.11+10",
        "DECOMPILER_BACKEND": "vineflower"
      }
    }
  }
}
```

> 本项目已包含此配置，无需手动创建。

### 方式二：全局配置

编辑 `C:\Users\<用户名>\.claude\settings.local.json`：

```json
{
  "mcpServers": {
    "java-decompile": {
      "command": "node",
      "args": ["D:/gitRepository/projects/mcp/java-decompile/build/index.js"],
      "env": {
        "JAVA_DECOMPILE_HOME": "D:/ProgramFiles/Java/jdk-21.0.11+10",
        "DECOMPILER_BACKEND": "vineflower"
      }
    }
  }
}
```

### 配置说明

| 环境变量 | 说明 | 默认值 |
|----------|------|--------|
| `JAVA_DECOMPILE_HOME` | Java 安装目录（优先使用） | → `JAVA_HOME` → `PATH` 中的 `java` |
| `DECOMPILER_BACKEND` | 反编译器后端选择 | `vineflower`（可选 `cfr`） |

### 验证集成

重启 Claude Code，如果配置正确，启动时应能看到类似提示：

```
MCP server 'java-decompile' connected successfully
```

## 使用方法

### 列出 JAR 内容

```
list_jar_contents
```

**参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| `jarPath` | string | JAR 文件的绝对路径 |

**示例：**
```
jarPath: D:/projects/my-app/libs/spring-core-6.0.jar
```

**返回：** 所有类和资源的完整列表，含数量统计。

### 反编译类

```
decompile_class
```

**参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| `jarPath` | string | JAR 文件的绝对路径 |
| `className` | string | 完全限定类名 |

**示例：**
```
jarPath: D:/projects/my-app/libs/spring-core-6.0.jar
className: org.springframework.util.StringUtils
```

**返回：** 完整 Java 源码（包含 package 声明、import、类定义和所有方法实现）。

### 搜索类

```
search_classes
```

**参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| `jarPath` | string | JAR 文件的绝对路径 |
| `pattern` | string | 搜索模式，`*` 表示通配符 |

**示例：**
```
jarPath: D:/projects/my-app/libs/spring-core-6.0.jar
pattern: *Service*
```

**返回：** 匹配的所有类名列表。

### 反编译包

```
decompile_package
```

**参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| `jarPath` | string | JAR 文件的绝对路径 |
| `packageName` | string | 包名 |

**示例：**
```
jarPath: D:/projects/my-app/libs/spring-core-6.0.jar
packageName: org.springframework.util
```

**返回：** 该包中所有类的反编译源码。

### 查看后端状态

```
get_backend_info
```

**参数：** 无

**返回：** 当前反编译器名称、JAR 路径、JAR 是否存在。

### 在 Claude Code 中的自然语言调用示例

> "Can you list the contents of `D:/libs/commons-lang3.jar`?"
>
> "Decompile `com.example.MyService` from the JAR at `D:/project/libs/my-lib.jar`"
>
> "Search for all classes matching `*Exception` in that JAR"
>
> "Show me the source code for the `org.springframework.web` package"

## 反编译器后端切换

### 使用 Vineflower（默认）

Vineflower 是默认的反编译器，支持 Java 21+ 语言特性（记录类、密封类、模式匹配、switch 表达式等），输出可读性高。

```json
{
  "env": {
    "DECOMPILER_BACKEND": "vineflower"
  }
}
```

### 使用 CFR

CFR 更加稳定成熟，支持更广泛的 Java 版本（Java 8+），适合反编译旧版本编译的类。

```json
{
  "env": {
    "DECOMPILER_BACKEND": "cfr"
  }
}
```

> **注意：** Vineflower 需要 Java 17+ 运行，CFR 只需要 Java 8+。

## 常用命令

```bash
# 安装依赖
npm install

# 下载反编译器 JAR
npm run setup

# 编译 TypeScript
npm run build

# 开发模式（直接运行 TS）
npm run dev

# 启动服务器
npm start
```

## 卸载

### 1. 移除 MCP 配置

从以下文件中删除 `java-decompile` 配置段：

- **项目配置：** `D:\gitRepository\projects\mcp\java-decompile\.claude\settings.json`
- **全局配置（如果添加过）：** `C:\Users\<用户名>\.claude\settings.local.json`

删除后，将 `mcpServers` 中的 `java-decompile` 条目完整移除：

```json
{
  "mcpServers": {
    // 删除以下内容：
    // "java-decompile": { ... }
  }
}
```

### 2. 删除项目文件

```bash
# 从上级目录删除整个项目
rm -rf D:/gitRepository/projects/mcp/java-decompile
```

### 3. 可选：清理 npm 缓存

```bash
npm cache clean --force
```

### 4. 重启 Claude Code

重新启动 Claude Code 以确保 MCP 服务器已完全断开。

## 常见问题

### Q: 启动时提示 "MCP server 'java-decompile' failed to connect"

- 检查 `JAVA_DECOMPILE_HOME` 是否正确配置
- 确认已执行 `npm run build` 且 `build/index.js` 存在
- 检查 `bin/` 目录下是否已下载反编译器 JAR

### Q: "Vineflower exited with code 1: UnsupportedClassVersionError"

Vineflower 需要 Java 17+，但当前 PATH 上的 Java 版本过旧。
设置 `JAVA_DECOMPILE_HOME` 指向 JDK 17+ 的安装目录。

### Q: "CFR exited with code 1" 或格式异常

CFR 对较复杂的类（特别是 Java 8+ 的 lambda 表达式）输出可读性可能不如 Vineflower。
推荐切换到 Vineflower 后端尝试。

### Q: 如何对类路径上的 JAR 使用相对路径？

MCP 工具要求绝对路径。可以在 Claude Code 中使用类似以下的提示：

> "The JAR is at `~/projects/my-app/libs/guava.jar`. Resolve it to an absolute path first."

Claude 会将相对路径转为绝对路径再传递给 MCP 工具。

## 技术栈

| 组件 | 技术 |
|------|------|
| MCP 框架 | `@modelcontextprotocol/sdk` |
| 验证 | `zod` |
| JAR 解析 | `adm-zip` |
| 反编译器 | Vineflower 1.12.0 / CFR 0.152 |
| 运行时 | Node.js 24, JDK 21 |
| 语言 | TypeScript 5 |

## 许可证

MIT