# Transmission MCP Server

A multi-instance Transmission BitTorrent client MCP server following the "Hybrid MCP Light" pattern.

## Features

- **Multi-instance support**: Connect to multiple Transmission daemons simultaneously
- **Default instance**: Configure a default instance for convenience
- **Full API coverage**: Pass-through tool for any Transmission RPC method
- **Embedded documentation**: API reference available as an MCP resource

## Quick Start

1. Copy the environment template:
   ```bash
   cp .env.example .env
   ```

2. Edit `.env` with your Transmission instances:
   ```bash
   TRANSMISSION_INSTANCES='[
     {"name": "home", "url": "http://localhost:9091", "username": "admin", "password": "secret"},
     {"name": "seedbox", "url": "https://seedbox.example.com/transmission"}
   ]'
   TRANSMISSION_DEFAULT_INSTANCE=home
   ```

3. Run with Docker:
   ```bash
   docker-compose up -d
   ```

   Or run directly:
   ```bash
   pip install .
   python server.py
   ```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `TRANSMISSION_INSTANCES` | Yes | JSON array of instance configurations |
| `TRANSMISSION_DEFAULT_INSTANCE` | No | Name of the default instance |
| `HOST` | No | Server bind address (default: `0.0.0.0`) |
| `PORT` | No | Server port (default: `8000`) |

### Instance Configuration

Each instance in `TRANSMISSION_INSTANCES` supports:

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Yes | Unique identifier for this instance |
| `url` | Yes | Full URL to Transmission RPC endpoint |
| `username` | No | Username for HTTP Basic Auth |
| `password` | No | Password for HTTP Basic Auth |

## MCP Tools

### `list_instances`
Returns all configured Transmission instances with connectivity status.

### `get_torrents`
Get torrent list with common fields for a specific instance.

**Parameters:**
- `instance` (optional): Instance name (uses default if not specified)
- `ids` (optional): Specific torrent IDs to fetch

### `get_session_stats`
Get session statistics including speeds and torrent counts.

**Parameters:**
- `instance` (optional): Instance name (uses default if not specified)

### `rpc_call`
Execute any Transmission RPC method directly.

**Parameters:**
- `method`: RPC method name (e.g., `torrent_get`, `session_set`)
- `params` (optional): JSON string of method parameters
- `instance` (optional): Instance name (uses default if not specified)

## MCP Resources

### `transmission://api-reference`
Embedded Transmission RPC API documentation for AI agent reference.

## Examples

### List all torrents on default instance
```json
{"tool": "get_torrents"}
```

### Get torrents from specific instance
```json
{"tool": "get_torrents", "arguments": {"instance": "seedbox"}}
```

### Add a torrent via pass-through
```json
{
  "tool": "rpc_call",
  "arguments": {
    "method": "torrent_add",
    "params": "{\"filename\": \"magnet:?xt=urn:btih:...\"}"
  }
}
```

### Pause all torrents
```json
{
  "tool": "rpc_call",
  "arguments": {
    "method": "torrent_stop",
    "params": "{}"
  }
}
```

## Health Check

The server exposes a `/health` endpoint for Docker health checks and monitoring.

```bash
curl http://localhost:8000/health
```

## License

MIT