vineflower-mcp

一个将 vineflower（Java 反编译 CLI）封装为 MCP 工具的 Python 服务。

快速开始

前置依赖

• 安装 Vineflower CLI：brew install vineflower

启动 MCP Server

服务运行方式为 stdio MCP server，通常由 MCP Host 拉起。

uv run vineflower-mcp

Claude CLI 接入示例

claude mcp add vineflower -- uv run --project "/private/tmp/vineflower-mcp" vineflower-mcp

核心能力

• 单文件反编译：支持 .jar / .class
• 目录批量反编译：递归扫描并汇总执行结果
• 路径与包名过滤：
  • 路径前缀（相对 input_dir）
  • 包名前缀（如 com.foo）
• 参数白名单校验：基于 vineflower -h 解析结果

工具接口

• vineflower_get_help(force_refresh=False)
• vineflower_validate_options(options)
• vineflower_decompile_single(input_path, output_path, options=None, include_packages=None, exclude_packages=None, save_mode=None)
• vineflower_decompile_directory(input_dir, output_dir, recursive=True, dry_run=False, max_workers=4, options=None, include_paths=None, exclude_paths=None, include_packages=None, exclude_packages=None, fail_fast=False, save_mode=None)

参数与行为说明

save_mode

• 支持值：file、folder、legacy-saving
• 别名：
  • flat、dir、directory、files -> folder
  • legacy -> legacy-saving

目录工具行为

• dry_run=true：只做扫描和筛选，不执行反编译。
• max_workers>=1：控制目录反编译并发度，默认 4。
• fail_fast=true：仅支持 max_workers=1。

目录工具返回字段（新增）

• artifacts：逐输入文件返回执行明细
  • input_path / relative_path
  • selected / selection_reason
  • executed / ok / return_code / stderr_summary

运行配置

• 默认二进制路径：/opt/homebrew/bin/vineflower
• 可通过环境变量覆盖：VINEFLOWER_BIN
• 外部命令执行方式：subprocess.run(..., shell=False)

项目结构

src/vineflower_mcp/
  ├── server.py          # MCP 工具入口
  ├── vineflower_cli.py  # Vineflower CLI 封装、校验、执行
  ├── models.py          # 返回结构模型
  └── __init__.py
tests/
  ├── test_integration_vineflower_tools.py
  ├── test_directory_params.py
  ├── test_directory_structure.py
  └── test_save_mode.py

依赖信息

• 运行时依赖：mcp>=1.10.0
• 开发依赖：pytest>=8.3.0
• 锁文件：uv.lock

更新内容（2026-03-10）

• 新增目录反编译 dry_run 模式：仅扫描和筛选，不执行反编译。
• 新增目录结果 artifacts 明细：逐文件返回是否命中、筛选原因、执行状态与错误摘要。
• 新增目录反编译并发参数 max_workers，默认值调整为 4。
• 约束并发语义：fail_fast=true 仅支持 max_workers=1。
• 优化 save_mode 兼容性，支持 flat/dir/directory/files/legacy 别名与更友好的错误提示。