mysheet MCP Server

mysheet MCP サーバー

Mysheet-mcp は、Excel ファイルを JSON 形式に変換する MCP サーバーです。特に、LLM やエージェントでのデータ処理に適しています。本プロジェクトは Excel ファイルの解析に対応しており、Excel に埋め込まれたファイルを Tencent Cloud COS（オブジェクトストレージ）に自動でアップロードします。

主な機能

• Excel から JSON への変換：アップロードされた Excel ファイルを JSON 形式に変換し、セルの種類（テキスト、数値、通貨、日付など）の詳細な情報を含めます。
• 行オブジェクトモード："row-object" 解析モードに対応しており、各行をオブジェクトとして扱い、結合セルの処理にも対応しています。
• Tencent Cloud COS との連携：Excel に埋め込まれたファイルを Tencent Cloud COS に自動でアップロードし、JSON 出力で COS の URL を使用します。
• 高性能な変換：
  • 仮想スレッドによる並行処理：Java 21 の仮想スレッド（Virtual Threads）技術を活用して、埋め込みファイルを並行してアップロードします。画像やファイルを多数含む Excel の処理速度が大幅に向上します。
  • リソースの最適化：解析ロジックを再構築し、Workbook を一度だけ開くことで、重複する I/O を減らし、大容量ファイルの変換時間を大幅に短縮します。
• セッション管理：
  • openFile、foreach、reset インターフェースを提供し、大容量ファイルを分割して読み取れます。
  • セッション状態（Session）はメモリ内に 24 時間保持され、中断した処理の再開とポインター管理に対応しています。
• キャッシュ機構：MD5 ベースのキャッシュ機構により、同じファイルの重複解析を防ぎます。
• MCP SSE 対応：MCP 通信用のサーバー送信イベント（SSE）エンドポイントを提供します。

システム要件

• Java 21 以上（仮想スレッドのサポートに必須）
• Maven 3.6 以上
• Tencent Cloud COS アカウント（ファイルストレージ用）

インストールとビルド

1. プロジェクトをクローン

git clone <项目地址>
cd mysheet-mcp

2. 依存関係をインストール

./mvnw clean install

3. プロジェクトをビルド

./mvnw compile

4. テストを実行

./mvnw test

設定

設定ファイルは src/main/resources/application.yml にあります。ご利用の環境に合わせて設定してください。

# 服务器配置
server:
  port: 8080  # MCP SSE 服务器端口，默认为 8080

# Spring AI MCP 配置
spring:
  ai:
    mcp:
      server:
        sse-message-endpoint: /sse  # SSE 消息端点路径

# 存储配置
storage:
  file: /var/mysheet-mcp/upload  # 上传的 Excel 文件存储目录
  cache: /var/mysheet-mcp/cache   # 缓存 JSON 结果的目录

# 腾讯云 COS 配置
cos:
  secret-id: YOUR_SECRET_ID       # 腾讯云访问密钥 ID
  secret-key: YOUR_SECRET_KEY     # 腾讯云访问密钥 Key
  region: ap-beijing              # COS 存储桶地域
  bucket-name: YOUR_BUCKET_NAME   # COS 存储桶名称

サーバーを起動

1. 開発環境での起動

./mvnw spring-boot:run

2. 本番環境での起動

まず、プロジェクトをパッケージ化します。

./mvnw clean package

次に、生成された JAR ファイルを実行します。

java -jar target/mysheet-mcp-0.0.1-SNAPSHOT.jar

3. サーバーの稼働を確認

サーバーの起動後、以下の方法で確認できます。

• http://localhost:8080/actuator/health にアクセスして、ヘルス状態を確認します。
• コンソールログを確認し、MCP サーバーが起動していることを確認します。

使用方法（MCP ツール）

本サーバーは、エージェントから呼び出せる以下の MCP ツールを提供します。

1. excel2Json

Excel ファイル全体を一度に JSON に変換します。

• パラメーター：
  • excelFileURL (String)：Excel ファイルの URL またはローカルパスです。
  • type (String)：解析モードです。basic（デフォルト）または row-object を指定します。
• 戻り値：完全な JSON データ文字列です。

2. openFile（セッションモード）

Excel ファイルを開いて読み取りセッションを作成します。大容量ファイルの処理に適しています。

• パラメーター：
  • excelFileURL (String)：Excel ファイルの URL またはローカルパスです。
  • type (String)：解析モードです。basic または row-object を指定します。
  • offset (int, 任意)：開始行番号です。デフォルトは 0 です。
• 戻り値：セッション情報を含む JSON オブジェクトです。

  {
    "text": "sessionId_string",
    "sessionId": "sessionId_string",
    "files": [],
    "json": [ { "data": [] } ]
  }
  

  • sessionId：セッションの一意な識別子です。後続の操作で使用します。
  • text：互換性のためのフィールドで、sessionId と同じ値です。

