xliff-mcp/README.md

MCP server for XLIFF bilingual file processing

# XLIFF MCP Server

一个专门处理XLIFF双语文件的Model Context Protocol (MCP)服务器，基于filesystem功能扩展，提供完整的XLIFF文件处理能力。

## 功能特性

### 文件系统操作
- 读写文件
- 列出目录内容
- 搜索文件
- 安全的路径验证（只允许在指定目录内操作）

### XLIFF专用功能
- **解析XLIFF文件**：将XLIFF文件转换为JSON数据
- **创建XLIFF文件**：根据JSON数据生成XLIFF文件
- **更新XLIFF文件**：更新现有XLIFF文件的翻译内容
- **验证XLIFF文件**：检查XLIFF文件格式和结构
- **批量处理**：批量解析和验证目录中的XLIFF文件

### 支持的XLIFF版本
- XLIFF 1.2
- XLIFF 2.0
- XLIFF 2.1

## 安装

```bash
npm install -g xliff-mcp
```

## 使用方法

### 与Claude Desktop一起使用

在`claude_desktop_config.json`中添加以下配置：

```json
{
  "mcpServers": {
    "xliff": {
      "command": "xliff-mcp",
      "args": ["/path/to/your/xliff/files", "/path/to/output/directory"]
    }
  }
}
```

### 与VS Code一起使用

```json
{
  "mcp": {
    "servers": {
      "xliff": {
        "command": "xliff-mcp",
        "args": ["${workspaceFolder}"]
      }
    }
  }
}
```

## API工具

### 文件系统工具

#### `read_file`
读取文件内容
- 输入：`path` (string) - 文件路径

#### `write_file`
写入文件内容
- 输入：
  - `path` (string) - 文件路径
  - `content` (string) - 文件内容

#### `list_directory`
列出目录内容
- 输入：`path` (string) - 目录路径

#### `search_files`
搜索文件
- 输入：
  - `path` (string) - 搜索起始目录
  - `pattern` (string) - 搜索模式
  - `excludePatterns` (string[]) - 排除模式（可选）

### XLIFF工具

#### `parse_xliff`
解析XLIFF文件为JSON格式
- 输入：`path` (string) - XLIFF文件路径
- 输出：包含翻译单元的JSON数组

#### `create_xliff`
根据JSON数据创建XLIFF文件
- 输入：
  - `path` (string) - 输出文件路径
  - `data` (XliffData[]) - 翻译数据数组
  - `options` (CreateXliffOptions) - 创建选项

#### `update_xliff`
更新现有XLIFF文件
- 输入：
  - `path` (string) - XLIFF文件路径
  - `updates` (XliffData[]) - 更新数据数组
  - `options` (UpdateXliffOptions) - 更新选项

#### `validate_xliff`
验证XLIFF文件格式
- 输入：`path` (string) - XLIFF文件路径
- 输出：验证结果和错误信息

#### `batch_process_xliff`
批量处理XLIFF文件
- 输入：
  - `directory` (string) - 包含XLIFF文件的目录
  - `pattern` (string) - 文件匹配模式（默认：*.xlf）
  - `operation` ('parse' | 'validate') - 操作类型

## 数据结构

### XliffData
```typescript
interface XliffData {
    fileName: string;        // 文件名
    segNumber: number;       // 段落编号
    percent: number;         // 匹配百分比
    source: string;          // 源文本
    target: string;          // 目标文本
    srcLang: string;         // 源语言
    tgtLang: string;         // 目标语言
    id?: string;             // 单元ID
    approved?: boolean;      // 是否已批准
    state?: string;          // 状态
    resname?: string;        // 资源名称
}
```

## 示例用法

### 解析XLIFF文件
```bash
# 通过MCP调用
parse_xliff --path "/path/to/file.xlf"
```

### 创建XLIFF文件
```javascript
const xliffData = [
  {
    fileName: "test.xlf",
    segNumber: 1,
    percent: 100,
    source: "Hello",
    target: "你好",
    srcLang: "en",
    tgtLang: "zh-cn",
    id: "1"
  }
];

const options = {
  version: "1.2",
  sourceLanguage: "en",
  targetLanguage: "zh-cn",
  original: "source.txt"
};
```

## 开发

### 构建
```bash
npm run build
```

### 监听变化
```bash
npm run watch
```

## 许可证

MIT License

## 贡献

欢迎提交Issues和Pull Requests！