星战科技xingzhan.cloud
返回市场
调查洞察mcp

调查洞察mcp

作者：sinjorjob2 星标更新：2025-10-25
安装使用来源：spider==github.com

项目介绍

技术文档摘要

📊 Survey Insight MCP Server

基于AI的调查评论分析MCP服务器，生成美观的交互式仪表板。

自动分析公司内部调查中的自由评论栏，并生成精美的HTML仪表板的MCP服务器。

📸 生成的报告示例

<div align="center">

执行摘要 & 词云

<img src="images/report-01.png" width="45%" alt="执行摘要"> <img src="images/report-02.png" width="45%" alt="词云">

关键词排名 & 分析轴别图表

<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分析结果始终以日语输出
  • 📈 分析轴支持: 按部门、年龄、职位等多维度分析
  • ☁️ 词云生成: 美丽的颜色方案（紫色渐变）
  • 📊 交互式图表: 使用Plotly生成柱状图（关键词排名）和饼图（分析轴别分布）
  • 🤖 AI问题分析: 使用Claude/Gemini API发现并提出改进建议
  • 🎨 HTML仪表板: 响应式设计，带有动画效果

🚀 快速开始

在Claude Code中使用

方法1: 通过命令行安装（推荐）

基本安装（无AI分析）:

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订阅（推荐）:

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:

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:

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分析）:

{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ]
    }
  }
}

包含AI分析 - 使用Claude Code订阅:

{
  "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:

{
  "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:

{
  "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: 重新注册命令

# 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报告和词云。

📋 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结构

日语:

部门,年龄,评论
销售,30代,服务很礼貌，很好
技术,40代,等待时间有点长

英语:

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分析:

  • 仅执行词法分析、关键词提取、图表生成、词云
  • 不需要环境变量设置

包含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分析）:

{
  "mcpServers": {
    "survey-insight": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sinjorjob/survey-insight-mcp.git",
        "survey-insight-mcp"
      ]
    }
  }
}

包含AI分析（推荐使用Google Gemini API）:

{
  "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规范的客户端都可以使用：

  • 传输: stdio
  • 命令: uvx
  • 参数: ["--from", "git+https://github.com/sinjorjob/survey-insight-mcp.git", "survey-insight-mcp"]
  • 环境变量: 参考上述环境变量设置

🌐 多语言支持

Survey Insight MCP Server支持日语和英语的调查。

支持的语言

  • 日语: 使用janome进行词法分析
  • 英语: 使用spacy (en_core_web_sm) 进行词法分析

语言识别

自动识别（推荐）:

从评论列文本中自动识别语言。

分析examples/customer_feedback_en.csv。

手动指定:

可以通过language参数明确指定。

{
  "csv_path": "examples/survey_data.csv",
  "language": "en"  # "ja" 或 "en"
}

英语环境设置

全自动设置:

首次分析英语CSV时，spacy的英语模型 (en_core_web_sm) 将全自动下载。用户无需事先设置。

  • 首次下载约12MB的模型（几秒到几十秒）
  • 第二次及以后使用已存在的模型，无需再次下载
  • 在uvx环境中自动执行 uv pip install

处理差异

处理日语 (janome)英语 (spacy)
词法分析✅✅
关键词提取使用表层形式使用词根（基本形式）
复合名词提取✅ 支持❌ 不支持（仅单词）
词性过滤名词、动词、形容词NOUN、VERB、ADJ
最小字符数至少1个字符至少3个字符
停用词日语停用词列表英语停用词列表

📖 MCP工具规格

analyze_survey

从CSV文件中执行调查分析，并生成HTML报告和词云。

参数:

  • csv_path (必需): CSV文件路径
  • comment_column (可选): 自由评论列名称（未指定时自动检测）
  • analysis_axes (可选): 分析轴列表（例如: ["部门", "年龄", "职位"]）
  • output_path (可选): 输出HTML路径（默认: output/survey_report.html）
  • enable_ai_analysis (可选): 启用AI问题分析（默认: true）
  • language (可选): 语言代码（"ja" 或 "en"，未指定时自动检测评论列语言）

使用示例:

分析examples/healthcare_service_survey.csv，并生成按诊疗科和年龄层分组的报告。

英语CSV分析示例:

分析examples/customer_feedback_en.csv。

🛠️ 本地开发

环境搭建

# 克隆仓库
git clone https://github.com/sinjorjob/survey-insight-mcp.git
cd survey-insight-mcp

# 创建uv虚拟环境
uv venv

# 安装依赖包
uv pip install -e .

环境变量设置

cp .env.example .env
# 编辑.env文件以设置LLM

本地测试

# 从本地运行MCP服务器
uvx --from . survey-insight-mcp

# 或者使用MCP Inspector进行测试
npm install -g @modelcontextprotocol/inspector
mcp-inspector uvx --from . survey-insight-mcp

测试执行

# 单元测试
pytest

# 代码检查
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文件

🔄 更新方法

获取最新版本：

# 清除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: 依赖关系错误

解决办法:

# 清除uvx缓存
uv cache clean --force

# 重启Claude Code

📝 许可证

MIT License

🤖 提供商：Claude AI