# Pararam Nexus MCP

A Model Context Protocol (MCP) server for interacting with [pararam.io](https://pararam.io) - a modern communication and collaboration platform.

## About pararam.io

Pararam.io is a communication platform that provides:

- **Messaging**: Create groups and private chats
- **Team Organization**: Organize people into teams
- **Communication**: Group and private calls (audio and video)
- **Cross-platform**: Available on mobile (iOS, Android, Huawei) and web

This MCP server uses the `pararamio-aio` library to provide asynchronous access to pararam.io features through the Model Context Protocol.

## Features

- Asynchronous API client for pararam.io
- Two-factor authentication support (TOTP)
- Session persistence with cookie storage
- Comprehensive chat and message management
- File attachment handling (upload and download)
- URL-based message retrieval
- Conversation thread building

## Available Tools

### Message Operations
- **search_messages**: Search for messages across all chats with advanced search syntax (Boolean operators, wildcards, filters)
- **get_chat_messages**: Get recent messages from a specific chat
- **send_message**: Send a message to a chat with optional reply and quote text
- **get_message_from_url**: Extract and retrieve a message from pararam.io URL

### Chat Operations
- **search_chats**: Search for chats by name or description
- **build_conversation_thread**: Build a conversation tree from a root message

### File Operations
- **upload_file_to_chat**: Upload files to a chat (from path or base64 content)
- **get_post_attachments**: List all attachments in a post
- **download_post_attachment**: Download attachments (to disk or as ImageContent)
  - 1MB size limit for downloads
  - Supported formats for direct display: images (JPEG, PNG, GIF, WEBP), documents (PDF, DOCX, DOC, TXT, RTF, ODT, HTML, EPUB), spreadsheets (XLSX, XLS, CSV), data (JSON, XML)
  - Returns ImageContent for supported types (displays natively in Claude Desktop/Code)
  - For unsupported types, requires output_path to save to disk
  - Saves to disk when output path is provided

### User Operations
- **search_users**: Search for users by name or unique name
- **get_user_info**: Get detailed information about a specific user
- **get_user_team_status**: Get user's status in teams (member, admin, guest)

## Tool Details

### send_message

Send a message to a chat with optional reply and quote functionality.

**Parameters:**
- `chat_id` (required): ID of the chat to send message to
- `text` (required): Message text to send
- `reply_to_message_id` (optional): Post number to reply to
- `quote_text` (optional): Text to quote from the replied message (only used with `reply_to_message_id`)

**Message formatting:**
Pararam supports Markdown-like text, but does not support Markdown headings (`#`, `##`, `###`).
Use `**bold**` section titles instead. Use colors as `[#RRGGBB](text)`;
colored bullet example: `[#2E7D32](●)`. Keep tables simple because colors may not render inside
table cells. Use `@all`, `@online`, `@admin`, and `@groups` only when the user explicitly asks
for broad notification, and ask for explicit confirmation before sending such mentions.
See [docs/PARARAM_FORMATTING.md](docs/PARARAM_FORMATTING.md) for the full syntax.

**Examples:**
```python
# Simple message
send_message(chat_id="123", text="Hello!")

# Reply to a message
send_message(
    chat_id="123",
    text="I agree!",
    reply_to_message_id="456"
)

# Reply with quoted text
send_message(
    chat_id="123",
    text="That's a great idea!",
    reply_to_message_id="456",
    quote_text="We should implement this feature next week"
)
```

## Installation

### Quick Install with uvx (Recommended)

Use the published PyPI package by default:

```bash
uvx pararam-nexus-mcp
```

For unreleased development snapshots, you can run directly from GitHub:

```bash
uvx --from git+https://github.com/ivolnistov/pararam-nexus-mcp pararam-nexus-mcp
```

For local development, clone the repository and install dependencies:

```bash
git clone https://github.com/ivolnistov/pararam-nexus-mcp.git ~/.mcp/pararam-nexus-mcp
cd ~/.mcp/pararam-nexus-mcp
uv sync
```

### Docker Installation

Pull from [Docker Hub](https://hub.docker.com/r/ivolnistov/pararam-nexus-mcp):

```bash
docker pull ivolnistov/pararam-nexus-mcp:latest
```

Or from GitHub Container Registry:

```bash
docker pull ghcr.io/ivolnistov/pararam-nexus-mcp:latest
```

### Development Installation

For local development:

```bash
git clone https://github.com/ivolnistov/pararam-nexus-mcp.git
cd pararam-nexus-mcp
uv sync --dev
```

## Configuration

The server runs in one of two modes depending on which env vars are set.

### Full mode — login + password (+ optional 2FA)

All tools are registered. Cookies are persisted between runs.

```env
PARARAM_LOGIN=your_login
PARARAM_PASSWORD=your_password
PARARAM_2FA_KEY=your_2fa_key  # optional
```

### Limited mode — `X-UserToken` service token

Set `PARARAM_USER_TOKEN` (mutually exclusive with `PARARAM_LOGIN`/`PARARAM_PASSWORD`).
Only the chat / message / post / replies / edit / delete tools are registered;
user lookups, global search, and file ops are excluded.

```env
PARARAM_USER_TOKEN=your_service_token
```

To get a service token in Pararam:

1. Open the Pararam **Info Chat** bot documentation.
2. In **User Tokens**, run **Create new token** (`bot://cmd_create_user_token?title=Create+new+token&conf=True`).
3. InfoBot will reply with `New user token - ...`.
4. Copy that value into `PARARAM_USER_TOKEN` and store it as a secret.

Tools available in limited mode:

- **Chats** — `get_chat`, `create_private_chat`, `create_group_chat`,
  `create_thread_chat`
- **Posts** — `get_chat_messages`, `get_message_from_url`,
  `get_reply_thread`, `get_replies_to_post`, `send_message`,
  `edit_post`, `delete_post`

## MCP Client Configuration

### Claude Code (CLI)

Add the server using the Claude Code CLI:

```bash
# Using uvx (recommended)
claude mcp add pararam-nexus \
  --env PARARAM_LOGIN=myuser@example.com \
  --env PARARAM_PASSWORD=mySecurePassword123 \
  --env PARARAM_2FA_KEY=JBSWY3DPEHPK3PXP \
  -- uvx pararam-nexus-mcp

# Using Docker
claude mcp add pararam-nexus \
  --env PARARAM_LOGIN=myuser@example.com \
  --env PARARAM_PASSWORD=mySecurePassword123 \
  --env PARARAM_2FA_KEY=JBSWY3DPEHPK3PXP \
  -- docker run -i --rm ivolnistov/pararam-nexus-mcp:latest
```

### Claude Desktop

#### Option 1: Using uvx (Recommended)

1. Open Claude Desktop preferences
2. Navigate to the MCP section
3. Click Edit to open `claude_desktop_config.json`
4. Add the server configuration:

```json
{
  "mcpServers": {
    "pararam-nexus": {
      "command": "uvx",
      "args": ["pararam-nexus-mcp"],
      "env": {
        "PARARAM_LOGIN": "myuser@example.com",
        "PARARAM_PASSWORD": "mySecurePassword123",
        "PARARAM_2FA_KEY": "JBSWY3DPEHPK3PXP"
      }
    }
  }
}
```

#### Option 2: Using Docker

First, create a volume for session persistence:
```bash
docker volume create pararam-mcp-data
```

Then add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "pararam-nexus": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "pararam-mcp-data:/app/.cookies",
        "-e",
        "PARARAM_LOGIN=myuser@example.com",
        "-e",
        "PARARAM_PASSWORD=mySecurePassword123",
        "-e",
        "PARARAM_2FA_KEY=JBSWY3DPEHPK3PXP",
        "ivolnistov/pararam-nexus-mcp:latest"
      ]
    }
  }
}
```

### Cursor IDE

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "pararam-nexus": {
      "command": "uvx",
      "args": ["pararam-nexus-mcp"],
      "env": {
        "PARARAM_LOGIN": "myuser@example.com",
        "PARARAM_PASSWORD": "mySecurePassword123",
        "PARARAM_2FA_KEY": "JBSWY3DPEHPK3PXP"
      }
    }
  }
}
```

