573 lines
17 KiB
Python
573 lines
17 KiB
Python
"""
|
|
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)
|