YaVendio
服务介绍
YaVendió Tools 🧰
一个基于MCP的消息和通知系统，允许AI系统通过模型上下文协议（MCP）与各种消息平台进行交互。该项目实现了一个MCP服务器，提供了发送文本、图片、文档、按钮和警报等消息工具。
目录
功能
-
消息功能：
- 通过WhatsApp和其他平台发送文本消息
- 发送带有适当格式的图片和媒体
- 发送带有适当元数据的视频
- 发送带有文件名和元数据的文档
- 创建用于用户互动的交互式按钮
-
WhatsApp客户端管理：
- 使用不同的凭据注册和管理多个WhatsApp客户端
- 使用Infisical安全存储令牌
- 无状态架构的客户端管理
- 每个WhatsApp操作都有专用工具
-
通知功能：
- 在多个渠道（WhatsApp、电子邮件、短信）上配置警报
- 支持支付按钮和交易通知
-
对话管理：
- 跟踪消息传递状态和元数据
-
其他实用工具：
- 用于定时交互的睡眠/延迟功能
- 公司和用户的配置管理
- 带有状态跟踪的实时消息传递
什么是MCP？
模型上下文协议（MCP）是由Anthropic开发的一个开放标准，它使AI系统与外部数据源或工具之间的无缝集成成为可能。它提供了一个通用的、开放的标准，将AI系统与数据源连接起来，用单一协议取代了碎片化的集成方式。
该项目实现了一个MCP服务器，暴露了各种消息工具，使它们能够以标准化的方式被AI系统访问。通过使用MCP，AI助手可以：
- 直接向用户发送WhatsApp消息
- 上传并发送媒体文件
- 通过按钮创建交互体验
- 高效地管理对话上下文
- 触发多渠道通知
安装
该项目使用uv进行包管理：
bash
如果你还没有安装uv
curl -L https://github.com/astral-sh/uv/releases/latest/download/install.sh | sh
或者，使用pip安装
pip install uv
克隆仓库
git clone https://your-repo-url/yatools.git
cd yatools
安装所有依赖（包括开发依赖）
make sync
或者单独安装
make install # 常规依赖
make dev-install # 开发依赖
要求
- Python 3.13或更高版本
- Docker和Docker Compose（用于容器化部署）
配置
在根目录下创建一个.env文件，并添加你的配置：
日志配置
LOG_LEVEL=INFO
LOG_FORMAT=json
使用Docker运行
bash
启动所有服务
docker-compose up -d
停止所有服务
docker-compose down
查看日志
docker-compose logs -f
查看特定服务的日志
docker-compose logs -f app
本地运行
bash
开发模式，自动重载
make run
生产模式
make run-prod
指定端口运行
PORT=8080 make run
开发该项目包含多个 Makefile 命令以简化开发流程：
bash
显示所有可用命令
make help
运行测试
make test
运行带有覆盖率报告的测试
make coverage
格式化代码
make format
代码检查
make lint
清理缓存文件
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 集成
此服务可以通过模型上下文协议 (MCP) 与 LLM 应用程序集成：
bash
在 Claude Desktop 中安装服务器
make mcp-install
以开发模式运行并自动重载
make mcp-dev
从 PyPI 安装（如果已发布）
make mcp-install-pkg
可用的 MCP 工具
send_text
向 WhatsApp 号码发送一条文本消息。
参数:
company_id: 公司标识符phone_number: 收件人的电话号码message: 要发送的文本
示例:
python
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 列表
示例:
python
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 列表
示例:
python
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": "..."}
示例:
python
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: SMS 配置{"type": "...", "recipients": ["..."]}pause_number: 是否暂停对话track_sale: 是否将此记录为销售
示例：
python
result = await send_alert(
company_id="company123",
phone_number="5551234567",
message="重要警报：检测到新活动",
whatsapp=True,
email={
"subject": "重要警报",
"recipients": ["user@example.com"]
},
sms={
"type": "urgent",
"recipients": ["5551234567", "5557654321"]
},
pause_number=False,
track_sale=True
)
print(f"警报结果: {result[ result ]}")
sleep
暂停执行指定秒数。
参数：
company_id: 公司标识符phone_number: 收件人的电话号码seconds: 暂停的秒数
示例：
python
result = await sleep(
company_id="company123",
phone_number="5551234567",
seconds=5
)
print(f"已暂停 {result[ seconds ]} 秒")
send_button
发送交互按钮。
参数：
company_id: 公司标识符phone_number: 收件人的电话号码body_text: 按钮消息正文buttons: 按钮配置列表[{"id": "...", "title": "..."}]button_type: "reply" 或 "payment"header: 可选的头部配置footer_text: 可选的底部文本payment_data: 用于支付按钮的支付数据
示例（回复按钮）：
python
result = await send_button(
company_id="company123",
phone_number="5551234567",
body_text="请选择一个选项：",
buttons=[
{"id": "btn1", "title": "选项 1"},
{"id": "btn2", "title": "选项 2"},
{"id": "btn3", "title": "选项 3"}
],
button_type="reply",
footer_text="点击按钮继续"
)
print(f"按钮消息 ID: {result[ message_id ]}")
示例（支付按钮）：
python
result = await send_button(
company_id="company123",
phone_number="5551234567",
body_text="完成您的购买：",
buttons=[{"id": "pay1", "title": "立即支付"}],
button_type="payment",
payment_data={
"title": "高级订阅",
"url": "https://pay.example.com/invoice123",
"amount": "19.99",
"currency": "USD"
}
)
print(f"支付按钮消息 ID: {result[ message_id ]}")
get_config
获取公司配置。
参数：
company_id: 公司标识符
示例：
python
config = await get_config(
company_id="company123"
)
print(f"公司配置: {config[ config ]}")
update_config
更新公司配置。
参数：
company_id: 公司标识符config: 新配置
示例：
python
result = await update_config(
company_id="company123",
config={
"welcome_message": "欢迎使用我们的服务！",
"auto_reply": True,
"notification_emails": ["admin@example.com"]
}
)
print(f"更新结果: {result[ message ]}")
测试
有关运行和编写测试的详细信息，请参阅 TEST.md。
基本测试命令：
bash
运行所有测试
make test
运行带有覆盖率的测试
make coverage
贡献
欢迎贡献！请遵循以下步骤：
- 分叉仓库
- 创建功能分支 (
git checkout -b feature/amazing-feature) - 进行更改
- 运行测试以确保它们通过 (
make test) - 提交更改 (
git commit -m 添加了惊人的功能) - 推送到分支 (
git push origin feature/amazing-feature) - 打开拉取请求
许可证
该项目根据 MIT 许可证许可 - 详情请参见 LICENSE 文件。
