Jxls MCP

🚀 JXLS Excel Template Generation MCP Server

This is a server based on the MCP (Model Context Protocol) for generating Excel template files that comply with JXLS specifications.

✨ Features

• 🎯 JXLS Specification Support: Generate Excel templates containing jx:area() and jx:each() annotations.
• 📊 Multiple Data Formats: Support both JSON objects and arrays as data formats.
• 🔧 MCP Protocol: A complete implementation of the MCP protocol, supporting the stdio communication mode.
• ✅ Parameter Validation: Strict input parameter validation and error handling.
• 🛡️ Security: File path security checks to prevent path traversal attacks.
• 📝 Type Safety: A type-safe data model based on Pydantic.

🚀 Quick Start

📦 Installation

uv sync

💻 Usage Examples

Basic Usage - JSON Format

from jxls_mcp.models import GenerateTemplateRequest, DataStruct, DataField
from jxls_mcp.services import TemplateGenerator

# Create a data structure
data_struct = DataStruct(
    collectName="employees",
    itemVariable="employee",
    dataFields=[
        DataField(name="姓名", field="name"),
        DataField(name="年龄", field="age"),
        DataField(name="部门", field="department")
    ]
)

# Create a request
request = GenerateTemplateRequest(
    templateName="employee_report",
    dataStruct=data_struct,
    dataFormat="json"
)

# Generate a template
generator = TemplateGenerator()
response = generator.generate_template(request)

print(f"生成成功: {response.success}")
print(f"文件路径: {response.templatePath}")

Basic Usage - Array Format

# Create a data structure for array format
data_struct = DataStruct(
    collectName="dataList",
    itemVariable="row",
    dataFields=[
        DataField(name="列1", index=0),
        DataField(name="列2", index=1),
        DataField(name="列3", index=2)
    ]
)

# Create a request
request = GenerateTemplateRequest(
    templateName="data_export",
    dataStruct=data_struct,
    dataFormat="array"
)

# Generate a template
generator = TemplateGenerator()
response = generator.generate_template(request)

MCP Server Mode

Start the MCP server:

uv run jxls-mcp-server

Or call it as an MCP tool:

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

📚 Documentation

Data Structure Definition

DataStruct Parameters

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

Explanation:

• collectName: The name of the collection variable, used for the items parameter in JXLS annotations.
• itemVariable: The variable name for the loop item, used for the var parameter in JXLS annotations.
• dataFields: An array of field definitions.
  • name: The display name of the column header.
  • field: The field name in JSON format (required when dataFormat="json").
  • index: The index position in array format (required when dataFormat="array").

Generated Excel Templates

JSON Format Template Example

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

JXLS Annotations:

• Cell A1: jx:area(lastCell="C2")
• Cell A2: jx:each(items="data" var="item" lastCell="C2")

Array Format Template Example

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

JXLS Annotations:

• Cell A1: jx:area(lastCell="C2")
• Cell A2: jx:each(items="data" var="item" lastCell="C2")

📄 API Reference

generateJxlsTemplate Tool

Input Parameters

Details of the outputPath Parameter

The outputPath parameter supports multiple path formats, and the system will automatically determine the processing method based on the path characteristics:

1. Relative Path Support

{
  "outputPath": "templates/my_template.xlsx"  // Use the specified file name.
}

2. Absolute Path Support

{
  "outputPath": "C:/Users/username/Documents/my_template.xlsx"  // Use the specified file name.
}

3. Directory Path (Automatically Generate File Name)

{
  "outputPath": "C:/Users/username/Documents/templates"  // Automatically generate: templateName_timestamp.xlsx
}

4. Custom File Name

{
  "outputPath": "reports/sales_report"  // Automatically add the .xlsx extension.
}

Path Processing Rules:

• If the path does not contain an extension and does not exist, it is considered a directory path, and a file name in the templateName_timestamp.xlsx format will be generated.
• If the path contains a file name (with an extension or an existing file with the same name), the file name will be used directly.
• If the file name does not have the .xlsx extension, the system will automatically add it.
• The system will automatically create non-existent directories.
• Protection against path traversal attacks is maintained (the use of .. is not allowed).

Output Result

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

🔧 Technical Details

Running Tests

pytest

Code Formatting

black src/ tests/
isort src/ tests/

Type Checking

mypy src/

Environment Variables

• JXLS_OUTPUT_DIR: The directory for template output, with a default value of ./templates.

📄 License

This project is licensed under the MIT License.

🤝 Contribution

We welcome the submission of Issues and Pull Requests!

📝 Changelog

v1.0.0

• Initial release.
• Support for generating Excel templates that comply with JXLS specifications.
• A complete implementation of the MCP protocol.
• Support for both JSON and array data formats.