Survey Insight MCP Server

# 📊 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**