JinDaGe - wweb-mcp MCP Details

article

README

🚀 WhatsApp Web 机器人框架

WhatsApp Web 机器人框架是一款强大的工具，可用于控制 WhatsApp 账号，实现消息的收发。它基于 whatsapp-web.js，通过浏览器版 WhatsApp 进行连接。

🚀 快速开始

安装依赖项

项目使用 npm 包管理器进行依赖管理和运行时环境配置。安装所有依赖项：

npm install

使用 Docker

为了方便部署，项目提供了 Docker 镜像。拉取镜像并启动：

docker pull liuhuanjin0927/whatsapp-web-mcp:latest
docker run -it --rm liuhuanjin0927/whatsapp-web-mcp

快速上手

在 main.ts 文件中，你可以看到一个简单的运行示例：

import { WhatsApp } from 'whatsapp-web.js';
import * as WAProto from '@whatsprotypes/core';

async function run() {
    const WA = new WhatsApp({
        puppeteer: {
            executablePath: process.env.CHROME_PATH || undefined,
            args: ['--no-sandbox']
        },
        logLevel: 'info'
    });

    await WA.start();
    console.log('WhatsApp 已启动');
}

run().catch(console.error);

✨ 主要特性

消息收发：支持发送和接收文本、图片等消息
媒体处理：可以发送和下载图片、音频、文件等媒体内容
群组管理：提供群组聊天的创建、加入和退出功能
联系人管理：支持添加、删除和搜索联系人
日志系统：内置基于 Winston 的强大日志记录功能

📦 安装指南

项目构建

从源代码构建项目：

npm run build

💻 使用示例

基础用法

import { WhatsApp } from 'whatsapp-web.js';
import * as WAProto from '@whatsprotypes/core';

async function run() {
    const WA = new WhatsApp({
        puppeteer: {
            executablePath: process.env.CHROME_PATH || undefined,
            args: ['--no-sandbox']
        },
        logLevel: 'info'
    });

    await WA.start();
    console.log('WhatsApp 已启动');
}

run().catch(console.error);

📚 详细文档

测试

使用 Jest 进行单元测试：

# 执行所有测试
npm test

# 监视模式下运行测试
npm run test:watch

# 生成覆盖报告
npm run test:coverage

格式化与代码质量

使用 ESLint 和 Prettier 维护代码规范：

# 运行检查
npm run lint

# 自动修复问题
npm run lint:fix

# 格式化代码
npm run format

🔧 技术细节

故障排除

集成问题

Claude Desktop 集成限制：由于 Claude 启动多个进程，无法在命令行模式下直接运行 wweb-mcp。为了解决这个问题，我们将应用拆分为 MCP 模式和 API 模式，以实现与 Claude 的兼容性。

未来计划

扩展媒体支持：支持发送视频、音频和文件
模板消息：提供常用场景的消息模板
高级群组功能：增强的群组管理特性
性能优化：提升机器人在高负载情况下的表现

贡献指南

如何贡献代码

Fork 项目仓库
创建新的分支
提交代码更改
提交 Pull Request

开发注意事项

遵循项目的代码规范和风格
确保新增功能通过单元测试
提供详细的文档说明

日志记录

日志级别

项目支持以下日志级别：

debug：调试信息
info：一般信息
warning：警告信息
error：错误信息
critical：严重错误
fatal：致命错误

默认日志级别为 info。

故障排除指南

常见问题

无法连接 WhatsApp 账号
- 确保浏览器已登录目标账号
- 检查网络连接状态
- 查看控制台输出的错误信息
Docker 部署失败
- 确保 Docker 服务正在运行
- 检查镜像拉取日志
- 核对端口映射和权限设置

📄 许可证

本项目遵循 MIT License 协议。

感谢使用 WhatsApp Web 机器人框架！如有任何问题或建议，请随时联系我们。

wweb-mcp