# 微信聊天数据存储系统 (Chat MCP)

基于 Node.js + PostgreSQL 的微信聊天数据存储解决方案，支持批量写入好友信息、群信息、群成员信息和对话记录。

## 特性

- 🚀 **高性能批量写入** - 支持批量操作，提升数据写入效率
- 💾 **完整数据模型** - 涵盖好友、群组、群成员、聊天消息等完整数据结构
- 🔄 **事务支持** - 确保数据一致性和完整性
- 🛡️ **数据验证** - 内置数据验证机制，保证数据质量
- 📦 **ES Module** - 使用现代 JavaScript 模块系统
- 🔍 **MCP高级查询** - 提供强大的搜索、分析和统计功能
- 📊 **智能分析** - 支持关系分析、活动分析、内容分析等
- 🎯 **快速查找** - 智能匹配和快速定位功能
- 💾 **数据导出** - 支持多种格式的数据导出
- 🤖 **标准MCP服务** - 基于 Model Context Protocol 的标准服务器
- 🔌 **AI模型集成** - 可与 Claude Desktop 等AI客户端无缝集成
- 🌐 **多种传输协议** - 支持 Stdio、SSE 和最新的 Streamable HTTP
- ⚡ **Streamable HTTP** - 最新的 MCP 传输协议，性能更优，兼容性更好
- 🚀 **Agent友好** - 提供多种接口供其他 agent 直接调用

## 项目结构

```
chat-mcp/
├── src/
│   ├── config/
│   │   └── database.js          # 数据库配置
│   ├── models/
│   │   ├── Friend.js            # 好友模型
│   │   ├── Group.js             # 群组模型
│   │   ├── GroupMember.js       # 群成员模型
│   │   ├── ChatMessage.js       # 聊天消息模型
│   │   └── index.js             # 模型导出
│   ├── services/
│   │   ├── ChatDataService.js   # 核心业务服务
│   │   ├── McpService.js        # MCP高级查询服务
│   │   └── McpTools.js          # MCP分析工具集
│   ├── mcp/
│   │   ├── schemas.js           # MCP数据验证模式
│   │   ├── server.js            # MCP服务器实现
│   │   ├── sse-server.js        # HTTP API服务器实现
│   │   ├── README.md            # MCP服务文档
│   │   └── http-api.md          # HTTP API文档
│   ├── scripts/
│   │   └── migrate.js           # 数据库迁移脚本
│   └── index.js                 # 主入口文件
├── example.js                   # 基础功能示例
├── example-mcp.js               # MCP功能示例
├── api-examples.js              # HTTP API示例
├── mcp-server.js                # MCP服务器入口
├── http-server.js               # HTTP服务器入口
├── mcp-config.json              # MCP配置示例
├── test-mcp.js                  # MCP测试文件
├── package.json
└── README.md
```

## 安装依赖

```bash
npm install
```

## 数据库配置

1. 确保已安装 PostgreSQL
2. 创建数据库（例如：`chat_mcp`）
3. 配置环境变量或修改 `src/config/database.js` 中的默认配置：

```javascript
const dbConfig = {
  host: 'localhost',
  port: 5432,
  database: 'chat_mcp',
  username: 'postgres',
  password: 'your_password'
};
```

## 初始化数据库

```bash
npm run db:migrate
```

## 使用方法

### 基础使用

```javascript
import ChatMCP from './src/index.js';

// 创建实例
const chatMCP = new ChatMCP();

// 初始化系统
await chatMCP.init();
```

### 批量写入好友信息

```javascript
const friendsData = [
  {
    robotId: 'robot_001',
    wxid: 'friend_001',
    wxNumber: 'friend001',
    name: '张三',
    avatar: 'https://example.com/avatar1.jpg',
    alias: '小张',
    remark: '同事',
    tags: '工作'
  },
  {
    robotId: 'robot_001',
    wxid: 'friend_002',
    name: '李四',
    remark: '朋友'
  }
];

const result = await chatMCP.batchCreateFriends(friendsData);
console.log(`成功写入 ${result.length} 条好友记录`);
```

