Recafmcp

🚀 Recaf MCP 插件

该插件可让 AI 助手通过 模型上下文协议 (MCP) 控制 Recaf 4.x，实现反编译、搜索、分析、编辑字节码、编译 Java 代码、汇编/反汇编 JASM、比较类、修补工作区以及直接从 AI 工作流程中导出 Java 字节码等功能。

中文文档

🚀 快速开始

工作原理

该插件采用双进程架构，将 AI 助手与 Recaf 强大的字节码分析引擎连接起来：

┌─────────────────┐     STDIO / JSON-RPC     ┌─────────────────┐    HTTP :9847     ┌─────────────────┐
│  AI 助手         │ ◄──────────────────────► │   MCP 服务器    │ ◄────────────────► │  Recaf 插件     │
│ (Claude Code,    │                          │ (独立 JAR)       │                    │ (桥接服务器)    │
│  Cursor 等)      │                          └─────────────────┘                    └────────┬────────┘
└─────────────────┘                                                                          │
                                                                                    ┌────────┴────────┐
                                                                                    │   Recaf 4.x     │
                                                                                    │ (分析引擎)      │
                                                                                    └─────────────────┘

• Recaf 插件（桥接服务器）：在 Recaf 进程内运行。通过 CDI (Jakarta) 注入 Recaf 服务，并将其作为 HTTP 端点暴露在 localhost:9847 上。
• MCP 服务器：由 AI 客户端启动的独立胖 JAR。通过 STDIO JSON-RPC 与 AI 通信，并通过 HTTP 将工具调用转发到桥接服务器。

这种分离是必要的，因为 Recaf 作为一个 JavaFX 桌面应用程序运行，有自己的模块系统，而 MCP 需要一个基于 STDIO 的进程，AI 客户端可以生成和管理该进程。

✨ 主要特性

可用的 MCP 工具（共 25 个）

工作区管理

分析

编译与汇编

修改

导出

MCP 资源

📦 安装指南

前提条件

• JDK 22+：Recaf 4.x 所需。确保 PATH 中的 java 指向 JDK 22 或更高版本。
• Recaf 4.x：此插件基于快照 d07958a5c7 构建。构建系统将自动下载它。

构建

git clone https://github.com/your-repo/recaf-mcp-plugin.git
cd recaf-mcp-plugin
./gradlew build

这将生成两个 JAR 文件：

设置与使用

步骤 1：使用插件启动 Recaf

选项 A：直接从项目运行（推荐用于开发）

./gradlew runRecaf

这将构建插件并自动加载它来启动 Recaf。

选项 B：手动安装 将 build/libs/recaf-mcp-plugin-1.2.0.jar 复制到 Recaf 的插件目录：

然后正常启动 Recaf。

验证：在 Recaf 的日志面板中查找以下内容：

========================================
  Recaf MCP 插件已启用
  桥接服务器在端口 9847 上运行
========================================

步骤 2：配置你的 AI 客户端

Claude Code

在 ~/.claude.json 中添加以下内容：

{
  "mcpServers": {
    "recaf": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/build/mcp/recaf-mcp-server-1.2.0.jar"]
    }
  }
}

然后重启 Claude Code。recaf 工具将出现在你的工具列表中。

Cursor

在 MCP 配置（设置 → MCP）中添加以下内容：

{
  "mcpServers": {
    "recaf": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/build/mcp/recaf-mcp-server-1.2.0.jar"]
    }
  }
}

其他支持 MCP 协议的客户端

任何支持 MCP 协议的客户端都可以使用此插件。将其配置为通过 java -jar 在 STDIO 上生成 MCP 服务器 JAR。

步骤 3：开始使用

当 Recaf 和你的 AI 客户端都运行后，你可以自然地进行交互：

Open /path/to/target.jar and list all classes
Decompile the com/example/Main class
Search for all strings containing "password"
Show me the call graph for com/example/Main
Rename com/example/a to com/example/LoginManager
Compare com/example/A with com/example/B
Remove the method "unused" from com/example/Foo
Show me the bytecode instructions for com/example/Main.main
Disassemble com/example/Crypto into JASM
Compile this modified Java source back into the workspace
Read the META-INF/MANIFEST.MF file
Create a patch of all my changes
Export the modified JAR to /tmp/output.jar

