# Transmission MCP Server - Implementation Guide

This document provides technical details for AI agents and developers working with this MCP server.

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    Starlette App                        │
├─────────────┬───────────────────────────────────────────┤
│  /health    │              FastMCP App                  │
│  endpoint   │  ┌─────────────────────────────────────┐  │
│             │  │  Tools:                             │  │
│             │  │  - list_instances                   │  │
│             │  │  - get_torrents                     │  │
│             │  │  - get_session_stats                │  │
│             │  │  - rpc_call (pass-through)          │  │
│             │  ├─────────────────────────────────────┤  │
│             │  │  Resources:                         │  │
│             │  │  - transmission://api-reference     │  │
│             │  └─────────────────────────────────────┘  │
└─────────────┴───────────────────────────────────────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │      InstanceRegistry         │
              │  ┌─────────────────────────┐  │
              │  │ TransmissionClient[home]│  │
              │  │ TransmissionClient[seed]│  │
              │  │ TransmissionClient[...]  │  │
              │  └─────────────────────────┘  │
              └───────────────────────────────┘
                              │
                              ▼
              ┌───────────────────────────────┐
              │   Transmission Daemons (RPC)  │
              └───────────────────────────────┘
```

## Key Classes

### TransmissionClient

Handles communication with a single Transmission daemon:
- Manages CSRF token (`X-Transmission-Session-Id`)
- Automatic retry on 409 responses
- HTTP Basic Auth support (optional)
- JSON-RPC 2.0 protocol (Transmission 4.1+)

### InstanceRegistry

Manages multiple TransmissionClient instances:
- Loads configuration from `TRANSMISSION_INSTANCES` env var
- Provides lookup by instance name
- Tracks default instance
- Health check aggregation

## Transmission RPC Protocol

This server uses the **JSON-RPC 2.0** protocol introduced in Transmission 4.1.0. Key points:

1. All method/field names use `snake_case` (not the old camelCase/kebab-case)
2. Request format:
   ```json
   {
     "jsonrpc": "2.0",
     "method": "torrent_get",
     "params": {"fields": ["name", "status"]},
     "id": 1
   }
   ```
3. CSRF protection requires `X-Transmission-Session-Id` header
4. On 409 response, extract session ID from response header and retry

## Common RPC Methods

### Torrent Operations
| Method | Description |
|--------|-------------|
| `torrent_get` | Get torrent info (requires `fields` array) |
| `torrent_add` | Add torrent (requires `filename` or `metainfo`) |
| `torrent_remove` | Remove torrent (optional `delete_local_data`) |
| `torrent_start` | Start torrents |
| `torrent_stop` | Stop/pause torrents |
| `torrent_set` | Modify torrent settings |
| `torrent_set_location` | Move torrent data |

### Session Operations
| Method | Description |
|--------|-------------|
| `session_get` | Get session settings (optional `fields`) |
| `session_set` | Modify session settings |
| `session_stats` | Get transfer statistics |
| `free_space` | Check disk space (requires `path`) |

### Torrent Status Values
| Value | Meaning |
|-------|---------|
| 0 | Stopped |
| 1 | Queued to verify |
| 2 | Verifying |
| 3 | Queued to download |
| 4 | Downloading |
| 5 | Queued to seed |
| 6 | Seeding |

## Common torrent_get Fields

```python
TORRENT_FIELDS = [
    "id", "name", "status", "hash_string",
    "percent_done", "rate_download", "rate_upload",
    "total_size", "downloaded_ever", "uploaded_ever",
    "eta", "error", "error_string", "is_finished",
    "peers_connected", "labels", "download_dir"
]
```

## Error Handling

The server returns JSON error responses:

```json
{
  "error": "Instance 'unknown' not found",
  "available_instances": ["home", "seedbox"]
}
```

For RPC errors, the Transmission error is passed through:

```json
{
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {"errorString": "..."}
  }
}
```

## Adding New Specific Tools

To add a new convenience tool, follow this pattern:

```python
@mcp.tool()
async def my_new_tool(instance: str = "") -> str:
    """Tool description for AI agents.
    
    Args:
        instance: Target instance name (uses default if empty)
    """
    try:
        client = registry.get(instance)
        result = await client.rpc("some_method", {"param": "value"})
        return json.dumps(result, indent=2)
    except Exception as e:
        return json.dumps({"error": str(e)})
```

## Testing

```bash
# Install dependencies
pip install -e .

# Create test config
cp .env.example .env
# Edit .env with your Transmission instance

# Run server
python server.py

# Test health endpoint
curl http://localhost:8000/health

# Test with MCP client or use transmission-remote for RPC comparison
transmission-remote --debug localhost:9091 -l
```