mi/webshare-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add MCP server for AI agents

Browse Source 
Expose webshare_search, webshare_get_link, and webshare_login_check over
stdio via the Model Context Protocol SDK. Document client configuration.
This commit is contained in:
Michal Pemcak
2026-08-07 08:50:10 +02:00
parent c2b5563c25
commit f7f1481a39
7 changed files with 929 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
README.md
View File

@@ -11,6 +11,7 @@ Official Webshare HTTP API documentation: [https://webshare.cz/apidoc/](https://
| **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.
@@ -18,12 +19,14 @@ Webshare download links expire after roughly ten minutes, so the torrent never e
```
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
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
@@ -77,6 +80,56 @@ When both run on the same Compose network, use the service name, e.g. `http://we
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