Metadata-Version: 2.4
Name: java-class-analyzer-mcp
Version: 0.1.1
Summary: MCP server for scanning Maven dependencies and decompiling Java classes
Author: java-class-analyzer-mcp contributors
License-Expression: MIT
Keywords: mcp,java,decompiler,maven
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp[cli]>=1.26.0
Requires-Dist: click>=8.0.0
Requires-Dist: twine>=6.2.0

# Java Class Analyzer MCP

一个基于 Model Context Protocol (MCP) 的 Java 类分析服务，可以扫描 Maven 项目依赖、反编译 Java 类文件、获取 class 方法列表等详细信息，并提供给 LLM 进行代码分析。

## 适用场景

Cursor 等 AI 工具直接生成调用二方（内部调用）、三方包（外部调用）接口的代码，但因 AI 无法读取未在当前工程中打开的依赖源码，导致生成的代码错误频出，甚至出现幻觉式编码。

为解决此问题，一般会直接拷贝源码内容喂给 LLM；或者先将源码文件放到当前工程内，再在对话中引用。

而使用本地反编译 MCP 方案最有效，能精准解析 jar 包中的类与方法，显著提升代码生成的准确性和可用性。

## 功能特性

- **使用方便**：基于 Python 实现，通过 `pip install` 一键安装，内置 CFR 反编译工具，无需手动下载
- **依赖扫描**：自动扫描 Maven 项目的所有依赖 JAR 包
- **类索引**：建立类全名到 JAR 包路径的映射索引
- **反编译**：使用内置 CFR 工具实时反编译 .class 文件为 Java 源码
- **类分析**：分析 Java 类的结构、方法、字段、继承关系等
- **智能缓存**：按包名结构缓存反编译结果，支持缓存控制
- **自动索引**：执行分析前自动检查并创建索引
- **LLM 集成**：通过 MCP 协议为 LLM 提供 Java 代码分析能力

## 安装说明

### 环境要求

- Python 3.11+
- Java Development Kit (JDK) 8+（用于运行 CFR 反编译工具）
- Maven 3.6+

### 安装

```bash
pip install java-class-analyzer-mcp
```

CFR 反编译工具已内置于包中，无需手动下载。

## MCP 服务配置

### Cursor / 通用 MCP 客户端配置

在 MCP 客户端配置文件中添加以下内容：

```json
{
  "mcpServers": {
    "java-class-analyzer": {
      "command": "java-class-analyzer-mcp",
      "env": {
        "LOG_LEVEL": "INFO",
        "MAVEN_REPO": "~/.m2/repository",
        "JAVA_HOME": "/path/to/your/jdk",
        "CFR_PATH": ""
      }
    }
  }
}
```

### OpenCode 配置示例

```json
{
  "mcp": {
    "java-class-analyzer": {
      "command": ["java-class-analyzer-mcp"],
      "enabled": true,
      "environment": {
        "LOG_LEVEL": "INFO",
        "MAVEN_REPO": "~/.m2/repository",
        "JAVA_HOME": "",
        "CFR_PATH": "",
        "CLASS_PACKAGE_PREFIXES": ""
      },
      "type": "local"
    }
  }
}
```

### 环境变量说明

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `LOG_LEVEL` | 日志级别（`INFO` 静默，`DEBUG` 详细） | `INFO` |
| `MAVEN_REPO` | Maven 本地仓库路径 | `~/.m2/repository` |
| `JAVA_HOME` | Java 安装路径（留空则使用 PATH 中的 java） | 空 |
| `CFR_PATH` | CFR jar 包路径（留空则使用内置 jar） | 空 |
| `CLASS_PACKAGE_PREFIXES` | 只索引指定包名前缀的类，多个用逗号分隔（如 `com.example,org.foo`）；留空则索引全部类 | 空 |

## 项目结构

```
java-class-analyzer-mcp/
├── java_class_analyzer_mcp/
│   ├── __init__.py
│   ├── main.py                     # MCP 服务器主入口
│   ├── cli.py                      # 命令行工具
│   ├── cfr-0.152.jar               # 内置 CFR 反编译工具
│   ├── scanner/
│   │   └── dependency_scanner.py   # Maven 依赖扫描模块
│   ├── decompiler/
│   │   └── decompiler_service.py   # Java 类反编译模块
│   └── analyzer/
│       └── java_class_analyzer.py  # Java 类结构分析模块
└── pyproject.toml
```

## 可用的 MCP 工具

### 1. scan_dependencies

扫描 Maven 项目的所有依赖，建立类名到 JAR 包的映射索引。

**参数:**
- `projectPath` (string): Maven 项目根目录路径
- `forceRefresh` (boolean, 可选): 是否强制刷新索引，默认 false

### 2. decompile_class

反编译指定的 Java 类文件，返回 Java 源码。

**参数:**
- `className` (string): 要反编译的类全名，如 `com.example.QueryBizOrderDO`
- `projectPath` (string): Maven 项目根目录路径
- `useCache` (boolean, 可选): 是否使用缓存，默认 true

### 3. analyze_class

分析 Java 类的结构、方法、字段等信息。

**参数:**
- `className` (string): 要分析的类全名
- `projectPath` (string): Maven 项目根目录路径

## 命令行工具

安装后可直接使用命令行工具：

```bash
# 启动 MCP 服务器（stdio 模式，供 MCP 客户端调用）
java-class-analyzer-mcp

# 生成 MCP 配置模板
java-class-analyzer-mcp config -o mcp-config.json

# 测试工具
java-class-analyzer-mcp test -t scan -p /path/to/project
java-class-analyzer-mcp test -t decompile -p /path/to/project -c com.example.MyClass
java-class-analyzer-mcp test -t analyze -p /path/to/project -c com.example.MyClass
java-class-analyzer-mcp test -t all -p /path/to/project -c com.example.MyClass --no-cache
```

## 缓存文件

在项目目录下会生成以下缓存：

- `.mcp-class-index.json`: 类索引缓存文件
- `.mcp-decompile-cache/`: 反编译结果缓存目录（按包名结构）
- `.mcp-class-temp/`: 临时文件目录（按包名结构）

## 工作流程

1. **自动索引**: 首次调用 `analyze_class` 或 `decompile_class` 时，自动检查并创建索引
2. **智能缓存**: 反编译结果按包名结构缓存，避免重复反编译
3. **分析类**: 使用 `analyze_class` 或 `decompile_class` 获取类的详细信息
4. **LLM 分析**: 将反编译的源码提供给 LLM 进行代码分析

## 故障排除

**Maven 命令失败**
- 确保 Maven 已安装并在 PATH 中
- 检查项目是否有有效的 `pom.xml` 文件

**CFR 反编译失败**
- 确保 Java 环境已正确配置（`java` 命令可用）
- 如需指定自定义 CFR jar，设置 `CFR_PATH` 环境变量

**类未找到**
- 检查类名是否正确（需要完整包名）
- 使用 `scan_dependencies` 刷新索引：`forceRefresh: true`

## 许可证

MIT License
