# Document Operator MCP

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

一个 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) Server，让 AI 助手（Claude Desktop、Trae、Cursor 等）能够通过自然语言操作 Word(.docx) 和 Excel(.xlsx) 文档。

---

## 功能

| 类别 | 操作 | 说明 |
|------|------|------|
| **Word** | 📖 读取全文 / 指定段落 | 支持查看文档结构（标题、段落、表格） |
| | 📊 提取表格 | 提取所有表格数据 |
| | ✏️ 修改段落 | 修改、追加、插入段落 |
| | 🔍 搜索替换 | 全文搜索并替换文本 |
| **Excel** | 📖 读取数据 | 读取 Sheet、单元格、区域 |
| | ✏️ 写入单元格 | 按地址或行列号写入 |
| | 🗂️ 管理 Sheet | 添加、删除、列出 Sheet |
| | 📝 创建文件 | 创建新的 xlsx 文件 |
| **临时表** | 📊 批量查询 | 按指定Sheet/行/列批量提取数据 |
| | 💾 内存暂存 | 将查询结果存入命名临时表 |
| | 📤 导出保存 | 将临时表保存为 .xlsx 文件 |

---

## 快速开始

### 1. 安装

```bash
# 方式一：pip 安装
pip install git+https://github.com/dai-zw/document-operator-mcp.git

# 方式二：uvx（推荐）
uvx --from git+https://github.com/dai-zw/document-operator-mcp.git document-operator-mcp
```

### 2. 配置到 AI 客户端

#### Claude Desktop

```json
{
  "mcpServers": {
    "document-operator": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dai-zw/document-operator-mcp.git", "document-operator-mcp"]
    }
  }
}
```

#### Trae IDE / Cursor

在项目的 `.trae/mcp.json` 或 `.cursor/mcp.json` 中添加：

```json
{
  "mcpServers": {
    "document-operator": {
      "command": "python",
      "args": ["-m", "document_operator_mcp.server"]
    }
  }
}
```

或直接指定路径：

```json
{
  "mcpServers": {
    "document-operator": {
      "command": "python",
      "args": [".trae/skills/document-operator/mcp_server/server.py"]
    }
  }
}
```

### 3. 开始对话

配置完成后，在 AI 对话中可以直接说：

- "读取这份 word 文档 d:/report.docx"
- "把第3段改成：项目已完成"
- "在 excel 的 B2 填入 500"
- "列出这个表格有哪些 sheet"
- "把文档里所有的'旧系统'替换成'新平台'"
- "从 data.xlsx 的 Sheet1 读取第2-50行的 A、C、F 列，存为临时表 tb1，然后保存到 extract.xlsx"

AI 会自动调用对应的 MCP Tool 完成操作。

---

## 本地开发

```bash
# 克隆项目
git clone https://github.com/dai-zw/document-operator-mcp.git
cd document-operator-mcp

# 安装依赖
pip install -e .

# 启动 MCP Server（stdio 模式）
python -m document_operator_mcp.server

# 用 MCP Inspector 调试
mcp dev document_operator_mcp/server.py
```

---

## 提供的 Tool 列表（14 个）

### Word 工具

| Tool | 用途 |
|------|------|
| `read_docx` | 读取全文或指定段落 |
| `read_docx_tables` | 提取所有表格 |
| `write_docx` | 修改 / 追加 / 插入段落 |
| `replace_docx_text` | 全文搜索替换 |
| `get_docx_info` | 查看文档结构 |

### Excel 工具

| Tool | 用途 |
|------|------|
| `read_xlsx` | 读取 Sheet / 单元格 / 区域 |
| `write_xlsx` | 写入单元格 |
| `list_xlsx_sheets` | 列出所有 Sheet |
| `create_xlsx` | 创建新工作簿 |
| `manage_xlsx_sheet` | 添加或删除 Sheet |

### 临时表 / 批量查询工具

| Tool | 用途 |
|------|------|
| `query_xlsx` | 从 Excel 批量读取指定Sheet/行/列，可选存入内存临时表 |
| `get_temp_table` | 查看内存临时表数据 |
| `save_temp_table` | 将临时表保存为 .xlsx 文件 |
| `list_temp_tables` | 列出当前会话所有临时表 |

**批量查询典型工作流：**
```
query_xlsx("data.xlsx", sheet_name="Sheet1", start_row=2, end_row=100, columns="A,C,F", output_table_name="mydata")
get_temp_table("mydata")                                    # 查看数据
save_temp_table("mydata", "output.xlsx")                    # 保存为新文件
```

---

## 技术栈

- [python-docx](https://python-docx.readthedocs.io/) - Word .docx 操作
- [openpyxl](https://openpyxl.readthedocs.io/) - Excel .xlsx 操作
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - MCP 协议实现

## 限制

- Word 仅支持 `.docx` 格式，不支持旧版 `.doc`
- Excel 仅支持 `.xlsx` 格式
- Word "分页" 操作为段落级近似（python-docx 不支持原生页码）
- 修改操作会直接保存到原文件，请注意备份

## License

MIT