docxtpl MCP Server

# 产品需求文档 (PRD) - docxtpl MCP 服务器 ## 1. 产品概述 ### 1.1 产品名称 docxtpl-mcp - 基于模型上下文协议的 Word 文档生成服务器 ### 1.2 产品定位 一个专门用于通过 AI 助手生成 Word 文档的 MCP 服务器，使用 docxtpl 库支持复杂的模板语法和动态内容生成。 ### 1.3 目标用户 - AI 应用开发者 - 需要自动化文档生成的企业用户 - 使用 Claude 等 AI 助手的终端用户 ### 1.4 核心价值 - **标准化接口**：通过 MCP 协议提供统一的文档生成接口 - **模板驱动**：支持复杂的 Jinja2 模板语法 - **AI 集成**：无缝与 AI 助手集成，实现智能文档生成 - **扩展性强**：易于添加新模板和自定义功能 ## 2. 功能需求 ### 2.1 核心功能 #### 2.1.1 文档生成 (P0) - **功能描述**：根据模板和数据生成 Word 文档 - **输入参数**： - template_name：模板文件名 - context_data：填充数据（JSON 格式） - output_name：输出文件名（可选） - **输出结果**：生成的文档信息，包括文件路径、ID、大小等 #### 2.1.2 模板管理 (P0) - **列出模板**：显示所有可用的 Word 模板 - **验证模板**：检查模板语法并提取所需变量 - **预览模板**：使用示例数据预览生成效果 #### 2.1.3 文档管理 (P1) - **列出文档**：查看所有已生成的文档 - **删除文档**：清理不需要的生成文档 - **获取文档信息**：通过资源 URI 访问文档详情 ### 2.2 高级功能 #### 2.2.1 自定义过滤器 (P1) - **货币格式化**：将数字格式化为货币显示 - **日期格式化**：支持多种日期格式转换 - **自定义函数**：允许注册自定义 Jinja2 过滤器 #### 2.2.2 动态内容 (P1) - **条件渲染**：根据条件显示或隐藏内容 - **循环结构**：支持列表和表格的动态生成 - **嵌套模板**：支持复杂的嵌套数据结构 #### 2.2.3 提示模板 (P2) - **发票生成器**：预设的发票生成提示 - **报告生成器**：预设的报告生成提示 - **可扩展提示**：支持添加自定义提示模板 ## 3. 技术架构 ### 3.1 系统架构 ``` ┌─────────────┐ ┌──────────────┐ ┌────────────┐ │ AI Client │────▶│ MCP Server │────▶│ docxtpl │ │ (Claude) │◀────│ (Python) │◀────│ Engine │ └─────────────┘ └──────────────┘ └────────────┘ │ ▼ ┌──────────────┐ │ Templates │ │ (.docx) │ └──────────────┘ ``` ### 3.2 技术栈 - **编程语言**：Python 3.10+ - **核心框架**：MCP Python SDK - **模板引擎**：docxtpl (基于 Jinja2) - **文档处理**：python-docx - **通信协议**：stdio (标准输入输出) ### 3.3 数据流 1. AI 客户端发送文档生成请求 2. MCP 服务器接收并解析请求 3. 加载对应的 Word 模板文件 4. 使用 docxtpl 渲染模板 5. 保存生成的文档 6. 返回文档信息给客户端 ## 4. 非功能需求 ### 4.1 性能要求 - 文档生成响应时间 < 5 秒（普通文档） - 支持最大文件大小：50MB（可配置） - 并发处理能力：10+ 请求/秒 ### 4.2 可靠性 - 错误处理：完善的异常捕获和错误提示 - 数据验证：输入数据类型和格式验证 - 回滚机制：生成失败时的清理机制 ### 4.3 安全性 - 文件访问控制：限制在指定目录内操作 - 模板验证：防止恶意模板注入 - 大小限制：防止资源耗尽攻击 ### 4.4 可维护性 - 模块化设计：功能模块清晰分离 - 日志记录：详细的操作日志 - 配置管理：环境变量配置 ## 5. 用户场景 ### 5.1 场景一：生成发票 ``` 用户：请帮我生成一份发票，客户是 ABC 公司，包含 3 个产品 AI：使用发票模板生成文档... 系统：返回生成的发票文件路径和预览 ``` ### 5.2 场景二：批量报告生成 ``` 用户：我需要为 10 个项目生成月度报告 AI：批量调用文档生成工具... 系统：生成 10 份报告并提供列表 ``` ### 5.3 场景三：模板定制 ``` 用户：我想创建一个新的合同模板 AI：帮助创建模板并验证变量... 系统：保存模板并显示所需变量列表 ``` ## 6. 接口设计 ### 6.1 工具接口 #### generate_document ```python { "template_name": "string", "context_data": "object", "output_name": "string (optional)" } ``` #### list_templates ```python { # 无参数 } ``` #### validate_template ```python { "template_name": "string" } ``` ### 6.2 资源 URI - `template://{name}` - 访问模板资源 - `document://{id}` - 访问生成的文档 ### 6.3 提示接口 - `invoice_generator` - 发票生成提示 - `report_generator` - 报告生成提示 ## 7. 里程碑计划 ### Phase 1：MVP (已完成) - [x] 基础 MCP 服务器架构 - [x] 核心文档生成功能 - [x] 模板管理功能 - [x] 基础错误处理 ### Phase 2：增强功能 - [ ] 批量文档生成 - [ ] 模板版本控制 - [ ] 高级数据验证 - [ ] 性能优化 ### Phase 3：企业特性 - [ ] 多用户支持 - [ ] 权限管理 - [ ] 审计日志 - [ ] 云存储集成 ## 8. 成功指标 ### 8.1 技术指标 - 文档生成成功率 > 99% - 平均响应时间 < 3 秒 - 系统可用性 > 99.9% ### 8.2 用户指标 - 用户满意度 > 90% - 日均文档生成量增长 > 20% - 模板复用率 > 80% ## 9. 风险与对策 ### 9.1 技术风险 - **风险**：模板语法错误导致生成失败 - **对策**：提供完善的模板验证工具 ### 9.2 性能风险 - **风险**：大文档生成导致内存溢出 - **对策**：实施文件大小限制和流式处理 ### 9.3 安全风险 - **风险**：恶意模板执行危险代码 - **对策**：沙箱化模板执行环境 ## 10. 附录 ### 10.1 术语表 - **MCP**：Model Context Protocol，模型上下文协议 - **docxtpl**：Python Word 文档模板库 - **Jinja2**：Python 模板引擎 - **stdio**：标准输入输出通信方式 ### 10.2 参考资料 - [MCP 官方文档](https://modelcontextprotocol.io) - [docxtpl 文档](https://docxtpl.readthedocs.io) - [Jinja2 模板语法](https://jinja.palletsprojects.com) --- *文档版本：1.0* *更新日期：2024-09-28* *作者：docxtpl-mcp 开发团队*