YaVendió 도구 🧰

AI 시스템이 모델 컨텍스트 프로토콜(MCP)을 통해 다양한 메시징 플랫폼과 상호 작용할 수 있도록 하는 MCP 기반 메시징 및 알림 시스템입니다. 이 프로젝트는 텍스트, 이미지, 문서, 버튼 및 알림을 전송하는 메시징 도구를 제공하는 MCP 서버를 구현합니다.

특징

메시징 기능 :
- WhatsApp 및 기타 플랫폼을 통해 문자 메시지를 보내세요
- 적절한 형식으로 이미지와 미디어를 보내세요
- 적절한 메타데이터를 포함한 비디오 보내기
- 파일 이름과 메타데이터가 포함된 문서 보내기
- 사용자 참여를 위한 대화형 버튼 만들기
WhatsApp 클라이언트 관리 :
- 다양한 자격 증명으로 여러 WhatsApp 클라이언트를 등록하고 관리하세요.
- Infisical을 사용하여 토큰을 안전하게 저장하세요
- 클라이언트 관리를 위한 상태 비저장 아키텍처
- 각 WhatsApp 작업에 대한 전용 도구
알림 기능 :
- 여러 채널(WhatsApp, 이메일, SMS)에 걸쳐 알림 구성
- 결제 버튼 및 거래 알림 지원
대화 관리 :
- 메시지 전달 상태 및 메타데이터 추적
추가 유틸리티 :
- 시간 제한 상호작용을 위한 수면/지연 기능
- 회사 및 사용자를 위한 구성 관리
- 상태 추적을 통한 실시간 메시지 전달

MCP란 무엇인가요?

모델 컨텍스트 프로토콜(MCP)은 Anthropic에서 개발한 개방형 표준으로, AI 시스템과 외부 데이터 소스 또는 도구 간의 원활한 통합을 지원합니다. AI 시스템과 데이터 소스를 연결하는 데 필요한 범용 개방형 표준을 제공하며, 단편화된 통합을 단일 프로토콜로 대체합니다.

이 프로젝트는 다양한 메시징 도구를 제공하는 MCP 서버를 구현하여 AI 시스템에서 표준화된 방식으로 접근할 수 있도록 합니다. MCP를 사용하여 AI 비서는 다음과 같은 작업을 수행할 수 있습니다.

WhatsApp 메시지를 사용자에게 직접 보냅니다.
미디어 파일 업로드 및 전송
버튼을 사용하여 대화형 경험을 만드세요
대화 맥락을 효율적으로 관리하세요
다중 채널 알림 트리거

설치

이 프로젝트에서는 패키지 관리를 위해 uv를 사용합니다.

지엑스피1

요구 사항

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, 이메일, 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 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

YaVendió Tools

YaVendió 도구 🧰

목차

특징

MCP란 무엇인가요?

설치

요구 사항

구성

Docker로 실행

지역적으로 실행

개발

프로젝트 구조

MCP 통합

사용 가능한 MCP 도구

`send_text`

`send_image`

`send_video`

`send_document`

`send_alert`

`sleep`

`send_button`

`get_config`

`update_config`

테스트

기여하다

특허