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和數組兩種數據格式