# MCP Perforce 服务器

Perforce 的模型上下文协议 (MCP) 服务器实现，支持通过 P4 原生命令获取变更列表信息和文件差异。

## 功能概述

MCP Perforce 服务器提供以下工具：

### 1. get-changelist-files-catalog

获取变更列表中的文件目录，自动检测 CL 类型（Shelved/Affected）。

**参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| changelist_id | integer | 是 | Perforce 变更列表 ID (CL号) |

**返回：**
- CL 类型（Shelved 未提交 / Affected 已提交）
- CL 描述信息
- 受影响的文件列表（已过滤二进制文件和配置的跳过扩展名）

### 2. get-file-details

获取变更列表中指定文件的详细差异信息。

**参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| action | string | 是 | 文件操作类型 (add/edit/delete/integrate/branch) |
| file_path | string | 是 | depot 文件路径 |
| revision | integer | 是 | 文件版本号 |
| changelist_id | integer | 是 | Perforce 变更列表 ID (CL号) |
| is_shelved | boolean | 是 | 是否是 Shelved CL (未提交为 true，已提交为 false) |

**diff 策略：**
- **Shelved (is_shelved=true)**：使用 `p4 diff2 file file@=<CL>` 比较未提交的变更
- **Affected (is_shelved=false)**：使用 `p4 diff2 file#(rev-1) file#rev` 比较已提交的变更

## 配置说明

### Cursor MCP 配置

```json
{
    "mcpServers": {
      "p4-review-dev": {
          "command": "uvx",
          "args": [
              "mcp-perforce",
              "--p4config",
              "./path/to/your/p4config.json"
          ]
      }
  }      
}  
```

### p4config.json 配置

```json
{
  "skip_file_extensions": [".pb.go", ".cs"]
}
```

### 配置项说明

| 配置项 | 必填 | 说明 |
|--------|------|------|
| skip_file_extensions | 否 | 需要跳过的文件扩展名列表，默认为 `[".pb.go", ".cs"]` |

## 编码自适应

服务器启动时会自动通过 `p4 set` 命令检测 `P4CHARSET` 配置，并使用对应的编码读取 P4 命令输出：

| P4CHARSET | Python 编码 |
|-----------|-------------|
| cp936 | gbk (简体中文) |
| utf8 / utf-8 | utf-8 |
| eucjp | euc-jp (日文) |
| shiftjis | shift_jis (日文) |
| winansi | cp1252 |
| 其他/未设置 | utf-8 (默认) |

## 使用说明

在 Cursor Agent 模式中输入：

```
帮我review一下3280706
```

Cursor 将自动：
1. 调用 `get-changelist-files-catalog` 获取文件列表
2. 根据 CL 类型（Shelved/Affected）调用 `get-file-details` 获取每个文件的差异
3. 进行代码审查

## 更新记录

* 0.3.0 - **重大重构**
  - 移除 Swarm API 依赖，完全使用 P4 原生命令
  - 支持 Shelved (未提交) 和 Affected (已提交) 两种 CL 类型
  - 新增 `is_shelved` 参数，根据 CL 类型使用不同的 diff 策略
  - 新增编码自适应功能，自动检测 P4CHARSET 配置
  - 移除 `get-changelist-diff-native` 工具，功能已合并到 `get-changelist-files-catalog` 和 `get-file-details`
* 0.2.6 - 新增 `skip_file_extensions` 配置项，支持自定义跳过的文件扩展名
* 0.2.5 - 新增 `get-changelist-diff-native` 工具，支持使用P4原生命令获取CL差异
* 0.2.4 - 修复代码提交后，无法获取reviews中的差异信息的BUG