# 问卷交叉分析 MCP Server (survey-crosstab)

AI 驱动的问卷数据交叉分析工具，作为 MCP Server 运行，可被 Claude Desktop、Cursor 及其他 MCP 客户端调用。

## 功能概览

| 工具 | 功能 |
|------|------|
| `load_survey_data` | 加载问卷（Excel/CSV），自动识别单选/多选/文本/元数据列 |
| `preview_column_data` | 预览指定列的频数分布 |
| `merge_column_options` | 合并选项（如 1-3 归为"不满意"，4-5 归为"满意"） |
| `run_crosstab_analysis` | 执行交叉分析（频数表 + 列百分比） |
| `calc_score_analysis` | 自动识别计算满意度得分或 NPS（支持 `["auto"]` 自动检测） |
| `get_analysis_summary` | 提取关键差异摘要（辅助 AI 撰写报告） |
| `export_report` | 导出格式化 Excel（含 DataBar、v3 结构化分析报告 sheet） |

## 安装

### 方式一：一键安装（推荐）

```bash
# 下载 survey-crosstab.exe 后，直接运行：
survey-crosstab.exe install

# 仅配置特定客户端：
survey-crosstab.exe install --client cursor
survey-crosstab.exe install --client claude
```

安装命令会自动：
1. 将 exe 复制到 `%LOCALAPPDATA%/survey-crosstab/`
2. 检测并配置已安装的 MCP 客户端（Cursor、Claude Desktop）
3. 输出手动配置说明（适用于其他 MCP 客户端）

### 方式二：手动配置

在 MCP 客户端的配置界面中填写：

| 字段 | 值 |
|------|---|
| **Command** | `C:\Users\你的用户名\AppData\Local\survey-crosstab\survey-crosstab.exe` |
| **Args** | （留空） |

或直接编辑 JSON 配置：

```json
{
  "mcpServers": {
    "survey-crosstab": {
      "command": "C:\\Users\\你的用户名\\AppData\\Local\\survey-crosstab\\survey-crosstab.exe",
      "args": [],
      "env": {}
    }
  }
}
```

### 方式三：从源码运行

```bash
cd MCP-crosstable
pip install -r requirements.txt
python server.py
```

## 命令行参考

```bash
survey-crosstab.exe                      # 启动 MCP 服务器（stdio 模式）
survey-crosstab.exe --port 8000          # 启动 MCP 服务器（SSE/HTTP 模式）
survey-crosstab.exe install              # 一键安装并配置
survey-crosstab.exe install --client cursor  # 仅配置 Cursor
survey-crosstab.exe uninstall            # 卸载并移除配置
survey-crosstab.exe --version            # 查看版本
survey-crosstab.exe --help               # 查看帮助
```

## 使用示例

### 示例 1：分析性别差异
> "帮我加载 survey_90450_w_0.xlsx，然后分析男生女生在各题目上的差异"

AI 会自动：
1. `load_survey_data` → 识别数据结构
2. `run_crosstab_analysis(行="all", 列="Q17.性别")` → 交叉分析
3. `calc_score_analysis(["auto"])` → 自动检测并计算所有满意度/NPS得分
4. `get_analysis_summary` → 获取差异摘要
5. 撰写分析报告
6. `export_report` → 导出 Excel

### 示例 2：合并选项后分析
> "把 Q1 满意度的 1-3 分归为不满意，4-5 分归为满意，然后和其他题目做交叉"

AI 会自动：
1. `load_survey_data` → 加载数据
2. `merge_column_options(rules={"不满意":[1,2,3], "满意":[4,5]})` → 合并选项
3. `run_crosstab_analysis(行="all", 列=合并后列名)` → 交叉分析
4. `export_report` → 导出 Excel

## 文件结构

```
MCP-crosstable/
├── server.py              # MCP Server 主入口（7 个工具定义 + CLI 入口）
├── crosstab_engine.py     # 核心数据处理引擎
├── crosstab_export.py     # Excel 导出与样式模块（v3 结构化报告）
├── installer.py           # 安装/卸载模块
├── requirements.txt       # Python 依赖
└── README.md              # 本文件
```

## 版本历史

| 版本 | 更新内容 |
|------|---------|
| v1.1.0 | 结构化分析报告 sheet (v3)、NPS 百分比格式、满意度双条件自动检测、一键安装 |
| v1.0.0 | 初始版本：7 个工具、交叉分析、DataBar 可视化 |