# Java Boilerplate Generator MCP

一个 [MCP（Model Context Protocol）](https://modelcontextprotocol.io) 服务器，用于为 Java 实体类**自动生成显式的样板方法**（getter/setter/equals/hashCode/toString/构造函数），并写回原文件。

## 为什么需要它

AI 编码助手在为 Java 实体类生成样板代码时，倾向于直接加 Lombok 注解（`@Data`、`@Getter` 等）。这会引入对 Lombok 的隐式依赖，且生成的代码不可见、不可审查。本工具由 MCP 替代 AI 直接生成**显式的、IDE 标准风格的 Java 方法**，让实体类自带完整方法，无需 Lombok。

## 工具：`generate_boilerplate`

解析指定 `.java` 文件中的实体类，生成缺失的样板方法并写回原文件。

### 参数

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `file_path` | `str` | 必填 | Java 实体类的绝对路径 |
| `generate` | `list[str]` | `["getter","setter"]` | 要**只补缺失**的方法类型子集，**仅接受** `"getter"`、`"setter"`。只为缺少访问器的字段生成，保留手写逻辑（如带校验的 setter）。其余 5 类不能放这里，请用 `regenerate`。 |
| `setter_style` | `str` | `"void"` | setter 返回风格：`"void"`（传统）或 `"fluent"`（返回 `this`，支持链式调用） |
| `include_super_fields` | `bool` | `false` | 为 `true` 时，equals 前置 `super.equals(o)`、hashCode 加 `super.hashCode()` |
| `regenerate` | `list[str]` | 后 5 类 | 要**删旧重建**的方法类型子集，可选值为全部 7 种：`"getter"`、`"setter"`、`"equals"`、`"hashCode"`、`"toString"`、`"no_args_ctor"`、`"all_args_ctor"`。删除旧方法后重新生成。**这是请求 equals/hashCode/toString/构造器的唯一途径**；把 getter/setter 列入则改为删旧重建（适合切换 setter 风格等重构）。默认后 5 类。 |

> **冲突**：同一访问器类型（getter 或 setter）不能同时出现在 `generate` 与 `regenerate` 中——"只补缺失"与"删旧重建"对同一访问器互斥。冲突时工具返回 `error="conflict"` 并给出说明，**不写回文件**，需重新调用二选一。同理，把 5 类放入 `generate` 也会触发该错误（它们只能经 `regenerate` 请求）。

### 行为规则

- **`generate`（仅 getter/setter）**：**只补缺失**——只为缺少访问器的字段生成，保留手写逻辑。
- **`regenerate`（全部 7 种皆可）**：**删旧重建**——删除旧方法后重新生成。equals/hashCode/toString/构造器**只能**经此参数请求；getter/setter 列入则改为删旧重建。
- **默认（不传参）**：生成全部 7 种——`generate` 默认 `[getter,setter]` 补缺失，`regenerate` 默认后 5 类删旧重建。
- **static/transient 字段**：不参与生成（与 IDE 行为一致）。
- **风格**：IDE 标准风格。equals 用 `instanceof` 模式；对象字段用 `Objects.equals`，基本类型用 `==`；hashCode 用 `Objects.hash`。
- **Lombok**：工具不解析 Lombok 语义，不处理与 Lombok 注解的冲突。

### 关于 `include_super_fields` 与继承

当 `include_super_fields=true` 时，子类的 equals/hashCode 会调用 `super.equals(o)` / `super.hashCode()`。由于 equals 使用 `instanceof` 模式（而非 `getClass()`），父类的 `o instanceof Parent` 对子类实例为 `true`，因此 **`super.equals(o)` 能在父子类间正确传递**——前提是父类也由本工具生成 equals/hashCode。

```java
// 父类 Parent（由本工具生成）
@Override
public boolean equals(Object o) {
    if (o == this) return true;
    if (!(o instanceof Parent)) return false;   // Child 也是 Parent，通过
    Parent other = (Parent) o;
    return Objects.equals(this.id, other.id);
}

// 子类 Child（include_super_fields=true）
@Override
public boolean equals(Object o) {
    if (o == this) return true;
    if (!(o instanceof Child)) return false;
    Child other = (Child) o;
    return super.equals(o)                       // 委托父类比较父类字段
        && Objects.equals(this.name, other.name); // 子类自己的字段
}
```

> 注意：`instanceof` 模式 + 继承有一个固有的对称性副作用（`parent.equals(child)` 可能为 true 而 `child.equals(parent)` 为 false），这是 IDE 生成代码的相同行为，实体类场景通常可接受。

## 安装与接入

### 前置要求

- Python 3.14+
- [uv](https://docs.astral.sh/uv/)（用于管理依赖与运行）

### 接入 Claude Code

在 Claude Code 的 MCP 配置（`~/.claude.json` 或项目的 `.mcp.json`）中添加：

```json
{
  "mcpServers": {
    "java-boilerplate": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/FlyDut/java-boilerplate-mcp", "python", "-m", "java_mcp.server"]
    }
  }
}
```

### 接入 Claude Desktop

在 Claude Desktop 的配置文件（`claude_desktop_config.json`）中添加同样的 `mcpServers` 条目。

### 验证

```bash
# 运行测试
uv run pytest

# 启动服务器（stdio 模式，应显示 FastMCP 横幅后等待输入）
uv run python -m java_mcp.server
```

## 使用示例

对 AI 说：

> 帮我为 `src/main/java/com/example/User.java` 生成 getter、setter、equals、hashCode、toString 和构造函数，不要用 Lombok。

AI 会调用 `generate_boilerplate` 工具，工具读取文件、生成方法、写回原文件，并返回生成统计。

## 项目结构

```
src/java_mcp/
├── server.py     # FastMCP 实例 + generate_boilerplate 工具 + 编排逻辑
├── parser.py     # tree-sitter-java 解析 → ParsedFile/EntityClass/Field
├── model.py      # 数据模型: Field, EntityClass, ParsedFile
├── detector.py   # 检测已存在的 getter/setter/equals/hashCode/toString/构造
├── generator.py  # 生成各方法的 Java 源码（IDE 标准风格）
└── writer.py     # 插入方法 + import，替换旧 @Override 方法，写回文件
```

## 测试

```bash
uv run pytest        # 全部测试（含用 javac/java 的端到端验证）
uv run pytest tests/test_e2e.py -v   # 端到端：编译运行生成的 Java 验证 equals 链
```

端到端测试会用 `javac` 编译工具生成的 Java 文件并运行，验证父子类 equals/hashCode 链在运行时自洽正确。