Jxls MCP

🚀 JXLS Excel模板生成MCP服务端

本项目是一个基于MCP（Model Context Protocol）协议的服务端，可生成符合JXLS规范的Excel模板文件，有效解决了特定格式Excel模板生成的难题，为数据处理和展示提供了便利。

🚀 快速开始

安装依赖

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)

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"}
    ]
  }
}

✨ 主要特性

• 🎯 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)

高级用法

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格式时的字段名（dataFormat="json"时必需）。
  • index：数组格式时的索引位置（dataFormat="array"时必需）。

生成的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工具

输入参数

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.0.0

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