# webshare-api

Node.js/Express proxy that exposes [Webshare.cz](https://webshare.cz) as protocols *arr apps understand.

Official Webshare HTTP API documentation: [https://webshare.cz/apidoc/](https://webshare.cz/apidoc/)

| Role | Endpoints | Purpose |
|------|-----------|---------|
| **Torznab indexer** | `GET /api?t=caps\|search\|tvsearch\|movie` | Search → Torznab RSS/XML |
| **Fake torrent** | `GET /download/:ident` | Minimal `.torrent` whose webseed points at `/stream/:ident` |
| **Stream** | `GET /stream/:ident` | Fresh Webshare `file_link` + HTTP 302 to CDN |
| **Fake qBittorrent** | `/api/v2/*` | Download client API; streams the HTTPS file to disk |
| **Debug** | `GET /resolve/:ident` | JSON with the resolved CDN URL |
| **MCP server** | stdio (`npm run mcp`) | Tools for AI agents: search, resolve links, login check |

Webshare download links expire after roughly ten minutes, so the torrent never embeds a CDN URL—only a path on this service that resolves a fresh link at fetch time.

## Layout

```
src/
  index.js       # Express app + optional Sonarr missing-episode search
  webshare.js    # salt/login, search, file_link
  md5crypt.js    # Unix $1$ MD5-crypt (Webshare password digest)
  torznab.js     # caps + search feed XML
  torrent.js     # bencode + fake torrent + info-hash
  qbt.js         # qBittorrent Web API façade + download queue
  mcp-server.js  # MCP tool registration (shared)
  mcp.js         # MCP stdio entrypoint for agents
__tests__/
compose.yaml
Dockerfile
```

## Configuration

Environment variables (required unless noted):

| Variable | Default | Description |
|----------|---------|-------------|
| `WEBSHARE_USERNAME` | — | Webshare username or email |
| `WEBSHARE_PASSWORD` | — | Webshare password (plain; hashed client-side) |
| `PORT` | `3001` | HTTP listen port |
| `BASE_URL` | `http://localhost:$PORT` | Public base URL Sonarr must reach (use the Compose service hostname when linking containers) |
| `DOWNLOAD_PATH` | `/downloads/webshare` | Where the fake qBittorrent writes files |
| `MEDIA_ROOT` | `/data` | Media root (used for path reporting) |
| `MAX_CONCURRENT_DOWNLOADS` | `2` | Parallel stream downloads |
| `SONARR_URL` | `http://sonarr:8989` | Optional; Sonarr base URL |
| `SONARR_API_KEY` | _(empty)_ | Optional; enables periodic missing-episode search |
| `SONARR_SEARCH_INTERVAL_HOURS` | `2` | Interval for that search |
| `DOWNLOAD_HOST_PATH` | `./data/webshare` | Host path mounted at `DOWNLOAD_PATH` in Compose |

Copy `.env.example` and fill in credentials. Do not commit a filled `.env`.

## Run with Compose

```bash
cp .env.example .env
# set WEBSHARE_USERNAME and WEBSHARE_PASSWORD
docker compose up -d --build
```

See `compose.yaml`. Override ports, `BASE_URL`, Sonarr settings, and volume mounts via `.env` as needed.

## Run without Compose

```bash
npm install
export WEBSHARE_USERNAME=...
export WEBSHARE_PASSWORD=...
npm start
```

## Sonarr / Radarr

1. **Indexer** (Torznab): `http://<host>:3001/api`  
2. **Download client** (qBittorrent): host/port of this service; any username/password (login accepts all).

When both run on the same Compose network, use the service name, e.g. `http://webshare-api:3001`.

Sonarr hands `.torrent` files to the fake qBittorrent API. This service extracts the webseed, streams the file into `DOWNLOAD_PATH`, and reports progress via `/api/v2/torrents/*`.

## MCP (AI agents)

Exposes Webshare to MCP-compatible clients over **stdio** (stdout is protocol-only; logs go to stderr).

### Tools

| Tool | Description |
|------|-------------|
| `webshare_search` | Search files (`query`, optional `limit` / `offset` / `sort` / `category`) |
| `webshare_get_link` | Resolve a temporary CDN URL for a file `ident` |
| `webshare_login_check` | Verify credentials against the Webshare API |

### Run

```bash
export WEBSHARE_USERNAME=...
export WEBSHARE_PASSWORD=...
npm run mcp
# or: npx webshare-mcp   (after npm link / global install)
```

### Client configuration example

**Claude Desktop / similar** (`mcpServers`):

```json
{
  "mcpServers": {
    "webshare": {
      "command": "node",
      "args": ["/absolute/path/to/webshare-api/src/mcp.js"],
      "env": {
        "WEBSHARE_USERNAME": "your-username",
        "WEBSHARE_PASSWORD": "your-password"
      }
    }
  }
}
```

**Grok / OpenCode-style** (TOML):

```toml
[mcp_servers.webshare]
command = "node"
args = ["/absolute/path/to/webshare-api/src/mcp.js"]
```

Pass `WEBSHARE_USERNAME` and `WEBSHARE_PASSWORD` via the client env settings or a process manager—not in the repo.

## Tests

```bash
npm test
```

## License

[MIT](LICENSE)

You need a valid Webshare account. This project only speaks their documented HTTP API ([apidoc](https://webshare.cz/apidoc/)). Use at your own risk.