Initial commit: multi-instance Transmission MCP server

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