金大哥 - WhatsApp Web MCP 详情

article

README

🚀 WhatsApp Web 项目文档

WhatsApp Web 是基于 WhatsApp 的网络客户端，借助网页浏览器就能使用 WhatsApp 功能。此项目提供了丰富的 API 及协议实现，极大地方便了开发者进行集成与扩展。

🚀 快速开始

WhatsApp Web 项目为开发者提供了便捷的集成和扩展途径，通过丰富的 API 和协议实现，可轻松实现与 WhatsApp Web 功能的交互。

✨ 主要特性

基于网页浏览器，支持使用 WhatsApp 功能。
提供丰富 API 和协议实现，便于开发者集成扩展。
架构灵活，支持多种部署场景。

📦 安装指南

构建

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

# 验证代码（检查 + 测试）
npm run validate

🔧 技术细节

架构

核心组件

WhatsApp 客户端：实现与 WhatsApp Web 浏览器应用的交互。
核心业务逻辑：处理 WhatsApp 的消息收发、联系人管理等核心功能。
WhatsApp API 客户端：提供对 WhatsApp API 服务器的访问接口。
REST API 路由：实现 HTTP 接口，供外部系统调用。
MCP 协议实现：实现模型上下文协议（Model Context Protocol）的支持。

部署选项

WhatsApp API 服务器：独立运行的 REST API 服务。
MCP 服务器（独立运行）：直接连接 WhatsApp Web 的 MCP 实现。
MCP 服务器（API 客户端）：通过 API 服务器进行连接。

这种架构设计使得系统可以灵活部署，支持以下场景：

在不同机器上分别运行 API 服务器和 MCP 服务器。
使用 MCP 服务器作为现有 API 服务器的客户端。
所有组件在单台机器上运行。

项目结构

src/
├── whatsapp-client.ts     # WhatsApp Web 客户端实现
├── whatsapp-service.ts    # 核心业务逻辑实现
├── whatsapp-api-client.ts # 对 WhatsApp API 服务器的客户端访问
├── api.ts                 # REST API 路由实现
├── mcp-server.ts          # MCP 协议实现
└── main.ts                # 应用程序入口点

💻 使用示例

基础用法

项目使用过程中的基础操作，可参考以下命令：

# 构建项目
npm run build

# 执行所有测试
npm test

高级用法

在开发过程中，可使用以下命令进行更高级的操作：

# 监视模式下运行测试（开发中）
npm run test:watch

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

⚙️ 故障排除

Claude Desktop 集成问题

由于 Claude 打开多个进程，无法在命令行独立模式下运行 wweb-mcp。为了解决此限制，我们将应用拆分为 API 和 MCP 模式，以支持与 Claude 的良好集成。

📈 计划功能

创建 webhook 用于接收消息和其他 WhatsApp 事件。
支持发送媒体文件（图片、音频、文档）。
群组聊天管理功能。
联系人管理（添加/删除联系人）。
消息模板实现常见场景。
增强错误处理和恢复机制。

🤝 贡献指南

叉取仓库。
创建功能分支。
提交更改。
推送到分支。
创建拉取请求。

请确保您的 PR：

代码清晰且经过适当测试。
遵循代码规范和命名约定。
提供详细的提交信息和描述。

📄 依赖项

| 属性 | 详情 | |------|------| | 包名 | express、ws、winston、dotenv | | 版本 | ^4.18.2、^7.5.3、^3.0.1、^16.3.1 | | 描述 | 实现 HTTP 服务器、WebSocket 支持、日志库、加载环境变量 |

📝 日志系统

级别

debug：调试信息。
info：一般信息。
warn：警告信息。
error：错误信息。
fatal：严重错误。

配置

const logger = winston.createLogger({
  level: 'info',
  transports: [
    new winston.transports.Console({ colorize: true })
  ]
});

⚠️ 安全注意事项

禁止在生产环境中暴露调试端点。
配置适当的认证机制保护 API 接口。
定期更新依赖库以修复安全漏洞。
使用 HTTPS 提供 API 服务。

📄 许可证

本项目遵循 MIT 协议。请查看 LICENSE 文件获取详细信息。

以上文档为 WhatsApp Web 项目的开发指南，更多细节请参考相关代码和注释。

WhatsApp Web