generateJxlsTemplate
Create JXLS-compliant Excel templates using JSON or array data formats to define structure and variables for dynamic spreadsheet generation.
Instructions
根据输入参数生成符合JXLS规范的Excel模板文件
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dataFormat | Yes | 数据格式类型 | |
| dataStruct | Yes | 数据结构定义 | |
| outputPath | No | 导出文件路径（可选） | |
| sampleData | No | 示例数据（可选） | |
| templateName | Yes | 模板文件名称 |
Implementation Reference
- src/jxls_mcp/server.py:127-174 (handler)The MCP tool handler that processes 'generateJxlsTemplate' calls: validates input using GenerateTemplateRequest model, calls TemplateGenerator.generate_template, handles errors, and returns JSON response as TextContent.async def _handle_generate_template(self, arguments: Dict[str, Any]) -> List[TextContent]: """处理generateJxlsTemplate工具调用""" try: # 验证和解析请求 request = GenerateTemplateRequest(**arguments) logger.info(f"生成模板请求: {request.templateName}, 格式: {request.dataFormat}") # 生成模板 response = self.template_generator.generate_template(request) # 记录结果 if response.success: logger.info(f"模板生成成功: {response.templatePath}") else: logger.error(f"模板生成失败: {response.error} - {response.details}") # 返回响应 return [TextContent( type="text", text=response.model_dump_json(indent=2) )] except ValidationError as e: logger.error(f"请求参数验证失败: {e}") error_response = { "success": False, "message": "请求参数验证失败", "error": "参数验证失败", "details": str(e) } return [TextContent( type="text", text=str(error_response) )] except Exception as e: logger.error(f"处理请求时发生未知错误: {e}") error_response = { "success": False, "message": "处理请求时发生未知错误", "error": "内部服务器错误", "details": str(e) } return [TextContent( type="text", text=str(error_response) )]
- src/jxls_mcp/models/request.py:1-95 (schema)Pydantic models (GenerateTemplateRequest, DataStruct, DataField) defining the input schema and validation for the generateJxlsTemplate tool."""请求数据模型定义""" from typing import Any, List, Literal, Optional from pydantic import BaseModel, Field, model_validator class DataField(BaseModel): """数据字段定义模型""" name: str = Field(..., description="列标题显示名称") field: Optional[str] = Field(None, description="JSON格式字段名") index: Optional[int] = Field(None, ge=0, description="数组格式索引位置") @model_validator(mode='after') def validate_field_or_index(self) -> 'DataField': """验证field和index的有效性 允许field和index都为空，表示该列不绑定数据 """ # 移除强制要求field或index必须有一个的验证 # 允许两者都为空，表示该列不需要数据绑定 return self class DataStruct(BaseModel): """数据结构定义模型""" collectName: str = Field( ..., min_length=1, description="集合变量名称，用于JXLS批注中的items参数" ) itemVariable: str = Field( ..., min_length=1, description="循环项变量名，用于JXLS批注中的var参数" ) dataFields: List[DataField] = Field( ..., min_length=1, description="字段定义数组" ) class GenerateTemplateRequest(BaseModel): """生成模板请求模型""" templateName: str = Field( ..., min_length=1, max_length=100, description="模板文件名称" ) dataStruct: DataStruct = Field(..., description="数据结构定义") dataFormat: Literal["json", "array"] = Field(..., description="数据格式类型") sampleData: Optional[List[Any]] = Field(None, description="示例数据（用于验证）") outputPath: Optional[str] = Field(None, description="导出文件路径") @model_validator(mode='after') def validate_data_format_consistency(self) -> 'GenerateTemplateRequest': """验证数据格式与dataStruct的一致性 对于需要数据绑定的字段： - JSON格式需要提供field属性 - 数组格式需要提供index属性 允许field和index都为空，表示该列不需要数据绑定 """ if self.dataFormat == "json": # JSON格式时，如果提供了index但没有field，则报错 for field in self.dataStruct.dataFields: if field.index is not None and not field.field: raise ValueError( f"JSON格式时字段'{field.name}'不应提供index属性，" f"请使用field属性或留空表示不绑定数据" ) elif self.dataFormat == "array": # 数组格式时，如果提供了field但没有index，则报错 for field in self.dataStruct.dataFields: if field.field and field.index is None: raise ValueError( f"数组格式时字段'{field.name}'不应提供field属性，" f"请使用index属性或留空表示不绑定数据" ) return self @model_validator(mode='after') def validate_template_name_safe(self) -> 'GenerateTemplateRequest': """验证模板名称安全性""" unsafe_chars = ['/', '\\', ':', '*', '?', '"', '<', '>', '|'] for char in unsafe_chars: if char in self.templateName: raise ValueError(f"模板名称不能包含字符: {char}") return self
- src/jxls_mcp/server.py:42-118 (registration)Registers the 'generateJxlsTemplate' tool with the MCP server via list_tools(), including detailed inputSchema matching the Pydantic model.@self.server.list_tools() async def list_tools() -> List[Tool]: """列出可用工具""" return [ Tool( name="generateJxlsTemplate", description="根据输入参数生成符合JXLS规范的Excel模板文件", inputSchema={ "type": "object", "properties": { "templateName": { "type": "string", "description": "模板文件名称", "minLength": 1, "maxLength": 100 }, "dataStruct": { "type": "object", "description": "数据结构定义", "properties": { "collectName": { "type": "string", "description": "集合变量名称", "minLength": 1 }, "itemVariable": { "type": "string", "description": "循环项变量名", "minLength": 1 }, "dataFields": { "type": "array", "description": "字段定义数组", "minItems": 1, "items": { "type": "object", "properties": { "name": { "type": "string", "description": "列标题显示名称" }, "field": { "type": "string", "description": "JSON格式字段名" }, "index": { "type": "integer", "description": "数组格式索引位置", "minimum": 0 } }, "required": ["name"] } } }, "required": ["collectName", "itemVariable", "dataFields"] }, "dataFormat": { "type": "string", "enum": ["json", "array"], "description": "数据格式类型" }, "sampleData": { "type": "array", "description": "示例数据（可选）", "items": {} }, "outputPath": { "type": "string", "description": "导出文件路径（可选）" } }, "required": ["templateName", "dataStruct", "dataFormat"] } ) ]
- Core implementation of template generation in TemplateGenerator.generate_template: handles JSON/array formats, creates Excel workbook with headers and Jxls annotations using helpers, generates file path, and returns structured response.def generate_template(self, request: GenerateTemplateRequest) -> GenerateTemplateResponse: """主要模板生成方法""" try: # 参数验证 self._validate_request(request) # 生成文件路径 file_path = self._generate_file_path(request.templateName, request.outputPath) # 根据数据格式生成模板 if request.dataFormat == "json": area_annotation, each_annotation = self._create_json_template(request, file_path) else: # array area_annotation, each_annotation = self._create_array_template(request, file_path) # 计算数据结构信息 column_count = len(request.dataStruct.dataFields) last_cell = self.jxls_helper.calculate_last_cell(column_count, 2) # 构建响应 jxls_annotations = JxlsAnnotations( area=area_annotation, each=each_annotation ) data_struct_info = DataStructInfo( collectName=request.dataStruct.collectName, itemVariable=request.dataStruct.itemVariable, columnCount=column_count, lastCell=last_cell ) return GenerateTemplateResponse.success_response( template_path=file_path, message="JXLS模板生成成功", jxls_annotations=jxls_annotations, data_struct=data_struct_info ) except ValueError as e: return GenerateTemplateResponse.error_response( error="参数验证失败", details=str(e) ) except Exception as e: return GenerateTemplateResponse.error_response( error="模板生成失败", details=str(e) )