# MCP Excel Workbook Processor for GitHub Copilot

このプロジェクトは、GitHub Copilotで使用できるExcelワークブック処理用のMCP（Model Context Protocol）サーバーです。Docker Composeを使用して簡単にセットアップ・実行できます。

## 機能

- Excelファイル（.xlsx）の全シートを読み取り
- シート名を指定して読み取り
- シートインデックスを指定して読み取り
- JSON形式でデータを返却
- 空のセルやデータ型の変換を適切に処理

## 前提条件

- Docker と Docker Compose がインストールされていること
- Python 3.10以上（ローカルでサンプルファイルを作成する場合）

## セットアップ

### 1. リポジトリのクローンまたはダウンロード

```bash
cd /path/to/your/workspace
```

### 2. サンプルExcelファイルの作成（オプション）

既に `sample/` ディレクトリにサンプルファイルが含まれていますが、追加で作成する場合：

```bash
python3 create_sample_excel.py
```

### 3. Docker Composeでサーバーを起動

Makefileを使用する場合（推奨）：

```bash
make build
make up
```

または直接Docker Composeを使用：

```bash
docker compose up -d --build
```

### 4. 動作確認

サーバーが正常に起動しているか確認：

```bash
make check
make logs
```

または直接Docker Composeを使用：

```bash
docker compose ps
docker compose logs mcp-excel-server
```

### Makefileコマンド

便利なMakefileコマンドが利用できます：

```bash
make help          # 利用可能なコマンド一覧を表示
make build         # Dockerイメージをビルド
make up            # コンテナを起動
make down          # コンテナを停止
make restart       # コンテナを再起動
make logs          # ログを表示
make test          # テストスクリプトを実行
make sample        # サンプルExcelファイルを作成
make clean         # コンテナとイメージを削除
make shell         # コンテナ内でシェルを開く
```

## GitHub Copilotでの設定

GitHub CopilotでこのMCPサーバーを使用するには、MCP設定ファイルに追加する必要があります。

### 設定ファイルの場所

GitHub CopilotのMCP設定ファイルは通常、以下の場所にあります：

- **macOS/Linux**: `~/.config/github-copilot/mcp.json` または `~/.config/github-copilot/hosts.json`
- **Windows**: `%APPDATA%\GitHub Copilot\mcp.json` または `%APPDATA%\GitHub Copilot\hosts.json`

### 設定例

`mcp-config-example.json` を参考に、実際のパスを設定してください：

```json
{
  "mcpServers": {
    "excel-workbook-processor": {
      "command": "docker",
      "args": [
        "compose",
        "-f",
        "/home/toyoaki/workspace/private-technology/mcp-excel-server-docker-compose-for-copilot/docker-compose.yml",
        "run",
        "--rm",
        "-T",
        "mcp-excel-server",
        "python",
        "-m",
        "src.excel_reader_server"
      ],
      "cwd": "/home/toyoaki/workspace/private-technology/mcp-excel-server-docker-compose-for-copilot"
    }
  }
}
```

**注意**: パスは実際のプロジェクトのパスに置き換えてください。

### 設定の適用

1. 設定ファイルを編集または作成
2. GitHub Copilotを再起動
3. MCPサーバーが利用可能になっているか確認

## 使用方法

### 利用可能なツール

#### 1. `load_workbook`

ワークブック内のすべてのシートからデータを抽出します。

```json
{
  "file_path": "sample.xlsx"
}
```

#### 2. `get_sheet_by_name`

指定したシート名のシートからデータを抽出します。シート名が指定されない場合は、最初のシートを抽出します。

```json
{
  "file_path": "sample.xlsx",
  "sheet_name": "Sales"
}
```

#### 3. `get_sheet_by_position`

指定した位置（インデックス）のシートからデータを抽出します。位置が指定されない場合は、最初のシート（位置0）を抽出します。

```json
{
  "file_path": "sample.xlsx",
  "sheet_position": 0
}
```

### ファイルパス

ファイルパスは以下のいずれかで指定できます：

- `/app/sample/` ディレクトリからの相対パス（例: `sample.xlsx`）
- `/app/data/` ディレクトリからの相対パス（例: `data.xlsx`）
- 絶対パス

## ディレクトリ構造

```
.
├── docker-compose.yml          # Docker Compose設定
├── Dockerfile                  # Dockerイメージ定義
├── Makefile                    # ビルド・実行用Makefile
├── requirements.txt            # Python依存関係
├── create_sample_excel.py      # サンプルExcelファイル作成スクリプト
├── test_server.sh              # テストスクリプト
├── mcp-config-example.json     # GitHub Copilot設定例
├── README.md                   # このファイル
├── sample/                     # サンプルExcelファイル（マウント用）
│   ├── sample.xlsx
│   └── simple.xlsx
├── data/                       # 追加のExcelファイル用（オプション）
└── src/
    └── excel_reader_server/
        ├── __init__.py
        ├── __main__.py         # MCPサーバーメインコード
        └── file_handler.py     # Excelファイル処理ユーティリティ
```

## テスト

### 自動テストスクリプト

提供されているテストスクリプトを実行：

```bash
make test
# または
./test_server.sh
```

このスクリプトは以下をテストします：
- すべてのシートの抽出
- シート名を指定した抽出
- シート位置を指定した抽出

### 手動テスト

Makefileを使用：

```bash
make test-interactive
```

またはDockerコンテナ内で直接テスト：

```bash
# コンテナをビルド
make build

# サンプルファイルの抽出テスト
docker compose run --rm mcp-excel-server python -c "
import sys
sys.path.insert(0, '/app')
from src.excel_reader_server.file_handler import ExcelFileResolver, WorkbookParser
import json
path = ExcelFileResolver.locate_file('sample.xlsx')
result = WorkbookParser.extract_all_sheets(path)
print(json.dumps(result, indent=2, ensure_ascii=False))
"
```

### サンプルファイルの確認

```bash
# コンテナ内のファイル一覧を確認
docker compose run --rm mcp-excel-server ls -la /app/sample/
```

## トラブルシューティング

### サーバーが起動しない

```bash
# ログを確認
docker compose logs mcp-excel-server

# コンテナを再ビルド
docker compose down
docker compose up -d --build
```

### ファイルが見つからない

- ファイルパスが正しいか確認
- `sample/` または `data/` ディレクトリにファイルが存在するか確認
- ファイル名の大文字小文字を確認

### GitHub Copilotで認識されない

- 設定ファイルのパスが正しいか確認
- Docker Composeが起動しているか確認
- GitHub Copilotを再起動

## ライセンス

このプロジェクトは、[mcp-excel-reader-server](https://github.com/softgridinc-pte-ltd/mcp-excel-reader-server)を参考に作成されています。

Apache 2.0 License

## 参考リポジトリ

- [mcp-excel-reader-server](https://github.com/softgridinc-pte-ltd/mcp-excel-reader-server)
- [Model Context Protocol](https://modelcontextprotocol.io/)