dujiepeng/easemob-mcp-server

环信IM MCP服务器 - 完整版

这是一个完整集成了环信即时通讯(Easemob IM) RESTful API的MCP (Model Context Protocol) 服务器。涵盖环信IM的所有主要功能，包括用户管理、消息管理、群组管理、聊天室管理、好友关系、黑名单管理、用户属性管理、文件管理等。

🚀 功能特性

✅ 用户管理系统

• 用户操作: 注册单个/批量用户、获取用户信息、删除用户
• 用户状态: 获取在线状态、强制下线、修改密码
• 用户属性: 设置/获取/删除用户自定义属性

✅ 消息管理系统

• 消息发送: 支持文本、图片、语音、视频、文件、位置、透传、自定义消息
• 消息操作: 消息撤回、历史消息查询
• 消息类型: 单聊、群聊、聊天室消息全覆盖

✅ 群组管理系统

• 群组操作: 创建、获取、修改、删除群组
• 成员管理: 添加/移除成员、获取成员列表、转让群主
• 权限管理: 管理员设置、群主转让
• 黑白名单: 群组黑名单、白名单管理
• 禁言管理: 单个/批量/全体禁言和解禁

✅ 聊天室管理系统

• 聊天室操作: 创建、获取、修改、删除聊天室
• 成员管理: 添加/移除成员、管理员设置
• 权限控制: 黑白名单、禁言管理
• 公告管理: 设置和修改聊天室公告

✅ 用户关系管理

• 好友系统: 添加/删除好友、获取好友列表
• 黑名单: 添加/移除黑名单、查看黑名单

✅ 文件管理系统

• 文件操作: 文件上传、下载
• 文件类型: 支持图片、语音、视频、文档等各种文件类型

✅ 高级特性

• 自动认证: 智能Token管理和自动刷新
• 错误处理: 完善的错误处理和中文错误信息
• API覆盖: 涵盖环信IM REST API的所有主要功能
• 类型安全: 完整的TypeScript类型定义

📖 环信文档参考

本项目基于环信即时通讯 REST API 开发，详细API文档请参考：

• 环信IM REST API概览
• 用户管理
• 消息管理
• 群组管理
• 聊天室管理

🛠 快速开始

1. 安装依赖

npm install

2. 配置环信应用信息

复制环境变量示例文件：

cp env.example .env

编辑 .env 文件，填入您的环信应用配置信息：

# 环信应用配置 - 在环信控制台获取
EASEMOB_ORG_NAME=your_org_name
EASEMOB_APP_NAME=your_app_name  
EASEMOB_APP_KEY=your_app_key
EASEMOB_APP_SECRET=your_app_secret

# 可选：自定义API域名（默认使用 https://a1.easemob.com）
# EASEMOB_BASE_URL=https://a1.easemob.com

获取配置信息：

1. 登录环信开发者控制台
2. 选择您的应用
3. 在"应用概览"页面获取所需配置信息

3. 编译和启动

# 编译项目
npm run build

# 开发模式启动
npm run dev

# 生产模式启动  
npm start

🔧 完整API功能列表

📱 用户管理API

💬 消息管理API

📁 文件管理API

👥 用户关系API

🏷 用户属性API

👥 群组管理API

👨‍👩‍👧‍👦 群组成员API

🚫 群组黑白名单API

🔇 群组禁言API

🏠 聊天室管理API

👨‍👩‍👧‍👦 聊天室成员API

🚫 聊天室黑白名单API

🔇 聊天室禁言API

📢 聊天室公告API

📝 使用示例

用户管理示例

// 创建用户
await easemobAPI.createUser({
  username: "testuser001",
  password: "123456", 
  nickname: "测试用户"
});

// 获取用户状态
await easemobAPI.getUserStatus("testuser001");

消息发送示例

// 发送文本消息
await easemobAPI.sendMessage({
  target_type: "users",
  target: ["testuser001"],
  msg: {
    type: "txt",
    msg: "你好，这是一条测试消息！"
  }
});

// 发送图片消息
await easemobAPI.sendMessage({
  target_type: "users", 
  target: ["testuser001"],
  msg: {
    type: "img",
    url: "https://example.com/image.jpg",
    filename: "image.jpg",
    size: 12345
  }
});

群组管理示例

// 创建群组
const group = await easemobAPI.createGroup({
  groupname: "测试群组",
  desc: "这是一个测试群组",
  owner: "testuser001",
  public: true,
  maxusers: 200,
  members: ["testuser002", "testuser003"]
});

// 添加群组成员
await easemobAPI.addGroupMembers(group.data.groupid, ["testuser004", "testuser005"]);

// 设置群组管理员
await easemobAPI.addGroupAdmin(group.data.groupid, "testuser002");

聊天室管理示例

// 创建聊天室
const chatroom = await easemobAPI.createChatroom({
  name: "测试聊天室",
  description: "这是一个测试聊天室",
  owner: "testuser001",
  maxusers: 1000
});

// 设置聊天室公告
await easemobAPI.updateChatroomAnnouncement(chatroom.data.id, "欢迎来到测试聊天室！");

🏗 项目结构

├── src/
│   ├── index.ts          # MCP服务器主文件
│   └── easemob-api.ts    # 完整环信API封装类
├── dist/                 # 编译输出目录
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript配置
├── .env                  # 环境变量（需要创建）
├── env.example           # 环境变量示例
├── mcp-config.json       # MCP客户端配置示例
├── .gitignore           # Git忽略文件
└── README.md             # 项目文档

⚙️ 环境变量说明

🛡️ 错误处理

项目包含完善的错误处理机制：

• 网络错误: 自动重试和超时处理（30秒超时）
• 认证错误: 自动刷新App Token，提前1分钟预刷新
• 参数错误: 详细的参数验证和错误信息
• API错误: 友好的中文错误信息，包含详细错误描述

⚠️ 注意事项

1. API频率限制: 请注意环信API的调用频率限制
2. Token管理: 系统会自动管理App Token的刷新，无需手动处理
3. 数据中心: 请根据您的应用所在数据中心配置正确的API域名
4. 安全性: 请妥善保管您的App Secret，不要泄露给第三方
5. 消息类型: 支持文本、图片、语音、视频、文件、位置、透传、自定义等所有消息类型
6. 并发处理: 建议使用连接池来优化并发请求性能

📄 许可证

MIT License

🤝 贡献

欢迎提交Issue和Pull Request来改进这个项目！如果您需要特定的功能或发现了bug，请随时联系我们。

这是一个功能完整的环信IM MCP服务器，涵盖了环信即时通讯的所有主要API功能，可以满足您的各种IM开发需求！ 🎉