Commit graph

7 commits

Author SHA1 Message Date
Deivid Soto
92ed47ebdf build: replace lefthook with husky, commitlint and commit-and-tag-version 2026-02-12 17:53:24 +01:00
Deivid Soto
fa913d1561 feat: expand API coverage with new tools, params, and 90% test threshold 2026-02-12 15:45:08 +01:00
Deivid Soto
8bb8e5507e chore: align project config with torrentclaw org standards 2026-02-12 15:44:09 +01:00
Deivid Soto
2f58ac7bf8 style: add prettier and format codebase 2026-02-12 15:22:11 +01:00
Deivid Soto
bf459740fe feat: add response cache and compact output mode
Response cache (api-client.ts):
- In-memory TTL cache (5 min default) avoids duplicate API calls
  when LLMs repeat the same tool call within a conversation.
- Cache key = full URL with params; only 200 OK responses are cached.
- Exposed via client.cache for manual clear() if needed.
- Configurable TTL via TorrentClawClient constructor.

Compact mode (search_content tool):
- New compact boolean parameter (default: false).
- When true, magnet links use short form magnet:?xt=urn:btih:{hash}
  (~60 chars) instead of full magnets with trackers (~300 chars).
- Short magnets are still valid and clickable (DHT peer discovery).
- Also generates a magnet from info_hash even when API returns null.
- Saves ~10K chars per typical search (5 torrents x 10 results).

Tests: 100 total (15 new), all passing.
2026-02-09 17:57:11 +01:00
Deivid Soto
e011c0f63e fix: correct README inconsistencies and add TORRENTCLAW_ALLOW_PRIVATE
- Rename get_torrent_download_url → get_torrent_url in README tools table
- Add TORRENTCLAW_ALLOW_PRIVATE env var to bypass SSRF checks for
  self-hosted setups (localhost, private IPs)
- Update self-hosted config example with TORRENTCLAW_ALLOW_PRIVATE=true
- Add Prompts section to README
- Add 3 tests for ALLOW_PRIVATE behavior (88 tests total)
2026-02-09 17:46:24 +01:00
Deivid Soto
d471c9b695 feat: initial release of torrentclaw-mcp server
MCP (Model Context Protocol) server that wraps the TorrentClaw REST API,
enabling LLMs (Claude Desktop, Claude Code, Cursor, etc.) to search movies
and TV shows with torrent downloads and streaming availability.

## Tools (6)
- search_content: primary search with filters (title, genre, year, rating,
  quality, language, sort). Returns content metadata + torrent magnet links.
- get_popular: trending content ranked by clicks
- get_recent: most recently added content
- get_watch_providers: streaming availability by country (Netflix, Disney+, etc.)
- get_credits: director and top 10 cast members
- get_torrent_url: .torrent file download URL from info_hash

## Resources
- torrentclaw://stats: catalog statistics (content/torrent counts, sources)

## Prompts (4)
- search_movie, search_show, whats_new, where_to_watch

## LLM Usability
- Server description with workflow guidance for tool chaining
- Tool descriptions include trigger phrases, cross-tool references, and
  explicit parameter examples
- Formatted output includes info_hash for tool chaining and call-syntax
  cross-references (e.g. "use with get_watch_providers(content_id=42)")
- Popular/recent output hints to use search_content for torrents
- Error messages include status-specific recovery guidance (400, 404, 429, 5xx)
- Prompts reference tools by name for reliable LLM execution

## Security
- SSRF protection: validates TORRENTCLAW_API_URL against private IPs,
  localhost, link-local, and IPv6 loopback addresses
- Protocol whitelist: only http/https allowed
- Error body sanitization: 4xx truncated to 200 chars, 5xx bodies omitted
- Input validation: control char filter on queries, regex on country codes,
  genre character whitelist, content_id bounds

## Testing
- 85 tests across 13 test files
- Coverage: 99.5% statements, 95.2% branches, 98.1% functions, 99.5% lines
- Vitest v4 with v8 coverage provider, 80% thresholds enforced

## Stack
- TypeScript ESM, Node.js >= 18 (native fetch)
- @modelcontextprotocol/sdk v1.12, zod v3.24
- STDIO transport, runnable via npx torrentclaw-mcp
2026-02-09 17:26:23 +01:00