dsh-docx-mcp

Readme

# dsh-docx-mcp

零依赖的 MCP stdio 服务，根据 JSON 规格生成**真正可打开的 .docx 文件**（标题 / 段落 / 项目符号列表 / 表格）。
属于 `helibeiqi` 的 DeepSeek Harness 插件矩阵中的 **中文办公自动化** 垂直。

- 纯 Node 实现，手写 OOXML + store-zip，**无需 `npm install`、无第三方依赖** —— 与 `dsh-quant-data-mcp` 同源的「自包含、抗重装」哲学。
- 通过 dsh 的 MCP 桥接（`@deepseek-ai/dsh-mcp-client`）注册为 `docx` 工具，供 dsh agent 直接调用。

---

## 工具：`docx_generate`

| 参数 | 类型 | 说明 |
|---|---|---|
| `title` | string | 文档大标题（自动作为一级标题插入开头） |
| `filename` | string | 输出文件名（可含或不含 `.docx`） |
| `outDir` | string | 输出目录，默认 `~/dsh-docx-output` |
| `blocks` | array | 内容块数组（见下） |

### blocks 内容块

| `type` | 字段 | 说明 |
|---|---|---|
| `heading` | `level`(1-3), `text` | 标题 |
| `paragraph` | `runs`(数组 `{text,bold}`) 或 `text`,`bold` | 段落；`runs` 支持同一段落内混合加粗 |
| `bullet` | `items`(string[]) 或 `text` | 项目符号列表 |
| `table` | `rows`(string[][]) | 表格，每行是一组单元格 |

### 调用示例

```json
{
  "title": "员工劳动合同续签通知书",
  "blocks": [
    { "type": "paragraph", "runs": [
      { "text": "致：", "bold": false },
      { "text": "张三", "bold": true },
      { "text": "（工号 E000123）" }
    ]},
    { "type": "heading", "level": 2, "text": "一、续签事项" },
    { "type": "bullet", "items": ["合同期限：3 年", "试用期：无", "工时制度：标准工时"] },
    { "type": "heading", "level": 2, "text": "二、薪资结构" },
    { "type": "table", "rows": [
      ["项目", "占比"], ["基本工资", "40%"], ["岗位工资", "40%"], ["绩效工资", "20%"]
    ]}
  ]
}
```

返回 `{ "path": "...", "bytes": N, "blocks": N }`。

---

## 与 dsh 集成

本仓库是一个 dsh bundle：`package.json` 声明 `dsh.bundle.patch` 指向 `cordis.patch.yml`，
后者以 `- insert:` 形式向 `@deepseek-ai/dsh-mcp-client` 注册一个 `docx` MCP server 行。

> 路径约定：当前 `cordis.patch.yml` 中 `args` / `cwd` 写的是作者本机的绝对路径
> `C:\Users\helib\dsh-docx-mcp\...`。部署到其他机器时，请改为该机器上 `docx-mcp-server.mjs` 的实际路径；
> 或通过 `QUANT_MCP_NODE` 环境变量指定 Node 运行时（与 `dsh-quant-data-mcp` 同款硬化写法，可兼容 managed-node 版本目录漂移）。

---

## 本地运行 / 自测

```bash
# 直接起 MCP 服务（stdio）
node docx-mcp-server.mjs

# 自测：生成 selftest.docx 并校验为合法 OOXML 包
node _selftest.mjs
```

---

## Roadmap

- `docx_fill_template`：对含 `{{占位符}}` 的 .docx 模板做字段填充（HR 合同 / 通知书高频场景）。
- 页眉页脚、多级编号、字体 / 对齐等段落属性。
- 与 `dsh-excel-kit` 联动（表格数据 → 文档）。

---

## 许可

MIT © helibeiqi —— 详见 [dsh-ecosystem](https://github.com/helibeiqi/dsh-ecosystem)。