💻 使用示例

逆向工程混淆的 JAR 文件

1. "Open /path/to/obfuscated.jar"
2. "List all classes" — 获取包结构概述
3. "Decompile com/a/b/c" — 阅读反编译的源代码
4. "Search for strings containing 'http'" — 查找网络端点
5. "Get the call graph for com/a/b/c method d" — 了解控制流
6. "Rename com/a/b/c to com/app/NetworkManager" — 给它一个有意义的名称
7. "Export mappings as TinyV1 to ./mappings.tiny" — 保存工作成果
8. "Export the modified JAR to ./cleaned.jar" — 保存结果

多 JAR 文件比较

1. "Open /path/to/v1.jar" — 打开第一个 JAR 文件，返回工作区 ID
2. "Open /path/to/v2.jar" — 打开第二个 JAR 文件，返回工作区 ID
3. "List workspaces" — 查看两个工作区
4. "Switch to workspace v1-1" — 切换到第一个 JAR 文件的工作区
5. "Decompile com/example/Main" — 获取 v1 版本的源代码
6. "Switch to workspace v2-2" — 切换到第二个 JAR 文件的工作区
7. "Diff com/example/Main against the v1 source" — 比较版本差异

字节码编辑

1. "Open /path/to/target.jar"
2. "Remove the method 'checkLicense' from com/app/Main"
3. "Add a public field 'debug' of type boolean to com/app/Config"
4. "Export the modified JAR to /tmp/patched.jar"

编译与汇编往返操作

1. "Open /path/to/target.jar"
2. "Decompile com/app/Main" — 获取 Java 源代码
3. （修改源代码）→ "Compile this Java source for com.app.Main" — 编译并应用更改
4. "Decompile com/app/Main" — 验证更改是否生效
5. "Disassemble com/app/Crypto" — 获取 JASM 汇编文本
6. "Show me the bytecode for com/app/Crypto.encrypt" — 检查方法指令
7. "Create a patch" — 以 JSON 格式保存所有修改
8. "Export the modified JAR to /tmp/patched.jar"

📚 详细文档

项目结构

src/main/java/dev/recaf/mcp/
├── RecafMcpPlugin.java                  # 插件入口点 — CDI 注入 14 个 Recaf 服务
├── bridge/
│   ├── BridgeServer.java                # 端口 :9847 上的 HTTP 服务器 — 将请求路由到处理程序
│   ├── WorkspaceRegistry.java           # 多工作区注册表 — ID → 工作区映射
│   └── handlers/
│       ├── WorkspaceHandler.java        # /workspace/* — 打开、关闭、切换、列出、类、信息、大纲、读取文件、删除类
│       ├── DecompileHandler.java        # /decompile — 将类反编译为 Java 源代码
│       ├── SearchHandler.java           # /search — 字符串、类、方法、字段、声明搜索
│       ├── AnalysisHandler.java         # /analysis/* — 调用图和继承层次结构
│       ├── MappingHandler.java          # /mapping/* — 重命名符号和导出映射
│       ├── BytecodeHandler.java         # /bytecode/* — 编辑/添加/删除方法和字段、方法字节码指令
│       ├── DiffHandler.java             # /diff — 比较两个类（统一差异）
│       ├── ExportHandler.java           # /export/* — 导出 JAR 和反编译的源代码
│       ├── CompileHandler.java          # /compile — 编译 Java 源代码并应用到工作区
│       ├── AssemblerHandler.java        # /disassemble, /assemble — JASM 反汇编和汇编
│       └── PatchHandler.java            # /patch — 创建和应用工作区更改补丁
├── server/
│   ├── RecafMcpServer.java              # MCP 服务器 — STDIO JSON-RPC，分发 25 个工具
│   └── BridgeClient.java               # HTTP 客户端 — 将 MCP 工具调用转发到桥接服务器
└── util/
    ├── JsonUtil.java                    # JSON 响应助手
    ├── ErrorMapper.java                 # 结构化错误代码、消息和建议
    └── DiffUtil.java                    # 基于 LCS 的统一差异算法

