将 文档生成能力 通过 MCP (Model Context Protocol) 开放给任意 AI Agent(Dify、Claude、OpenAI 等),支持生成 Word (.docx) / PDF / Excel (.xlsx) / PowerPoint (.pptx),并把生成结果上传到 对象存储(S3/MinIO/OSS/COS) 或本地磁盘,最终以 可下载链接 的形式返回给 Agent。
- 一服务多入口
- MCP (Streamable HTTP):供 Dify、OpenAI、Claude 等支持 MCP 的 Agent 远程调用
- MCP (stdio):供 Claude Desktop 等直接拉起进程的 Agent 使用
- REST API:供 Dify 插件、脚本或其他 HTTP 客户端调用(底层与 MCP 共用同一套引擎)
- 四种文档格式,统一的结构化输入模型,引擎彼此隔离、易于扩展
- 对象存储适配:支持 AWS S3、MinIO、阿里云 OSS、腾讯云 COS(切换端点即可),本地开发自动回退到本地磁盘 + 静态文件服务
- 链接输出:每次生成返回
{ url, filename, size, mimeType, ... },Agent 直接拿到可下载链接 - Dify 插件包:
dify-plugin/提供可直接打包导入 Dify 的工具插件 - 独立 Web 管理后台:HTTP 模式下自动在单独端口(默认 9001)启动管理界面,提供生成文件管理(列表/预览/下载/删除)、文档模板定制与一键生成,与功能端口(9000)完全分离,互不干扰
┌──────────────────────────────────────────┐
│ ai-doc (Node/TS) │
AI Agent / Dify ──▶│ │
(MCP client) │ /mcp MCP Streamable HTTP ──┐ │
│ /api/documents/:format ────┼── MCP 工具│
Dify Plugin ─────▶ │ (REST, 供插件使用) │ │
│ DocumentService │
│ │ │ │ │
│ Generator: docx │ pdf │ xlsx │ pptx │
│ │ │
│ Storage 抽象 │
│ S3(MinIO/OSS/COS) │ Local(dev) │
└──────────────────┬───────────┬──────────┘
上传 + 返回公开链接 本地磁盘 + /files
src/
├── index.ts # 入口:按 DOC_MCP_TRANSPORT 启动 stdio 或 HTTP 服务
├── config.ts # 环境变量配置(S3/存储/服务)
├── core.ts # DocumentService:生成 + 上传 + 组装链接结果
├── docs/ # 文档引擎(与存储/传输完全解耦)
│ ├── types.ts # 输入/输出数据模型
│ ├── schemas.ts # zod 输入校验
│ ├── generator.ts # Generator 接口
│ ├── index.ts # 格式注册表
│ ├── word.ts pdf.ts excel.ts ppt.ts
├── mcp/server.ts # MCP 工具/资源注册(registerTool)
├── http/server.ts # MCP Streamable HTTP + REST + 静态文件
├── admin/server.ts # Web 管理后台(独立端口 R EST:文件/模板/生成)
│ ├── templates.ts # 模板持久化(JSON 文件)
│ └── public/ # 管理界面前端(HTML/CSS/JS,零依赖)
└── storage/ # Storage 抽象:s3.ts / local.ts
dify-plugin/ # Dify 插件包(Python dify-plugin SDK)
scripts/ # 冒烟测试脚本
要求:Node.js ≥ 20。
npm install
npm run build
# 本地开发:HTTP 模式 + 本地磁盘存储(默认)
cp .env.example .env # 按需修改
npm run start:http # 或 npm run dev:http启动后:
- MCP 端点:
http://localhost:9000/mcp - REST 端点:
POST http://localhost:9000/api/documents/:format - 健康检查:
GET /health - 本地生成的文件通过
/files/...访问 - Web 管理后台:
http://localhost:9001/(独立端口,默认 9001,可用ADMIN_PORT修改)
HTTP 模式下自动启动一个独立的 Web 管理界面(端口与功能端口分离,默认 ADMIN_PORT=9001),用于:
- 生成文件管理:查看全部已生成文件(文件名/格式/大小/时间)、搜索、上传源预览(PDF 在线预览,Office 格式展示元数据)、下载、删除
- 模板定制:以 JSON 形式创建/编辑/保存文档内容模板(四种格式各带示例,可一键载入),模板持久化为
templates/*.json - 文档生成:从模板或直接编辑 JSON 输入生成 docx/pdf/xlsx/pptx,生成结果复用同一套存储,随即出现在「生成文件」列表中
初始启动会向
templates/写入 4 个示例模板便于上手;删除templates/目录后会自动重新写入。
样式模板是用户上传的真实文档文件(.pptx / .docx / .xlsx),生成同格式文档时自动继承它的主题 / 母版 / 布局 / 配色(PPT 的母版与版式、Word 的主题/样式、Excel 的表格样式)。
- 生成时不传
styleTemplateId,自动套用该格式在管理后台设置的默认样式模板;传了styleTemplateId则使用指定模板。 - 内置默认 PPT 模板:首次启动会自动把
src/assets/default-presentation.pptx注册为 pptx 的默认样式模板(浅色背景 + 深蓝页眉条 + 橙色点缀 + 16:9 版式),因此生成 PPT 默认就带样式、不再是白底。 - 更换默认外观:在管理后台「样式模板」上传自己的模板并「设为默认」即可。
- 内置默认只在首次启动、且该格式尚无默认时写入(
style-templates/.seed-defaults标记控制;删除该标记并重启可重新导入内置模板),不会覆盖你后来设置的默认。 - 注意:样式全部继承自模板的母版 / 布局 / 主题。若模板本身就是"白底、母版为空"的文件,生成结果仍会是白底——请使用带母版背景/版式的正式模板。
| 变量 | 默认 | 说明 |
|---|---|---|
DOC_MCP_TRANSPORT |
http |
stdio 或 http |
VERBOSE |
false |
是否输出详细日志 |
HOST / PORT |
0.0.0.0 / 9000 |
HTTP 监听地址 |
MCP_PATH |
/mcp |
MCP 端点路径 |
ADMIN_ENABLED |
true |
是否启动管理后台(仅 HTTP 模式有效) |
ADMIN_HOST / ADMIN_PORT |
0.0.0.0 / 9001 |
管理后台监听地址(独立于 PORT) |
TEMPLATE_DIR |
templates |
模板 JSON 持久化目录 |
STYLE_TEMPLATE_DIR |
style-templates |
样式模板(上传的 pptx/docx/xlsx 文件)存储目录 |
STORAGE_MODE |
local |
local 或 s3 |
LOCAL_STORAGE_DIR |
storage |
本地存储目录 |
LOCAL_PUBLIC_BASE_URL |
http://localhost:9000 |
生成链接的对外访问地址(部署到公网时改成本机公网域名) |
S3_ENDPOINT |
空(AWS) | 兼容 S3 的端点,如 MinIO http://localhost:9000 |
S3_REGION |
us-east-1 |
地区 |
S3_ACCESS_KEY / S3_SECRET_KEY |
空 | 密钥 |
S3_BUCKET |
ai-doc |
桶名 |
S3_PATH_STYLE |
true |
MinIO/OSS 用 true,AWS 用 false |
S3_PUBLIC_BASE_URL |
空 | 公开下载链接前缀,如 https://cdn.example.com(空则用端点推导) |
部署到公网时务必把
LOCAL_PUBLIC_BASE_URL或S3_PUBLIC_BASE_URL改为 Agent 可达的公网地址,否则返回的链接无法访问。
Dify 原生支持 MCP。在 工具 → MCP → 添加 MCP 服务 中选择 SSE / Streamable HTTP:
- 服务地址:开启服务后填写
http://<你的服务地址>:9000/mcp - 保存后即会出现 4 个工具:
generate_word_docx、generate_pdf、generate_excel_xlsx、generate_powerpoint_pptx
必填字段(缺失或为空会被拒绝并返回原因):
username:当前发起生成的用户(SSO 用户名),用于把文档归属到该用户而不是【系统】;filename:下载文件名(不含扩展名);title:文档标题;- 内容:
paragraphs(docx/pdf) /sheets(xlsx) /slides(pptx),至少 1 项。Agent 应在调用前向用户播报“正在生成…”,返回后立即展示下载链接,避免看起来“卡住”。
在 Claude 配置中注册:
{
"mcpServers": {
"ai-doc": {
"command": "node",
"args": ["/path/to/ai-doc/dist/index.js"],
"env": { "DOC_MCP_TRANSPORT": "stdio", "STORAGE_MODE": "local" }
}
}
}直接调用 HTTP MCP 端点,或用 REST API:
curl -X POST http://localhost:9000/api/documents/pdf \
-H "Content-Type: application/json" \
-d '{"username": "zhangsan", "filename": "周报", "title": "周报", "paragraphs": [{"text": "本周总结", "level": 1}, {"text": "完成 X 项任务", "bullet": true}]}'
# => { "url": "https://...", "filename": "周报.pdf", "size": ..., "format": "pdf" }dify-plugin/ 是基于 dify-plugin SDK 的 Tool 类型插件,内部通过 REST API 调用 ai-doc 服务,因此服务本身也可独立运行、被多个 Dify 实例共享。
cd dify-plugin
pip install -r requirements.txt
dify plugin init # 已有代码,用于生成 .dify/ 与配置
dify plugin package ./ # 打包生成 .difypkg
# 在 Dify 后台「插件 → 本地导入」上传安装插件包含 4 个工具,使用前在每个工具里填写「Service Base URL」(ai-doc 服务地址,如 http://localhost:9000)。
插件的每个工具都要求 LLM 提供必填的
username(当前用户)、filename(下载文件名,不含扩展名)、title以及内容 (paragraphs/sheets/slides)。缺失或为空时 REST 服务将返回 422 及具体原因。
- 在
src/docs/新建生成器(实现Generator接口 +generate(input): Buffer) - 在
src/docs/schemas.ts添加 zod 校验 - 在
src/docs/index.ts注册 - (可选)在
dify-plugin/tools/补对应工具的 yaml + py
引擎与存储、传输解耦,新增格式无需改动 MCP / REST / 存储逻辑。
npm run build
npm run start:http # 起服务后
# HTTP 模式的 MCP 全流程
node scripts/mcp-smoke.mjs
# stdio 模式全流程
node scripts/mcp-stdio-smoke.mjs- 对象存储采用 S3 协议,配合
forcePathStyle与endpoint即可对接 MinIO / OSS / COS,无需业务代码改动。 - 生成的文档不落临时文件,直接以 Buffer 上传到存储,节省磁盘并减少 IO。