<div align="center">

# 📄 MCP Word Commander

**强大的 Word 文档处理 MCP 服务器，支持图片读取/插入、表格操作等功能**

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Compatible-orange.svg)](https://modelcontextprotocol.io/)

*让 AI 助手直接读取、编辑和操作 Word 文档*

**[English](#-mcp-word-commander-english) | [中文](#-mcp-word-commander)**

</div>

---

## 📖 简介

**MCP Word Commander** 是一个基于 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 的 Word 文档处理服务，允许 AI 助手直接读取、编辑 Word 文档。

### ✨ 核心功能

| 功能模块 | 描述 |
|:--------|:-----|
| 🖼️ **图片处理** | 读取图片并直接展示给 AI、插入图片、删除/替换图片 |
| 📊 **表格操作** | 读取表格、在指定位置插入表格、修改单元格、添加/删除行 |
| 📝 **段落编辑** | 添加、替换、插入段落，支持完整的格式设置 |
| 🔍 **搜索替换** | 在文档中搜索并替换文本 |

---

## 📦 依赖

- **Python** 3.10+
- **Docker**（可选，用于容器化部署）
- 详见 `requirements.txt`

---

## 🚀 快速开始

### 方式一：本地运行

<details>
<summary><b>点击展开安装步骤</b></summary>

```bash
# Windows
.venv\Scripts\activate
pip install -r requirements.txt
python server.py

# macOS / Linux
source venv/bin/activate
pip install -r requirements.txt
python server.py
```

</details>

### 方式二：Docker 部署

#### 🐳 使用 Docker Compose（推荐）

```bash
# 构建并启动
docker-compose up -d --build

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

#### 🐳 使用 Docker 命令

<details>
<summary><b>点击展开 Docker 命令</b></summary>

```bash
# 构建镜像
docker build -t mcp-word-commander:latest .

# 运行容器（挂载本地 documents 目录）
docker run -it --rm \
  -v $(pwd)/documents:/documents \
  mcp-word-commander:latest

# Windows PowerShell
docker run -it --rm `
  -v ${PWD}/documents:/documents `
  mcp-word-commander:latest
```

</details>

### 方式三：在 Claude Desktop / Cursor 中配置

<details>
<summary><b>点击展开配置示例</b></summary>

#### 本地运行配置

```json
{
  "mcpServers": {
    "word-commander": {
      "command": "python",
      "args": ["D:/Program/mcp_word_edit/server.py"],
      "env": {}
    }
  }
}
```

#### Docker 配置

```json
{
  "mcpServers": {
    "word-commander": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "D:/Documents:/documents",
        "mcp-word-commander:latest"
      ],
      "env": {}
    }
  }
}
```

> ⚠️ **注意**：使用 Docker 时，文档路径需要是容器内的路径（如 `/documents/example.docx`），而非宿主机路径。

</details>

---

## 🛠️ 功能列表

### 📄 文档基础操作

| 工具 | 功能描述 |
|:-----|:---------|
| `create_new_document` | 创建新的空白 Word 文档 |
| `get_document_info` | 获取文档基本信息（段落数、表格数等） |
| `read_document_structure` | 分段读取文档内容和样式 |

### 📝 段落操作

| 工具 | 功能描述 |
|:-----|:---------|
| `add_formatted_paragraph` | 在文档末尾添加带格式的段落 |
| `replace_paragraph` | 替换指定段落的内容 |
| `insert_paragraph_after` | 在指定段落后插入新段落 |
| `search_and_replace` | 搜索并替换文本 |

### 🖼️ 图片操作

| 工具 | 功能描述 |
|:-----|:---------|
| `get_images_info` | 获取文档中所有图片的元信息 |
| `read_images` | **🌟 读取图片并直接返回给 AI 查看** |
| `add_image` | 在文档末尾添加图片 |
| `insert_image_after_paragraph` | 在指定段落后插入图片 |
| `delete_image` | 删除指定索引的图片 |
| `replace_image` | 替换指定索引的图片 |

### 📊 表格操作

| 工具 | 功能描述 |
|:-----|:---------|
| `read_tables` | 读取表格内容 |
| `create_table_with_data` | 在文档末尾创建表格 |
| `insert_table_after_paragraph` | 在指定段落后插入表格 |
| `update_table_cell` | 修改表格单元格内容 |
| `add_table_row` | 向表格添加新行 |
| `delete_table_row` | 删除表格中的行 |
| `delete_table` | 删除整个表格 |

---

## 💡 使用示例

### 🖼️ 读取文档中的图片

```python
# AI 可以直接"看到"文档中的图片
read_images("document.docx")