Or using Docker (with session persistence):

First, create a volume:
```bash
docker volume create pararam-mcp-data
```

Then add to `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "pararam-nexus": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "pararam-mcp-data:/app/.cookies",
        "-e",
        "PARARAM_LOGIN=myuser@example.com",
        "-e",
        "PARARAM_PASSWORD=mySecurePassword123",
        "-e",
        "PARARAM_2FA_KEY=JBSWY3DPEHPK3PXP",
        "ivolnistov/pararam-nexus-mcp:latest"
      ]
    }
  }
}
```

### Other MCP-Compatible Clients

For any MCP-compatible client that supports stdio transport:

**Using uvx:**
```bash
uvx pararam-nexus-mcp
```

**Using Docker (with session persistence):**
```bash
# Create volume for cookies
docker volume create pararam-mcp-data

# Run with volume mounted
docker run -i --rm \
  -v pararam-mcp-data:/app/.cookies \
  -e PARARAM_LOGIN=myuser@example.com \
  -e PARARAM_PASSWORD=mySecurePassword123 \
  -e PARARAM_2FA_KEY=JBSWY3DPEHPK3PXP \
  ivolnistov/pararam-nexus-mcp:latest
```

**Environment variables:**
- `PARARAM_LOGIN` (full mode): Your pararam.io login
- `PARARAM_PASSWORD` (full mode): Your pararam.io password
- `PARARAM_2FA_KEY` (optional): Your 2FA secret key for TOTP authentication in full mode
- `PARARAM_USER_TOKEN` (limited mode): Service token sent as `X-UserToken`

Set either `PARARAM_LOGIN`/`PARARAM_PASSWORD` or `PARARAM_USER_TOKEN`, not both.

## Usage

### If installed with uvx:

```bash
uvx pararam-nexus-mcp
```

### If cloned locally:

```bash
cd ~/.mcp/pararam-nexus-mcp
uv run pararam-nexus-mcp
```

### For development:

```bash
uv run pararam-nexus-mcp
```

## Development

Install pre-commit hooks:

```bash
uv run pre-commit install
```

Run linting and formatting:

```bash
uv run ruff check --fix src/
uv run ruff format src/
```

Run type checking:

```bash
uv run mypy src/pararam_nexus_mcp
```

Run tests:

```bash
uv run pytest
```

## Dependencies

- **FastMCP**: Model Context Protocol server framework
- **pararamio-aio**: Async Python client for pararam.io API
- **httpx**: Modern HTTP client
- **Pydantic**: Data validation using Python type annotations

## License

MIT