# 急语箱MCP服务器 - 智能场景与人物识别服务

> **基于MCP协议的沟通场景深度分析服务** | 识别准确率≥95% | 多模态支持

---

## 🎯 项目定位

**急语箱MCP服务器**是一个专注于沟通场景深度分析的智能服务，能够：

### 核心能力

1. **🔍 场景识别**（4类场景，≥95%准确率）
   - 职场（Workplace）
   - 恋爱（Love）
   - 家庭（Family）
   - 社交（Social）

2. **👥 人物识别**
   - 识别沟通双方（发送方、接收方）
   - 识别参与人（多人场景）
   - 识别角色（领导、同事、对象、父母等）

3. **🔗 关系分析**
   - 关系类型（上下级、情侣、家人、朋友等）
   - 亲密度评估
   - 权力结构分析
   - 正式程度判断

4. **😊 态度判断**
   - 情绪识别（愤怒、开心、担心、不满等）
   - 态度判断（支持、反对、中立、批评等）
   - 语气分析（正式、随意、温暖、冷漠等）
   - 强度评估

5. **🎯 决策要素提取**
   - 关键信息提取
   - 冲突点识别
   - 需求识别
   - 风险评估

6. **⚠️ 不确定性处理**
   - 明确标注"不确定"
   - 单独存放低置信度结果
   - 提供澄清建议

### 性能指标

| 指标 | 目标值 |
|-----|-------|
| **场景识别准确率** | ≥95% |
| **人物识别准确率** | ≥90% |
| **关系分析准确率** | ≥85% |
| **态度判断准确率** | ≥80% |
| **综合准确率** | ≥90% |
| **响应时间** | <2秒 |
| **并发处理** | ≥100 QPS |

---

## 🚀 快速开始

### 1. 本地测试

```bash
cd mcp_project

# 安装依赖
pip install -r requirements-mcp.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填写华为云API密钥

# 启动服务
python -m mcp_server.main

# 测试API
curl http://localhost:8000/health
```

### 2. Docker测试

```bash
cd mcp_project

# 启动服务
docker-compose up -d

# 查看日志
docker-compose logs -f mcp-server

# 测试API
curl http://localhost:8000/health
```

### 3. 第一个API调用

```bash
# 综合分析沟通场景
curl -X POST http://localhost:8000/api/v1/analyze \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{
    "text": "领导批评我业绩不好，说需要改进",
    "analysis_options": {
      "include_participants": true,
      "include_relationships": true,
      "include_attitudes": true,
      "include_decision_factors": true
    }
  }'
```

**返回示例**:
```json
{
  "analysis_id": "analysis_20260316_103000",
  "scenario": {
    "type": "workplace",
    "confidence": 0.98,
    "uncertain": false
  },
  "participants": [
    {
      "id": "person_1",
      "role": "领导",
      "position": "发送方",
      "confidence": 0.95
    },
    {
      "id": "person_2",
      "role": "下属/我",
      "position": "接收方",
      "confidence": 0.90
    }
  ],
  "relationships": [
    {
      "type": "上下级",
      "power_balance": "领导主导",
      "confidence": 0.95
    }
  ],
  "attitudes": [
    {
      "person_id": "person_1",
      "emotion": "不满",
      "stance": "批评",
      "tone": "严肃",
      "confidence": 0.90
    }
  ],
  "overall_confidence": 0.94,
  "uncertain_items": []
}
```

---

## 🔔 实时事件推送（SSE）

服务器支持 **Server-Sent Events (SSE)** 实时事件推送，可以订阅服务器事件流，实时接收场景识别结果和系统通知。

### 快速体验

```javascript
// JavaScript 客户端
const eventSource = new EventSource('http://localhost:8000/events');

// 监听场景识别完成事件
eventSource.addEventListener('scenario.recognized', (e) => {
    const data = JSON.parse(e.data);
    console.log('场景:', data.scenario);
    console.log('置信度:', data.confidence);
    console.log('文本:', data.text);
});

// 监听系统通知
eventSource.addEventListener('system.notification', (e) => {
    const data = JSON.parse(e.data);
    console.log('通知:', data.title, '-', data.message);
});
```

### 主要端点

| 端点 | 方法 | 描述 |
|-----|------|------|
| `/events` | GET | 连接SSE事件流 |
| `/events/scenario/recognized` | POST | 触发场景识别事件 |
| `/events/notify` | POST | 发送系统通知 |
| `/events/test` | POST | 测试SSE连接 |