# 只读取第一张图片
read_images("document.docx", image_index=0)
```

### 📸 在指定位置插入图片

```python
# 在第 3 段后插入图片，设置宽度为 4 英寸，居中对齐
insert_image_after_paragraph(
    file_path="document.docx",
    after_index=2,
    image_path="image.png",
    width_inches=4.0,
    alignment="CENTER"
)
```

### 📊 在指定位置插入表格

```python
# 在第 5 段后插入 3x3 表格
insert_table_after_paragraph(
    file_path="document.docx",
    after_index=4,
    rows=3,
    cols=3,
    data=[
        ["姓名", "年龄", "城市"],
        ["张三", "25", "北京"],
        ["李四", "30", "上海"]
    ],
    header_bold=True
)
```

### ✏️ 修改表格单元格

```python
# 修改第一个表格的 (1, 2) 单元格
update_table_cell(
    file_path="document.docx",
    table_index=0,
    row=1,
    col=2,
    new_text="新内容",
    font_name="Microsoft YaHei",
    font_size=12,
    is_bold=True
)
```

---

## 📁 项目结构

```
mcp_word_edit/
├── 📄 server.py           # MCP 服务器主文件
├── 📋 requirements.txt    # Python 依赖
├── 🐳 Dockerfile          # Docker 镜像配置
├── 🐳 docker-compose.yml  # Docker Compose 配置
├── 🚫 .dockerignore       # Docker 构建忽略文件
├── 📖 README.md           # 说明文档
└── 📂 documents/           # 文档目录（Docker 挂载点）
```

---

## 🐳 Docker 相关

### 💾 数据持久化

使用 Docker 时，建议将本地目录挂载到容器的 `/documents` 目录：

```bash
docker run -it --rm -v /path/to/your/docs:/documents mcp-word-commander:latest
```

### 📦 镜像信息

| 项目 | 详情 |
|:-----|:-----|
| **基础镜像** | `python:3.12-slim` |
| **预计大小** | 约 200MB |
| **工作目录** | `/documents` |

---

## ⚡ 技术特点

<div align="center">

| 特性 | 说明 |
|:-----|:-----|
| 🖼️ **图片直接展示** | 使用 MCP 的 `Image` 类型，AI 可以直接"看到"文档中的图片内容 |
| 🔤 **支持中文字体** | 完整支持中文字体设置（宋体、黑体等） |
| 📍 **灵活的位置插入** | 支持在任意段落后插入图片和表格 |
| 📊 **完整的表格操作** | 支持增删改查表格及其内容 |
| 🐳 **Docker 支持** | 提供完整的容器化部署方案 |

</div>

---

## 🤝 贡献

欢迎提交 Issue 或 Pull Request！

在提交前，请确保：
- ✅ 代码风格一致
- ✅ 包含必要的说明文档
- ✅ 通过相关测试

---

## 📜 许可证

本项目使用 **MIT 许可证**，详见 [LICENSE](LICENSE) 文件。

---

<div align="center">

---

# 📄 MCP Word Commander (English)

**A powerful Word document processing MCP server with image and table support**

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Compatible-orange.svg)](https://modelcontextprotocol.io/)

*Enable AI assistants to directly read, edit, and manipulate Word documents*

**[中文](#-mcp-word-commander) | [English](#-mcp-word-commander-english)**

</div>

---

## 📖 Overview

**MCP Word Commander** is a Word document processing service based on [MCP (Model Context Protocol)](https://modelcontextprotocol.io/), enabling AI assistants to directly read and edit Word documents.

### ✨ Core Features

| Module | Description |
|:-------|:------------|
| 🖼️ **Image Processing** | Read images and display them directly to AI, insert/delete/replace images |
| 📊 **Table Operations** | Read tables, insert tables at specific positions, modify cells, add/delete rows |
| 📝 **Paragraph Editing** | Add, replace, insert paragraphs with full formatting support |
| 🔍 **Search & Replace** | Find and replace text in documents |

---

## 📦 Requirements

- **Python** 3.10+
- **Docker** (optional, for containerized deployment)
- See `requirements.txt` for details

---

## 🚀 Quick Start

### Option 1: Local Installation

<details>
<summary><b>Click to expand installation steps</b></summary>

```bash
# Windows
.venv\Scripts\activate
pip install -r requirements.txt
python server.py

# macOS / Linux
source venv/bin/activate
pip install -r requirements.txt
python server.py
```

</details>

### Option 2: Docker Deployment

#### 🐳 Using Docker Compose (Recommended)

```bash
# Build and start
docker-compose up -d --build

# View logs
docker-compose logs -f

# Stop service
docker-compose down
```

#### 🐳 Using Docker Command

<details>
<summary><b>Click to expand Docker commands</b></summary>

```bash
# Build image
docker build -t mcp-word-commander:latest .

# Run container (mount local documents directory)
docker run -it --rm \
  -v $(pwd)/documents:/documents \
  mcp-word-commander:latest

# Windows PowerShell
docker run -it --rm `
  -v ${PWD}/documents:/documents `
  mcp-word-commander:latest