3. foreach（セッションを反復処理）

現在のセッションから次のデータを読み取ります。

• パラメーター：
  • sessionId (String)：openFile が返すセッション ID です。
  • limit (int, 任意)：読み取る行数の上限です。デフォルトは 10 です。
• 戻り値：データを含む JSON 文字列です。
  • データが残っている場合：データの JSON を返します。
  • 読み取りが完了している場合：通知メッセージまたは空のデータを返します。

4. reset（セッションをリセット）

セッションの読み取りポインターを指定した位置にリセットします。

• パラメーター：
  • sessionId (String)：セッション ID です。
  • offset (int)：リセット先の行番号です（0 から始まります）。
• 戻り値：リセット成功の通知メッセージです。

解析モードの詳細

基本モード（Basic Mode）

デフォルトの解析モードで、簡略化された JSON 構造を返します。

• 各セルの値をそのまま返します。
• シンプルなデータ抽出に適しています。

行オブジェクトモード（Row-Object Mode）

type="row-object" パラメーターを使用して有効にします。

• 各行を JSON オブジェクトに変換します。
• ヘッダー行でプロパティ名を定義します。
• 結合セルは値を繰り返すことで処理します。
• 各セルには type と value フィールドが含まれます。

セルの種類：

• text：テキスト型
• number：数値型
• money：通貨型（通貨記号が検出されると自動的に判定されます）
• date：日付型。yyyy-MM-dd 形式にフォーマットされます。
• file：ファイル型。値は COS の URL です。
• boolean：ブール型

入出力の例

入力 Excel ファイルの構造

test.xls ファイルに以下の内容が含まれているとします。

• ヘッダー：A1="", B1="タイトル1", C1="タイトル2", D1="タイトル1"
• データ行には、テキスト、数値、日付、ファイルなど、さまざまな種類のデータが含まれています。

出力 JSON の例（行オブジェクトモード）

{
  "header": {
    "A1": "",
    "B1": "标题1",
    "C1": "标题2",
    "D1": "标题1"
  },
  "data": [
    {
      "index": 1,
      "A1": {
        "type": "text",
        "value": "属性1"
      },
      "B1": {
        "type": "number",
        "value": 1
      },
      "C1": {
        "type": "date",
        "value": "2025-05-18"
      },
      "D1": {
        "type": "file",
        "value": "https://chinamobile-1320739042.cos.ap-beijing.myqcloud.com/attachment/20251230001822713_test.png"
      }
    }
  ],
  "filename": "test.xls",
  "md5": "a1b2c3d4e5f678901234567890123456"
}

キャッシュ機構

動作の仕組み

1. システムがアップロードされた Excel ファイルの MD5 ハッシュ値を計算します。
2. キャッシュディレクトリに対応する JSON ファイル（ファイル名の形式：{md5}_{type}.json）が存在するか確認します。
3. キャッシュが存在し、有効な場合は、キャッシュ内容をそのまま返します。
4. キャッシュが存在しないか無効な場合は、ファイルを再解析してキャッシュに保存します。

セッションキャッシュ

• セッションデータ（SessionData）はメモリ内（TimedCache）に保存されます。
• 有効期間：24 時間。
• クリーンアップ方針：期限切れのセッションを毎時自動で削除します。

トラブルシューティング

よくある問題

1. サーバーの起動に失敗する

   • Java のバージョンが 21 以上か確認してください（本プロジェクトでは仮想スレッドを使用するため、JDK 21 が必須です）。
   • ポート 8080 が使用中でないか確認します。
   • COS の設定が正しいか確認します。

2. ファイルのアップロードに失敗する

   • COS のキーにアップロード権限があるか確認します。
   • バケットのリージョンが正しいか確認します。
   • ネットワーク接続を確認します。

3. 解析エラーが発生する

   • Excel ファイルの形式がサポートされているか確認します（.xls と .xlsx に対応しています）。
   • ファイルが破損していないか確認します。
   • サーバーログを確認し、詳しいエラー情報を取得します。

ログの確認

# 查看实时日志
tail -f logs/application.log

# 或查看控制台输出

プロジェクト構成

mysheet-mcp/
├── src/
│   ├── main/
│   │   ├── java/link/wo/mysheetmcp/
│   │   │   ├── service/          # 服务层
│   │   │   │   ├── Excel2JsonService.java # 核心业务逻辑，含会话管理
│   │   │   │   └── CosService.java
│   │   │   ├── util/             # 工具类
│   │   │   │   └── Excel2JsonUtil.java    # Excel 解析与虚拟线程优化
│   │   │   └── McpServerApplication.java
│   │   └── resources/
│   │       └── application.yml   # 配置文件
│   └── test/                     # 测试代码
├── pom.xml                       # Maven 配置 (需 Java 21)
└── README.md                     # 本文档