JXLS Excel Template Generator

# JXLS Excel模板生成MCP服务端需求文档 ## 1. 项目概述 ### 1.1 项目目标 开发一个MCP服务端，用于根据输入参数生成符合JXLS规范的Excel模板文件。该服务端将作为AI应用和Excel模板生成功能之间的桥梁。 ### 1.2 JXLS简介 JXLS是一个Java库，用于从Excel模板生成Excel报告。它使用特殊的批注来标记模板中的动态内容区域。 ## 2. 功能需求 ### 2.1 核心功能 - 支持生成包含JXLS批注的Excel模板 - 支持两种主要的JXLS批注：`jx:area()` 和 `jx:each()` - 提供标准化的MCP工具接口 - 支持多种数据格式输入 ### 2.2 JXLS批注支持 #### 2.2.1 jx:area() 批注 - **功能**: 定义数据处理区域 - **语法**: `jx:area(lastCell="<cell_reference>")` - **用途**: 标记模板中需要进行数据处理的区域范围 #### 2.2.2 jx:each() 批注 - **功能**: 循环遍历集合数据 - **语法**: `jx:each(items="<collection_name>" var="<item_variable>" lastCell="<cell_reference>")` - **用途**: 对集合中的每个元素重复生成行或区域 ### 2.3 模板结构要求 - **第一行**: 列标题行 - **第二行**: 循环数据行，包含JXLS批注 - **支持简单的表格结构** ### 2.4 数据格式支持 #### 2.4.1 JSON对象格式 ```json [ {"name": "张三", "age": 25, "city": "北京"}, {"name": "李四", "age": 30, "city": "上海"} ] ``` #### 2.4.2 数组格式 ```json [ ["张三", 25, "北京"], ["李四", 30, "上海"] ] ``` ## 3. 技术需求 ### 3.1 MCP协议支持 - 实现MCP规范的完整协议支持 - 支持工具(Tools)定义和执行 - 提供标准化的错误处理 ### 3.2 通信模式支持 #### 3.2.1 stdio通信模式 - 通过标准输入输出进行通信 - 适用于本地集成和开发调试 - 支持同步和异步操作 ### 3.3 开发技术栈 - **语言**: Python 3.10+ - **MCP框架**: 使用MCP Python SDK - **Excel处理**: openpyxl库 - **JSON处理**: 标准json库 ## 4. MCP工具定义 ### 4.1 generateJxlsTemplate工具 #### 4.1.1 功能描述 根据输入参数生成符合JXLS规范的Excel模板文件 #### 4.1.2 输入参数 | 参数名 | 类型 | 必需 | 描述 | |-------------|--------|------|---------------------------| | templateName | string | 是 | 模板文件名称 | | dataStruct | object | 是 | 数据结构定义 | | dataFormat | string | 是 | 数据格式类型 ("json" 或 "array") | | sampleData | array | 否 | 示例数据（用于验证） | | outputPath | string | 否 | 导出文件路径 | ##### dataStruct参数结构 ```json { "collectName": "data", "itemVariable": "item", "dataFields": [ { "name": "名字", "field": "name", // JSON格式时使用 "index": 0 // 数组格式时使用 }, { "name": "年龄", "field": "age", "index": 1 } ] } ``` **说明**： - `collectName`: 集合变量名称，用于JXLS批注中的items参数 - `itemVariable`: 循环项变量名，用于JXLS批注中的var参数 - `dataFields`: 字段定义数组 - `name`: 列标题显示名称 - `field`: JSON格式时的字段名（dataFormat="json"时必需） - `index`: 数组格式时的索引位置（dataFormat="array"时必需） #### 4.1.3 输出结果 ```json { "success": true, "templatePath": "/path/to/generated/template.xlsx", "message": "JXLS模板生成成功" } ``` #### 4.1.4 错误处理 ```json { "success": false, "error": "参数验证失败", "details": "dataStruct.dataFields不能为空" } ``` ## 5. 实现规范 ### 5.1 Excel模板结构 #### 5.1.1 JSON格式模板示例 ``` A1: 姓名 B1: 年龄 C1: 城市 A2: ${item.name} B2: ${item.age} C2: ${item.city} ``` 批注位置：A1单元格添加 - `jx:area(lastCell="C2")` 批注位置：A2单元格添加 - `jx:each(items="data" var="item" lastCell="C2")` #### 5.1.2 数组格式模板示例 ``` A1: 列1 B1: 列2 C1: 列3 A2: ${item[0]} B2: ${item[1]} C2: ${item[2]} ``` 批注位置：A1单元格添加 - `jx:area(lastCell="C2")` 批注位置：A2单元格添加 - `jx:each(items="data" var="item" lastCell="C2")` ### 5.2 文件输出 - 生成的Excel文件保存在指定目录 - 文件名格式：`{templateName}_{timestamp}.xlsx` - 返回完整的文件路径 ### 5.3 验证机制 - 参数有效性验证 - Excel文件格式验证 - JXLS批注语法验证 - 示例数据格式验证（如果提供） ## 6. 配置需求 ### 6.1 服务器配置 ```python # 服务器配置 SERVER_NAME = "JXLS Template Generator" SERVER_VERSION = "1.0.0" OUTPUT_DIRECTORY = "./templates" ``` ### 6.2 MCP服务器能力声明 ```python capabilities = { "tools": { "listChanged": True }, "logging": {} } ``` ## 7. 测试需求 ### 7.1 单元测试 - 参数验证功能测试 - Excel文件生成测试 - JXLS批注生成测试 - 错误处理测试 ### 7.2 集成测试 - MCP协议通信测试 - stdio模式完整流程测试 - 与AI应用集成测试 ### 7.3 性能测试 - 大数据量模板生成测试 - 并发请求处理测试 - 内存使用优化测试 ## 8. 部署需求 ### 8.1 依赖管理 ```toml [project] name = "jxls-mcp-server" version = "1.0.0" dependencies = [ "mcp[cli]>=1.0.0", "openpyxl>=3.1.0", "pydantic>=2.0.0" ] ``` ### 8.2 启动脚本 - stdio模式启动脚本 - Docker容器化支持 ## 9. 文档需求 ### 9.1 用户文档 - 安装和配置指南 - 使用示例和最佳实践 - 故障排除指南 ### 9.2 开发者文档 - API参考文档 - 代码架构说明 - 扩展开发指南 ## 10. 安全考虑 ### 10.1 输入验证 - 严格的参数类型检查 - 防止路径遍历攻击 - 限制文件大小和复杂度 ### 10.2 输出安全 - 安全的文件路径处理 - 临时文件清理机制 - 访问权限控制 ## 11. 可扩展性 ### 11.1 未来增强功能 - 支持更多JXLS批注类型 - 支持复杂的模板结构 - 支持多sheet模板 - 支持模板样式定制 ### 11.2 插件架构 - 数据源适配器 - 格式转换器 - 自定义验证器 --- **版本**: 1.0 **最后更新**: 2025-01-30 **状态**: 待开发