Jxls MCP

🚀 JXLS Excelテンプレート生成MCPサーバー

MCP（Model Context Protocol）プロトコルに基づくサーバーで、JXLS規格に準拠したExcelテンプレートファイルを生成します。

✨ 主な機能

• 🎯 JXLS規格対応：jx:area() と jx:each() 注釈を含むExcelテンプレートを生成します。
• 📊 複数のデータ形式：JSONオブジェクトと配列の2種類のデータ形式をサポートします。
• 🔧 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サーバーモード

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形式（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ライセンス

貢献

IssueとPull Requestの投稿を歓迎します！

更新履歴

v1.0.0

• 初期バージョンのリリース
• JXLS規格のExcelテンプレート生成のサポート
• 完全なMCPプロトコルの実装
• JSONと配列の2種類のデータ形式のサポート