### 测试SSE

```bash
# 测试SSE连接
curl -X POST http://localhost:8000/events/test

# 触发场景识别事件
curl -X POST http://localhost:8000/events/scenario/recognized \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "workplace",
    "confidence": 0.95,
    "text": "老板让我加班到很晚"
  }'

# 发送系统通知
curl -X POST http://localhost:8000/events/notify \
  -H "Content-Type: application/json" \
  -d '{
    "level": "info",
    "title": "系统通知",
    "message": "场景识别服务已启动"
  }'
```

### 详细文档

查看 **[SSE_USAGE.md](SSE_USAGE.md)** 获取完整的SSE使用文档，包括：
- 所有事件类型说明
- 客户端集成示例（JavaScript、Python）
- 使用场景和最佳实践
- 故障排除指南

---

## 📡 MCP工具

### 工具1: analyze_communication_scenario
**综合分析沟通场景**（推荐使用）

```json
POST /mcp/tools/analyze_communication_scenario
{
  "text": "领导批评我业绩不好，说需要改进",
  "image_data": "base64_image...",  // 可选
  "analysis_options": {
    "include_participants": true,
    "include_relationships": true,
    "include_attitudes": true,
    "include_decision_factors": true
  }
}
```

### 工具2: identify_scenario
**单独识别场景类型**

```json
POST /mcp/tools/identify_scenario
{
  "text": "对象生气了，怎么哄？"
}
```

### 工具3: identify_participants
**识别参与人和角色**

```json
POST /mcp/tools/identify_participants
{
  "text": "妈妈说太晚回家不安全",
  "scenario_hint": "family"
}
```

### 工具4: analyze_relationships
**分析人物关系**

```json
POST /mcp/tools/analyze_relationships
{
  "text": "领导找我和小王谈项目",
  "participants": [
    {"id": "p1", "role": "领导"},
    {"id": "p2", "role": "我"},
    {"id": "p3", "role": "小王"}
  ]
}
```

### 工具5: analyze_attitudes
**分析态度和情绪**

```json
POST /mcp/tools/analyze_attitudes
{
  "text": "老板说这次做得不错，继续努力",
  "focus_person": "p1"
}
```

### 工具6: extract_decision_factors
**提取决策要素**

```json
POST /mcp/tools/extract_decision_factors
{
  "text": "客户说价格太高，需要考虑一下",
  "scenario": "workplace"
}
```

---

## 🏗️ 项目结构

```
mcp_project/
├── mcp_server/                    # MCP服务器核心代码
│   ├── main.py                    # FastAPI应用入口
│   ├── mcp_protocol/              # MCP协议实现
│   ├── analyzers/                 # 识别分析器 ⭐
│   │   ├── scenario_recognizer.py      # 场景识别器
│   │   ├── participant_recognizer.py   # 人物识别器
│   │   ├── relationship_analyzer.py    # 关系分析器
│   │   ├── attitude_analyzer.py        # 态度分析器
│   │   └── uncertainty_handler.py      # 不确定性处理器
│   ├── config/                    # 配置管理
│   ├── core/                      # 核心业务逻辑（复用）
│   └── services/                  # 外部服务
├── tests/                         # 测试文件夹 ⭐
│   ├── data/                      # 测试数据
│   │   └── test_data_2000.json    # 主测试数据集（8000样本）
│   ├── tools/                     # 测试工具
│   │   ├── run_8000_test.py       # 准确率测试
│   │   ├── validate_test_data.py  # 数据验收
│   │   └── generate_sample_test_data.py  # 数据生成
│   ├── results/                   # 测试结果
│   ├── reports/                   # 测试报告
│   ├── docs/                      # 测试文档
│   │   ├── TEST_DATA_STANDARD.md       # 数据标准
│   │   └── TEST_DATA_QUICK_REFERENCE.md  # 快速参考
│   └── README.md                  # 测试说明
├── k8s/                           # Kubernetes配置
├── monitoring/                    # 监控配置
├── scripts/                       # 部署脚本
└── docs/                          # 项目文档
    ├── MCP_REDIGN.md             # 重新设计方案 ⭐
    ├── MCP_SERVICE_DESIGN.md     # 架构设计
    └── README_DEPLOY.md          # 部署指南
```

### 🧪 测试相关

所有测试相关内容已整理到 `tests/` 文件夹：