桥接 HTTP API 参考

所有端点都接受带有 JSON 主体的 POST 请求，并返回 JSON 响应。

🔧 技术细节

🛠️ 故障排除

"Connection refused" 错误

• 确保 Recaf 正在运行，并且桥接服务器在端口 9847 上处于活动状态。
• 检查 Recaf 的日志面板中的启动横幅。

MCP 工具未出现在 AI 客户端中

• 验证 recaf-mcp-server-1.2.0.jar 的路径是否正确且为绝对路径。
• 确保 java 指向 JDK 22+：运行 java -version 进行检查。
• 更新 MCP 配置后重启你的 AI 客户端。

反编译返回空或错误

• 确保已打开工作区（先使用 open_jar）。
• 检查类名格式：使用 / 分隔符（例如 com/example/Main），而不是 . 分隔符。

结构化错误响应

• 所有错误现在都包含 code、message 和 suggestion 字段。
• 常见代码：NO_WORKSPACE、CLASS_NOT_FOUND、MEMBER_NOT_FOUND、INVALID_PARAMS、DECOMPILE_TIMEOUT、COMPILE_FAILED、ASSEMBLER_FAILED、PATCH_FAILED。

构建失败

• 确保已安装 JDK 22+。运行 ./gradlew -q javaToolchains 查看检测到的 JDK。
• 如果使用非默认 JDK，请配置 Gradle 工具链。

📝 更新日志

v1.2.0

• Java 编译：compile_java 通过 Recaf 的 JavacCompiler 编译 Java 源代码，并将结果应用到工作区。
• JASM 汇编/反汇编：disassemble_class 和 assemble_class 用于完整类的 JASM 往返操作；method_disassemble 用于单个方法的反汇编。
• 方法字节码查看器：method_bytecode 通过 ASM 树 API 显示详细的字节码指令（操作码、操作数、异常处理块、局部变量）。
• 类大纲：class_outline 提供轻量级类结构（字段、方法、访问标志），无需反编译代码。
• 文件读取器：read_file 从工作区读取非类文件（例如 MANIFEST.MF、配置文件、资源）。
• 类删除：class_delete 从工作区中删除一个类。
• 补丁系统：patch 工具创建和应用工作区更改补丁（可序列化的 JSON 格式）。
• 新错误代码：COMPILE_FAILED、COMPILER_UNAVAILABLE、PATCH_FAILED。
• 4 个新的 Recaf 服务注入：AssemblerPipelineManager、JavacCompiler、PatchProvider、PatchApplier。
• 工具数量：从 16 个增加到 25 个。

v1.1.0

• 多工作区支持：可以同时打开多个 JAR 文件，使用 switch_workspace 和 list_workspaces 在它们之间切换。
• 字节码编辑：edit_bytecode 工具具有 5 个操作：edit_method、edit_field、remove_member、add_field、add_method（基于 ASM）。
• 类比较：diff_classes 工具生成两个反编译类之间或类与提供的源代码之间的统一差异。
• 导出：export_jar 将工作区（包含修改）导出为 JAR 文件；export_source 将反编译的源代码导出到目录。
• 分页：list_classes 现在支持 offset/limit，并带有 totalMatched/hasMore 元数据。
• 结构化错误：所有错误返回 code、message 和 suggestion 字段（例如 NO_WORKSPACE、CLASS_NOT_FOUND）。
• 错误检测：MCP 服务器现在在错误响应中设置 isError: true，以便 AI 客户端更好地处理。
• 工具数量：从 10 个增加到 16 个。

v1.0.0

• 初始版本，包含 10 个 MCP 工具：open_jar、close_workspace、list_classes、get_class_info、decompile_class、search_code、get_call_graph、get_inheritance、rename_symbol、export_mappings。

📄 许可证

本项目采用 MIT 许可证。