### 批量写入群信息

```javascript
const groupsData = [
  {
    robotId: 'robot_001',
    wxid: 'group_001',
    adminId: 'admin_001',
    name: '技术交流群',
    avatar: 'https://example.com/group1.jpg',
    memberCount: 50
  }
];

await chatMCP.batchCreateGroups(groupsData);
```

### 批量写入群成员信息

```javascript
const membersData = [
  {
    robotId: 'robot_001',
    roomWxid: 'group_001',  // 关联群的wxid
    wxid: 'member_001',
    name: '群成员1',
    alias: '成员A',
    remark: '活跃成员'
  }
];

await chatMCP.batchCreateGroupMembers(membersData);
```

### 写入对话记录

```javascript
// 单条消息
const messageData = {
  robotId: 'robot_001',
  robotName: '智能助手',
  conversationId: 'friend_001',
  conversationName: '张三',
  recordType: 'contact',  // 'contact' 私聊, 'room' 群聊
  chatUserId: 'friend_001',
  chatUserName: '张三',
  content: '你好，最近怎么样？',
  contentType: '文字',
  timestamp: Date.now()
};

await chatMCP.createChatMessage(messageData);

// 批量消息
const messagesData = [
  {
    robotId: 'robot_001',
    conversationId: 'group_001',
    recordType: 'room',
    chatUserId: 'member_001',
    content: '大家好！',
    timestamp: Date.now()
  }
];

await chatMCP.createChatMessage(messagesData);
```

### 事务批量写入所有数据

```javascript
const allData = {
  friends: friendsData,
  groups: groupsData,
  groupMembers: membersData,
  messages: messagesData
};

const results = await chatMCP.batchCreateAllData(allData);
console.log('批量写入结果:', results);
```

### 查询数据

```javascript
// 查询好友列表
const friends = await chatMCP.getFriends('robot_001');

// 查询群组列表（包含成员信息）
const groups = await chatMCP.getGroups('robot_001');

// 查询聊天记录
const messages = await chatMCP.getChatMessages({
  robotId: 'robot_001',
  conversationId: 'friend_001',
  limit: 50
});
```

## MCP 高级查询功能

### 高级搜索

```javascript
// 搜索好友
const friendResults = await chatMCP.searchFriends({
  robotId: 'robot_001',
  keyword: '张三',
  tags: '同事',
  limit: 20
});

// 搜索群组
const groupResults = await chatMCP.searchGroups({
  robotId: 'robot_001',
  keyword: '技术',
  minMemberCount: 10,
  includeMembers: true
});

// 搜索聊天消息
const messageResults = await chatMCP.searchChatMessages({
  robotId: 'robot_001',
  keyword: '会议',
  contentType: '文字',
  startTime: Date.now() - 86400000, // 24小时内
  endTime: Date.now()
});

// 全文搜索
const fullResults = await chatMCP.fullTextSearch({
  robotId: 'robot_001',
  keyword: '项目',
  searchTypes: ['friends', 'groups', 'messages']
});
```

### 统计分析

```javascript
// 获取机器人统计信息
const stats = await chatMCP.getRobotStatistics('robot_001');
console.log('好友数量:', stats.statistics.friendCount);
console.log('群组数量:', stats.statistics.groupCount);
console.log('今日消息:', stats.statistics.todayMessageCount);

// 获取会话详细信息
const conversationDetails = await chatMCP.getConversationDetails({
  robotId: 'robot_001',
  conversationId: 'friend_001'
});

// 获取群组成员详细信息
const groupMembersDetail = await chatMCP.getGroupMembersDetail({
  robotId: 'robot_001',
  roomWxid: 'group_001',
  includeMessageStats: true
});

// 获取消息热力图数据
const heatmapData = await chatMCP.getMessageHeatmap({
  robotId: 'robot_001',
  conversationId: 'friend_001',
  granularity: 'hour' // hour, day, week, month
});
```

