YaVendió 工具🧰

基于 MCP 的消息传递和通知系统，允许 AI 系统通过模型上下文协议 (MCP) 与各种消息传递平台进行交互。该项目实现了一个 MCP 服务器，该服务器公开了用于发送文本、图像、文档、按钮和警报的消息传递工具。

特征

消息传递功能：
- 通过 WhatsApp 和其他平台发送短信
- 发送格式正确的图像和媒体
- 发送带有适当元数据的视频
- 发送带有文件名和元数据的文档
- 创建交互式按钮以吸引用户参与
WhatsApp 客户端管理：
- 使用不同的凭证注册和管理多个 WhatsApp 客户端
- 使用 Infisical 安全存储代币
- 客户端管理的无状态架构
- 每个 WhatsApp 操作的专用工具
通知功能：
- 配置跨多个渠道的警报（WhatsApp、电子邮件、短信）
- 支持支付按钮和交易通知
对话管理：
- 跟踪消息传递状态和元数据
附加实用程序：
- 用于定时交互的睡眠/延迟功能
- 为公司和用户提供配置管理
- 实时消息传递和状态跟踪

什么是 MCP？

模型上下文协议 (MCP) 是由 Anthropic 开发的一项开放标准，旨在实现 AI 系统与外部数据源或工具的无缝集成。它提供了一个通用的开放标准，用于连接 AI 系统和数据源，用单一协议取代分散的集成。

该项目实现了一个 MCP 服务器，该服务器公开各种消息传递工具，使 AI 系统能够以标准化方式访问它们。通过使用 MCP，AI 助手可以：

直接向用户发送 WhatsApp 消息
上传和发送媒体文件
使用按钮创建交互式体验
有效管理对话上下文
触发多渠道通知

安装

该项目使用uv进行包管理：

# Install uv if you don't have it
curl -L https://github.com/astral-sh/uv/releases/latest/download/install.sh | sh

# Alternatively, install with pip
pip install uv

# Clone the repository
git clone https://your-repo-url/yatools.git
cd yatools

# Install all dependencies (including dev dependencies)
make sync
# Or individually
make install      # Regular dependencies
make dev-install  # Development dependencies

要求

Python 3.13 或更高版本
Docker 和 Docker Compose（用于容器化部署）

配置

使用您的配置在根目录中创建一个.env文件：

# Logging configuration
LOG_LEVEL=INFO
LOG_FORMAT=json

使用 Docker 运行

# Start all services
docker-compose up -d

# Stop all services
docker-compose down

# View logs
docker-compose logs -f

# View logs for specific service
docker-compose logs -f app

本地运行

# Development mode with auto-reload
make run

# Production mode
make run-prod

# Run with specific port
PORT=8080 make run

发展

该项目包括几个 Makefile 命令来简化开发：

# Show all available commands
make help

# Run tests
make test

# Run tests with coverage report
make coverage

# Format code
make format

# Lint code
make lint

# Clean cache files
make clean

项目结构

app/ ：主应用程序代码
- server.py ：MCP 服务器实现
- logging.py ：使用 structlog 进行日志配置
- lifespan.py ：应用程序生命周期管理
tools/ ：工具实现
- base_tool.py ：所有工具的抽象基类
- text_tool.py ：发送短信的工具
- image_tool.py ：发送图像的工具
- video_tool.py ：发送视频的工具
- document_tool.py ：发送文档的工具
- button_tool.py ：发送交互式按钮的工具
- alert_tool.py ：发送多渠道警报的工具
- sleep_tool.py ：用于在工具执行中添加延迟的工具
services/ ：服务实现
- interfaces.py ：定义契约的服务接口
- message_service.py ：消息存储和检索服务
- message_service_mock.py ：用于测试的模拟实现
- whatsapp_service.py ：WhatsApp 客户端管理服务
- whatsapp_service_mock.py ：模拟 WhatsApp 服务进行测试
tests/ ：测试实现
- app/ ：测试应用程序结构
- tools/ ：针对单个工具的测试
- services/ ：服务测试
- server/ ：测试 MCP 服务器集成

MCP 集成

该服务可以通过模型上下文协议与 LLM 应用程序集成：

# Install the server in Claude Desktop
make mcp-install

# Run in development mode with auto-reload
make mcp-dev

# Install from PyPI (if published)
make mcp-install-pkg

可用的 MCP 工具

`send_text`

向 WhatsApp 号码发送短信。

参数：

company_id ：公司标识符
phone_number ：收件人的电话号码
message ：要发送的文本

例子：

result = await send_text(
    company_id="company123",
    phone_number="5551234567",
    message="Hello, this is a test message!"
)
print(f"Message ID: {result['message_id']}")

