Metadata-Version: 2.4
Name: revia-mcp
Version: 0.1.0
Summary: Python client for the Revia MCP bridge — connect your coding agent to WhatsApp, Telegram, Slack, and Gmail
Author: Revia Team
License: MIT
Keywords: coding-agent,gmail,mcp,revia,telegram,whatsapp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Revia MCP Client

Python client for the [Revia](https://revia.devshub.ai) MCP bridge. Connect your Python code to WhatsApp, Telegram, Slack, and Gmail through a single async client.

## Install

```bash
pip install revia-mcp
```

Or from source:

```bash
pip install -e clients/python-mcp/
```

## Quickstart

```python
import asyncio
from revia_mcp import ReviaMCPClient

async def main():
    async with ReviaMCPClient(
        "https://revia.devshub.ai/api/v1/mcp",
        token="rvagent_YOUR_TOKEN_HERE",
    ) as revia:

        # Health check
        pong = await revia.ping()
        print(pong)  # {"status": "pong", "user_id": "...", ...}

        # List channels
        channels = await revia.channels_list()
        for ch in channels["channels"]:
            print(f"{ch['platform']}: {'connected' if ch['reachable'] else 'offline'}")

        # Send a WhatsApp message
        await revia.messages_send(
            "whatsapp:974XXXXXXXX@s.whatsapp.net",
            "Hello from Python!",
        )

        # Read recent messages
        msgs = await revia.messages_read("whatsapp:974XXXXXXXX@s.whatsapp.net", limit=10)
        for m in msgs["messages"]:
            print(f"[{m['timestamp']}] {m.get('sender')}: {m.get('content')}")

        # Send an email
        await revia.email_send(
            to="client@example.com",
            subject="Meeting follow-up",
            body="Thanks for your time today!",
        )

asyncio.run(main())
```

## Real-time events via WebSocket

```python
async def stream_events():
    async with ReviaMCPClient(
        "https://revia.devshub.ai/api/v1/mcp",
        token="rvagent_YOUR_TOKEN_HERE",
    ) as revia:

        async for event in revia.events_ws():
            print(f"[{event['platform']}] {event['from']}: {event['content']}")
```

The WebSocket reconnects automatically on disconnect with exponential backoff.

## Chat with connected coding agents

```python
async def chat_with_agents():
    async with ReviaMCPClient(
        "https://revia.devshub.ai/api/v1/mcp",
        token="rvagent_YOUR_TOKEN_HERE",
    ) as revia:

        # See who's connected
        agents = await revia.agents_list()
        for a in agents["agents"]:
            print(f"  {a['name']} ({a['agent_id']})")

        # Send a natural language message and get a response
        reply = await revia.agent_chat(
            agent_id="agent_abc123",
            message="What's the status of the deployment?",
        )
        print(reply["response"])
```

## API Reference

### Health

| Method | MCP Tool | Description |
|--------|----------|-------------|
| `ping()` | `ping` | Health check — returns user scope and server time |

### Channels & Contacts

| Method | MCP Tool | Description |
|--------|----------|-------------|
| `channels_list()` | `channels_list` | List channels and connectivity |
| `contacts_list(platform?, query?, limit?)` | `contacts_list` | List contacts |
| `conversations_list(platform?, limit?)` | `conversations_list` | List conversations |
| `conversation_get(target)` | `conversation_get` | Get one conversation |

### Messages

| Method | MCP Tool | Description |
|--------|----------|-------------|
| `messages_read(target, limit?, before?, after?)` | `messages_read` | Read message history |
| `messages_send(target, message, reply_to?)` | `messages_send` | Send a message |
| `attachments_fetch(target, message_id?, limit?)` | `attachments_fetch` | Fetch attachment metadata |

### Email

| Method | MCP Tool | Description |
|--------|----------|-------------|
| `email_list(query?, max_results?)` | `email_list` | List Gmail messages |
| `email_search(query, max_results?)` | `email_search` | Search Gmail |
| `email_read(email_id)` | `email_read` | Read full email |
| `email_send(to, subject, body, cc?, draft?)` | `email_send` | Send or draft email |

### Revia AI

| Method | MCP Tool | Description |
|--------|----------|-------------|
| `revia_ask(prompt, contact?, use_context?)` | `revia_ask` | Ask Revia (read-only) |
| `conversation_claim(target, ttl_s?)` | `conversation_claim` | Mute auto-responder |

### Events

| Method | MCP Tool | Description |
|--------|----------|-------------|
| `events_poll(after_cursor?, limit?)` | `events_poll` | Poll for events |
| `events_wait(after_cursor?, timeout_ms?, limit?)` | `events_wait` | Long-poll for events |
| `events_subscribe(callback_url, events?, secret?)` | `events_subscribe` | Register webhook |
| `events_unsubscribe(subscription_id)` | `events_unsubscribe` | Remove webhook |
| `events_ws()` | — | WebSocket event stream (recommended) |

### Agents

| Method | MCP Tool | Description |
|--------|----------|-------------|
| `agents_list()` | `agents_list` | List connected coding agents |
| `agent_chat(agent_id, message)` | `agent_chat` | Chat with a connected agent |

## Token

Generate an agent token in the Revia dashboard: **Settings → Coding Agent (MCP) → Generate Token**. Tokens use the `rvagent_` prefix and are shown only once.

## License

MIT
