JXLS Excel模板生成MCP服务端
一个基于MCP（Model Context Protocol）协议的服务端，用于生成符合JXLS规范的Excel模板文件。
功能特性
- 🎯 JXLS规范支持: 生成包含
jx:area()和jx:each()批注的Excel模板 - 📊 多数据格式: 支持JSON对象和数组两种数据格式
- 🔧 MCP协议: 完整的MCP协议实现，支持stdio通信模式
- ✅ 参数验证: 严格的输入参数验证和错误处理
- 🛡️ 安全性: 文件路径安全检查，防止路径遍历攻击
- 📝 类型安全: 基于Pydantic的类型安全数据模型
快速开始
安装依赖
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和数组两种数据格式支持