commit 7812a3c42d67af856aa0c5665808cf96e5300d7b Author: Ben Date: Tue Dec 30 04:38:44 2025 +0000 Initial commit: multi-instance Transmission MCP server diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..2495952 --- /dev/null +++ b/.env.example @@ -0,0 +1,32 @@ +# Transmission MCP Server Configuration +# Copy this file to .env and configure your instances + +# JSON array of Transmission instances +# Each instance requires: name, url +# Optional: username, password (for authenticated instances) +TRANSMISSION_INSTANCES='[ + { + "name": "home", + "url": "http://192.168.1.100:9091", + "username": "admin", + "password": "secretpassword" + }, + { + "name": "seedbox", + "url": "https://seedbox.example.com:443/transmission", + "username": "user", + "password": "pass" + }, + { + "name": "local", + "url": "http://localhost:9091" + } +]' + +# Default instance to use when no instance is specified +# Must match a "name" from TRANSMISSION_INSTANCES +TRANSMISSION_DEFAULT_INSTANCE=home + +# Server settings +HOST=0.0.0.0 +PORT=8000 diff --git a/.gitea/workflows/build.yml b/.gitea/workflows/build.yml new file mode 100644 index 0000000..4b72fdc --- /dev/null +++ b/.gitea/workflows/build.yml @@ -0,0 +1,46 @@ +name: Build and Push Docker Image + +on: + push: + branches: + - main + +jobs: + build: + runs-on: ubuntu-latest + container: + image: catthehacker/ubuntu:act-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Login to Gitea Container Registry + uses: docker/login-action@v3 + with: + registry: git.nixc.us + username: ${{ secrets.DOCKER_USERNAME }} + password: ${{ secrets.DOCKER_PASSWORD }} + + - name: Extract metadata + id: meta + uses: docker/metadata-action@v5 + with: + images: git.nixc.us/${{ github.repository }} + tags: | + type=ref,event=branch + type=sha,prefix= + type=raw,value=latest,enable={{is_default_branch}} + + - name: Build and push + uses: docker/build-push-action@v5 + with: + context: . + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max diff --git a/BLUEPRINT.md b/BLUEPRINT.md new file mode 120000 index 0000000..5a9cc4e --- /dev/null +++ b/BLUEPRINT.md @@ -0,0 +1 @@ +../BLUEPRINT.md \ No newline at end of file diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..7ffaf86 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,18 @@ +FROM python:3.12-slim + +WORKDIR /app + +# Install dependencies +COPY pyproject.toml . +RUN pip install --no-cache-dir . + +# Copy application +COPY server.py . + +# Health check +HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \ + CMD python -c "import httpx; httpx.get('http://localhost:8000/health').raise_for_status()" + +EXPOSE 8000 + +CMD ["python", "server.py"] diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md new file mode 100644 index 0000000..d9ee865 --- /dev/null +++ b/IMPLEMENTATION.md @@ -0,0 +1,180 @@ +# 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 +``` diff --git a/README.md b/README.md new file mode 100644 index 0000000..b3ac7f0 --- /dev/null +++ b/README.md @@ -0,0 +1,136 @@ +# 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 diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..450e1cd --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,18 @@ +services: + transmission-mcp: + build: . + container_name: transmission-mcp + restart: unless-stopped + ports: + - "8000:8000" + env_file: + - .env + environment: + - HOST=0.0.0.0 + - PORT=8000 + healthcheck: + test: ["CMD", "python", "-c", "import httpx; httpx.get('http://localhost:8000/health').raise_for_status()"] + interval: 30s + timeout: 10s + retries: 3 + start_period: 5s diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..72488f7 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,25 @@ +[project] +name = "transmission-mcp" +version = "0.1.0" +description = "MCP server for managing multiple Transmission daemon instances" +requires-python = ">=3.11" +dependencies = [ + "fastmcp>=2.0.0", + "httpx>=0.28.0", + "starlette>=0.45.0", + "uvicorn>=0.34.0", + "python-dotenv>=1.0.0", +] + +[project.optional-dependencies] +dev = [ + "pytest>=8.0.0", + "pytest-asyncio>=0.24.0", +] + +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[tool.hatch.build.targets.wheel] +packages = ["."] diff --git a/rpc-spec.md b/rpc-spec.md new file mode 100644 index 0000000..da47b45 --- /dev/null +++ b/rpc-spec.md @@ -0,0 +1,1094 @@ +> [!IMPORTANT] +> Transmisson 4.1.0 (`rpc_version_semver` 6.0.0) added support for the JSON-RPC 2.0 protocol and converted all RPC strings to snake_case. +> +> The old bespoke RPC protocol, and the old mix of kebab-case and camelCase strings, are still supported in Transmission 4 but are deprecated and will be removed in the future. People using the old protocol should update their code! +> +> For documentation of the old RPC protocol and strings, please consult documentation from previous versions. +> https://github.com/transmission/transmission/blob/4.0.6/docs/rpc-spec.md + +# Transmission's RPC specification +This document describes a protocol for interacting with Transmission sessions remotely. + +### 1.1 Terminology +The [JSON](https://www.json.org/) terminology in [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259) is used. +RPC requests and responses are formatted in JSON. + +### 1.2 Tools +If `transmission-remote` is called with a `--debug` argument, its RPC traffic to the Transmission server will be dumped to the terminal. This can be useful when you want to compare requests in your application to another for reference. + +If `transmission-qt` is run with an environment variable `TR_RPC_VERBOSE` set, it too will dump the RPC requests and responses to the terminal for inspection. + +Lastly, using the browser's developer tools in the Transmission web client is always an option. + +### 1.3 Libraries of ready-made wrappers +Some people outside of the Transmission project have written libraries that wrap this RPC API. These aren't supported by the Transmission project, but are listed here in the hope that they may be useful: + +| Language | Link +|:---|:--- +| C# | https://www.nuget.org/packages/Transmission.API.RPC +| Go | https://github.com/hekmon/transmissionrpc +| Python | https://github.com/Trim21/transmission-rpc +| Rust | https://crates.io/crates/transmission-rpc + + +## 2 Message format +Transmission follows the [JSON-RPC 2.0](https://www.jsonrpc.org/specification) specification and supports the entirety of it, +except that parameters by-position is not supported, meaning the request parameters must be an Object. + +Response parameters are returned in the `result` Object. + +#### Example request +```json +{ + "jsonrpc": "2.0", + "params": { + "fields": [ "version" ] + }, + "method": "session_get", + "id": 912313 +} +``` + +#### Example response +```json +{ + "jsonrpc": "2.0", + "result": { + "version": "4.1.0-dev (ae226418eb)" + }, + "id": 912313 +} +``` + +### 2.1 Error data + +JSON-RPC 2.0 allows for additional information about an error be included in the `data` key of the Error object in an implementation-defined format. + +In Transmission, this key is an Object that includes: + +1. An optional `errorString` string that provides additional information that is not included in the `message` key of the Error object. +2. An optional `result` Object that contains additional keys defined by the method. + +```json +{ + "jsonrpc": "2.0", + "error": { + "code": 7, + "message": "HTTP error from backend service", + "data": { + "errorString": "Couldn't test port: No Response (0)", + "result": { + "ipProtocol": "ipv6" + } + } + }, + "id": 912313 +} +``` + +### 2.2 Transport mechanism +HTTP POSTing a JSON-encoded request is the preferred way of communicating +with a Transmission RPC server. The current Transmission implementation +has the default URL as `http://host:9091/transmission/rpc`. Clients +may use this as a default, but should allow the URL to be reconfigured, +since the port and path may be changed to allow mapping and/or multiple +daemons to run on a single server. + +The RPC server will normally return HTTP 200 regardless of whether the +request succeeded. For JSON-RPC 2.0 notifications, HTTP 204 will be returned. + +#### 2.2.1 CSRF protection +Most Transmission RPC servers require a `X-Transmission-Session-Id` +header to be sent with requests, to prevent CSRF attacks. + +When your request has the wrong id -- such as when you send your first +request, or when the server expires the CSRF token -- the +Transmission RPC server will return an HTTP 409 error with the +right `X-Transmission-Session-Id` in its own headers. + +So, the correct way to handle a 409 response is to update your +`X-Transmission-Session-Id` and to resend the previous request. + +#### 2.2.2 DNS rebinding protection +Additional check is being made on each RPC request to make sure that the +client sending the request does so using one of the allowed hostnames by +which RPC server is meant to be available. + +If host whitelisting is enabled (which is true by default), Transmission +inspects the `Host:` HTTP header value (with port stripped, if any) and +matches it to one of the whitelisted names. Regardless of host whitelist +content, `localhost` and `localhost.` domain names as well as all the IP +addresses are always implicitly allowed. + +For more information on configuration, see settings.json documentation for +`rpc_host_whitelist_enabled` and `rpc_host_whitelist` keys. + +#### 2.2.3 Authentication +Enabling authentication is an optional security feature that can be enabled +on Transmission RPC servers. Authentication occurs by method of HTTP Basic +Access Authentication. + +If authentication is enabled, Transmission inspects the `Authorization:` +HTTP header value to validate the credentials of the request. The value +of this HTTP header is expected to be [`Basic `](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization#basic), +where is equal to a base64 encoded string of the +username and password (respectively), separated by a colon. + +## 3 Torrent requests +### 3.1 Torrent action requests +| Method name | libtransmission function | Description +|:--|:--|:-- +| `torrent_start` | tr_torrentStart | start torrent +| `torrent_start_now` | tr_torrentStartNow | start torrent disregarding queue position +| `torrent_stop` | tr_torrentStop | stop torrent +| `torrent_verify` | tr_torrentVerify | verify torrent +| `torrent_reannounce` | tr_torrentManualUpdate | re-announce to trackers now + +Request parameters: `ids`, which specifies which torrents to use. +All torrents are used if the `ids` parameter is omitted. + +`ids` should be one of the following: + +1. an integer referring to a torrent id +2. a list of torrent id numbers, SHA1 hash strings, or both +3. a string, `recently_active`, for recently-active torrents + +Note that integer torrent ids are not stable across Transmission daemon +restarts. Use torrent hashes if you need stable ids. + +Response parameters: none + +### 3.2 Torrent mutator: `torrent_set` +Method name: `torrent_set` + +Request parameters: + +| Key | Value Type | Value Description +|:--|:--|:-- +| `bandwidth_priority` | number | this torrent's bandwidth tr_priority_t +| `download_limit` | number | maximum download speed (kB/s) +| `download_limited` | boolean | true if `download_limit` is honored +| `files_unwanted` | array | indices of file(s) to not download +| `files_wanted` | array | indices of file(s) to download +| `group` | string | The name of this torrent's bandwidth group +| `honors_session_limits` | boolean | true if session upload limits are honored +| `ids` | array | torrent list, as described in 3.1 +| `labels` | array | array of string labels +| `location` | string | new location of the torrent's content +| `peer_limit` | number | maximum number of peers +| `priority_high` | array | indices of high-priority file(s) +| `priority_low` | array | indices of low-priority file(s) +| `priority_normal` | array | indices of normal-priority file(s) +| `queue_position` | number | position of this torrent in its queue [0...n) +| `seed_idle_limit` | number | torrent-level number of minutes of seeding inactivity +| `seed_idle_mode` | number | which seeding inactivity to use. See tr_idlelimit +| `seed_ratio_limit` | double | torrent-level seeding ratio +| `seed_ratio_mode` | number | which ratio to use. See tr_ratiolimit +| `sequential_download` | boolean | download torrent pieces sequentially +| `sequential_download_from_piece` | number | download from a specific piece when sequential download is enabled +| `tracker_add` | array | **DEPRECATED** use `tracker_list` instead +| `tracker_list` | string | string of announce URLs, one per line, and a blank line between [tiers](https://www.bittorrent.org/beps/bep_0012.html). +| `tracker_remove` | array | **DEPRECATED** use `tracker_list` instead +| `tracker_replace` | array | **DEPRECATED** use `tracker_list` instead +| `upload_limit` | number | maximum upload speed (kB/s) +| `upload_limited` | boolean | true if `upload_limit` is honored + +Just as an empty `ids` value is shorthand for "all ids", using an empty array +for `files_wanted`, `files_unwanted`, `priority_high`, `priority_low`, or +`priority_normal` is shorthand for saying "all files". + + Response parameters: none + +### 3.3 Torrent accessor: `torrent_get` +Method name: `torrent_get`. + +Request parameters: + +1. An optional `ids` array as described in 3.1. +2. A required `fields` array of keys. (see list below) +3. An optional `format` string specifying how to format the + `torrents` response field. Allowed values are `objects` + (default) and `table`. (see "Response parameters" below) + +Response parameters: + +1. A `torrents` array. + + If the `format` request was `objects` (default), `torrents` will + be an array of objects, each of which contains the key/value + pairs matching the request's `fields` arg. This was the only + format before Transmission 3 and has some obvious programmer + conveniences, such as parsing directly into Javascript objects. + + If the format was `table`, then `torrents` will be an array of + arrays. The first row holds the keys and each remaining row holds + a torrent's values for those keys. This format is more efficient + in terms of JSON generation and JSON parsing. + +2. If the request's `ids` field was `recently_active`, + a `removed` array of torrent-id numbers of recently-removed + torrents. + +Note: For more information on what these fields mean, see the comments +in [libtransmission/transmission.h](../libtransmission/transmission.h). +The 'source' column here corresponds to the data structure there. + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `activity_date` | number | tr_stat +| `added_date` | number | tr_stat +| `availability` | array (see below)| tr_torrentAvailability() +| `bandwidth_priority` | number | tr_priority_t +| `bytes_completed` | array (see below)| n/a +| `comment` | string | tr_torrent_view +| `corrupt_ever`| number | tr_stat +| `creator`| string | tr_torrent_view +| `date_created`| number| tr_torrent_view +| `desired_available`| number| tr_stat +| `done_date`| number | tr_stat +| `download_dir` | string | tr_torrent +| `downloaded_ever` | number | tr_stat +| `download_limit` | number | tr_torrent +| `download_limited` | boolean | tr_torrent +| `edit_date` | number | tr_stat +| `error` | number | tr_stat +| `error_string` | string | tr_stat +| `eta` | number | tr_stat +| `eta_idle` | number | tr_stat +| `file_count` | number | tr_info +| `files`| array (see below)| n/a +| `file_stats`| array (see below)| n/a +| `group`| string| n/a +| `hash_string`| string| tr_torrent_view +| `have_unchecked`| number| tr_stat +| `have_valid`| number| tr_stat +| `honors_session_limits`| boolean| tr_torrent +| `id` | number | tr_torrent +| `is_finished` | boolean| tr_stat +| `is_private` | boolean| tr_torrent +| `is_stalled` | boolean| tr_stat +| `labels` | array of strings | tr_torrent +| `left_until_done` | number| tr_stat +| `magnet_link` | string| n/a +| `manual_announce_time` | number| **DEPRECATED** don't use it, it never worked +| `max_connected_peers` | number| tr_torrent +| `metadata_percent_complete` | double| tr_stat +| `name` | string| tr_torrent_view +| `peer_limit` | number| tr_torrent +| `peers` | array (see below)| n/a +| `peers_connected` | number| tr_stat +| `peers_from` | object (see below)| n/a +| `peers_getting_from_us` | number| tr_stat +| `peers_sending_to_us` | number| tr_stat +| `percent_complete` | double | tr_stat +| `percent_done` | double | tr_stat +| `pieces` | string (see below)| tr_torrent +| `piece_count`| number| tr_torrent_view +| `piece_size`| number| tr_torrent_view +| `priorities`| array (see below)| n/a +| `primary_mime_type`| string| tr_torrent +| `queue_position`| number| tr_stat +| `rate_download` (B/s)| number| tr_stat +| `rate_upload` (B/s)| number| tr_stat +| `recheck_progress`| double| tr_stat +| `seconds_downloading`| number| tr_stat +| `seconds_seeding`| number| tr_stat +| `seed_idle_limit`| number| tr_torrent +| `seed_idle_mode`| number| tr_inactivelimit +| `seed_ratio_limit`| double| tr_torrent +| `seed_ratio_mode`| number| tr_ratiolimit +| `sequential_download`| boolean| tr_torrent +| `sequential_download_from_piece`| number| tr_torrent +| `size_when_done`| number| tr_stat +| `start_date`| number| tr_stat +| `status`| number (see below)| tr_stat +| `torrent_file`| string| tr_info +| `total_size`| number| tr_torrent_view +| `trackers`| array (see below)| n/a +| `tracker_list` | string | string of announce URLs, one per line, with a blank line between tiers +| `tracker_stats`| array (see below)| n/a +| `uploaded_ever`| number| tr_stat +| `upload_limit`| number| tr_torrent +| `upload_limited`| boolean| tr_torrent +| `upload_ratio`| double| tr_stat +| `wanted`| array (see below)| n/a +| `webseeds`| array of strings | tr_tracker_view +| `webseeds_sending_to_us`| number| tr_stat + +`availability`: An array of `piece_count` numbers representing the number of connected peers that have each piece, or -1 if we already have the piece ourselves. + +`bytes_completed`: An array of `tr_info.filecount` numbers. Each is the completed bytes for the corresponding file. + +`files`: array of objects, each containing: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `bytes_completed` | number | tr_file_view +| `length` | number | tr_file_view +| `name` | string | tr_file_view +| `begin_piece` | number | tr_file_view +| `end_piece` | number | tr_file_view + +Files are returned in the order they are laid out in the torrent. References to "file indices" throughout this specification should be interpreted as the position of the file within this ordering, with the first file bearing index 0. + +`file_stats`: a file's non-constant properties. An array of `tr_info.filecount` objects, in the same order as `files`, each containing: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `bytes_completed` | number | tr_file_view +| `wanted` | boolean | tr_file_view +| `priority` | number | tr_file_view + +`peers`: an array of objects, each containing: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `address` | string | tr_peer_stat +| `bytes_to_client` | number | tr_peer_stat +| `bytes_to_peer` | number | tr_peer_stat +| `client_is_choked` | boolean | tr_peer_stat +| `client_is_interested` | boolean | tr_peer_stat +| `client_name` | string | tr_peer_stat +| `flag_str` | string | tr_peer_stat +| `is_downloading_from` | boolean | tr_peer_stat +| `is_encrypted` | boolean | tr_peer_stat +| `is_incoming` | boolean | tr_peer_stat +| `is_uploading_to` | boolean | tr_peer_stat +| `is_utp` | boolean | tr_peer_stat +| `peer_id` | string | tr_peer_stat +| `peer_is_choked` | boolean | tr_peer_stat +| `peer_is_interested` | boolean | tr_peer_stat +| `port` | number | tr_peer_stat +| `progress` | double | tr_peer_stat +| `rate_to_client` (B/s) | number | tr_peer_stat +| `rate_to_peer` (B/s) | number | tr_peer_stat + +`peers_from`: an object containing: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `from_cache` | number | tr_stat +| `from_dht` | number | tr_stat +| `from_incoming` | number | tr_stat +| `from_lpd` | number | tr_stat +| `from_ltep` | number | tr_stat +| `from_pex` | number | tr_stat +| `from_tracker` | number | tr_stat + + +`pieces`: A bitfield holding `piece_count` flags which are set to 'true' if we have the piece matching that position. JSON doesn't allow raw binary data, so this is a base64-encoded string. (Source: tr_torrent) + +`priorities`: An array of `tr_torrentFileCount()` numbers. Each is the `tr_priority_t` mode for the corresponding file. + +`status`: A number between 0 and 6, where: + +| Value | Meaning +|:--|:-- +| 0 | Torrent is stopped +| 1 | Torrent is queued to verify local data +| 2 | Torrent is verifying local data +| 3 | Torrent is queued to download +| 4 | Torrent is downloading +| 5 | Torrent is queued to seed +| 6 | Torrent is seeding + + +`trackers`: array of objects, each containing: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `announce` | string | tr_tracker_view +| `id` | number | tr_tracker_view +| `scrape` | string | tr_tracker_view +| `sitename` | string | tr_tracker_view +| `tier` | number | tr_tracker_view + +`tracker_stats`: array of objects, each containing: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `announce` | string | tr_tracker_view +| `announce_state` | number | tr_tracker_view +| `download_count` | number | tr_tracker_view +| `downloader_count` | number | tr_tracker_view +| `has_announced` | boolean | tr_tracker_view +| `has_scraped` | boolean | tr_tracker_view +| `host` | string | tr_tracker_view +| `id` | number | tr_tracker_view +| `is_backup` | boolean | tr_tracker_view +| `last_announce_peer_count` | number | tr_tracker_view +| `last_announce_result` | string | tr_tracker_view +| `last_announce_start_time` | number | tr_tracker_view +| `last_announce_succeeded` | boolean | tr_tracker_view +| `last_announce_time` | number | tr_tracker_view +| `last_announce_timed_out` | boolean | tr_tracker_view +| `last_scrape_result` | string | tr_tracker_view +| `last_scrape_start_time` | number | tr_tracker_view +| `last_scrape_succeeded` | boolean | tr_tracker_view +| `last_scrape_time` | number | tr_tracker_view +| `last_scrape_timed_out` | boolean | tr_tracker_view +| `leecher_count` | number | tr_tracker_view +| `next_announce_time` | number | tr_tracker_view +| `next_scrape_time` | number | tr_tracker_view +| `scrape` | string | tr_tracker_view +| `scrape_state` | number | tr_tracker_view +| `seeder_count` | number | tr_tracker_view +| `sitename` | string | tr_tracker_view +| `tier` | number | tr_tracker_view + + +`wanted`: An array of `tr_torrentFileCount()` booleans, true if the corresponding file is to be downloaded. (Source: `tr_file_view`) + +**Note:** For backwards compatibility, in the old bespoke API, `wanted` is serialized as an array of `0` or `1` that should be treated as booleans. + +Example: + +Say we want to get the name and total size of torrents #7 and #10. + +Request: + +```json +{ + "jsonrpc": "2.0", + "params": { + "fields": [ "id", "name", "total_size" ], + "ids": [ 7, 10 ] + }, + "method": "torrent_get", + "id": 39693 +} +``` + +Response: + +```json +{ + "jsonrpc": "2.0", + "result": { + "torrents": [ + { + "id": 10, + "name": "Fedora x86_64 DVD", + "total_size": 34983493932 + }, + { + "id": 7, + "name": "Ubuntu x86_64 DVD", + "total_size": 9923890123 + } + ] + }, + "id": 39693 +} +``` + +### 3.4 Adding a torrent +Method name: `torrent_add` + +Request parameters: + +| Key | Value Type | Description +|:--|:--|:-- +| `cookies` | string | pointer to a string of one or more cookies. +| `download_dir` | string | path to download the torrent to +| `filename` | string | filename or URL of the .torrent file +| `labels` | array | array of string labels +| `metainfo` | string | base64-encoded .torrent content +| `paused` | boolean | if true, don't start the torrent +| `peer_limit` | number | maximum number of peers +| `bandwidth_priority` | number | torrent's bandwidth tr_priority_t +| `files_wanted` | array | indices of file(s) to download +| `files_unwanted` | array | indices of file(s) to not download +| `priority_high` | array | indices of high-priority file(s) +| `priority_low` | array | indices of low-priority file(s) +| `priority_normal` | array | indices of normal-priority file(s) +| `sequential_download` | boolean | download torrent pieces sequentially +| `sequential_download_from_piece` | number | download from a specific piece when sequential download is enabled + +Either `filename` **or** `metainfo` **must** be included. All other parameters are optional. + +The format of the `cookies` should be `NAME=CONTENTS`, where `NAME` is the cookie name and `CONTENTS` is what the cookie should contain. Set multiple cookies like this: `name1=content1; name2=content2;` etc. See [libcurl documentation](http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCOOKIE) for more information. + +Response parameters: + +* On success, a `torrent_added` object in the form of one of 3.3's torrent objects with the fields for `id`, `name`, and `hash_string`. + +* When attempting to add a duplicate torrent, a `torrent_duplicate` object in the same form is returned, but the response's `result` value is still `success`. + +### 3.5 Removing a torrent +Method name: `torrent_remove` + +| Key | Value Type | Description +|:--|:--|:-- +| `ids` | array | torrent list, as described in 3.1 +| `delete_local_data` | boolean | delete local data. (default: false) + +Response parameters: none + +### 3.6 Moving a torrent +Method name: `torrent_set_location` + +Request parameters: + +| Key | Value Type | Description +|:--|:--|:-- +| `ids` | array | torrent list, as described in 3.1 +| `location` | string | the new torrent location +| `move` | boolean | if true, move from previous location. otherwise, search `location` for files (default: false) + +Response parameters: none + +### 3.7 Renaming a torrent's path +Method name: `torrent_rename_path` + +For more information on the use of this function, see the transmission.h +documentation of `tr_torrentRenamePath()`. In particular, note that if this +call succeeds you'll want to update the torrent's `files` and `name` field +with `torrent_get`. + +Request parameters: + +| Key | Value Type | Description +|:--|:--|:-- +| `ids` | array | the torrent list, as described in 3.1 (must only be 1 torrent) +| `path` | string | the path to the file or folder that will be renamed +| `name` | string | the file or folder's new name + +Response parameters: `path`, `name`, and `id`, holding the torrent ID integer + +## 4 Session requests +### 4.1 Session parameters +| Key | Value Type | Description +|:--|:--|:-- +| `alt_speed_down` | number | max global download speed (kB/s) +| `alt_speed_enabled` | boolean | true means use the alt speeds +| `alt_speed_time_begin` | number | when to turn on alt speeds (units: minutes after midnight) +| `alt_speed_time_day` | number | what day(s) to turn on alt speeds (look at tr_sched_day) +| `alt_speed_time_enabled` | boolean | true means the scheduled on/off times are used +| `alt_speed_time_end` | number | when to turn off alt speeds (units: same) +| `alt_speed_up` | number | max global upload speed (kB/s) +| `anti_brute_force_enabled` | boolean | true means to enable a basic brute force protection for RPC server +| `blocklist_enabled` | boolean | true means enabled +| `blocklist_size` | number | number of rules in the blocklist +| `blocklist_url` | string | location of the blocklist to use for `blocklist_update` +| `cache_size_mib` | number | maximum size of the disk cache (MiB). Pieces are guaranteed to be written to filesystem if sequential download is enabled. Otherwise, data might still be in cache only. +| `config_dir` | string | location of transmission's configuration directory +| `default_trackers` | string | announce URLs, one per line, and a blank line between [tiers](https://www.bittorrent.org/beps/bep_0012.html). +| `dht_enabled` | boolean | true means allow DHT in public torrents +| `download_dir` | string | default path to download torrents +| `download_dir_free_space` | number | **DEPRECATED** Use the `free_space` method instead. +| `download_queue_enabled` | boolean | if true, limit how many torrents can be downloaded at once +| `download_queue_size` | number | max number of torrents to download at once (see `download_queue_enabled`) +| `encryption` | string | `required`, `preferred`, `tolerated` +| `idle_seeding_limit` | number | torrents we're seeding will be stopped if they're idle for this long +| `idle_seeding_limit_enabled` | boolean | true if the seeding inactivity limit is honored by default +| `incomplete_dir` | string | path for incomplete torrents, when enabled +| `incomplete_dir_enabled` | boolean | true means keep torrents in `incomplete_dir` until done +| `lpd_enabled` | boolean | true means allow Local Peer Discovery in public torrents +| `peer_limit_global` | number | maximum global number of peers +| `peer_limit_per_torrent` | number | maximum global number of peers +| `peer_port_random_on_start` | boolean | true means pick a random peer port on launch +| `peer_port` | number | port number +| `pex_enabled` | boolean | true means allow PEX in public torrents +| `port_forwarding_enabled` | boolean | true means ask upstream router to forward the configured peer port to transmission using UPnP or NAT-PMP +| `preferred_transports` | string[] | preference of transport protocols, see `settings.json` for details +| `queue_stalled_enabled` | boolean | whether or not to consider idle torrents as stalled +| `queue_stalled_minutes` | number | torrents that are idle for N minuets aren't counted toward `seed_queue_size` or `download_queue_size` +| `rename_partial_files` | boolean | true means append `.part` to incomplete files +| `reqq` | number | the number of outstanding block requests a peer is allowed to queue in the client +| `rpc_version_minimum` | number | **DEPRECATED** the minimum RPC API version supported +| `rpc_version_semver` | string | the current RPC API version in a [semver](https://semver.org)-compatible string +| `rpc_version` | number | **DEPRECATED** the current RPC API version +| `script_torrent_added_enabled` | boolean | whether or not to call the `added` script +| `script_torrent_added_filename` | string | filename of the script to run +| `script_torrent_done_enabled` | boolean | whether or not to call the `done` script +| `script_torrent_done_filename` | string | filename of the script to run +| `script_torrent_done_seeding_enabled` | boolean | whether or not to call the `seeding_done` script +| `script_torrent_done_seeding_filename` | string | filename of the script to run +| `seed_queue_enabled` | boolean | if true, limit how many torrents can be uploaded at once +| `seed_queue_size` | number | max number of torrents to uploaded at once (see `seed_queue_enabled`) +| `seed_ratio_limit` | double | the default seed ratio for torrents to use +| `seed_ratio_limited` | boolean | true if `seed_ratio_limit` is honored by default +| `sequential_download` | boolean | true means sequential download is enabled by default for added torrents +| `session_id` | string | the current `X-Transmission-Session-Id` value +| `speed_limit_down` | number | max global download speed (kB/s) +| `speed_limit_down_enabled` | boolean | true means enabled +| `speed_limit_up` | number | max global upload speed (kB/s) +| `speed_limit_up_enabled` | boolean | true means enabled +| `start_added_torrents` | boolean | true means added torrents will be started right away +| `tcp_enabled` | boolean | true means allow TCP +| `trash_original_torrent_files` | boolean | true means the .torrent file of added torrents will be deleted +| `units` | object | see below +| `utp_enabled` | boolean | **DEPRECATED** Use `preferred_transports` instead +| `version` | string | long version string `$version ($revision)` + + +`units`: an object containing: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `speed_units` | array | 4 strings: KB/s, MB/s, GB/s, TB/s +| `speed_bytes` | number | number of bytes in a KB (1000 for kB; 1024 for KiB) +| `size_units` | array | 4 strings: KB/s, MB/s, GB/s, TB/s +| `size_bytes` | number | number of bytes in a KB (1000 for kB; 1024 for KiB) +| `memory_units` | array | 4 strings: KB/s, MB/s, GB/s, TB/s +| `memory_bytes` | number | number of bytes in a KB (1000 for kB; 1024 for KiB) + +#### 4.1.1 Mutators +Method name: `session_set` + +Request parameters: the mutable properties from 4.1's parameters, i.e. all of them +except: + +* `blocklist_size` +* `config_dir` +* `rpc_version_minimum`, +* `rpc_version_semver` +* `rpc_version` +* `session_id` +* `tcp_enabled` +* `units` +* `version` + +Response parameters: none + +#### 4.1.2 Accessors +Method name: `session_get` + +Request parameters: an optional `fields` array of keys (see 4.1) + +Response parameters: key/value pairs matching the request's `fields` +parameter if present, or all supported fields (see 4.1) otherwise. + +### 4.2 Session statistics +Method name: `session_stats` + +Request parameters: none + +Response parameters: + +| Key | Value Type | Description +|:--|:--|:-- +| `active_torrent_count` | number +| `download_speed` | number +| `paused_torrent_count` | number +| `torrent_count` | number +| `upload_speed` | number +| `cumulative_stats` | stats object (see below) +| `current_stats` | stats object (see below) + +A stats object contains: + +| Key | Value Type | transmission.h source +|:--|:--|:-- +| `uploaded_bytes` | number | tr_session_stats +| `downloaded_bytes` | number | tr_session_stats +| `files_added` | number | tr_session_stats +| `seconds_active` | number | tr_session_stats +| `session_count` | number | tr_session_stats + +### 4.3 Blocklist +Method name: `blocklist_update` + +Request parameters: none + +Response parameters: a number `blocklist_size` + +### 4.4 Port checking +This method tests to see if your incoming peer port is accessible +from the outside world. + +Method name: `port_test` + +Request parameters: an optional parameter `ip_protocol`. +`ip_protocol` is a string specifying the IP protocol version to be used for the port test. +Set to `ipv4` to check IPv4, or set to `ipv6` to check IPv6. +For backwards compatibility, it is allowed to omit this parameter to get the behaviour before Transmission `4.1.0`, +which is to check whichever IP protocol the OS happened to use to connect to our port test service, +frankly not very useful. + +Response parameters: + +| Key | Value Type | Description +| :-- | :-- | :-- +| `port_is_open` | boolean | true if port is open, false if port is closed +| `ip_protocol` | string | `ipv4` if the test was carried out on IPv4, `ipv6` if the test was carried out on IPv6, unset if it cannot be determined + +### 4.5 Session shutdown +This method tells the Transmission session to shut down. + +Method name: `session_close` + +Request parameters: none + +Response parameters: none + +### 4.6 Queue movement requests +| Method name | transmission.h source +|:--|:-- +| `queue_move_top` | tr_torrentQueueMoveTop() +| `queue_move_up` | tr_torrentQueueMoveUp() +| `queue_move_down` | tr_torrentQueueMoveDown() +| `queue_move_bottom` | tr_torrentQueueMoveBottom() + +Request parameters: + +| Key | Value Type | Description +|:--|:--|:-- +| `ids` | array | torrent list, as described in 3.1. + +Response parameters: none + +### 4.7 Free space +This method tests how much free space is available in a +client-specified folder. + +Method name: `free_space` + +Request parameters: + +| Key | Value type | Description +|:--|:--|:-- +| `path` | string | the directory to query + +Response parameters: + +| Key | Value type | Description +|:--|:--|:-- +| `path` | string | same as the Request parameter +| `size_bytes` | number | the size, in bytes, of the free space in that directory +| `total_size` | number | the total capacity, in bytes, of that directory + +### 4.8 Bandwidth groups +#### 4.8.1 Bandwidth group mutator: `group_set` +Method name: `group_set` + +Request parameters: + +| Key | Value type | Description +|:--|:--|:-- +| `honors_session_limits` | boolean | true if session upload limits are honored +| `name` | string | Bandwidth group name +| `speed_limit_down` | number | max global download speed (kB/s) +| `speed_limit_down_enabled` | boolean | true means enabled +| `speed_limit_up` | number | max global upload speed (kB/s) +| `speed_limit_up_enabled` | boolean | true means enabled + +Response parameters: none + +#### 4.8.2 Bandwidth group accessor: `group_get` +Method name: `group_get` + +Request parameters: An optional parameter `group`. +`group` is either a string naming the bandwidth group, +or a list of such strings. +If `group` is omitted, all bandwidth groups are used. + +Response parameters: + +| Key | Value type | Description +|:--|:--|:-- +|`group`| array | A list of bandwidth group description objects + +A bandwidth group description object has: + +| Key | Value type | Description +|:--|:--|:-- +| `honors_session_limits` | boolean | true if session upload limits are honored +| `name` | string | Bandwidth group name +| `speed_limit_down` | number | max global download speed (kB/s) +| `speed_limit_down_enabled` | boolean | true means enabled +| `speed_limit_up` | number | max global upload speed (kB/s) +| `speed_limit_up_enabled` | boolean | true means enabled + +## 5 Protocol versions +This section lists the changes that have been made to the RPC protocol. + +There are two ways to check for API compatibility. Since most developers know +[semver](https://semver.org/), `session_get`'s `rpc_version_semver` is the +recommended way. That value is a semver-compatible string of the RPC protocol +version number. + +**DEPRECATED** Since Transmission predates the semver 1.0 spec, the previous scheme was for +the RPC version to be a whole number and to increment it whenever a change was +made. That is `session_get`'s `rpc_version`. `rpc_version_minimum` lists the +oldest version that is compatible with the current version; i.e. an app coded +to use `rpc_version_minimum` would still work on a Transmission release running +`rpc_version`. + +Starting from `rpc-version-semver` 6.0.0, Transmission returns the RPC +version in an HTTP header `X-Transmission-Rpc-Version: {rpc_version_semver}` +in the CSRF HTTP 409 response. This is so +that clients supporting both JSON-RPC and the old bespoke API can determine +which scheme to use without making any extra requests. +Example: `X-Transmission-Rpc-Version: 6.0.0` + +Breaking changes are denoted with a :bomb: emoji. + +Transmission 1.30 (`rpc-version-semver` 1.0.0, `rpc-version`: 1) + +Initial revision. + +Transmission 1.40 (`rpc-version-semver` 1.1.0, `rpc-version`: 2) + +| Method | Description +|:---|:--- +| `torrent-get` | new `port` to `peers` + +Transmission 1.41 (`rpc-version-semver` 1.2.0, `rpc-version`: 3) + +| Method | Description +|:---|:--- +| `session-get` | new arg `version` +| `torrent-get` | new arg `downloaders` +| `torrent-remove` | new method + +Transmission 1.50 (`rpc-version-semver` 1.3.0, `rpc-version`: 4) + +| Method | Description +|:---|:--- +|`session-get` | new arg `rpc-version-minimum` +|`session-get` | new arg `rpc-version` +|`session-stats` | added `cumulative-stats` +|`session-stats` | added `current-stats` +|`torrent-get` | new arg `downloadDir` + +Transmission 1.60 (`rpc-version-semver` 2.0.0, `rpc-version`: 5) + +| Method | Description +|:---|:--- +| `session-get` | :bomb: renamed `peer-limit` to `peer-limit-global` +| `session-get` | :bomb: renamed `pex-allowed` to `pex-enabled` +| `session-get` | :bomb: renamed `port` to `peer-port` +| `torrent-get` | :bomb: removed arg `downloadLimitMode` +| `torrent-get` | :bomb: removed arg `uploadLimitMode` +| `torrent-set` | :bomb: renamed `speed-limit-down-enabled` to `downloadLimited` +| `torrent-set` | :bomb: renamed `speed-limit-down` to `downloadLimit` +| `torrent-set` | :bomb: renamed `speed-limit-up-enabled` to `uploadLimited` +| `torrent-set` | :bomb: renamed `speed-limit-up` to `uploadLimit` +| `blocklist-update` | new method +| `port-test` | new method +| `session-get` | new arg `alt-speed-begin` +| `session-get` | new arg `alt-speed-down` +| `session-get` | new arg `alt-speed-enabled` +| `session-get` | new arg `alt-speed-end` +| `session-get` | new arg `alt-speed-time-enabled` +| `session-get` | new arg `alt-speed-up` +| `session-get` | new arg `blocklist-enabled` +| `session-get` | new arg `blocklist-size` +| `session-get` | new arg `peer-limit-per-torrent` +| `session-get` | new arg `seedRatioLimit` +| `session-get` | new arg `seedRatioLimited` +| `torrent-add` | new arg `files-unwanted` +| `torrent-add` | new arg `files-wanted` +| `torrent-add` | new arg `priority-high` +| `torrent-add` | new arg `priority-low` +| `torrent-add` | new arg `priority-normal` +| `torrent-get` | new arg `bandwidthPriority` +| `torrent-get` | new arg `fileStats` +| `torrent-get` | new arg `honorsSessionLimits` +| `torrent-get` | new arg `percentDone` +| `torrent-get` | new arg `pieces` +| `torrent-get` | new arg `seedRatioLimit` +| `torrent-get` | new arg `seedRatioMode` +| `torrent-get` | new arg `torrentFile` +| `torrent-get` | new ids option `recently-active` +| `torrent-reannounce` | new method +| `torrent-set` | new arg `bandwidthPriority` +| `torrent-set` | new arg `honorsSessionLimits` +| `torrent-set` | new arg `seedRatioLimit` +| `torrent-set` | new arg `seedRatioLimited` + +Transmission 1.70 (`rpc-version-semver` 2.1.0, `rpc-version`: 6) + +| Method | Description +|:---|:--- +| method `torrent-set-location` | new method + +Transmission 1.80 (`rpc-version-semver` 3.0.0, `rpc-version`: 7) + +| Method | Description +|:---|:--- +| `torrent-get` | :bomb: removed arg `announceResponse` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `announceURL` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `downloaders` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `lastAnnounceTime` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `lastScrapeTime` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `leechers` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `nextAnnounceTime` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `nextScrapeTime` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `scrapeResponse` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `scrapeURL` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `seeders` (use `trackerStats instead`) +| `torrent-get` | :bomb: removed arg `swarmSpeed` +| `torrent-get` | :bomb: removed arg `timesCompleted` (use `trackerStats instead`) +| `session-set` | new arg `incomplete-dir-enabled` +| `session-set` | new arg `incomplete-dir` +| `torrent-get` | new arg `magnetLink` +| `torrent-get` | new arg `metadataPercentComplete` +| `torrent-get` | new arg `trackerStats` + +Transmission 1.90 (`rpc-version-semver` 3.1.0, `rpc-version`: 8) + +| Method | Description +|:---|:--- +| `session-set` | new arg `rename-partial-files` +| `session-get` | new arg `rename-partial-files` +| `session-get` | new arg `config-dir` +| `torrent-add` | new arg `bandwidthPriority` +| `torrent-get` | new trackerStats arg `lastAnnounceTimedOut` + +Transmission 1.92 (`rpc-version-semver` 3.2.0, `rpc-version`: 8) + +Note: `rpc-version` was not bumped in this release due to an oversight. + +| Method | Description +|:---|:--- +| `torrent-get` | new trackerStats arg `lastScrapeTimedOut` + +Transmission 2.00 (`rpc-version-semver` 3.3.0, `rpc-version`: 9) + +| Method | Description +|:---|:--- +| `session-set` | new arg `start-added-torrents` +| `session-set` | new arg `trash-original-torrent-files` +| `session-get` | new arg `start-added-torrents` +| `session-get` | new arg `trash-original-torrent-files` +| `torrent-get` | new arg `isFinished` + +Transmission 2.10 (`rpc-version-semver` 3.4.0, `rpc-version`: 10) + +| Method | Description +|:---|:--- +| `session-get` | new arg `cache-size-mb` +| `session-get` | new arg `units` +| `session-set` | new arg `idle-seeding-limit-enabled` +| `session-set` | new arg `idle-seeding-limit` +| `torrent-set` | new arg `seedIdleLimit` +| `torrent-set` | new arg `seedIdleMode` +| `torrent-set` | new arg `trackerAdd` +| `torrent-set` | new arg `trackerRemove` +| `torrent-set` | new arg `trackerReplace` + +Transmission 2.12 (`rpc-version-semver` 3.5.0, `rpc-version`: 11) + +| Method | Description +|:---|:--- +| `session-get` | new arg `blocklist-url` +| `session-set` | new arg `blocklist-url` + +Transmission 2.20 (`rpc-version-semver` 3.6.0, `rpc-version`: 12) + +| Method | Description +|:---|:--- +| `session-get` | new arg `download-dir-free-space` +| `session-close` | new method + +Transmission 2.30 (`rpc-version-semver` 4.0.0, `rpc-version`: 13) + +| Method | Description +|:---|:--- +| `torrent-get` | :bomb: removed arg `peersKnown` +| `torrent-get` | new arg `isUTP` to the `peers` list +| `torrent-add` | new arg `cookies` + +Transmission 2.40 (`rpc-version-semver` 5.0.0, `rpc-version`: 14) + +| Method | Description +|:---|:--- +| `torrent-get` | :bomb: values of `status` field changed +| `queue-move-bottom` | new method +| `queue-move-down` | new method +| `queue-move-top` | new method +| `session-set` | new arg `download-queue-enabled` +| `session-set` | new arg `download-queue-size` +| `session-set` | new arg `queue-stalled-enabled` +| `session-set` | new arg `queue-stalled-minutes` +| `session-set` | new arg `seed-queue-enabled` +| `session-set` | new arg `seed-queue-size` +| `torrent-get` | new arg `fromLpd` in `peersFrom` +| `torrent-get` | new arg `isStalled` +| `torrent-get` | new arg `queuePosition` +| `torrent-set` | new arg `queuePosition` +| `torrent-start-now` | new method + +Transmission 2.80 (`rpc-version-semver` 5.1.0, `rpc-version`: 15) + +| Method | Description +|:---|:--- +| `torrent-get` | new arg `etaIdle` +| `torrent-rename-path` | new method +| `free-space` | new method +| `torrent-add` | new return arg `torrent-duplicate` + +Transmission 3.00 (`rpc-version-semver` 5.2.0, `rpc-version`: 16) + +| Method | Description +|:---|:--- +| `session-get` | new request arg `fields` +| `session-get` | new arg `session-id` +| `torrent-get` | new arg `labels` +| `torrent-set` | new arg `labels` +| `torrent-get` | new arg `editDate` +| `torrent-get` | new request arg `format` + +Transmission 4.0.0 (`rpc-version-semver` 5.3.0, `rpc-version`: 17) + +| Method | Description +|:---|:--- +| `/upload` | :warning: undocumented `/upload` endpoint removed +| `session-get` | :warning: **DEPRECATED** `download-dir-free-space`. Use `free-space` instead. +| `free-space` | new return arg `total_size` +| `session-get` | new arg `default-trackers` +| `session-get` | new arg `rpc-version-semver` +| `session-get` | new arg `script-torrent-added-enabled` +| `session-get` | new arg `script-torrent-added-filename` +| `session-get` | new arg `script-torrent-done-seeding-enabled` +| `session-get` | new arg `script-torrent-done-seeding-filename` +| `torrent-add` | new arg `labels` +| `torrent-get` | new arg `availability` +| `torrent-get` | new arg `file-count` +| `torrent-get` | new arg `group` +| `torrent-get` | new arg `percentComplete` +| `torrent-get` | new arg `primary-mime-type` +| `torrent-get` | new arg `tracker.sitename` +| `torrent-get` | new arg `trackerStats.sitename` +| `torrent-get` | new arg `trackerList` +| `torrent-set` | new arg `group` +| `torrent-set` | new arg `trackerList` +| `torrent-set` | :warning: **DEPRECATED** `trackerAdd`. Use `trackerList` instead. +| `torrent-set` | :warning: **DEPRECATED** `trackerRemove`. Use `trackerList` instead. +| `torrent-set` | :warning: **DEPRECATED** `trackerReplace`. Use `trackerList` instead. +| `group-set` | new method +| `group-get` | new method +| `torrent-get` | :warning: old arg `wanted` was implemented as an array of `0` or `1` in Transmission 3.00 and older, despite being documented as an array of booleans. Transmission 4.0.0 and 4.0.1 "fixed" this by returning an array of booleans; but in practical terms, this change caused an unannounced breaking change for any 3rd party code that expected `0` or `1`. For this reason, 4.0.2 restored the 3.00 behavior and updated this spec to match the code. + +Transmission 4.1.0 (`rpc_version_semver` 6.0.0, `rpc_version`: 18) + +:bomb: switch to the JSON-RPC 2.0 protocol +:bomb: switch to snake_case for all strings + +| Method | Description +|:---|:--- +| `session_get` | new arg `sequential_download` +| `session_set` | new arg `sequential_download` +| `torrent_add` | new arg `sequential_download` +| `torrent_get` | new arg `sequential_download` +| `torrent_set` | new arg `sequential_download` +| `torrent_add` | new arg `sequential_download_from_piece` +| `torrent_get` | new arg `sequential_download_from_piece` +| `torrent_set` | new arg `sequential_download_from_piece` +| `torrent_get` | new arg `files.begin_piece` +| `torrent_get` | new arg `files.end_piece` +| `port_test` | new arg `ip_protocol` +| `torrent_get` | new arg `trackerStats.downloader_count` +| `torrent_get` | :warning: **DEPRECATED** `manual_announce_time`, it never worked +| `session_get` | new arg `preferred_transports` +| `session_set` | new arg `preferred_transports` +| `session_get` | :warning: **DEPRECATED** `utp_enabled`. Use `preferred_transports` instead. +| `session_set` | :warning: **DEPRECATED** `utp_enabled`. Use `preferred_transports` instead. +| `session_get` | :warning: **DEPRECATED** `rpc_version`. Use `rpc_version_semver` instead. +| `session_get` | :warning: **DEPRECATED** `rpc_version_minimum`. Use `rpc_version_semver` instead. +| `torrent_get` | :bomb: `wanted` is now a boolean array instead of 1/0 +| `session_get` | :bomb: renamed `cache_size_mb` to `cache_size_mib` +| `session_set` | :bomb: renamed `cache_size_mb` to `cache_size_mib` diff --git a/server.py b/server.py new file mode 100644 index 0000000..95dc024 --- /dev/null +++ b/server.py @@ -0,0 +1,572 @@ +""" +Transmission MCP Server - Multi-instance Transmission daemon management via MCP. + +Follows the "Hybrid MCP Light" pattern: +- Minimal specific tools for common operations +- Raw RPC pass-through for full API access +- Embedded API documentation as a resource +""" + +from __future__ import annotations + +import json +import os +from dataclasses import dataclass +from typing import Any + +import httpx +from dotenv import load_dotenv +from fastmcp import FastMCP +from starlette.applications import Starlette +from starlette.responses import JSONResponse +from starlette.routing import Mount, Route + +load_dotenv() + +# ============================================================================= +# Configuration +# ============================================================================= + + +@dataclass +class InstanceConfig: + """Configuration for a single Transmission instance.""" + + name: str + url: str + username: str | None = None + password: str | None = None + + @property + def rpc_url(self) -> str: + """Full RPC endpoint URL.""" + base = self.url.rstrip("/") + if not base.endswith("/transmission/rpc"): + base = f"{base}/transmission/rpc" + return base + + +def load_instances() -> list[InstanceConfig]: + """Load instance configurations from TRANSMISSION_INSTANCES env var.""" + raw = os.getenv("TRANSMISSION_INSTANCES", "[]") + try: + data = json.loads(raw) + except json.JSONDecodeError as e: + raise ValueError(f"Invalid TRANSMISSION_INSTANCES JSON: {e}") from e + + instances = [] + for item in data: + if not isinstance(item, dict): + raise ValueError(f"Each instance must be an object, got: {type(item)}") + if "name" not in item or "url" not in item: + raise ValueError("Each instance requires 'name' and 'url' fields") + instances.append( + InstanceConfig( + name=item["name"], + url=item["url"], + username=item.get("username"), + password=item.get("password"), + ) + ) + return instances + + +def get_default_instance() -> str | None: + """Get the default instance name from env.""" + return os.getenv("TRANSMISSION_DEFAULT_INSTANCE") + + +# ============================================================================= +# Transmission Client +# ============================================================================= + + +class TransmissionClient: + """ + Async client for a single Transmission daemon instance. + + Handles: + - HTTP Basic authentication (optional) + - CSRF token management (X-Transmission-Session-Id) + - JSON-RPC 2.0 protocol + """ + + def __init__(self, config: InstanceConfig): + self.config = config + self._session_id: str | None = None + self._request_id = 0 + + # Build auth if credentials provided + auth = None + if config.username: + auth = httpx.BasicAuth(config.username, config.password or "") + + self._client = httpx.AsyncClient( + auth=auth, + timeout=30.0, + headers={"Content-Type": "application/json"}, + ) + + async def close(self) -> None: + """Close the HTTP client.""" + await self._client.aclose() + + def _next_request_id(self) -> int: + """Generate unique request ID.""" + self._request_id += 1 + return self._request_id + + async def rpc( + self, method: str, params: dict[str, Any] | None = None + ) -> dict[str, Any]: + """ + Execute a JSON-RPC 2.0 call to the Transmission daemon. + + Args: + method: RPC method name (e.g., "torrent_get", "session_stats") + params: Method parameters + + Returns: + The 'result' field from the response, or error details + + Raises: + httpx.HTTPError: On network/HTTP errors after retry + """ + payload = { + "jsonrpc": "2.0", + "method": method, + "id": self._next_request_id(), + } + if params: + payload["params"] = params + + # Try request, handle CSRF token refresh on 409 + response = None + for attempt in range(2): + headers = {} + if self._session_id: + headers["X-Transmission-Session-Id"] = self._session_id + + response = await self._client.post( + self.config.rpc_url, + json=payload, + headers=headers, + ) + + if response.status_code == 409: + # CSRF token expired/missing - extract new one and retry + self._session_id = response.headers.get("X-Transmission-Session-Id") + if not self._session_id: + raise ValueError("Got 409 but no X-Transmission-Session-Id header") + continue + + response.raise_for_status() + break + + if response is None: + raise RuntimeError("No response received from Transmission") + + data = response.json() + + # Handle JSON-RPC error response + if "error" in data: + error = data["error"] + return { + "error": True, + "code": error.get("code"), + "message": error.get("message"), + "data": error.get("data"), + } + + return data.get("result", {}) + + async def health_check(self) -> dict[str, Any]: + """Check connectivity to this instance.""" + try: + result = await self.rpc( + "session_get", {"fields": ["version", "rpc_version_semver"]} + ) + if "error" in result: + return {"healthy": False, "error": result["message"]} + return { + "healthy": True, + "version": result.get("version"), + "rpc_version": result.get("rpc_version_semver"), + } + except Exception as e: + return {"healthy": False, "error": str(e)} + + +# ============================================================================= +# Instance Registry +# ============================================================================= + + +class InstanceRegistry: + """Manages multiple TransmissionClient instances.""" + + def __init__(self, configs: list[InstanceConfig], default: str | None = None): + self._clients: dict[str, TransmissionClient] = {} + self._default = default + + for config in configs: + self._clients[config.name] = TransmissionClient(config) + + # Validate default exists + if self._default and self._default not in self._clients: + raise ValueError( + f"Default instance '{self._default}' not found in configured instances: " + f"{list(self._clients.keys())}" + ) + + def get(self, name: str | None = None) -> TransmissionClient: + """ + Get a client by name, or the default if name is None. + + Raises: + KeyError: If instance not found or no default configured + """ + if name is None: + if self._default is None: + raise KeyError("No instance name provided and no default configured") + name = self._default + + if name not in self._clients: + raise KeyError( + f"Instance '{name}' not found. Available: {list(self._clients.keys())}" + ) + return self._clients[name] + + def list_names(self) -> list[str]: + """List all configured instance names.""" + return list(self._clients.keys()) + + def get_default(self) -> str | None: + """Get the default instance name.""" + return self._default + + async def close_all(self) -> None: + """Close all clients.""" + for client in self._clients.values(): + await client.close() + + +# ============================================================================= +# Initialize Registry +# ============================================================================= + +try: + _instances = load_instances() + _default = get_default_instance() + registry = InstanceRegistry(_instances, _default) +except Exception as e: + # Allow server to start even with bad config for debugging + print(f"WARNING: Failed to load instances: {e}") + registry = InstanceRegistry([]) + + +# ============================================================================= +# MCP Server +# ============================================================================= + +mcp = FastMCP( + name="transmission-mcp", + instructions=""" +Transmission MCP Server - Manage multiple Transmission BitTorrent daemon instances. + +Use 'list_instances' to see available instances and their status. +Use 'get_torrents' and 'get_session_stats' for common operations. +Use 'rpc_call' for any Transmission RPC method not covered by specific tools. +Refer to the 'transmission://rpc-reference' resource for API documentation. +""", +) + + +# ============================================================================= +# MCP Tools +# ============================================================================= + + +@mcp.tool() +async def list_instances() -> str: + """ + List all configured Transmission instances and their connectivity status. + + Returns a JSON object with: + - instances: Array of instance objects with name, url, healthy status, and version info + - default: The default instance name (if configured) + """ + results = [] + for name in registry.list_names(): + client = registry.get(name) + health = await client.health_check() + results.append( + { + "name": name, + "url": client.config.url, + "authenticated": client.config.username is not None, + **health, + } + ) + + return json.dumps( + { + "instances": results, + "default": registry.get_default(), + }, + indent=2, + ) + + +@mcp.tool() +async def get_torrents( + instance: str | None = None, + ids: str | None = None, +) -> str: + """ + Get torrent list with common fields from a Transmission instance. + + Args: + instance: Instance name (uses default if not specified) + ids: Optional torrent IDs - can be: + - Omitted for all torrents + - A single ID number as string + - Comma-separated IDs (e.g., "1,5,10") + - "recently_active" for recently changed torrents + + Returns JSON with torrents array containing: id, name, status, percent_done, + rate_download, rate_upload, total_size, error, error_string, labels + """ + try: + client = registry.get(instance) + except KeyError as e: + return json.dumps({"error": str(e)}) + + params: dict[str, Any] = { + "fields": [ + "id", + "name", + "status", + "percent_done", + "rate_download", + "rate_upload", + "total_size", + "error", + "error_string", + "labels", + "eta", + "download_dir", + ] + } + + # Parse ids parameter + if ids: + if ids == "recently_active": + params["ids"] = "recently_active" + elif "," in ids: + params["ids"] = [int(i.strip()) for i in ids.split(",")] + else: + params["ids"] = [int(ids)] + + result = await client.rpc("torrent_get", params) + return json.dumps(result, indent=2) + + +@mcp.tool() +async def get_session_stats(instance: str | None = None) -> str: + """ + Get session statistics from a Transmission instance. + + Args: + instance: Instance name (uses default if not specified) + + Returns JSON with: active_torrent_count, paused_torrent_count, torrent_count, + download_speed, upload_speed, cumulative_stats, current_stats + """ + try: + client = registry.get(instance) + except KeyError as e: + return json.dumps({"error": str(e)}) + + result = await client.rpc("session_stats") + return json.dumps(result, indent=2) + + +@mcp.tool() +async def rpc_call( + method: str, + params: str = "{}", + instance: str | None = None, +) -> str: + """ + Execute a raw JSON-RPC 2.0 call to a Transmission instance. + + This is the "escape hatch" for any RPC method not covered by specific tools. + Refer to the 'transmission://rpc-reference' resource for available methods. + + Args: + method: RPC method name (e.g., "torrent_add", "torrent_set", "session_set") + params: JSON string of method parameters (default: "{}") + instance: Instance name (uses default if not specified) + + Examples: + - Add torrent: method="torrent_add", params='{"filename": "magnet:?xt=..."}' + - Start torrent: method="torrent_start", params='{"ids": [1, 2]}' + - Set speed limit: method="session_set", params='{"speed_limit_down": 1000}' + """ + try: + client = registry.get(instance) + except KeyError as e: + return json.dumps({"error": str(e)}) + + try: + parsed_params = json.loads(params) + except json.JSONDecodeError as e: + return json.dumps({"error": f"Invalid JSON params: {e}"}) + + result = await client.rpc(method, parsed_params if parsed_params else None) + return json.dumps(result, indent=2) + + +# ============================================================================= +# MCP Resource - API Reference +# ============================================================================= + +RPC_REFERENCE = """ +# Transmission RPC Reference (JSON-RPC 2.0) + +## Overview +Transmission 4.1.0+ uses JSON-RPC 2.0 with snake_case naming. +All methods require the `method` name and optional `params` object. + +## Torrent Actions +| Method | Description | Key Params | +|--------|-------------|------------| +| `torrent_start` | Start torrents | `ids` | +| `torrent_start_now` | Start immediately (skip queue) | `ids` | +| `torrent_stop` | Stop torrents | `ids` | +| `torrent_verify` | Verify torrent data | `ids` | +| `torrent_reannounce` | Re-announce to trackers | `ids` | + +**`ids` parameter**: integer, array of integers/hashes, or "recently_active" + +## Torrent Accessors +| Method | Description | +|--------|-------------| +| `torrent_get` | Get torrent info (requires `fields` array) | +| `torrent_set` | Modify torrent settings | +| `torrent_add` | Add new torrent (`filename` or `metainfo`) | +| `torrent_remove` | Remove torrent (`delete_local_data`: bool) | +| `torrent_set_location` | Move torrent (`location`, `move`: bool) | +| `torrent_rename_path` | Rename file/folder (`path`, `name`) | + +### Common `torrent_get` fields: +- `id`, `name`, `status`, `hash_string` +- `percent_done`, `percent_complete`, `eta` +- `rate_download`, `rate_upload` (bytes/sec) +- `total_size`, `size_when_done`, `left_until_done` +- `download_dir`, `labels`, `error`, `error_string` +- `files`, `file_stats`, `peers`, `trackers` + +### Status values: +| Value | Meaning | +|-------|---------| +| 0 | Stopped | +| 1 | Queued to verify | +| 2 | Verifying | +| 3 | Queued to download | +| 4 | Downloading | +| 5 | Queued to seed | +| 6 | Seeding | + +## torrent_add params: +- `filename`: URL or path to .torrent file +- `metainfo`: Base64-encoded .torrent content +- `download_dir`: Download location +- `paused`: Start paused (bool) +- `labels`: Array of string labels + +## Session Methods +| Method | Description | +|--------|-------------| +| `session_get` | Get session settings (optional `fields`) | +| `session_set` | Modify session settings | +| `session_stats` | Get statistics | +| `session_close` | Shutdown daemon | +| `free_space` | Check free space (`path`) | + +### Common session settings: +- `download_dir`, `incomplete_dir` +- `speed_limit_down`, `speed_limit_down_enabled` +- `speed_limit_up`, `speed_limit_up_enabled` +- `peer_limit_global`, `peer_limit_per_torrent` + +## Queue Methods +| Method | Params | +|--------|--------| +| `queue_move_top` | `ids` | +| `queue_move_up` | `ids` | +| `queue_move_down` | `ids` | +| `queue_move_bottom` | `ids` | + +## Bandwidth Groups +| Method | Description | +|--------|-------------| +| `group_get` | Get bandwidth groups (optional `group` name/array) | +| `group_set` | Create/modify group (`name`, speed limits) | + +## Full Documentation +See: https://github.com/transmission/transmission/blob/main/docs/rpc-spec.md +""" + + +@mcp.resource("transmission://rpc-reference") +def get_rpc_reference() -> str: + """ + Returns the Transmission RPC API reference documentation. + + Use this to learn available methods and parameters for the rpc_call tool. + """ + return RPC_REFERENCE + + +# ============================================================================= +# Health Check & ASGI App +# ============================================================================= + + +async def health(request) -> JSONResponse: + """Health check endpoint for container orchestration.""" + # Quick check - just verify we can list instances + instance_count = len(registry.list_names()) + return JSONResponse( + { + "status": "ok", + "instances_configured": instance_count, + "default_instance": registry.get_default(), + } + ) + + +def create_app() -> Starlette: + """Create the Starlette ASGI application wrapping the MCP server.""" + mcp_app = mcp.http_app() + return Starlette( + routes=[ + Route("/health", health), + Mount("/", app=mcp_app), + ], + lifespan=mcp_app.lifespan, + ) + + +app = create_app() + + +if __name__ == "__main__": + import uvicorn + + port = int(os.getenv("PORT", "8000")) + host = os.getenv("HOST", "0.0.0.0") + + uvicorn.run(app, host=host, port=port)