### 智能分析工具

```javascript
// 快速查找
const quickResult = await chatMCP.quickFind({
  robotId: 'robot_001',
  query: '张三',
  type: 'auto' // auto, friend, group, member
});

// 关系分析
const relationships = await chatMCP.analyzeRelationships({
  robotId: 'robot_001',
  userId: 'friend_001',
  analysisType: 'comprehensive'
});

// 活动分析
const activity = await chatMCP.analyzeActivity({
  robotId: 'robot_001',
  targetId: 'friend_001',
  timeRange: 30, // 天数
  granularity: 'day'
});

// 内容分析
const content = await chatMCP.analyzeContent({
  robotId: 'robot_001',
  conversationId: 'friend_001',
  timeRange: 30,
  analysisTypes: ['contentType', 'keywords', 'sentiment']
});

// 数据导出
const exportResult = await chatMCP.exportData({
  robotId: 'robot_001',
  exportType: 'messages', // messages, friends, groups, statistics
  format: 'json', // json, csv, txt
  timeRange: 30
});
```

### 系统信息查询

```javascript
// 获取系统信息
const systemInfo = await chatMCP.getSystemInfo();
console.log('数据库状态:', systemInfo.database.status);
console.log('总消息数:', systemInfo.statistics.totalMessages);
```

## MCP 服务器集成

本项目提供了标准的 MCP (Model Context Protocol) 服务器，可以与支持 MCP 的 AI 客户端（如 Claude Desktop）无缝集成。

### 启动 MCP 服务器

```bash
# 启动 MCP 服务器
npm run mcp:server

# 或直接运行
node mcp-server.js
```

### 配置 AI 客户端

#### Claude Desktop 配置

