YaVendió ツール 🧰

MCPベースのメッセージングおよび通知システム。AIシステムがモデルコンテキストプロトコル（MCP）を介して様々なメッセージングプラットフォームと連携できるようにします。このプロジェクトは、テキスト、画像、ドキュメント、ボタン、アラートを送信するためのメッセージングツールを公開するMCPサーバーを実装します。

特徴

メッセージング機能:
- WhatsAppやその他のプラットフォーム経由でテキストメッセージを送信する
- 画像やメディアを適切な形式で送信する
- 適切なメタデータを含む動画を送信する
- ファイル名とメタデータを含むドキュメントを送信する
- ユーザーエンゲージメントのためのインタラクティブなボタンを作成する
WhatsAppクライアント管理:
- 異なる資格情報を持つ複数の WhatsApp クライアントを登録および管理します
- Infisicalを使用してトークンを安全に保管する
- クライアント管理のためのステートレスアーキテクチャ
- WhatsAppの各操作専用のツール
通知機能:
- 複数のチャネル（WhatsApp、メール、SMS）にわたるアラートを設定する
- 支払いボタンと取引通知のサポート
会話管理:
- メッセージの配信ステータスとメタデータを追跡する
追加ユーティリティ:
- 時間指定のインタラクションのためのスリープ/遅延機能
- 企業とユーザー向けの構成管理
- ステータス追跡によるリアルタイムメッセージ配信

MCPとは何ですか?

モデルコンテキストプロトコル（MCP）は、Anthropicが開発したオープンスタンダードであり、AIシステムと外部データソースまたはツールとのシームレスな統合を可能にします。MCPは、AIシステムとデータソースを接続するための普遍的なオープンスタンダードを提供し、断片化された統合を単一のプロトコルに置き換えます。

このプロジェクトは、様々なメッセージングツールを公開し、AIシステムが標準化された方法でアクセスできるようにするMCPサーバーを実装します。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`

1 つ以上の画像を 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`

1 つ以上のビデオを 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、電子メール、SMS) を通じてアラートを送信します。

パラメータ:

company_id : 会社識別子
phone_number : 受信者の電話番号
message : 警告メッセージ
whatsapp : WhatsAppメッセージを送信するかどうか
email : メール設定{"subject": "..."}
sms : 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 : オプションのヘッダー設定
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 ファイルを参照してください。

YaVendió Tools

YaVendió ツール 🧰

目次

特徴

MCPとは何ですか?

インストール

要件

構成

Dockerで実行する

ローカルで実行

発達

プロジェクト構造

MCP統合

利用可能なMCPツール

`send_text`

`send_image`

`send_video`

`send_document`

`send_alert`

`sleep`

`send_button`

`get_config`

`update_config`

テスト

貢献

ライセンス