- **测试数据**: `tests/data/test_data_2000.json` (8000个真实样本)
- **测试工具**: `tests/tools/` (6个测试脚本)
- **测试报告**: `tests/reports/` (准确率测试报告)
- **测试文档**: `tests/docs/` (数据标准和使用指南)

查看 [tests/README.md](tests/README.md) 了解测试详情。

---

## 📊 应用场景

### 1. 对话分析系统
- 分析聊天记录的场景和人物关系
- 理解对话的情感和态度
- 提取关键决策要素

### 2. CRM系统
- 自动分析客户沟通场景
- 识别客户关系和态度
- 提供决策支持

### 3. 智能客服
- 理解客户问题的场景
- 识别客户情绪和态度
- 提供个性化响应建议

### 4. 社交媒体分析
- 分析社交媒体内容的场景
- 识别人物关系和态度
- 舆情监控和分析

### 5. 企业协作工具
- 分析工作沟通场景
- 识别团队关系动态
- 提升沟通效率

---

## 🔬 技术实现

### 场景识别算法（≥95%准确率）

采用三层识别架构：

1. **精确关键词匹配**（100%准确，覆盖60%）
   - 预定义4类场景的关键词词典
   - 精确匹配，零误差

2. **上下文模式匹配**（98%准确，覆盖25%）
   - 使用正则表达式匹配上下文模式
   - 结合语序和语境

3. **LLM辅助判断**（90%准确，覆盖15%）
   - 使用华为盘古大模型
   - 处理复杂和模糊场景

### 人物识别算法

- **角色词典匹配**: 预定义4类场景的角色词典
- **代词分析**: 识别"我"、"你"、"他"等人称代词
- **位置判断**: 判断人物在沟通中的位置（发送方/接收方）
- **置信度评估**: 基于证据强度计算置信度

### 关系分析算法

- **关系类型推断**: 基于角色组合推断关系
- **亲密度评估**: 基于称呼和语气判断亲密度
- **权力结构分析**: 识别上下级、长辈晚辈等权力关系
- **正式程度判断**: 分析语言正式程度

### 态度分析算法

- **情绪识别**: 基于情绪词典和语义分析
- **态度判断**: 识别支持、反对、中立等态度
- **语气分析**: 识别正式、随意、温暖、冷漠等语气
- **强度评估**: 评估情绪和态度的强度

### 不确定性处理

- **置信度阈值**: 默认0.7，低于阈值标记为"不确定"
- **明确标注**: 在结果中标注"uncertain"字段
- **单独存放**: 将不确定的结果放入"uncertain_items"数组
- **澄清建议**: 提供需要澄清的问题列表

---

## 📖 文档

### 核心文档
- **[MCP_REDIGN.md](docs/MCP_REDIGN.md)** - 重新设计方案（⭐ 推荐）
- **[MCP_SERVICE_DESIGN.md](docs/MCP_SERVICE_DESIGN.md)** - 完整架构设计
- **[README_DEPLOY.md](docs/README_DEPLOY.md)** - 部署指南
- **[PROJECT_STRUCTURE.md](docs/PROJECT_STRUCTURE.md)** - 文件结构说明

### 快速开始
- **[QUICKSTART.md](QUICKSTART.md)** - 5分钟快速开始
- **[DEVELOPMENT_CHECKLIST.md](DEVELOPMENT_CHECKLIST.md)** - 开发检查清单

---

## 🎯 与原方案的区别

| 维度 | 原方案 | 新方案 |
|-----|-------|--------|
| **核心功能** | 生成回复建议 | 识别分析场景、人物、关系、态度 |
| **主要输出** | 文本建议 | 结构化数据 |
| **准确率要求** | 未明确 | 场景≥95%、综合≥90% |
| **不确定性** | 隐式处理 | 明确标注或单独存放 |
| **应用场景** | 对话助手 | 决策支持系统 |

---

## 💰 成本估算

月度成本约 **¥500**，详见 [docs/MCP_SERVICE_DESIGN.md](docs/MCP_SERVICE_DESIGN.md)

---

## 📞 技术支持

- **技术支持**: support@jiyuxiang.com
- **项目地址**: https://github.com/jiyuxiang/mcp-server
- **文档地址**: https://docs.jiyuxiang.com

---

## 📝 版本信息

- **版本**: 2.0.0（重新设计）
- **创建日期**: 2026-03-16
- **状态**: 框架已完成，待开发核心识别引擎

---

**许可证**: Copyright © 2026 急语箱智能体. All rights reserved.
