# 📊 Survey Insight MCP Server

AI-powered survey comment analysis MCP server that generates beautiful interactive dashboards.

社内アンケートの自由コメント欄を自動分析し、**洗練されたHTMLダッシュボード**を生成するMCPサーバです。

## 📸 生成されるレポート例

<div align="center">

### エグゼクティブサマリー & WordCloud
<img src="images/report-01.png" width="45%" alt="エグゼクティブサマリー"> <img src="images/report-02.png" width="45%" alt="WordCloud">

### キーワードランキング & 分析軸別グラフ
<img src="images/report-03.png" width="45%" alt="頻出キーワードランキング"> <img src="images/report-04.png" width="45%" alt="分析軸別グラフ">

### AI課題分析 & 改善提案
<img src="images/report-05.png" width="45%" alt="AI課題分析"> <img src="images/report-06.png" width="45%" alt="改善提案">

</div>

## ✨ 主な機能

- 📝 **CSV自動解析**: エンコーディング自動検出、データクレンジング
- 🔍 **形態素解析**:
  - 日本語: janomeによる高精度解析
  - 英語: spaCyによる自然言語処理
  - キーワード抽出・頻度分析
- 🌐 **多言語対応**:
  - 日本語・英語の自動判別
  - AI分析結果は常に日本語で出力
- 📈 **分析軸対応**: 部署、年代、役職などで多角的分析
- ☁️ **WordCloud生成**: 美しいカラースキーム（パープルグラデーション）
- 📊 **インタラクティブグラフ**: Plotlyで棒グラフ（キーワードランキング）、円グラフ（分析軸別分布）
- 🤖 **AI課題分析**: Claude/Gemini APIで課題発見・改善提案
- 🎨 **HTMLダッシュボード**: レスポンシブ、アニメーション付き

## 🚀 クイックスタート

### Claude Codeでの使用

#### 方法1: コマンドラインでインストール（推奨）

**基本インストール（AI分析なし）:**
```bash
claude mcp add --transport stdio survey-insight --scope user -- \
  uvx --from git+https://github.com/sinjorjob/survey-insight-mcp.git survey-insight-mcp
```

**AI分析あり - Claude Code Subscription利用（推奨）:**
```bash
claude mcp add --transport stdio survey-insight --scope user \
  -e USE_CLAUDE_CODE_SUBSCRIPTION=true -- \
  uvx --from git+https://github.com/sinjorjob/survey-insight-mcp.git survey-insight-mcp
```

**AI分析あり - Anthropic Claude API利用:**
```bash
claude mcp add --transport stdio survey-insight --scope user \
  -e LLM_PROVIDER=anthropic \
  -e LLM_API_KEY=sk-ant-api03-your_key_here \
  -e LLM_MODEL=claude-3-5-sonnet-20241022 -- \
  uvx --from git+https://github.com/sinjorjob/survey-insight-mcp.git survey-insight-mcp
```

**AI分析あり - Google Gemini API利用:**
```bash
claude mcp add --transport stdio survey-insight --scope user \
  -e LLM_PROVIDER=google \
  -e LLM_API_KEY=your_google_api_key_here \
  -e LLM_MODEL=gemini-2.0-flash-exp -- \
  uvx --from git+https://github.com/sinjorjob/survey-insight-mcp.git survey-insight-mcp
```

インストール後、**Claude Codeを再起動**してください。

#### 方法2: 設定ファイルで手動インストール

設定ファイル（Windows: `%USERPROFILE%\.claude.json`、macOS/Linux: `~/.claude.json`）を編集：

**基本設定（AI分析なし）:**
```json
{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ]
    }
  }
}
```

**AI分析あり - Claude Code Subscription利用:**
```json
{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ],
      "env": {
        "USE_CLAUDE_CODE_SUBSCRIPTION": "true"
      }
    }
  }
}
```

**AI分析あり - Anthropic Claude API利用:**
```json
{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ],
      "env": {
        "LLM_PROVIDER": "anthropic",
        "LLM_API_KEY": "sk-ant-api03-your_key_here",
        "LLM_MODEL": "claude-3-5-sonnet-20241022"
      }
    }
  }
}
```

**AI分析あり - Google Gemini API利用:**
```json
{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ],
      "env": {
        "LLM_PROVIDER": "google",
        "LLM_API_KEY": "your_google_api_key_here",
        "LLM_MODEL": "gemini-2.0-flash-exp"
      }
    }
  }
}
```

設定後、**Claude Codeを再起動**してください。

#### LLMプロバイダーの変更方法

後からLLMプロバイダーを変更する場合：

