# 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/)
