Metadata-Version: 2.4
Name: scrm-mcp-xyt
Version: 1.0.0
Summary: MCP Server for SCRM (xyt) Integration
Author-email: SCRM MCP Team <scrm@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/your-org/scrm-mcp-xyt
Project-URL: Issues, https://github.com/your-org/scrm-mcp-xyt/issues
Keywords: scrm,xyt,mcp,server
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=0.1.1
Requires-Dist: requests>=2.31.0
Requires-Dist: httpx>=0.24.0
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# SCRM MCP Server

基于 xyt SCRM 系统的 MCP 服务，为 AI 助手提供企业微信数据访问能力。

## 功能特性

### 会话存档

- ✅ 会话消息查询和搜索
- ✅ 支持单聊、群聊、内外部联系人会话
- ✅ 全文检索功能
- ✅ 会话权限管理

### 企微基础数据（已同步到 SCRM）

- ✅ **员工列表查询** - 获取企微员工信息和 weUserId
- ✅ **部门列表查询** - 获取组织架构
- ✅ **客户列表/搜索** - 外部联系人搜索和列表
- ✅ **客户详情/画像** - 客户完整档案、标签、跟进状态
- ✅ **客户标签管理** - 标签组和标签列表
- ✅ **客户群管理** - 群列表、群详情、群成员
- ✅ **跟进记录查询** - 销售跟进历史
- ✅ **客户轨迹查询** - 互动行为轨迹
- ✅ **企业动态查询** - 全公司客户活动流
- ✅ **离职员工管理** - 离职员工列表
- ✅ **任务管理** - 待办/历史任务

### 复合场景查询

- ✅ 通过客户姓名直接获取消息（支持时间筛选）
- ✅ **通过客户姓名获取完整档案**（含详情+跟进+轨迹）
- ✅ **通过员工姓名获取其跟进数据**
- ✅ 获取群聊时间范围内的消息
- ✅ 通过成员名称搜索群会话记录

## 快速开始

### 1. 安装 Python 3.10+

确保已安装 Python 3.10 或更高版本。

### 2. 克隆并安装项目

```bash
cd scrm-mcp-xyt
pip install -e .
```

### 3. 配置 SCRM 连接

创建 `scrm_config.json` 配置文件：

```json
{
  "base_url": "http://your-scrm-gateway:8080",
  "access_key": "your-access-key",
  "secret_key": "your-secret-key-md5-encrypted"
}
```

**说明**：

- `access_key`: 从 SCRM 系统生成的 Access Key
- `secret_key`: Secret Key 的 MD5 加密值（32 位小写）
- AK/SK 认证无需验证码，适合自动化场景

或者使用环境变量：

```bash
export SCRM_URL="http://your-scrm-gateway:8080"
export SCRM_ACCESS_KEY="your-access-key"
export SCRM_SECRET_KEY="your-secret-key-md5"
```

### 4. 运行服务器

```bash
python run_server.py
```

或使用命令行入口：

```bash
scrm-mcp-xyt
```

### 5. 在 Claude Desktop 中配置

