@birthday8/doc-mcp

v1.0.14

Published

7 days ago

Doc Creator MCP Server - Generate Word documents from HTML with rich formatting support

0High
0Medium
0Low

birthday8

mcp mcp-server docx word document html converter document-generator word-document

Doc Creator

简介

Doc Creator 是一个强大的文档生成工具，通过 YAML 格式定义文档结构和样式，自动生成专业的 Microsoft Word (.docx) 文档。采用严格的样式白名单机制，确保生成的文档风格一致、格式规范。

特性

🎯 严格的样式约束 - 预定义样式白名单，防止样式不一致
📝 YAML 格式 - 结构清晰，易于编写和维护
✅ 自动验证 - 内置验证器确保格式正确
🎨 丰富的格式支持 - 标题、段落、列表、表格、图表、数学公式等
📊 数据可视化 - 支持柱状图、折线图、饼图、雷达图
📐 科学排版 - 支持 LaTeX 数学公式
📄 标准输出 - 生成标准 .docx 文件，兼容 Microsoft Word

技术栈

Python 3.8+ - 核心运行时
python-docx - Word 文档生成
PyYAML - YAML 解析
Matplotlib - 图表绘制
NumPy - 数值计算

安装

环境要求

Node.js 14.0 或更高版本（用于便捷启动）
Python 3.8 或更高版本（核心运行时）

方式一：使用 npx（推荐）

无需克隆仓库，直接使用 npx 运行：

npx -y @birthday8/doc-mcp

方式二：克隆仓库

git clone https://github.com/233a45/doc-mcp.git
cd doc-mcp
node index.js

方式三：Python 直接使用

如果你不想使用 Node.js，可以直接使用 Python：

pip install pyyaml python-docx matplotlib numpy
python python/server.py

MCP 配置

将 Doc Creator 配置到你的 AI 客户端中：

Claude Desktop

编辑 claude_desktop_config.json：

Windows: %APPDATA%/Claude/claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "doc-creator": {
      "command": "npx",
      "args": [
        "-y",
        "@birthday8/doc-mcp"
      ]
    }
  }
}

Cursor

在 Cursor 设置中找到 MCP 配置，添加：

{
  "mcpServers": {
    "doc-creator": {
      "command": "npx",
      "args": [
        "-y",
        "@birthday8/doc-mcp"
      ]
    }
  }
}

其他支持 MCP 的客户端

参考上述配置格式，将 npx -y @birthday8/doc-mcp 作为命令配置即可。

快速开始

1. 创建 YAML 文件

version: "1.0"
metadata:
  title: "示例文档"
content:
  - type: heading
    level: 1
    children:
      - type: text
        content: "欢迎使用 Doc Creator"
  
  - type: paragraph
    style:
      align: justify
      lineHeight: 1.5
    children:
      - type: text
        content: "这是一个使用 YAML 格式生成的 Word 文档示例。"
  
  - type: chart
    chartType: bar
    title: "季度销售数据"
    labels: ["Q1", "Q2", "Q3", "Q4"]
    data: [120, 150, 180, 200]

2. 生成文档

from python.yaml_to_docx import convert_yaml_to_docx

with open("document.yaml", "r", encoding="utf-8") as f:
    yaml_content = f.read()

convert_yaml_to_docx(yaml_content, "output.docx")

3. 命令行使用

cd python
python yaml_to_docx.py input.yaml output.docx

核心功能

支持的节点类型

| 类型 | 说明 | 示例 | |------|------|------| | heading | 标题 | level: 1-6 | | paragraph | 段落 | 支持样式和缩进 | | text | 纯文本 | 基础文本节点 | | span | 样式容器 | 字体、颜色、加粗等 | | emphasis | 强调 | strong/em/u/s/sup/sub | | list / listItem | 列表 | 有序/无序列表 | | table | 表格 | 支持合并单元格 | | chart | 图表 | 柱状图/折线图/饼图/雷达图 | | math | 数学公式 | LaTeX 公式 | | image | 图片 | 支持本地和网络图片 | | codeBlock | 代码块 | 语法高亮 | | callout | 提示框 | info/warning/success | | toc | 目录 | 自动生成 | | columns | 多栏布局 | 1-4 栏 | | pageBreak | 分页符 | 强制分页 |

样式白名单

所有样式值必须来自预定义白名单：

| 属性 | 可选值 | |------|--------| | fontSize | 8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 26, 28, 36, 48, 72 | | fontFamily | 微软雅黑, 宋体, 黑体, 楷体, Arial, Times New Roman, Consolas, Calibri, Helvetica, Georgia | | color | black, darkGray, gray, lightGray, red, blue, green, yellow, orange, purple, pink, brown, white, darkBlue, navy, darkGreen, darkRed, gold, silver | | align | left, center, right, justify | | lineHeight | 1.0, 1.15, 1.5, 2.0, 2.5 | | bgColor | lightBlue, lightGreen, lightYellow, lightRed, lightGray, white, lightPurple, lightOrange, lightPink |

示例

项目报告

version: "1.0"
metadata:
  title: "项目进度报告"
content:
  - type: heading
    level: 1
    align: center
    children:
      - type: text
        content: "项目进度报告"
  
  - type: table
    children:
      - type: tableRow
        isHeader: true
        children:
          - type: tableCell
            bgColor: lightBlue
            children:
              - type: text
                content: "任务"
          - type: tableCell
            bgColor: lightBlue
            children:
              - type: text
                content: "状态"
      - type: tableRow
        children:
          - type: tableCell
            children:
              - type: text
                content: "需求分析"
          - type: tableCell
            children:
              - type: text
                content: "已完成"

数据可视化

- type: chart
  chartType: line
  title: "销售趋势"
  labels: ["1月", "2月", "3月", "4月", "5月", "6月"]
  series:
    - name: "2024年"
      data: [100, 120, 140, 160, 180, 200]
    - name: "2025年"
      data: [110, 135, 155, 175, 195, 220]

数学公式

- type: math
  latex: "E = mc^2"
  display: true

文档

AI 使用指南 - 详细的 AI 使用说明
AI 提示词 - AI 提示词模板
YAML Schema - 完整的格式规范

项目结构

doc-creator/
├── python/
│   ├── server.py              # MCP 服务器
│   ├── yaml_schema.py         # YAML 格式定义
│   ├── yaml_document.py       # 文档模型
│   ├── yaml_validator.py      # 验证器
│   ├── yaml_to_docx.py        # 转换器
│   └── sample/                # 示例文档
├── AI_USAGE_GUIDE.md          # AI 使用指南
├── AI_USAGE_PROMPT.md         # AI 提示词
└── README.md                  # 本文档

MCP 工具

本项目提供 MCP (Model Context Protocol) 工具供 AI 使用：

| 工具 | 说明 | |------|------| | get-yaml-schema | 获取 YAML 格式规范 | | validate-yaml | 验证 YAML 格式 | | convert-yaml-document | 转换为 DOCX | | get-document-guide | 获取完整指南 |

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT