Wweb MCP

🚀 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

测试

使用 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 的兼容性。

未来计划

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

贡献指南

如何贡献代码

1. Fork 项目仓库。
2. 创建新的分支。
3. 提交代码更改。
4. 提交 Pull Request。

开发注意事项

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

日志记录

日志级别

项目支持以下日志级别：

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

默认日志级别为 info。

故障排除指南

常见问题

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

贡献者名单

• 开发者：[你的名字]
• 维护人员：[维护者姓名]

📄 许可证

本项目遵循 MIT License 协议。

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