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 機器人框架！如有任何問題或建議，請隨時聯繫我們。