编辑 Claude Desktop 配置文件 (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "scrm-mcp-xyt": {
      "command": "python",
      "args": ["/path/to/scrm-mcp-xyt/run_server.py"],
      "env": {
        "SCRM_URL": "http://your-scrm-gateway:8080",
        "SCRM_ACCESS_KEY": "your-access-key",
        "SCRM_SECRET_KEY": "your-secret-key-md5"
      }
    }
  }
}
```

## 可用的 MCP Tools

### 会话消息查询

1. **get_chat_messages** - 获取会话消息列表
   - 参数：
     - `from_id` (可选): 发送者 ID
     - `start_time` (可选): 开始时间
     - `end_time` (可选): 结束时间
     - `page_num`: 页码 (默认 1)
     - `page_size`: 每页大小 (默认 10)

2. **get_chat_detail** - 获取消息详细信息
   - 参数：
     - `msg_id`: 消息 ID

3. **search_messages** - 全文检索消息
   - 参数：
     - `keyword`: 搜索关键词
     - `msg_type` (可选): 消息类型
     - `start_time` (可选): 开始时间
     - `end_time` (可选): 结束时间
     - `page_num`: 页码
     - `page_size`: 每页大小

### 会话列表查询

4. **get_external_chat_list** - 获取外部联系人会话
   - 参数：
     - `from_id`: 外部联系人 ID
     - `page_num`: 页码
     - `page_size`: 每页大小

5. **get_internal_chat_list** - 获取内部用户会话
   - 参数：
     - `from_id`: 内部用户 ID
     - `page_num`: 页码
     - `page_size`: 每页大小

6. **get_group_chat_list** - 获取群聊会话
   - 参数：
     - `from_id`: 群聊 ID 或用户 ID
     - `page_num`: 页码
     - `page_size`: 每页大小

7. **get_alone_chat_list** - 获取单聊会话
   - 参数：
     - `page_num`: 页码
     - `page_size`: 每页大小

### 权限和信息查询

8. **get_permit_user_list** - 获取有权限的用户列表

9. **check_single_agree** - 检查单聊同意情况
   - 参数：
     - `user_ids`: 用户 ID 列表

10. **check_room_agree** - 检查群聊同意情况
    - 参数：
      - `room_id`: 群聊房间 ID

11. **get_group_chat_info** - 获取群聊信息
    - 参数：
      - `room_id`: 群聊房间 ID

12. **get_current_time** - 获取当前时间

### 客户管理 (新增)

13. **search_customers_by_name** - 通过名称搜索客户
    - 参数：
      - `name`: 客户姓名关键词（支持模糊匹配）
      - `page_num`: 页码 (默认 1)
      - `page_size`: 每页大小 (默认 10)

14. **list_all_customers** - 获取所有客户列表
    - 参数：
      - `page_num`: 页码 (默认 1)
      - `page_size`: 每页大小 (默认 20)

### 群聊管理 (新增)

15. **search_groups_by_name** - 通过名称搜索群聊
    - 参数：
      - `name`: 群名称关键词（支持模糊匹配）
      - `page_num`: 页码 (默认 1)
      - `page_size`: 每页大小 (默认 10)

16. **list_all_groups** - 获取所有群聊列表
    - 参数：
      - `page_num`: 页码 (默认 1)
      - `page_size`: 每页大小 (默认 20)

17. **get_group_members_list** - 获取群成员列表
    - 参数：
      - `chat_id`: 群聊 ID

### 复合场景查询 (新增)

18. **get_customer_messages_by_name** - 通过客户姓名获取消息
    - 参数：
      - `customer_name`: 客户姓名
      - `start_time` (可选): 开始时间 (格式: YYYY-MM-DD HH:MM:SS)
      - `end_time` (可选): 结束时间 (格式: YYYY-MM-DD HH:MM:SS)
      - `page_num`: 页码 (默认 1)
      - `page_size`: 每页大小 (默认 50)
    - 功能：自动搜索客户 → 获取消息 → 时间过滤

19. **get_group_messages_with_time** - 获取群聊时间范围内的消息
    - 参数：
      - `group_id`: 群聊 ID
      - `start_time` (可选): 开始时间
      - `end_time` (可选): 结束时间
      - `member_id` (可选): 成员 ID（筛选特定成员）
      - `page_num`: 页码 (默认 1)
      - `page_size`: 每页大小 (默认 50)

20. **search_member_group_messages** - 通过成员名称搜索群会话
    - 参数：
      - `member_name`: 群成员名称
      - `group_name` (可选): 群名称（限定在特定群内搜索）
      - `start_time` (可选): 开始时间
      - `end_time` (可选): 结束时间
      - `page_num`: 页码 (默认 1)
      - `page_size`: 每页大小 (默认 50)
    - 功能：自动搜索成员 → 搜索群聊 → 获取消息 → 过滤

## MCP Resources

- **scrm://config** - 获取 SCRM 系统配置信息

## 使用示例

在 Claude Desktop 或其他支持 MCP 的 AI 助手中，你可以直接使用自然语言询问：

### 基础查询

- "帮我查询最近的会话记录"
- "搜索包含'合同'关键词的消息"
- "查看某个外部联系人的聊天记录"
- "获取某个群聊的详细信息"

### 场景化查询 (新增功能)

#### 场景 1：客户消息查询

```
问：查询客户"郝彦飞"发给我的所有消息

AI 会自动：
1. 搜索客户"郝彦飞"
2. 获取该客户的消息列表
3. 展示消息内容

追加查询：
问：只看最近7天的消息
```

#### 场景 2：群聊分析

```
问：查看群聊"新优态AI-测试2"的群成员和最近的聊天记录

AI 会自动：
1. 搜索群聊"新优态AI-测试2"
2. 获取群成员列表
3. 获取群内消息记录
```

#### 场景 3：获取群聊列表

```
问：给我看看所有的群聊

AI 会返回：
- 群聊名称列表
- 群ID
- 群主信息
```

#### 场景 4：获取客户列表

```
问：显示所有客户

AI 会返回：
- 客户姓名列表
- 客户类型
- 添加时间等
```

#### 场景 5：特定群聊的成员

```
问：查看"新优态AI-测试群"的所有成员

AI 会自动：
1. 搜索群聊
2. 获取成员列表
3. 展示成员详情
```

#### 场景 6：通过名称搜索群聊

```
问：搜索包含"AI"的群聊

AI 会返回：
- 所有名称包含"AI"的群聊列表
```

#### 场景 7：成员的群聊记录

```
问：查找"张三"在群里的所有发言

AI 会自动：
1. 搜索成员"张三"
2. 获取他的群消息
3. 支持指定时间范围和特定群聊
```

## 架构说明

本项目采用以下架构：

```
scrm-mcp-xyt/
├── src/scrm_mcp/
│   ├── __init__.py          # 包初始化
│   ├── __main__.py          # 命令行入口
│   ├── server.py            # MCP 服务器实现
│   └── scrm_client.py       # SCRM REST API 客户端
├── scrm_config.json         # 配置文件
├── run_server.py            # 独立运行脚本
└── pyproject.toml           # 项目配置
```

### 核心组件

1. **scrm_client.py**: REST API 客户端
   - 实现 JWT 认证
   - 封装所有会话存档 API
   - 自动处理 Token 刷新

2. **server.py**: MCP 服务器
   - 定义所有 MCP Tools
   - 数据模型和类型安全
   - 错误处理和响应格式化

## 依赖项

- Python >= 3.10
- mcp >= 0.1.1
- requests >= 2.31.0
- httpx >= 0.24.0

## 开发

### 安装开发依赖

```bash
pip install -e ".[dev]"
```

### 代码格式化

```bash
black src/
isort src/
```

### 类型检查

```bash
mypy src/
```

## 许可证

MIT License

## 相关链接

- [MCP 协议文档](https://modelcontextprotocol.io/)
- [xyt GitHub](https://github.com/qwdigital/xyt)

## 贡献

欢迎提交 Issue 和 Pull Request！