在 Claude Desktop 的配置文件中添加以下配置：

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "chat-mcp": {
      "command": "node",
      "args": ["/path/to/your/project/mcp-server.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

### 可用 MCP 工具

#### 查询工具
- `search_friends` - 搜索好友信息
- `search_groups` - 搜索群组信息
- `search_messages` - 搜索聊天消息
- `full_text_search` - 全文搜索
- `get_robot_statistics` - 获取统计信息
- `get_conversation_details` - 获取会话详情
- `get_system_info` - 获取系统信息

#### 分析工具
- `quick_find` - 快速查找工具
- `analyze_relationships` - 关系分析
- `analyze_activity` - 活动分析
- `analyze_content` - 内容分析
- `export_data` - 数据导出

#### 数据写入工具
- `batch_create_friends` - 批量创建好友
- `batch_create_groups` - 批量创建群组
- `batch_create_group_members` - 批量创建群成员
- `create_chat_message` - 创建聊天消息

### MCP 使用示例

配置完成后，您可以在 Claude Desktop 中直接使用自然语言来操作微信聊天数据：

- "帮我搜索名字包含'张三'的好友"
- "获取机器人robot_001的统计信息"  
- "分析用户friend_001的活动模式"
- "导出最近30天的聊天记录为JSON格式"

详细的 MCP 配置和使用说明请参考：[src/mcp/README.md](src/mcp/README.md)

## 🆕 Streamable HTTP 服务器 (推荐)

基于最新 **MCP Streamable HTTP 传输协议** 的服务器，替代了 SSE 传输方式，具有更好的性能和兼容性。

### 主要优势

- ⚡ **更高性能**: 无长连接开销，标准 HTTP 请求/响应
- 🌐 **更好兼容性**: 更好的防火墙、代理和移动网络支持  
- 🔄 **灵活模式**: 支持有状态和无状态两种模式
- 📱 **移动友好**: 更适合移动设备和不稳定网络
- 🔧 **易于调试**: 可使用标准 HTTP 工具调试

### 启动 Streamable HTTP 服务器

```bash
# 有状态模式（默认，支持会话管理）
npm run streamable:server

# 无状态模式（每个请求独立，更高性能）
npm run streamable:server:stateless

# 开发模式（自动重启）
npm run streamable:server:dev

# 自定义选项
node streamable-server.js 3001 --stateless --no-cors
```

### Streamable HTTP API 端点

- **MCP 端点**: `POST http://localhost:3001/mcp`
- **健康检查**: `GET http://localhost:3001/health`
- **服务信息**: `GET http://localhost:3001/`
- **删除会话**: `DELETE http://localhost:3001/mcp` (仅有状态模式)

### 使用示例

#### 原生 JavaScript

```javascript
// 初始化会话
const initResponse = await fetch('http://localhost:3001/mcp', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'Accept': 'application/json, text/event-stream'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'initialize',
    params: {
      protocolVersion: '2025-06-18',
      capabilities: { tools: {} },
      clientInfo: { name: 'my-app', version: '1.0.0' }
    },
    id: 1
  })
});

const sessionId = initResponse.headers.get('Mcp-Session-Id');

// 调用工具
const toolResponse = await fetch('http://localhost:3001/mcp', {
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'Mcp-Session-Id': sessionId 
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'tools/call',
    params: {
      name: 'search_friends',
      arguments: { robotId: 'robot_001', keyword: '张三' }
    },
    id: 2
  })
});
```

#### cURL

```bash
# 初始化会话
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{"tools":{}},"clientInfo":{"name":"curl-client","version":"1.0.0"}},"id":1}'

# 调用工具（使用返回的会话ID）
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"search_friends","arguments":{"robotId":"robot_001","keyword":"张三"}},"id":2}'
```

### 运行示例

```bash
# 运行完整的 Streamable HTTP 示例
npm run streamable:examples

# 测试服务器功能
npm run test:streamable
```

详细的 Streamable HTTP 文档请参考：[src/mcp/streamable-http.md](src/mcp/streamable-http.md)

## HTTP API 服务器 (传统 SSE)

除了标准的 MCP 协议，本项目还提供了基于 Express 和 SSE 的 HTTP API 服务器，让其他 agent 可以通过标准 HTTP 接口调用 MCP 服务。

### 启动 HTTP 服务器

```bash
# 启动 HTTP 服务器（默认端口 3001）
npm run http:server

# 指定端口启动
node http-server.js 3001

# 开发模式（自动重启）
npm run http:server:dev
```

### HTTP API 端点

- **服务地址**: `http://localhost:3001`
- **API 文档**: `http://localhost:3001/api/docs`
- **健康检查**: `http://localhost:3001/health`
- **工具列表**: `http://localhost:3001/api/tools`
- **SSE 端点**: `http://localhost:3001/sse`

### API 使用示例

#### 搜索好友
```bash
curl -X POST http://localhost:3001/api/tools/search_friends \
  -H "Content-Type: application/json" \
  -d '{"robotId": "robot_001", "keyword": "张三", "limit": 10}'
```

#### 批量创建好友
```bash
curl -X POST http://localhost:3001/api/tools/batch_create_friends \
  -H "Content-Type: application/json" \
  -d '{
    "robotId": "robot_001",
    "friends": [
      {
        "robotId": "robot_001",
        "wxid": "friend_001",
        "name": "张三",
        "remark": "同事"
      }
    ],
    "updateOnDuplicate": true
  }'
```

#### 获取统计信息
```bash
curl -X POST http://localhost:3001/api/tools/get_robot_statistics \
  -H "Content-Type: application/json" \
  -d '{"robotId": "robot_001"}'
```

### Agent 集成示例

```python
import requests

class WeChatDataAgent:
    def __init__(self, base_url="http://localhost:3001"):
        self.base_url = base_url
    
    def search_friends(self, robot_id, keyword):
        response = requests.post(f"{self.base_url}/api/tools/search_friends", 
            json={"robotId": robot_id, "keyword": keyword}
        )
        return response.json()["data"]
    
    def create_friends(self, robot_id, friends_data):
        response = requests.post(f"{self.base_url}/api/tools/batch_create_friends",
            json={"robotId": robot_id, "friends": friends_data}
        )
        return response.json()["data"]
```

### 运行示例

```bash
# 运行完整的 API 使用示例
npm run api:examples
```

详细的 HTTP API 文档请参考：[src/mcp/http-api.md](src/mcp/http-api.md)

## 数据模型说明

### 好友信息 (Friends)
- `robotId`: 机器人账号ID
- `wxid`: 好友微信ID
- `wxNumber`: 好友微信号
- `name`: 昵称
- `avatar`: 头像URL
- `alias`: 别名
- `remark`: 备注
- `tags`: 标签

### 群信息 (Groups)
- `robotId`: 机器人账号ID
- `wxid`: 群微信ID
- `adminId`: 群管理员微信ID
- `name`: 群名
- `avatar`: 群头像URL
- `memberCount`: 群成员数

### 群成员信息 (GroupMembers)
- `robotId`: 机器人账号ID
- `roomWxid`: 群微信ID（外键关联群信息）
- `wxid`: 群成员微信ID
- `wxNumber`: 群成员微信号
- `name`: 群成员昵称
- `avatar`: 群成员头像URL
- `alias`: 群成员别名
- `remark`: 群成员备注

### 聊天消息 (ChatMessages)
- `robotId`: 机器人账号ID
- `conversationId`: 会话ID
- `recordType`: 记录类型（contact/room）
- `content`: 聊天内容
- `contentType`: 内容类型（文字/图片/文件等）
- `timestamp`: 时间戳
- 更多字段请参考模型定义

## 脚本命令

```bash
# 启动服务
npm start

# 开发模式（自动重启）
npm run dev

# 数据库迁移
npm run db:migrate

# 运行基础功能示例
npm run example

# 运行MCP功能示例
npm run example:mcp

# 启动标准MCP服务器 (Stdio)
npm run mcp:server

# 启动Streamable HTTP服务器 (推荐)
npm run streamable:server

# 启动传统HTTP API服务器 (SSE)
npm run http:server

# 运行各种示例
npm run api:examples        # HTTP API示例
npm run streamable:examples # Streamable HTTP示例
```

## 配置选项

### 批量写入配置

```javascript
const options = {
  updateOnDuplicate: true  // 是否更新重复记录，默认 true
};

await chatMCP.batchCreateFriends(friendsData, options);
```

## 错误处理

系统内置了完善的错误处理机制：

```javascript
try {
  await chatMCP.batchCreateFriends(friendsData);
} catch (error) {
  console.error('写入失败:', error.message);
  // 处理错误
}
```

## MCP 功能详解

### 搜索功能
- **关键词搜索**: 支持模糊匹配姓名、备注、别名等字段
- **标签搜索**: 支持按标签筛选好友
- **时间范围搜索**: 支持按时间范围搜索聊天记录
- **内容类型搜索**: 支持按消息类型筛选（文字、图片、文件等）

### 分析功能
- **关系分析**: 分析用户间的关系网络，包括直接好友、共同群组等
- **活动分析**: 分析用户或群组的活动模式和频率
- **内容分析**: 分析消息内容，包括关键词提取、情感分析等
- **热力图分析**: 生成基于时间的消息活动热力图

### 工具功能
- **快速查找**: 智能识别查询类型，快速定位目标
- **数据导出**: 支持JSON、CSV、TXT等多种格式导出
- **系统监控**: 实时监控数据库状态和系统性能

## 注意事项

1. 确保 PostgreSQL 服务已启动
2. 配置正确的数据库连接信息
3. robotId 和 wxid 的组合在各表中具有唯一性约束
4. 群成员的 roomWxid 必须与群信息的 wxid 对应
5. 聊天消息的 timestamp 字段为必填项
6. MCP 功能需要一定的数据量才能展现最佳效果
7. 复杂查询可能需要较长时间，建议合理设置超时和限制

## 许可证

MIT License