# docx_mcp_rust

**Repository Path**: awol2010ex/docx_mcp_rust

## Basic Information

- **Project Name**: docx_mcp_rust
- **Description**: A Rust-based MCP (Model Context Protocol) server for creating and manipulating DOCX files
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-12
- **Last Updated**: 2026-01-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# DOCX MCP Rust

一个基于 Rust 的 DOCX 文件操作 MCP（Model Context Protocol）服务器，使用 `docx-rs = "0.4.18"` 库生成标准 DOCX 文件，支持图片插入功能。

> 🚀 **Trae IDE 用户**：直接安装即可使用！支持自然语言操作 DOCX 文档，详见 [Trae IDE 集成开发](#trae-ide-集成开发) 部分。
> mcp界面点击“新建”,粘贴
```json
{
  "mcpServers": {
    "docx_mcp_rust": {
      "command": "./target/release/docx_mcp_rust.exe",
      "args": []
    }
  }
}
```

## 功能特性

- **标准 DOCX 文件生成**：使用 `docx-rs` 库生成符合 Office Open XML 标准的 DOCX 文件
- **图片插入支持**：支持插入 PNG、JPG、JPEG、BMP 格式的图片到文档中
- **文档结构操作**：支持段落、运行（文本片段）、文本的层级结构
- **JSON-RPC 接口**：提供完整的 JSON-RPC 2.0 接口
- **丰富的文本格式化**：
  - 字体样式：粗体、斜体、下划线
  - 字体属性：字体名称、字体大小、颜色
  - 段落对齐：左对齐、居中、右对齐、两端对齐
- **文档属性管理**：标题、作者、主题、关键词、描述等
- **MCP 协议支持**：作为 Model Context Protocol 服务器运行

## 快速开始

### 🎯 Trae IDE 用户（推荐）

1. **一键安装**：在 Trae IDE 中点击左侧 MCP 图标，搜索 "docx" 或输入仓库地址
2. **自动配置**：Trae IDE 会自动处理依赖安装和服务器启动
3. **立即使用**：在聊天界面直接说 "创建一个 Word 文档"

### 🔧 标准开发环境

#### 安装依赖

```bash
cargo build
```

#### 运行服务器

```bash
cargo run
```

### 基本使用

服务器启动后，可以通过 JSON-RPC 请求来操作 DOCX 文档：

```json
{
  "jsonrpc": "2.0",
  "method": "create_docx",
  "params": {
    "name": "test_document",
    "title": "测试文档"
  },
  "id": 1
}
```

## 可用方法

### 文档管理

- `create_docx` - 创建新文档
  - 参数：`name` (文档名称), `title` (文档标题)
  - 返回：新创建的文档ID和基本信息
- `save_docx` - 保存文档到文件
  - 参数：`file_path` (保存路径), `document_id` (可选，默认为当前文档)
  - 返回：保存状态和文件路径
  - 使用 `docx-rust` 库生成标准 DOCX 文件
- `load_docx` - 从文件加载文档
  - 参数：`file_path` (文件路径), `name` (文档名称)
  - 返回：加载的文档信息
  - 支持标准 DOCX 文件格式
- `close_docx` - 关闭文档
  - 参数：`document_id` (可选，默认为当前文档)
  - 返回：关闭状态
- `get_current_document` - 获取当前文档信息
  - 返回：当前文档的详细信息和统计
- `get_all_documents` - 获取所有文档列表
  - 返回：所有打开的文档及其基本信息

### 段落操作

- `add_paragraph` - 添加段落
  - 参数：`alignment` (可选，对齐方式: left/center/right/justify)
  - 返回：新段落的ID和索引
- `get_paragraph` - 获取段落信息
  - 参数：`paragraph_index` (段落索引)
  - 返回：段落的详细信息和属性
- `update_paragraph_style` - 更新段落样式
  - 参数：`paragraph_index` (段落索引), `alignment` (对齐方式)
  - 返回：更新状态
- `get_paragraphs` - 获取所有段落信息
  - 返回：所有段落的列表和统计信息

### 运行操作

- `add_run` - 添加运行（文本片段）
  - 参数：`paragraph_index` (段落索引)
  - 返回：新运行的ID和索引
- `get_run` - 获取运行信息
  - 参数：`paragraph_index` (段落索引), `run_index` (运行索引)
  - 返回：运行的详细信息和属性
- `update_run_properties` - 更新运行属性（字体、大小、颜色等）
  - 参数：`paragraph_index` (段落索引), `run_index` (运行索引), 格式化属性
  - 返回：更新状态
- `get_runs` - 获取段落中的所有运行
  - 参数：`paragraph_index` (段落索引)
  - 返回：该段落的所有运行列表

### 图片操作

- `add_image` - 添加图片到运行中
  - 参数：`paragraph_index` (段落索引), `run_index` (运行索引), `filename` (文件名), `data` (Base64编码的图片数据), `format` (格式: png/jpg/jpeg/bmp), `width` (宽度), `height` (高度)
  - 返回：图片索引和关系ID
- `get_images` - 获取运行中的所有图片
  - 参数：`paragraph_index` (段落索引), `run_index` (运行索引)
  - 返回：该运行中的所有图片列表

### 文本操作

- `add_text` - 添加文本
  - 参数：`paragraph_index` (段落索引), `run_index` (运行索引), `content` (文本内容)
  - 返回：新文本的索引
- `get_text` - 获取文本内容
  - 参数：`paragraph_index` (段落索引), `run_index` (运行索引), `text_index` (文本索引)
  - 返回：文本内容和属性
- `update_text` - 更新文本内容
  - 参数：`paragraph_index` (段落索引), `run_index` (运行索引), `text_index` (文本索引), `new_content` (新内容)
  - 返回：更新状态
- `update_text_properties` - 更新文本属性
  - 参数：`paragraph_index` (段落索引), `run_index` (运行索引), `text_index` (文本索引), 属性参数
  - 返回：更新状态

## 示例

### 创建文档并添加内容

```json
// 1. 创建文档
{
  "jsonrpc": "2.0",
  "method": "create_docx",
  "params": {
    "name": "my_document",
    "title": "我的文档"
  },
  "id": 1
}

// 2. 添加段落
{
  "jsonrpc": "2.0",
  "method": "add_paragraph",
  "params": {
    "alignment": "center"
  },
  "id": 2
}

// 3. 添加运行
{
  "jsonrpc": "2.0",
  "method": "add_run",
  "params": {
    "paragraph_index": 0
  },
  "id": 3
}

// 4. 添加文本
{
  "jsonrpc": "2.0",
  "method": "add_text",
  "params": {
    "paragraph_index": 0,
    "run_index": 0,
    "content": "Hello, DOCX World!"
  },
  "id": 4
}
```

### 格式化文本

```json
{
  "jsonrpc": "2.0",
  "method": "update_run_properties",
  "params": {
    "paragraph_index": 0,
    "run_index": 0,
    "font_size": 14.0,
    "bold": true,
    "color": "FF0000",
    "font_name": "Arial"
  },
  "id": 5
}
```

### 插入图片

```json
// 1. 添加段落
{
  "jsonrpc": "2.0",
  "method": "add_paragraph",
  "params": {},
  "id": 6
}

// 2. 添加运行
{
  "jsonrpc": "2.0",
  "method": "add_run",
  "params": {
    "paragraph_index": 2
  },
  "id": 7
}

// 3. 插入图片（Base64编码）
{
  "jsonrpc": "2.0",
  "method": "add_image",
  "params": {
    "paragraph_index": 2,
    "run_index": 0,
    "filename": "test.png",
    "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
    "format": "png",
    "width": 100,
    "height": 100
  },
  "id": 8
}
```

### 保存为标准 DOCX 文件

```json
{
  "jsonrpc": "2.0",
  "method": "save_docx",
  "params": {
    "file_path": "output/document.docx"
  },
  "id": 9
}
```

### Trae IDE 自然语言使用示例

在 Trae IDE 中，您可以直接使用自然语言：

```
"帮我创建一个标题为'项目报告'的Word文档"
"添加一个居中的段落，内容是'项目概述'"
"把这段文字设置为蓝色、加粗、16号字体"
"插入一张图片到文档中"
"保存文档到桌面"
```

Trae IDE 会自动将这些自然语言转换为相应的 JSON-RPC 调用。

## DOCX-Rust 库集成

本项目基于 [`docx-rs = "0.4.18"`](https://crates.io/crates/docx-rs) 库构建，提供以下优势：

- **标准兼容性**：生成的 DOCX 文件完全符合 Office Open XML 标准
- **可靠格式**：使用成熟的 Rust 库确保文件格式正确性
- **丰富功能**：支持复杂的文档结构和格式化选项
- **性能优化**：Rust 的高性能特性确保快速文档生成
- **跨平台**：支持 Windows、Linux、macOS 等主流操作系统

### 支持的格式特性

- **段落格式**：对齐方式（左对齐、居中、右对齐、两端对齐）
- **文本格式**：
  - 字体样式：粗体、斜体、下划线
  - 字体属性：字体名称、字体大小、颜色
  - 高级格式：支持扩展格式化选项
- **文档属性**：标题、作者、主题、关键词、描述等元数据

### 技术架构

```
MCP Client (如 Claude Desktop)
    ↓ JSON-RPC 2.0
DOCX MCP Rust Server
    ↓ 内部API调用
docx-rust 库
    ↓ Office Open XML
标准 DOCX 文件
```

## 项目结构

```
docx_mcp_rust/
├── src/
│   ├── lib.rs              # 库入口
│   ├── main.rs             # 主程序
│   ├── core.rs             # 核心数据结构
│   ├── handlers.rs         # JSON-RPC 处理器
│   ├── tools/              # 工具模块
│   │   ├── management.rs   # 文档管理（集成 docx-rust）
│   │   ├── document.rs     # 文档操作
│   │   ├── paragraph.rs    # 段落操作
│   │   ├── run.rs          # 运行操作
│   │   └── text.rs         # 文本操作
│   └── utils.rs            # 工具函数
├── Cargo.toml              # 项目配置
└── README.md               # 项目文档
```

## 开发

### 运行测试

```bash
cargo test
```

### 交互式测试

启动服务器后，输入 `test` 命令可以运行内置的测试序列。

## 依赖

- [`docx-rs = "0.4.18"`](https://crates.io/crates/docx-rs) - 核心 DOCX 文件生成库，提供 Office Open XML 标准支持，支持图片插入
- [`serde = "=1.0.228"`](https://crates.io/crates/serde) - JSON 序列化/反序列化
- [`serde_json = "=1.0.145"`](https://crates.io/crates/serde_json) - JSON 数据处理
- [`anyhow = "=1.0.100"`](https://crates.io/crates/anyhow) - 错误处理
- [`chrono = "=0.4.42"`](https://crates.io/crates/chrono) - 时间戳和日期处理
- [`uuid = "=1.19.0"`](https://crates.io/crates/uuid) - 唯一标识符生成

## 使用示例

### 创建复杂格式的文档

```json
// 1. 创建文档
{
  "jsonrpc": "2.0",
  "method": "create_docx",
  "params": {
    "name": "formatted_document",
    "title": "格式化文档示例"
  },
  "id": 1
}

// 2. 添加标题段落（居中）
{
  "jsonrpc": "2.0",
  "method": "add_paragraph",
  "params": {
    "alignment": "center"
  },
  "id": 2
}

// 3. 添加大号粗体标题文本
{
  "jsonrpc": "2.0",
  "method": "add_run",
  "params": {
    "paragraph_index": 0
  },
  "id": 3
}

{
  "jsonrpc": "2.0",
  "method": "add_text",
  "params": {
    "paragraph_index": 0,
    "run_index": 0,
    "content": "重要文档标题"
  },
  "id": 4
}

{
  "jsonrpc": "2.0",
  "method": "update_run_properties",
  "params": {
    "paragraph_index": 0,
    "run_index": 0,
    "font_size": 18.0,
    "bold": true,
    "color": "2E86AB"
  },
  "id": 5
}

// 4. 添加正文段落（两端对齐）
{
  "jsonrpc": "2.0",
  "method": "add_paragraph",
  "params": {
    "alignment": "justify"
  },
  "id": 6
}

// 5. 添加带格式的正文
{
  "jsonrpc": "2.0",
  "method": "add_run",
  "params": {
    "paragraph_index": 1
  },
  "id": 7
}

{
  "jsonrpc": "2.0",
  "method": "add_text",
  "params": {
    "paragraph_index": 1,
    "run_index": 0,
    "content": "这是一个使用 docx-rust 库生成的标准 DOCX 文件。"
  },
  "id": 8
}

{
  "jsonrpc": "2.0",
  "method": "update_run_properties",
  "params": {
    "paragraph_index": 1,
    "run_index": 0,
    "font_size": 12.0,
    "font_name": "宋体"
  },
  "id": 9
}

// 6. 保存文档
{
  "jsonrpc": "2.0",
  "method": "save_docx",
  "params": {
    "file_path": "output/formatted_document.docx"
  },
  "id": 10
}
```

## 更新日志

### v0.0.2 (2026-01-27)

#### 🚀 新增功能
- **图片插入支持**：新增 `add_image` 和 `get_images` 方法，支持插入 PNG、JPG、JPEG、BMP 格式的图片
- **图片管理**：新增 ImageManager 模块，管理图片数据和关系ID
- **文档验证**：生成的 DOCX 文件包含真实的图片数据，而非占位符文本

#### 🔧 技术改进
- **依赖升级**：从 `docx-rust = "0.1.10"` 升级到 `docx-rs = "0.4.18"`
- **API兼容性**：适配新版本的文档生成API
- **图片ID管理**：修复图片关系ID格式不匹配问题
- **错误处理**：优化图片插入逻辑，移除对元数据的依赖

#### 🐛 问题修复
- **图片插入逻辑**：修复了只在有元数据时插入真实图片的问题，现在只要有图片数据就插入真实图片
- **图片ID格式**：修复了 `add_image` 和 `save_docx` 之间图片ID格式不匹配的问题
- **编译警告**：修复了所有未使用函数和弃用API的编译警告
- **Base64解码**：更新了弃用的 `base64::decode` 为新的 `Engine::decode` API

#### 📋 测试验证
- **功能测试**：创建了完整的图片插入测试流程
- **文件验证**：生成的 DOCX 文件包含 `word/media/` 目录和真实的图片文件
- **XML验证**：文档XML中包含正确的 `<w:drawing>` 元素和关系定义

### v0.0.1 (初始版本)

- 基础 DOCX 文档生成功能
- 段落、运行、文本操作
- 文本格式化支持（粗体、斜体、下划线、字体、颜色等）
- JSON-RPC 接口
- MCP 协议支持

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

### 贡献指南

1. Fork 本仓库
2. 创建您的功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交您的更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 打开一个 Pull Request

### 开发环境

#### 标准开发环境

```bash
# 克隆仓库
git clone https://gitee.com/awol2010ex/docx_mcp_rust.git

# 进入项目目录
cd docx_mcp_rust

# 构建项目
cargo build

# 运行测试
cargo test

# 运行服务器
cargo run
```

#### Trae IDE 集成开发

在 [Trae IDE](https://www.trae.ai/) 中使用本项目的步骤：

1. **打开 Trae IDE**，点击左侧边栏的 MCP 图标
2. **添加 MCP 服务器**：
   - 点击 "Install from Git" 或 "Add Custom Server"
   - 输入仓库地址：`https://gitee.com/awol2010ex/docx_mcp_rust.git`
   - 或选择本地项目目录

3. **自动安装**：Trae IDE 会自动识别 `Cargo.toml` 并安装依赖

4. **启动服务**：Trae IDE 会自动启动 MCP 服务器

5. **使用方式**：在 Trae IDE 的聊天界面中，可以直接使用自然语言操作 DOCX 文档，例如：
   - "创建一个标题为'项目报告'的文档"
   - "在文档中添加一个居中的段落"
   - "将这段文字设置为粗体和蓝色"
   - "保存文档到 output/report.docx"

#### 手动配置（可选）

如果需要手动配置，可以在 Trae IDE 的 MCP 设置中添加：

```json
{
  "mcpServers": {
    "docx-rust": {
      "command": "cargo",
      "args": ["run", "--bin", "docx_mcp_rust"],
      "cwd": "/path/to/docx_mcp_rust"
    }
  }
}
```