ChatAds MCP Wrapper

This directory houses the Model Context Protocol (MCP) wrapper that exposes the ChatAds Affiliate API to Claude (or any MCP-aware client). The wrapper normalizes responses, hides backend-specific errors, and provides consistent metadata so Claude always receives a predictable envelope.

Requirements

• Python 3.10+
• uv or standard pip
• Environment variables:
  • CHATADS_API_KEY – your ChatAds API key (required)
  • Optional overrides:
    • CHATADS_API_BASE_URL (default: https://api.getchatads.com)
    • CHATADS_API_ENDPOINT (default: /v1/chatads/messages)
    • CHATADS_MCP_TIMEOUT (default: 10 seconds)
    • CHATADS_MCP_MAX_RETRIES (default: 3)
    • CHATADS_MCP_BACKOFF (default: 0.6 seconds)
    • CHATADS_CIRCUIT_BREAKER_THRESHOLD (default: 5 failures before opening)
    • CHATADS_CIRCUIT_BREAKER_TIMEOUT (default: 60 seconds)
    • CHATADS_QUOTA_WARNING_THRESHOLD (default: 0.9 / 90%)
    • LOGLEVEL (default: INFO, options: DEBUG, INFO, WARNING, ERROR)
    • CHATADS_LOG_FORMAT (default: text, options: text, json)

Installation

From PyPI (recommended)

pip install chatads-mcp-wrapper

From source (development)

git clone https://github.com/chatads/chatads-mcp-wrapper.git
cd chatads-mcp-wrapper
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt

Set your API key:

export CHATADS_API_KEY=your_chatads_api_key

Running the MCP Server

chatads-mcp
# or: python -m chatads_mcp_wrapper

The server provides one MCP tool:

• chatads_message_send - Main tool for fetching affiliate recommendations

Claude Desktop integration

Add a server entry to claude_desktop_config.json (path varies per OS):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "chatads": {
      "command": "chatads-mcp",
      "args": [],
      "env": {
        "CHATADS_API_KEY": "your_chatads_api_key",
        "CHATADS_API_BASE_URL": "https://api.getchatads.com"
      }
    }
  }
}

Restart Claude Desktop and the tool will be available.

Tool Signature

chatads_message_send(
    message: str,                                          # Required: 1-5000 chars
    ip?: str,                                              # IPv4/IPv6 address for country detection (max 45 chars)
    country?: str,                                         # Country code (e.g., 'US'). If provided, skips IP-based country detection
    input_type?: str,                                      # Content type: 'text' (default), 'image_url', or 'image_file'
    # api_key is accepted via CHATADS_API_KEY env var (hidden from tool schema)
) -> {
    status: "success" | "no_match" | "error",
    offers?: [
        {
            link_text: str,                                # Text to use for affiliate link
            url: str,                                      # Affiliate URL (always populated)
            confidence_score?: float,                      # Confidence score (0.0-1.0)
            search_term?: str,                             # Search term used
            product?: { title?: str, description?: str }   # Product metadata
        }
    ],
    offers_requested?: int,
    offers_returned?: int,
    reason?: str,
    error_code?: str,
    error_message?: str,
    metadata: {
        request_id: str,
        timestamp: str,
        latency_ms: float,
        status_code: int,
        source: str,
        country?: str,
        language?: str,
        usage_summary?: {...},
        notes?: str
    }
}

Features

Circuit Breaker

Prevents retry storms when the API is experiencing issues. After N consecutive failures (default: 5), the circuit breaker "opens" and fails fast for a cooldown period (default: 60 seconds) instead of wasting resources.

States:

• CLOSED: Normal operation
• OPEN: Failing fast, not attempting requests
• HALF_OPEN: Testing if service recovered

Configuration:

export CHATADS_CIRCUIT_BREAKER_THRESHOLD=5
export CHATADS_CIRCUIT_BREAKER_TIMEOUT=60

Quota Warnings

The wrapper automatically checks usage metadata and warns when approaching limits:

• Monthly quota < 10 requests remaining
• Daily quota ≥ 90% used (configurable via CHATADS_QUOTA_WARNING_THRESHOLD)

Development

Install Dev Dependencies

python3 -m pip install -r requirements-dev.txt

This installs the full test stack (pytest, pytest-asyncio, pytest-cov, etc.).

Run Tests with Coverage

pytest

Tests are async and the default pytest configuration enforces ≥85% coverage.
If you need to run a focused subset (e.g., only the message-send tests) without failing the coverage gate:

PYTEST_ADDOPTS="" pytest -k message_send
# or equivalently
pytest -k message_send --no-cov

Remember to run the full suite before committing so coverage stays above the required threshold.

Warnings appear in metadata.notes and logs. No client-side state management needed - uses real-time data from backend.

Monitoring Hooks

Integrate with your monitoring system:

from chatads_mcp_wrapper import set_metric_callback
import datadog

# Configure callback for metrics
set_metric_callback(datadog.statsd.gauge)

Emitted metrics:

• chatads.request.latency_ms - Request latency
• chatads.circuit_breaker.state_change - Circuit breaker transitions

Best Practices

• Validate prompts: ensure message is non-empty and under 100 words to avoid upstream validation errors.
• Monitor quota warnings: Check metadata.notes for quota warnings to avoid hitting limits.
• Honor circuit breaker: When circuit is open, wait for cooldown period before retrying.
• Log metadata: persist metadata.request_id and metadata.usage_summary for debugging and analytics.
• Handle no_match: treat status="no_match" as a graceful fallback—use reason to explain why no ad was returned.
• Override cautiously: only pass country when you have high-confidence signals; otherwise let ChatAds infer it from the IP.
• Secure API keys: prefer environment variables; only use the api_key argument for per-request overrides inside trusted contexts.

Troubleshooting

Enable debug logging if deeper insight is needed:

# Text logging (default)
LOGLEVEL=DEBUG chatads-mcp

# JSON structured logging (recommended for production)
CHATADS_LOG_FORMAT=json LOGLEVEL=INFO chatads-mcp

JSON logging outputs structured logs compatible with log aggregation systems (CloudWatch, Datadog, etc.).

Logs include upstream latency, retry attempts, and normalized error payloads without exposing internal stack traces or API keys to Claude.