JXLS Excel模板生成MCP服务端

一个基于MCP（Model Context Protocol）协议的服务端，用于生成符合JXLS规范的Excel模板文件。

功能特性

🎯 JXLS规范支持: 生成包含jx:area()和jx:each()批注的Excel模板
📊 多数据格式: 支持JSON对象和数组两种数据格式
🔧 MCP协议: 完整的MCP协议实现，支持stdio通信模式
✅ 参数验证: 严格的输入参数验证和错误处理
🛡️ 安全性: 文件路径安全检查，防止路径遍历攻击
📝 类型安全: 基于Pydantic的类型安全数据模型

Related MCP server: Excel MCP Server

快速开始

安装依赖

uv sync

基本使用

JSON格式示例

from jxls_mcp.models import GenerateTemplateRequest, DataStruct, DataField from jxls_mcp.services import TemplateGenerator # 创建数据结构 data_struct = DataStruct( collectName="employees", itemVariable="employee", dataFields=[ DataField(name="姓名", field="name"), DataField(name="年龄", field="age"), DataField(name="部门", field="department") ] ) # 创建请求 request = GenerateTemplateRequest( templateName="employee_report", dataStruct=data_struct, dataFormat="json" ) # 生成模板 generator = TemplateGenerator() response = generator.generate_template(request) print(f"生成成功: {response.success}") print(f"文件路径: {response.templatePath}")

数组格式示例

# 创建数组格式数据结构 data_struct = DataStruct( collectName="dataList", itemVariable="row", dataFields=[ DataField(name="列1", index=0), DataField(name="列2", index=1), DataField(name="列3", index=2) ] ) # 创建请求 request = GenerateTemplateRequest( templateName="data_export", dataStruct=data_struct, dataFormat="array" ) # 生成模板 generator = TemplateGenerator() response = generator.generate_template(request)

带有不绑定列的示例

# 创建包含绑定和不绑定列的数据结构 data_struct = DataStruct( collectName="employees", itemVariable="employee", dataFields=[ DataField(name="序号"), # 不绑定数据，留空供手工填写 DataField(name="姓名", field="name"), # 绑定到name字段 DataField(name="年龄", field="age"), # 绑定到age字段 DataField(name="部门", field="department"), # 绑定到department字段 DataField(name="备注") # 不绑定数据，留空供手工填写 ] ) # 创建请求 request = GenerateTemplateRequest( templateName="employee_with_static_columns", dataStruct=data_struct, dataFormat="json" ) # 生成模板 generator = TemplateGenerator() response = generator.generate_template(request) # 生成的Excel模板将包含： # 第1行：序号 | 姓名 | 年龄 | 部门 | 备注 # 第2行：(空) | ${employee.name} | ${employee.age} | ${employee.department} | (空)

MCP服务器模式

启动MCP服务器：

uv run jxls-mcp-server

或者作为MCP工具调用：

{ "name": "generateJxlsTemplate", "arguments": { "templateName": "sales_report", "dataStruct": { "collectName": "sales", "itemVariable": "sale", "dataFields": [ {"name": "产品名称", "field": "product"}, {"name": "销售额", "field": "amount"}, {"name": "销售日期", "field": "date"} ] }, "dataFormat": "json", "sampleData": [ {"product": "产品A", "amount": 1000, "date": "2024-01-01"} ] } }

数据结构定义

DataStruct参数

{ "collectName": "data", "itemVariable": "item", "dataFields": [ { "name": "列标题", "field": "fieldName", "index": 0 } ] }

说明：

collectName: 集合变量名称，用于JXLS批注中的items参数
itemVariable: 循环项变量名，用于JXLS批注中的var参数
dataFields: 字段定义数组
- name: 列标题显示名称（必需）
- field: JSON格式时的字段名（可选，为空表示该列不绑定数据）
- index: 数组格式时的索引位置（可选，为空表示该列不绑定数据）

新特性 - 不绑定数据的列：从v1.1.0开始，支持创建不绑定数据的列。当field（JSON格式）或index（数组格式）为空时，该列在数据行中将保持为空单元格，不生成JXLS表达式。这对于以下场景非常有用：

静态列：如序号、固定文本说明等
手工填写列：如备注、审批意见等需要用户手动填写的列
计算列：由Excel公式计算得出的列

生成的Excel模板

JSON格式模板示例

A1: 姓名 B1: 年龄 C1: 城市 A2: ${item.name} B2: ${item.age} C2: ${item.city}

JXLS批注：

A1单元格: jx:area(lastCell="C2")
A2单元格: jx:each(items="data" var="item" lastCell="C2")

数组格式模板示例

A1: 列1 B1: 列2 C1: 列3 A2: ${item[0]} B2: ${item[1]} C2: ${item[2]}

JXLS批注：

A1单元格: jx:area(lastCell="C2")
A2单元格: jx:each(items="data" var="item" lastCell="C2")

API参考

generateJxlsTemplate工具

输入参数

参数名	类型	必需	描述
templateName	string	是	模板文件名称
dataStruct	object	是	数据结构定义
dataFormat	string	是	数据格式类型 ("json" 或 "array")
sampleData	array	否	示例数据（用于验证）
outputPath	string	否	导出文件路径

outputPath 参数详解

outputPath 参数支持多种路径格式，系统会根据路径特征自动判断处理方式：

1. 相对路径支持

{ "outputPath": "templates/my_template.xlsx" // 使用指定文件名 }

2. 绝对路径支持

{ "outputPath": "C:/Users/username/Documents/my_template.xlsx" // 使用指定文件名 }

3. 目录路径（自动生成文件名）

{ "outputPath": "C:/Users/username/Documents/templates" // 自动生成: templateName_timestamp.xlsx }

4. 自定义文件名

{ "outputPath": "reports/sales_report" // 自动添加.xlsx扩展名 }

路径处理规则：

如果路径不包含扩展名且不存在，则视为目录路径，使用 templateName_timestamp.xlsx 格式生成文件名
如果路径包含文件名（有扩展名或存在同名文件），则直接使用该文件名
如果文件名没有 .xlsx 扩展名，系统会自动添加
系统会自动创建不存在的目录
保持路径遍历攻击防护（不允许包含 ..）

输出结果

{ "success": true, "templatePath": "/path/to/generated/template.xlsx", "message": "JXLS模板生成成功", "jxlsAnnotations": { "area": "jx:area(lastCell=\"C2\")", "each": "jx:each(items=\"data\" var=\"item\" lastCell=\"C2\")" }, "dataStruct": { "collectName": "data", "itemVariable": "item", "columnCount": 3, "lastCell": "C2" } }

开发

运行测试

pytest

代码格式化

black src/ tests/ isort src/ tests/

类型检查

mypy src/

环境变量

JXLS_OUTPUT_DIR: 模板输出目录，默认为 ./templates

许可证

MIT License

贡献

欢迎提交Issue和Pull Request！

更新日志

v1.1.0

新增：支持不绑定数据的列
- 允许field和index都为空，表示该列不需要数据绑定
- 适用于静态列、手工填写列、计算列等场景
- 向后兼容，不影响现有使用方式

v1.0.0

初始版本发布
支持JXLS规范的Excel模板生成
完整的MCP协议实现
JSON和数组两种数据格式支持

JXLS Excel Template Generator