**方法A: コマンドで再登録**
```bash
# 1. 既存の設定を削除
claude mcp remove survey-insight

# 2. 新しいプロバイダーで再登録
# Google Geminiに変更する場合：
claude mcp add --transport stdio survey-insight --scope user \
  -e LLM_PROVIDER=google \
  -e LLM_API_KEY=your_new_key_here \
  -e LLM_MODEL=gemini-2.0-flash-exp -- \
  uvx --from git+https://github.com/sinjorjob/survey-insight-mcp.git survey-insight-mcp

# Anthropic Claudeに変更する場合：
claude mcp add --transport stdio survey-insight --scope user \
  -e LLM_PROVIDER=anthropic \
  -e LLM_API_KEY=sk-ant-api03-your_new_key_here \
  -e LLM_MODEL=claude-3-5-sonnet-20241022 -- \
  uvx --from git+https://github.com/sinjorjob/survey-insight-mcp.git survey-insight-mcp

# 3. Claude Codeを再起動
```

**方法B: 設定ファイルを直接編集**
`~/.claude.json`の`env`セクションを編集して、Claude Codeを再起動。

#### 使い方

Claude Code上で以下のように依頼：

```
examples/sample_survey.csvを分析して、部署別・年代別のレポートを生成してください。
```

MCPツールが自動的に呼び出され、HTMLレポートとWordCloudが生成されます。

---

## 📋 CSVファイル要件

### ファイル形式

- **拡張子**: `.csv`
- **エンコーディング**: 自動検出対応
  - `cp932` (Excel日本語 / Shift-JIS)
  - `shift-jis`
  - `utf-8-sig` (BOM付きUTF-8)
  - `utf-8`
- **言語**: 日本語・英語に対応
  - **日本語**: デフォルトで対応（追加設定不要）
  - **英語**: 自動で対応（英語モデルは依存関係に含まれます）
  - コメント列のテキストから**言語を自動判別**
  - `language`パラメータで明示的な指定も可能（`"ja"` または `"en"`）
  - **AI分析結果は常に日本語で出力**（入力言語に関わらず）

### データ形式

**必須要素:**
- **コメント列**: 自由記述テキストを含む列
  - 列名に「コメント」「comment」「自由記述」「意見」「感想」「フィードバック」を含む場合は自動検出
  - 上記以外の場合は最も平均文字数が長い文字列型の列を自動選択
  - `comment_column`パラメータで明示的に指定も可能

**オプション要素:**
- **分析軸列**: カテゴリカルデータ（部署、年代、役職など）
  - 以下の条件で自動検出:
    - ユニーク値が2以上
    - ユニーク値が全体の50%未満
    - データ型が文字列 (object) またはカテゴリ (category)
  - `analysis_axes`パラメータで明示的に指定も可能
  - 除外: コメント列、ID列

**データクレンジング:**
- 完全に空の行は自動削除
- 重複行は自動削除
- 文字列の前後空白は自動トリミング

### サンプルCSV構造

**日本語:**
```csv
部署,年代,コメント
営業,30代,対応が丁寧で良かったです
技術,40代,待ち時間が長いのが気になりました
```

**英語:**
```csv
Department,Age_Group,Comments_Feedback
Sales,30s,The service was very polite and helpful
Technical,40s,The waiting time was a bit long
```

サンプルファイル:
- 日本語版: `examples/sample_survey.csv`
- 英語版: `examples/healthcare_service_survey_en.csv`

---

## 📝 AI分析機能について

**AI分析なし**:
- 形態素解析、キーワード抽出、グラフ生成、WordCloudのみ実行
- 環境変数設定不要

**AI分析あり**:
- 上記に加えて、AIによる課題発見・改善提案を実行
- 以下のいずれかの環境変数設定が必要：
  - `USE_CLAUDE_CODE_SUBSCRIPTION=true`（Claude Codeサブスクリプション）
  - `LLM_PROVIDER` + `LLM_API_KEY`（Anthropic/Google API）

---

## 🔧 その他のMCPクライアント

### Gemini CLI

設定ファイル（Windows: `%USERPROFILE%\.gemini\settings.json`、macOS/Linux: `~/.gemini/settings.json`）を編集：

**基本設定（AI分析なし）:**
```json
{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ]
    }
  }
}
```

**AI分析あり（Google Gemini API利用 - 推奨）:**
```json
{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ],
      "env": {
        "LLM_PROVIDER": "google",
        "LLM_API_KEY": "your_google_api_key_here",
        "LLM_MODEL": "gemini-2.0-flash-exp"
      }
    }
  }
}
```

設定後、**Gemini CLIを再起動**してください。

### その他のMCPクライアント

MCP仕様に準拠した任意のクライアントで使用できます：

- **Transport**: stdio
- **Command**: `uvx`
- **Args**: `["--from", "git+https://github.com/sinjorjob/survey-insight-mcp.git", "survey-insight-mcp"]`
- **Environment Variables**: 上記の環境変数設定を参照

---

## 🌐 多言語対応

Survey Insight MCP Serverは日本語と英語のアンケートに対応しています。

### サポート言語

- **日本語**: janome による形態素解析
- **英語**: spacy (`en_core_web_sm`) による形態素解析

### 言語判別