`send_image`

将一张或多张图像发送到 WhatsApp 号码。

参数：

company_id ：公司标识符
phone_number ：收件人的电话号码
image_urls ：要发送的图像 URL 列表

例子：

result = await send_image(
    company_id="company123",
    phone_number="5551234567",
    image_urls=["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
)
print(f"Message IDs: {result['message_ids']}")

`send_video`

将一个或多个视频发送到 WhatsApp 号码。

参数：

company_id ：公司标识符
phone_number ：收件人的电话号码
video_urls ：要发送的视频 URL 列表

例子：

result = await send_video(
    company_id="company123",
    phone_number="5551234567",
    video_urls=["https://example.com/video.mp4"]
)
print(f"Message IDs: {result['message_ids']}")

`send_document`

将文档文件发送到 WhatsApp 号码。

参数：

company_id ：公司标识符
phone_number ：收件人的电话号码
files ：文档文件列表，格式为{"url": "...", "filename": "..."}

例子：

result = await send_document(
    company_id="company123",
    phone_number="5551234567",
    files=[
        {
            "url": "https://example.com/document.pdf",
            "filename": "report.pdf"
        }
    ]
)
print(f"Message IDs: {result['message_ids']}")

`send_alert`

通过多种渠道（WhatsApp、电子邮件、短信）发送警报。

参数：

company_id ：公司标识符
phone_number ：收件人的电话号码
message ：警报消息
whatsapp ：是否发送 WhatsApp 消息
email ：电子邮件配置{"subject": "..."}
sms ：短信配置{"type": "...", "recipients": ["..."]}
pause_number ：是否暂停对话
track_sale ：是否将此作为销售进行跟踪

例子：

result = await send_alert(
    company_id="company123",
    phone_number="5551234567",
    message="Important alert: New activity detected",
    whatsapp=True,
    email={
        "subject": "Important Alert", 
        "recipients": ["user@example.com"]
    },
    sms={
        "type": "urgent", 
        "recipients": ["5551234567", "5557654321"]
    },
    pause_number=False,
    track_sale=True
)
print(f"Alert Result: {result['result']}")

`sleep`

暂停执行指定的秒数。

参数：

company_id ：公司标识符
phone_number ：收件人的电话号码
seconds ：睡眠秒数

例子：

result = await sleep(
    company_id="company123",
    phone_number="5551234567",
    seconds=5
)
print(f"Slept for {result['seconds']} seconds")

`send_button`

发送交互式按钮。

参数：

company_id ：公司标识符
phone_number ：收件人的电话号码
body_text ：按钮消息正文
buttons ：按钮配置列表[{"id": "...", "title": "..."}]
button_type ：“回复”或“付款”
header ：可选的 header 配置
footer_text ：可选页脚文本
payment_data ：支付按钮的支付数据

示例（回复按钮）：

result = await send_button(
    company_id="company123",
    phone_number="5551234567",
    body_text="Please select an option:",
    buttons=[
        {"id": "btn1", "title": "Option 1"},
        {"id": "btn2", "title": "Option 2"},
        {"id": "btn3", "title": "Option 3"}
    ],
    button_type="reply",
    footer_text="Tap a button to proceed"
)
print(f"Button Message ID: {result['message_id']}")

示例（付款按钮）：

result = await send_button(
    company_id="company123",
    phone_number="5551234567",
    body_text="Complete your purchase:",
    buttons=[{"id": "pay1", "title": "Pay Now"}],
    button_type="payment",
    payment_data={
        "title": "Premium Subscription",
        "url": "https://pay.example.com/invoice123",
        "amount": "19.99",
        "currency": "USD"
    }
)
print(f"Payment Button Message ID: {result['message_id']}")

`get_config`

获取公司配置。

参数：

company_id ：公司标识符

例子：

config = await get_config(
    company_id="company123"
)
print(f"Company Config: {config['config']}")

`update_config`

更新公司配置。

参数：

company_id ：公司标识符
config ：新配置

例子：

result = await update_config(
    company_id="company123",
    config={
        "welcome_message": "Welcome to our service!",
        "auto_reply": True,
        "notification_emails": ["admin@example.com"]
    }
)
print(f"Update Result: {result['message']}")

测试

有关运行和编写测试的详细信息，请参阅TEST.md 。

基本测试命令：

# Run all tests
make test

# Run tests with coverage
make coverage

贡献

欢迎贡献！请按以下步骤操作：

分叉存储库
创建功能分支（ git checkout -b feature/amazing-feature ）
进行更改
运行测试以确保它们通过（ make test ）
提交您的更改（ git commit -m 'Add amazing feature' ）
推送到分支（ git push origin feature/amazing-feature ）
打开拉取请求

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。