first commit

README.md

@@ -0,0 +1,107 @@
+## DOCX 转换工具 MCP 服务器
+
+这是一个基于 MCP (Model Context Protocol) 的服务器，目前**只提供 HTML → DOCX** 的转换能力，底层通过 Pandoc 实现高质量排版。
+
+### 功能
+
+- **html_to_docx_pandoc**：将包含 HTML 标签的文本转换为 DOCX 文件，支持引用模板、Lua 过滤器等高级格式控制。
+
+### 安装依赖（本机运行）
+
+```bash
+pip install -r requirements.txt
+```
+
+请确保系统已安装 Pandoc（`pandoc --version` 可正常执行）。
+
+### 使用方法
+
+#### 方式一：本机直接运行
+
+运行服务器：
+
+```bash
+python mcp_docx_server.py
+```
+
+在 MCP 客户端中连接该服务器后，会看到一个名为 `html_to_docx_pandoc` 的工具。
+
+#### 方式二：使用 Docker 封装运行
+
+本项目已提供 `Dockerfile`，可以直接构建镜像并运行：
+
+```bash
+# 构建镜像
+docker build -t mcp-docx-server .
+
+# 运行容器（前台运行）
+docker run --rm -it mcp-docx-server
+```
+
+如果你希望在容器外部自定义 `ref.docx`、`color.lua` 或输出目录，可以通过挂载卷的方式：
+
+```bash
+docker run --rm -it ^
+  -v %cd%/ref.docx:/app/ref.docx ^
+  -v %cd%/color.lua:/app/color.lua ^
+  -v %cd%/output:/app/output ^
+  mcp-docx-server
+```
+
+在类 Unix 系统（如 macOS / Linux）中可改为：
+
+```bash
+docker run --rm -it \
+  -v "$(pwd)/ref.docx:/app/ref.docx" \
+  -v "$(pwd)/color.lua:/app/color.lua" \
+  -v "$(pwd)/output:/app/output" \
+  mcp-docx-server
+```
+
+#### 方式三：使用 docker-compose 运行
+
+已提供 `docker-compose.yml`，可以一条命令完成构建与运行：
+
+```bash
+# 构建并启动（前台）
+docker-compose up --build
+```
+
+默认会：
+
+- **构建镜像**：使用当前目录下的 `Dockerfile`
+- **挂载当前目录到容器 `/app`**：方便直接访问 `ref.docx`、`color.lua` 和输出文件
+- **在容器内执行**：`python mcp_docx_server.py`
+
+如需在后台运行，可使用：
+
+```bash
+docker-compose up -d --build
+```
+
+### 工具说明：html_to_docx_pandoc
+
+**作用：** 使用 Pandoc 将 HTML 文本转换为 DOCX 文件，尽可能保留原始样式，并支持：
+- 使用 `ref.docx` 作为参考模板（如果文件存在）
+- 使用 `color.lua` 作为 Lua 过滤器（如果文件存在）
+- 独立 HTML 模式、图片提取、自定义 CSS 等选项
+
+**参数：**
+- `html_text`（必需）：需要转换的 HTML 文本内容
+- `output_path`（必需）：输出 DOCX 文件的完整路径
+- `standalone`（可选，默认 `true`）：是否以独立 HTML 模式调用 Pandoc
+- `extract_media`（可选）：图片提取目录（如 `./media`），不需要提取可不传
+- `css_file`（可选）：CSS 样式文件路径
+
+### 依赖项
+
+- `mcp`: MCP Python SDK
+- `python-docx`、`lxml`：内部保留的 DOCX/HTML 处理能力（当前未通过 MCP 暴露）
+- **外部工具**：Pandoc（必须预先在系统中安装）
+
+### 注意事项
+
+- 必须安装 MCP SDK 才能运行服务器
+- 确保有足够的权限读取输入文件和写入输出文件
+- 大文件转换可能需要较长时间
+