# CSV Analyzer MCP

**Model Context Protocol (MCP)** を使って CSV ファイルを分析し、統計情報を提供するサーバーであり、AI アシスタントツールとしても利用できます。

- LLM が発見・呼び出し可能なツールを公開
- ユーザー入力（CSV ファイルパス）を処理
- 構造化された結果を返す
- Claude for Desktop および他の MCP 互換クライアントと統合

## 機能

- **CSV 分析**: 統計情報の計算と分析
- **サマリー取得**: CSV 構造の JSON 形式サマリー
- **型アノテーション**: Python 3.12+ 対応
- **ロギング**: stderr へのログ出力
- **エラーハンドリング**: ファイル I/O と入力検証
- **MCP 互換性**: 複数の MCP クライアントに対応

## クイックスタート

### 前提条件

- Python 3.12 以上
- `uv` パッケージマネージャー（[インストール](https://docs.astral.sh/uv/getting-started/installation/)）

### インストール

```bash
# プロジェクトディレクトリに移動
cd csv-analyzer-mcp

# 仮想環境を作成して依存パッケージをインストール
uv venv
source .venv/bin/activate  # Windows の場合: .venv\Scripts\activate

# 開発モードでパッケージをインストール
uv sync
```

### サーバーの実行

```bash
# uv 経由（開発時に推奨）
uv run csv-analyzer-mcp

# または、venv をアクティベート後
python -m csv_analyzer_mcp.main
```

サーバーが起動し、MCP クライアント接続を STDIO でリッスンします。

## Claude for Desktop との統合

このMCPサーバーを Claude for Desktop と一緒に使用するには：

1. Claude設定ファイルを探します：
   ```bash
   # macOS/Linux
   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   
   # Windows
   code $env:AppData\Claude\claude_desktop_config.json
   ```

2. サーバー設定を追加します：
   ```json
   {
     "mcpServers": {
       "csv-analyzer": {
         "command": "uv",
         "args": [
           "--directory",
           "/ABSOLUTE/PATH/TO/csv-analyzer-mcp",
           "run",
           "csv-analyzer-mcp"
         ]
       }
     }
   }
   ```

3. `/ABSOLUTE/PATH/TO/csv-analyzer-mcp` を実際のパスに置き換えます（例：`/Users/username/python/csv-analyzer-mcp`）

4. Claude for Desktop を再起動します

5. Claude で、コネクター メニューに「csv-analyzer」サーバーが利用可能として表示されるようになります。以下でテストできます：
   - 「このCSVを分析して: /path/to/your/file.csv」
   - 「data.csvの構造をまとめて」

## ツール

### 1. `analyze_csv`

CSV ファイルの包括的な統計分析

**入力:**
- `file_path` (文字列): CSV ファイルへのパス

**出力:**
以下を含むフォーマット済みレポート:
- 行数と列数
- 列名とデータ型
- 列ごとの統計（数値列: 最小値、最大値、平均値、標準偏差、中央値、文字列列: ユニーク値数）
- 全体サマリー（数値列、欠損値、メモリ使用量）

**例:**
```
ユーザー: 「/Users/john/data/sales.csv を分析して」

Claude: [analyze_csv ツールを呼び出し]

出力:
======================================================================
CSV 分析レポート
======================================================================

基本情報
  行数:          1000
  列数:          5
  列名:          date, product, amount, region, discount

列の統計情報
  ...
```

### 2. `get_csv_summary`

CSV 構造の JSON フォーマット済みクイックサマリー

**入力:**
- `file_path` (文字列): CSV ファイルへのパス

**出力:**
以下を含む JSON オブジェクト:
- `rows`: 行数
- `columns`: 列数
- `column_names`: すべての列名のリスト
- `column_types`: 列型の辞書
- `numeric_columns`: 数値列のリスト
- `total_missing_values`: 欠損値の数

**例:**
```json
{
  "rows": 1000,
  "columns": 5,
  "column_names": ["date", "product", "amount", "region", "discount"],
  "column_types": {
    "date": "object",
    "product": "object",
    "amount": "float64",
    "region": "object",
    "discount": "int64"
  },
  "numeric_columns": ["amount", "discount"],
  "total_missing_values": 12
}
```

## アーキテクチャ

```
csv-analyzer-mcp/
├── pyproject.toml              # プロジェクトメタデータ、依存関係、エントリポイント
├── README.md                   # このファイル
├── .gitignore                  # Git無視パターン
│
├── src/csv_analyzer_mcp/
│   ├── __init__.py            # パッケージ初期化とバージョン
│   ├── main.py                # サーバーエントリポイントと STDIO トランスポート設定
│   ├── tools.py               # MCP ツール定義（@mcp.tool デコレータ）
│   ├── utils.py               # ヘルパー関数（CSV読込、統計処理）
│   └── py.typed               # PEP 561 型ヒントマーカー
│
├── examples/
│   ├── sample.csv             # テスト用サンプルデータ
│   └── example_usage.md       # 使用例
│
└── tests/ (オプション)
    ├── test_utils.py
    └── test_tools.py
```

### モジュール概要

- **`main.py`**: FastMCP サーバーを初期化し、STDIO トランスポートで実行します。これは MCP サーバーのエントリポイントです。

- **`tools.py`**: `@mcp.tool()` デコレータを使用して MCP ツールを定義します。各関数は LLM クライアントが利用可能なツールになります。

- **`utils.py`**: ビジネスロジックを含みます:
  - `read_csv_file()`: エラー処理付きで CSV を安全に読み込み
  - `calculate_statistics()`: pandas を使用して統計を計算
  - `format_statistics_report()`: 出力を人間が読みやすいテキストにフォーマット

## 動作原理

```
┌─────────────┐
│ Claude for  │
│ Desktop     │
└──────┬──────┘
       │ (JSON-RPC over STDIO)
       │
   ┌───▼────────────────────┐
   │ MCP サーバープロセス   │
   │ (csv-analyzer-mcp)     │
   └───┬────────────────────┘
       │
   ┌───▼────────────────────┐
   │ tools.py               │
   │ - analyze_csv          │
   │ - get_csv_summary      │
   └───┬────────────────────┘
       │
   ┌───▼────────────────────┐
   │ utils.py               │
   │ - read_csv_file()      │
   │ - calculate_statistics │
   │ - format_report()      │
   └────────────────────────┘
```

**フロー:**
1. Claude がCSV分析に関する質問をします
2. Claude のクライアントが JSON-RPC リクエストをこの MCP サーバーに送信します
3. `tools.py` モジュールがリクエストを受け取ります
4. `utils.py` が実際のファイル読み込みと計算を実行します
5. 結果をフォーマットして JSON-RPC レスポンスとして返送します
6. Claude は結果をユーザーに表示します

## サンプルデータ

`examples/sample.csv` に 12行5列のサンプル従業員データが含まれています:

| 列 | 型 | 説明 |
|--------|------|-------------|
| name | 文字列 | 従業員フルネーム |
| age | 整数 | 従業員年齢 |
| salary | 整数 | 年間給与（USD） |
| department | 文字列 | 部門名 |
| hire_date | 日付 | 採用日（YYYY-MM-DD形式） |

## 使用例

### Claude for Desktop での使用

Claude for Desktop を開いて、以下のように質問できます:

**例 1: CSV ファイルの詳細分析**

```
ユーザー: 「/Users/username/python/csv-analyzer-mcp/examples/sample.csv ファイルを分析してもらえますか？」

Claude: [analyze_csv ツールを呼び出し]

出力:
======================================================================
CSV 分析レポート
======================================================================

基本情報
  行数:          12
  列数:          5
  列名:          name, age, salary, department, hire_date

列の統計情報

  name (型: object)
    非null値:   12
    null値:     0
    ユニーク値: 12

  age (型: int64)
    非null値:   12
    null値:     0
    最小値:     26
    最大値:     52
    平均値:     36.25
    標準偏差:   8.91
    中央値:     34.5

  salary (型: int64)
    非null値:   12
    null値:     0
    最小値:     65000
    最大値:     105000
    平均値:     83916.67
    標準偏差:   11899.63
    中央値:     84500.0

  department (型: object)
    非null値:   12
    null値:     0
    ユニーク値: 5

  hire_date (型: object)
    非null値:   12
    null値:     0
    ユニーク値: 12

サマリー
  数値列:       age, salary
  欠損値の合計: 0
  メモリ使用量: 0.18 MB

======================================================================
```

**例 2: CSV 構造のクイックサマリー**

```
ユーザー: 「/Users/username/python/csv-analyzer-mcp/examples/sample.csv の JSON サマリーをください」

Claude: [get_csv_summary ツールを呼び出し]

出力:
{
  "rows": 12,
  "columns": 5,
  "column_names": ["name", "age", "salary", "department", "hire_date"],
  "column_types": {
    "name": "object",
    "age": "int64",
    "salary": "int64",
    "department": "object",
    "hire_date": "object"
  },
  "numeric_columns": ["age", "salary"],
  "total_missing_values": 0
}
```

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

### Claude for Desktop にサーバーが表示されない

1. `claude_desktop_config.json` が正しくフォーマットされているか確認してください（有効な JSON）
2. プロジェクトディレクトリへの絶対パスが正しいか確認してください
3. Claude for Desktop を再起動してください（macOS では Cmd+Q で完全に終了）
4. ログを確認: `tail -f ~/Library/Logs/Claude/mcp*.log`

### CSV ファイルが見つからないエラー

- 絶対パスまたは現在の作業ディレクトリに相対的なパスを使用してください
- ファイルが存在し、読み取り可能か確認: `ls -la /path/to/file.csv`

### 最初の実行時の「許可が拒否されました」エラー

macOS/Linux では、実行許可を与える必要がある場合があります:
```bash
chmod +x /Users/username/python/csv-analyzer-mcp
```

## さらに詳しく

- [MCP ドキュメント](https://modelcontextprotocol.io/)
- [MCP クイックスタート](https://modelcontextprotocol.io/quickstart)
- [FastMCP ガイド](https://modelcontextprotocol.io/docs/develop/server-patterns#fastmcp)
- [Claude for Desktop MCP 設定](https://claude.ai/docs/connectors)
- [pandas ドキュメント](https://pandas.pydata.org/)

## ライセンス

MIT ライセンス - [LICENSE](LICENSE) ファイルの詳細を参照してください。