# ideadiffmcpplugin

**Repository Path**: lazytai/ideadiffmcpplugin

## Basic Information

- **Project Name**: ideadiffmcpplugin
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-29
- **Last Updated**: 2026-03-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# IDEA Diff/MCP Server Plugin

一个 IntelliJ IDEA 插件，在本地启动 MCP (Model Context Protocol) Server，允许外部 AI Agent（如 Claude Desktop、Cursor）通过 HTTP JSON-RPC 远程调用 IDEA 原生 Diff/Merge 窗口。

## 核心特性

- **100% 复用 IDEA 原生 DiffManager API** — 顶级语法高亮、词级对比、三路合并
- **零外部网络依赖** — 仅监听 `127.0.0.1:9876`，不暴露到公网
- **线程安全** — HTTP Worker → EDT 桥接，不阻塞不死锁
- **支持纯文本模式** — AI 不生成物理文件时，也能弹出带语法高亮的 Diff

## MCP Tool 列表

| Tool | 说明 |
|------|------|
| `idea_show_file_diff` | 双栏 Diff 视图（**patches 模式** / 文件路径 / 纯文本） |
| `idea_merge_three_way` | 三路合并视图（Base/Local/Remote） |
| `idea_server_status` | 查询服务器状态和项目信息 |

### 核心：Patches 模式

插件最核心的能力。AI 只需返回**行级修改指令**（哪一行加、删、改什么），插件自动拼装完整文件并弹出 Diff：

```
AI 返回 patches  →  插件按行号拼装  →  IDEA Diff 弹窗  →  用户 >> 接受
```

