emotion-analyzer-mcp 1.0.0
MCP服务器：使用Gemma-3模型分析图像中的人物表情
License: MIT
Requires Python: >=3.8
Keywords: mcp, emotion, analysis, ai, gemma, openrouter

# Emotion Analyzer MCP Server

一个使用 OpenRouter 的 Gemma-3 模型分析图像中人物表情的 MCP (Model Context Protocol) 服务器。

## 功能特性

- 🎭 **表情识别**: 识别快乐、悲伤、愤怒、惊讶、恐惧、厌恶、中性等表情
- 📊 **强度评估**: 提供 1-10 分的表情强度评分
- 🎯 **置信度评估**: 提供 0-1 的分析置信度
- 👤 **详细描述**: 提供面部特征和情绪状态的详细描述
- 🌐 **多种输入**: 支持文件路径和 base64 编码的图像
- 🔧 **标准 MCP**: 完全兼容 MCP 协议，可与各种 MCP 客户端集成

## 安装

### 方法 1: 使用 pip 安装（推荐）

```bash
pip install emotion-analyzer-mcp
```

### 方法 2: 从源码安装

```bash
git clone https://github.com/yourusername/emotion-analyzer-mcp.git
cd emotion-analyzer-mcp
pip install -e .
```

## 配置

### 1. 获取 OpenRouter API 密钥

1. 访问 [OpenRouter](https://openrouter.ai/)
2. 注册账户并获取 API 密钥
3. 设置环境变量：

```bash
export OPENROUTER_API_KEY="your_api_key_here"
```

### 2. 在 Cherry Studio 中配置

在 Cherry Studio 的 MCP 设置中添加以下配置：

```json
{
  "mcpServers": {
    "emotion-analyzer": {
      "command": "emotion-analyzer-mcp",
      "env": {
        "OPENROUTER_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### 3. 在其他 MCP 客户端中配置

对于支持 MCP 的其他客户端，使用类似的配置：

```json
{
  "name": "emotion-analyzer",
  "command": "emotion-analyzer-mcp",
  "env": {
    "OPENROUTER_API_KEY": "your_api_key_here"
  }
}
```

## 使用方法

### 可用工具

#### 1. analyze_emotion
通过文件路径分析图像中的表情。

**参数:**
- `image_path` (string, 必需): 图像文件的路径

**示例:**
```json
{
  "name": "analyze_emotion",
  "arguments": {
    "image_path": "/path/to/image.jpg"
  }
}
```

#### 2. analyze_emotion_base64
通过 base64 编码的图像数据分析表情。

**参数:**
- `image_data` (string, 必需): base64 编码的图像数据
- `image_format` (string, 可选): 图像格式，默认为 "jpeg"

**示例:**
```json
{
  "name": "analyze_emotion_base64",
  "arguments": {
    "image_data": "base64_encoded_image_data",
    "image_format": "jpeg"
  }
}
```

### 在 Cherry Studio 中使用

1. 确保 MCP 服务器已正确配置
2. 在对话中使用工具调用：

```
请分析这张图片中人物的表情：/path/to/image.jpg
```

Cherry Studio 会自动调用 `analyze_emotion` 工具并显示分析结果。

### 输出格式

分析结果包含以下信息：

```
表情分析结果：

📸 图像: /path/to/image.jpg
😊 主要表情: 快乐
📊 表情强度: 8/10
🎯 置信度: 0.90
👤 面部特征: 眼角上扬，嘴角微笑，面部肌肉放松
💭 情绪状态: 积极愉悦的情绪状态
📝 其他观察: 表情自然真实

原始JSON结果:
{
  "success": true,
  "image_path": "/path/to/image.jpg",
  "analysis": {
    "emotion": "快乐",
    "intensity": 8,
    "confidence": 0.9,
    "facial_features": "眼角上扬，嘴角微笑，面部肌肉放松",
    "emotional_state": "积极愉悦的情绪状态",
    "additional_notes": "表情自然真实"
  }
}
```

## 支持的图像格式

- JPEG (.jpg, .jpeg)
- PNG (.png)
- GIF (.gif)
- BMP (.bmp)
- WebP (.webp)

## 故障排除

### 常见问题

1. **API 密钥错误**
   - 确保 `OPENROUTER_API_KEY` 环境变量已正确设置
   - 验证 API 密钥是否有效

2. **图像文件不存在**
   - 检查图像文件路径是否正确
   - 确保文件存在且可读

3. **网络连接问题**
   - 确保网络连接正常
   - 检查防火墙设置

4. **MCP 服务器无法启动**
   - 检查 Python 环境和依赖是否正确安装
   - 查看错误日志获取详细信息

### 调试模式

设置环境变量启用调试模式：

```bash
export DEBUG=1
emotion-analyzer-mcp
```

## 开发

### 本地开发

1. 克隆仓库：
```bash
git clone https://github.com/yourusername/emotion-analyzer-mcp.git
cd emotion-analyzer-mcp
```

2. 安装开发依赖：
```bash
pip install -e ".[dev]"
```

3. 运行测试：
```bash
pytest
```

### 贡献

欢迎提交 Issue 和 Pull Request！

## 许可证

MIT License

## 更新日志

### v1.0.0
- 初始版本
- 支持基本表情分析功能
- 支持文件路径和 base64 输入
- 完整的 MCP 协议支持