**自動判別（推奨）:**

コメント列のテキストから自動的に言語を判別します。

```
examples/customer_feedback_en.csvを分析してください。
```

**手動指定:**

`language`パラメータで明示的に指定することも可能です。

```python
{
  "csv_path": "examples/survey_data.csv",
  "language": "en"  # "ja" or "en"
}
```

### 英語環境のセットアップ

**完全自動セットアップ:**

英語CSVを初めて分析する際、spacyの英語モデル (`en_core_web_sm`) が**完全自動で**ダウンロードされます。ユーザーによる事前セットアップは一切不要です。

- 初回のみ約12MBのモデルダウンロードが発生します（数秒〜数十秒）
- 2回目以降は既存のモデルを使用するため、ダウンロードは不要です
- uvx環境で自動的に `uv pip install` が実行されます

### 処理の違い

| 処理 | 日本語 (janome) | 英語 (spacy) |
|------|----------------|--------------|
| 形態素解析 | ✅ | ✅ |
| キーワード抽出 | 表層形を使用 | レンマ（基本形）を使用 |
| 複合名詞抽出 | ✅ 対応 | ❌ 非対応（単語のみ） |
| 品詞フィルタリング | 名詞・動詞・形容詞 | NOUN・VERB・ADJ |
| 最小文字数 | 1文字以上 | 3文字以上 |
| ストップワード | 日本語用リスト | 英語用リスト |

---

## 📖 MCPツール仕様

### `analyze_survey`

CSVファイルからアンケート分析を実行し、HTMLレポートとWordCloudを生成します。

**パラメータ:**

- `csv_path` (必須): CSVファイルのパス
- `comment_column` (オプション): 自由コメント列の名前（省略時は自動検出）
- `analysis_axes` (オプション): 分析軸のリスト（例: `["部署", "年代", "役職"]`）
- `output_path` (オプション): 出力HTMLパス（デフォルト: `output/survey_report.html`）
- `enable_ai_analysis` (オプション): AI課題分析を有効化（デフォルト: `true`）
- `language` (オプション): 言語コード（`"ja"` or `"en"`、省略時はコメント列から自動判別）

**使用例:**

```
examples/healthcare_service_survey.csvを分析して、診療科別と年齢層別のレポートを生成してください。
```

**英語CSVの分析例:**

```
examples/customer_feedback_en.csvを分析してください。
```

---

## 🛠️ ローカル開発

### 環境構築

```bash
# リポジトリのクローン
git clone https://github.com/sinjorjob/survey-insight-mcp.git
cd survey-insight-mcp

# uv仮想環境作成
uv venv

# 依存パッケージインストール
uv pip install -e .
```

### 環境変数設定

```bash
cp .env.example .env
# .envファイルを編集してLLM設定
```

### ローカルでのテスト

```bash
# MCPサーバをローカルから実行
uvx --from . survey-insight-mcp

# または、MCP Inspectorでテスト
npm install -g @modelcontextprotocol/inspector
mcp-inspector uvx --from . survey-insight-mcp
```

### テスト実行

```bash
# ユニットテスト
pytest

# Lintチェック
ruff check --line-length=127
ruff format --check --diff --line-length=127
```

---

## 📁 プロジェクト構造

```
survey-insight-mcp/
├── pyproject.toml              # パッケージ設定
├── README.md                   # このファイル
├── LICENSE                     # MITライセンス
├── .env.example                # 環境変数テンプレート
├── src/survey_insight/
│   ├── server.py              # エントリーポイント
│   ├── mcp_server.py          # MCPサーバ実装
│   ├── csv_loader.py          # CSV読み込み
│   ├── text_analyzer.py       # 形態素解析
│   ├── chart_generator.py     # グラフ生成
│   ├── ai_analyzer.py         # AI課題分析
│   └── templates/
│       └── dashboard.html     # HTMLテンプレート
├── tests/                     # テストコード
└── examples/                  # サンプルCSVファイル
```

---

## 🔄 アップデート方法

最新版を取得するには：

```bash
# uvxキャッシュをクリア
uv cache clean

# Claude Code / Gemini CLIを再起動
```

uvxは自動的に最新のコミットを取得します。

---

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

### 問題1: MCPサーバが表示されない

**解決策:**
1. Claude Code設定ファイル（`~/.claude.json`）を確認
2. GitHubリポジトリのURLが正しいか確認
3. Claude Codeを再起動

### 問題2: AI分析が実行されない

**原因**: 環境変数が正しく設定されていない

**解決策:**
- `USE_CLAUDE_CODE_SUBSCRIPTION=true` を設定
- または、`LLM_PROVIDER` と `LLM_API_KEY` を設定

### 問題3: 依存関係のエラー

**解決策:**
```bash
# uvxキャッシュをクリア
uv cache clean --force

# Claude Codeを再起動
```

---

## 📝 ライセンス

MIT License

---

🤖 Powered by **Claude AI**