详见下方 [Patches 模式（推荐）](#patches-模式推荐)。

## 开发工作流

### 构建原则

1. **先提交代码**，再构建（避免构建产物污染 git diff）
2. **构建前必须询问**，不要自动构建（构建耗时长、容易卡住）
3. 构建命令：`./gradlew buildPlugin`
4. 构建产物：`build/distributions/idea-diff-mcp-plugin-*.zip`

### 国内镜像使用规则

| 组件 | 镜像源 | 原因 |
|------|--------|------|
| Maven 依赖 | 阿里云 (`maven.aliyun.com`) | 依赖包多、下载频繁，国内源提速明显 |
| JDK 17 | apt: 阿里云 (`mirrors.aliyun.com`) | 内网源不通时切换公网源，`apt install openjdk-17-jdk` 一步搞定 |
| IntelliJ IDEA | JetBrains 中国 CDN (`download-cdn.jetbrains.com`) | 官方中国节点，直链下载；华为云 JetBrains 镜像为 SPA 页面，curl 拿到的是 HTML 而非文件，无法用于命令行下载 |
| **Gradle Wrapper** | **华为云 (`repo.huaweicloud.com/gradle/`)** | **下载快，国内直连** |

> ⚠️ **Gradle Wrapper 已配置华为云镜像**，首次 `./gradlew` 会自动使用国内源下载 Gradle。

## 快速开始

### 准备本地 IDE（必须）

构建需要 IntelliJ IDEA Community 2024.1 的本体（约 779MB），无法绕过。

**下载方式（国内镜像）：**

```bash
# 1. 安装 JDK 17（阿里云公网镜像源）
sudo sed -i 's|http://mirrors.cloud.aliyuncs.com|http://mirrors.aliyun.com|g' /etc/apt/sources.list
sudo apt update && sudo apt install -y openjdk-17-jdk
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
java -version

# 2. 下载 IntelliJ IDEA Community 2024.1（JetBrains 中国 CDN，无需翻墙）
curl -L -o ideaIC-2024.1.tar.gz "https://download-cdn.jetbrains.com/idea/ideaIC-2024.1.tar.gz"

# 3. 解压到项目目录下的 idea-ide 文件夹
mkdir -p idea-ide
tar xzf ideaIC-2024.1.tar.gz -C idea-ide --strip-components=1

# 4. 删除下载包（节省空间）
rm ideaIC-2024.1.tar.gz
```

> ⚠️ `idea-ide/` 目录已在 `.gitignore` 中排除，不会提交到仓库。每个开发者需要自行下载一份。

### 构建

```bash
# 使用 Gradle Wrapper
./gradlew buildPlugin
```

构建产物在 `build/distributions/idea-diff-mcp-plugin-*.zip`。

### 安装

1. IDEA → Settings → Plugins → ⚙️ → Install Plugin from Disk
2. 选择构建出的 zip 文件
3. 重启 IDEA

### 使用

1. 打开任意项目，插件自动启动 MCP Server（端口 9876）
2. 在 AI Agent 配置中添加 MCP Server 地址：`http://127.0.0.1:9876/mcp`
3. AI 通过 JSON-RPC 调用 Tool，IDEA 弹出原生 Diff 窗口

### 手动控制

Tools → Start/Stop MCP Server

## MCP 协议

### tools/list

```json
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}
```

### tools/call — idea_show_file_diff

支持三种模式（优先级从高到低）：

| 模式 | 参数 | 适用场景 |
|------|------|---------|
| **patches（推荐）** | `patches` 数组 | AI 只返回行级修改指令，插件自动拼装 |
| 文件路径 | `modified_file_path` | AI 已把完整修改文件写到磁盘 |
| 纯文本 | `modified_content` + `language_id` | AI 直接传完整文件字符串 |

#### Patches 模式（推荐）

AI **不需要生成完整文件**，只需返回行级修改指令。插件自动读取原始文件，按行号应用修改，组装出完整修改后文件，再弹出 Diff 窗口。

**工作流程：**

```
用户需求 → AI 返回 patches（行号 + 操作 + 内容）
               ↓
         插件 PatchApplier 按行号拼装完整文件
               ↓
         IDEA Diff 弹窗：左(原文件) vs 右(拼装后)
               ↓
         用户点击 >> 接受 / 关闭窗口拒绝
```

**调用示例：**

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "idea_show_file_diff",
    "arguments": {
      "original_file_path": "/absolute/path/to/Service.java",
      "context_description": "新增用户校验逻辑",
      "patches": [
        {
          "line": 3,
          "action": "add",
          "content": "import java.util.regex.Pattern;",
          "comment": "新增正则工具 import"
        },
        {
          "line": 15,
          "action": "add",
          "content": "    public boolean validateEmail(String email) {\n        return Pattern.matches(EMAIL_REGEX, email);\n    }",
          "comment": "在第15行之后插入邮箱校验方法"
        },
        {
          "line": 8,
          "action": "modify",
          "content": "    private static final String EMAIL_REGEX = \"^[\\\\w.-]+@[\\\\w.-]+\\\\.\\\\w{2,}$\";",
          "comment": "更新正则表达式"
        }
      ]
    }
  },
  "id": 2
}
```

**Patches 规则：**

| 字段 | 说明 |
|------|------|
| `line` | 行号，从 1 开始。`0` 表示文件开头 |
| `action` | `add`（在该行之后插入）、`remove`（删除该行）、`modify`（替换该行） |
| `content` | 代码内容，保留正确缩进。`remove` 时可省略 |
| `comment` | 可选，说明修改意图 |

> 💡 **多个 patches 按 `line` 降序排列**（从下往上改），避免行号偏移。插件内部会自动排序。

**给 AI 的提示词模板：**

```
你是代码修改指令助手。用户需求：${userRequest}。代码上下文：${fileContent}。
返回严格JSON：{"operationType":"modify","targetFile":"文件路径","patches":[{"line":行号,"action":"add|remove|modify","content":"代码内容","comment":"说明"}],"summary":"摘要"}。
规则：line从1开始，0表示文件开头；add在该行之后插入；remove删除该行；modify替换该行；多个patch按line降序；只返回JSON。
```

#### 文件路径模式

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "idea_show_file_diff",
    "arguments": {
      "original_file_path": "/path/to/original.java",
      "modified_file_path": "/path/to/modified.java",
      "context_description": "重构：提取方法抽取公共逻辑"
    }
  },
  "id": 2
}
```

#### 纯文本模式（左边原始文件 + 右边修改代码字符串）

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "idea_show_file_diff",
    "arguments": {
      "original_file_path": "/absolute/path/to/OriginalFile.java",
      "modified_content": "public class OriginalFile {\n  // 修改后的代码...\n}",
      "language_id": "java",
      "context_description": "重构：提取公共方法"
    }
  },
  "id": 2
}
```

### tools/call — idea_merge_three_way

```json
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "idea_merge_three_way",
    "arguments": {
      "base_path": "/path/to/base.java",
      "local_path": "/path/to/local.java",
      "remote_path": "/path/to/remote.java",
      "context_description": "合并 feature 分支冲突"
    }
  },
  "id": 3
}
```

## 技术栈

- Kotlin + IntelliJ Platform Plugin SDK (2023.2+)
- JDK `com.sun.net.httpserver.HttpServer`（零外部 HTTP 依赖）
- Gson（JSON 解析）
- Gradle + IntelliJ Platform Gradle Plugin 2.x

## 兼容性

- IntelliJ IDEA 2023.2 ~ 2024.3
- JDK 17+
- 也兼容其他基于 IntelliJ 的 IDE（WebStorm、PyCharm 等，需调整 build.gradle.kts 中的 platform）

## License

MIT