```

</details>

### Option 3: Configure in Claude Desktop / Cursor

<details>
<summary><b>Click to expand configuration examples</b></summary>

#### Local Configuration

```json
{
  "mcpServers": {
    "word-commander": {
      "command": "python",
      "args": ["/path/to/mcp_word_edit/server.py"],
      "env": {}
    }
  }
}
```

#### Docker Configuration

```json
{
  "mcpServers": {
    "word-commander": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/documents:/documents",
        "mcp-word-commander:latest"
      ],
      "env": {}
    }
  }
}
```

> ⚠️ **Note**: When using Docker, document paths should be container paths (e.g., `/documents/example.docx`), not host paths.

</details>

---

## 🛠️ Feature List

### 📄 Basic Document Operations

| Tool | Function |
|:-----|:---------|
| `create_new_document` | Create a new blank Word document |
| `get_document_info` | Get basic document information (paragraph count, table count, etc.) |
| `read_document_structure` | Read document content and styles in segments |

### 📝 Paragraph Operations

| Tool | Function |
|:-----|:---------|
| `add_formatted_paragraph` | Add a formatted paragraph at the end of document |
| `replace_paragraph` | Replace content of a specific paragraph |
| `insert_paragraph_after` | Insert a new paragraph after a specific paragraph |
| `search_and_replace` | Search and replace text |

### 🖼️ Image Operations

| Tool | Function |
|:-----|:---------|
| `get_images_info` | Get metadata of all images in the document |
| `read_images` | **🌟 Read images and return them directly for AI to view** |
| `add_image` | Add image at the end of document |
| `insert_image_after_paragraph` | Insert image after a specific paragraph |
| `delete_image` | Delete image by index |
| `replace_image` | Replace image by index |

### 📊 Table Operations

| Tool | Function |
|:-----|:---------|
| `read_tables` | Read table content |
| `create_table_with_data` | Create table at the end of document |
| `insert_table_after_paragraph` | Insert table after a specific paragraph |
| `update_table_cell` | Modify table cell content |
| `add_table_row` | Add new row to table |
| `delete_table_row` | Delete row from table |
| `delete_table` | Delete entire table |

---

## 💡 Usage Examples

### 🖼️ Read Images from Document

```python
# AI can directly "see" images in the document
read_images("document.docx")

# Read only the first image
read_images("document.docx", image_index=0)
```

### 📸 Insert Image at Specific Position

```python
# Insert image after paragraph 3, set width to 4 inches, center alignment
insert_image_after_paragraph(
    file_path="document.docx",
    after_index=2,
    image_path="image.png",
    width_inches=4.0,
    alignment="CENTER"
)
```

### 📊 Insert Table at Specific Position

```python
# Insert a 3x3 table after paragraph 5
insert_table_after_paragraph(
    file_path="document.docx",
    after_index=4,
    rows=3,
    cols=3,
    data=[
        ["Name", "Age", "City"],
        ["John", "25", "Beijing"],
        ["Jane", "30", "Shanghai"]
    ],
    header_bold=True
)
```

### ✏️ Modify Table Cell

```python
# Modify cell (1, 2) of the first table
update_table_cell(
    file_path="document.docx",
    table_index=0,
    row=1,
    col=2,
    new_text="New Content",
    font_name="Microsoft YaHei",
    font_size=12,
    is_bold=True
)
```

---

## 📁 Project Structure

```
mcp_word_edit/
├── 📄 server.py           # MCP server main file
├── 📋 requirements.txt    # Python dependencies
├── 🐳 Dockerfile          # Docker image configuration
├── 🐳 docker-compose.yml  # Docker Compose configuration
├── 🚫 .dockerignore       # Docker build ignore file
├── 📖 README.md           # Documentation
└── 📂 documents/          # Documents directory (Docker mount point)
```

---

## 🐳 Docker Information

### 💾 Data Persistence

When using Docker, mount a local directory to `/documents` in the container:

```bash
docker run -it --rm -v /path/to/your/docs:/documents mcp-word-commander:latest
```

### 📦 Image Details

| Item | Details |
|:-----|:--------|
| **Base Image** | `python:3.12-slim` |
| **Estimated Size** | ~200MB |
| **Working Directory** | `/documents` |

---

## ⚡ Technical Features

<div align="center">

| Feature | Description |
|:--------|:------------|
| 🖼️ **Direct Image Display** | Uses MCP's `Image` type, allowing AI to directly "see" image content in documents |
| 🔤 **Chinese Font Support** | Full support for Chinese font settings (SimSun, SimHei, etc.) |
| 📍 **Flexible Position Insertion** | Support inserting images and tables after any paragraph |
| 📊 **Complete Table Operations** | Support CRUD operations for tables and their content |
| 🐳 **Docker Support** | Complete containerized deployment solution |

</div>

---

## 🤝 Contributing

Issues and PRs are welcome!

Before submitting, please ensure:
- ✅ Code style consistency
- ✅ Necessary documentation included
- ✅ Related tests passed

---

## 📜 License

This project is licensed under the **MIT License**. See [LICENSE](LICENSE) for details.

---

<div align="center">

**Made with ❤️ for the MCP community**

</div>