fileclaw 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RZacharias44
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,275 @@
+# fileclaw
+
+Ask Claude to find you any file on the internet. It does.
+
+fileclaw is an [MCP server](https://modelcontextprotocol.io) that gives Claude the ability to search 26 sources, download files, and stream video — all through natural conversation. Books, papers, movies, TV, anime, manga, music, games, ROMs, software, subtitles — if it's out there, fileclaw can probably find it.
+
+## What it looks like
+
+> **You:** Find me the EPUB of "Designing Data-Intensive Applications"
+>
+> **Claude:** Found it on Library Genesis (14MB, EPUB). Downloading now... saved to ~/Downloads/
+
+> **You:** Get me Sintel in 1080p
+>
+> **Claude:** Found on YTS (1.4GB, 1080p BluRay). Sending to Real-Debrid... download complete.
+
+> **You:** Stream Big Buck Bunny
+>
+> **Claude:** Found a 1080p copy. Opening in VLC now.
+
+> **You:** I need the paper with DOI 10.1038/nature12373
+>
+> **Claude:** Found on Sci-Hub. Downloaded PDF to ~/Downloads/
+
+No manual searching, no navigating sketchy sites, no configuring torrent clients. Just ask.
+
+## How it works
+
+```
+You  -->  Claude  -->  fileclaw  -->  26 sources
+                                         |
+                          LibGen, Sci-Hub, Anna's Archive,
+                          YTS, Nyaa, The Pirate Bay, FitGirl,
+                          Internet Archive, MangaDex, Soulseek, ...
+                                         |
+                                    Download via:
+                              Direct HTTP / Real-Debrid /
+                               Usenet / Torrent client
+```
+
+1. You ask Claude for something in plain language
+2. fileclaw searches the right sources for that type of content
+3. Results are deduplicated, ranked, and the best match is picked
+4. The file is downloaded through whatever method works — direct download, Real-Debrid, usenet, or torrent client
+5. Claude tells you when it's done
+
+fileclaw learns over time: sources that deliver good results get ranked higher in future searches.
+
+## Install
+
+### Quickest way
+
+```bash
+npx fileclaw setup
+```
+
+Interactive wizard — configures downloads, registers the MCP server with Claude Desktop or Claude Code. Done in under a minute.
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "fileclaw": {
+      "command": "npx",
+      "args": ["-y", "fileclaw", "--mcp"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Ask Claude to find something.
+
+> **Troubleshooting: "Failed to spawn process" / "No such file or directory"**
+>
+> Desktop apps (Claude, Cursor, etc.) don't inherit your shell's PATH. If you manage Node with **fnm**, **nvm**, or **volta**, `npx` won't be found. Fix options:
+>
+> - **Use `bunx` instead** (if you have Bun installed via Homebrew):
+>   ```json
+>   { "command": "bunx", "args": ["fileclaw", "--mcp"] }
+>   ```
+> - **Use the full path to `npx`** (find it with `which npx` in your terminal):
+>   ```json
+>   { "command": "/Users/you/.local/share/fnm/aliases/default/bin/npx", "args": ["-y", "fileclaw", "--mcp"] }
+>   ```
+> - **Use the standalone binary** — no Node/Bun required (see below)
+
+### Claude Code
+
+```bash
+claude mcp add fileclaw -- npx -y fileclaw --mcp
+```
+
+> **Note:** The MCP server loads code once at startup. If you edit source files, restart the server for changes to take effect — restart Claude Desktop or start a new Claude Code session.
+
+### Standalone binary
+
+Download from [GitHub Releases](https://github.com/RZacharias44/fileclaw/releases) — no Node/Bun required.
+
+```bash
+./fileclaw search "sintel" --type=video
+./fileclaw --mcp   # start as MCP server
+```
+
+## What it can find
+
+**Books & papers** — LibGen, Sci-Hub, Anna's Archive, Internet Archive
+Search by title, author, ISBN, or DOI. Direct downloads, no torrenting needed.
+
+**Movies & TV** — YTS, EZTV, The Pirate Bay, Nyaa, Stremio addons, Torrents-CSV
+Finds the best quality available. Streams directly to VLC/mpv or downloads via Real-Debrid.
+
+**Music** — Soulseek, Piped, Librivox, Nyaa, Internet Archive
+Soulseek gives you lossless FLAC from a massive P2P network. Librivox for free audiobooks.
+
+**Anime & manga** — Nyaa, MangaDex, WeebCentral, Comick
+Torrents for anime, chapter-by-chapter reads or bulk downloads for manga.
+
+**Games** — FitGirl, DODI, Myrient, RomHeaven, MarioCube
+Repacked PC games and retro ROMs for every console.
+
+**Software** — FileCR, The Pirate Bay, Torrents-CSV, Internet Archive
+Mac and PC applications.
+
+**Subtitles** — OpenSubtitles, YTS-Subs
+Auto-matched to your downloads by language preference.
+
+**Power-user sources** — Prowlarr, Newznab indexers
+Prowlarr aggregates dozens of torrent and usenet indexers behind a single API. Newznab gives direct access to usenet indexers like NZBgeek. Both need an API key or self-hosted instance.
+
+19 of the 26 sources work with zero configuration For the rest, you just need an API key.
+
+## Download methods
+
+fileclaw routes downloads automatically based on what you have configured:
+
+| Method | Best for | Setup |
+|--------|----------|-------|
+| **Direct HTTP** | Books, papers, subtitles | Nothing — works out of the box |
+| **Real-Debrid** | Movies, TV, games, software | API key (~$3/mo) — recommended for torrents |
+| **Usenet** | Everything | NZBGet or SABnzbd + indexer |
+| **Torrent client** | Everything | qBittorrent or Transmission |
+
+Real-Debrid is the easiest upgrade: it downloads torrents in the cloud and gives you a fast direct link. No torrent client needed.
+
+## Configuration
+
+`~/.config/fileclaw/config.json` — or just ask Claude to run `setup()` and it walks you through it conversationally.
+
+<details>
+<summary>Example config</summary>
+
+```jsonc
+{
+  "download_dir": "~/Downloads",
+
+  // Torrent downloads via Real-Debrid (recommended)
+  "realdebrid": {
+    "api_key": "YOUR_KEY",
+    "prefer": true
+  },
+
+  // Usenet (pick one)
+  "usenet": {
+    "type": "sabnzbd",           // "nzbget", "nzbget-cli", or "sabnzbd"
+    "url": "http://localhost:8080",
+    "api_key": "YOUR_KEY"
+  },
+
+  // Extra sources that need API keys
+  "sources": {
+    "newznab": [
+      { "name": "nzbgeek", "url": "https://api.nzbgeek.info", "api_key": "YOUR_KEY" }
+    ],
+    "opensubtitles": { "api_key": "YOUR_KEY" }
+  },
+
+  // Media player for streaming (auto-detected if omitted)
+  "player": "vlc"
+}
+```
+
+</details>
+
+<details>
+<summary>Disable a source</summary>
+
+```json
+{ "sources": { "tpb": false } }
+```
+
+</details>
+
+<details>
+<summary>Usenet setup</summary>
+
+**NZBGet CLI** (lightest — no daemon):
+```jsonc
+{ "usenet": { "type": "nzbget-cli" } }
+```
+Needs `brew install nzbget` and `~/.nzbget` with your usenet server credentials.
+
+**NZBGet daemon**:
+```jsonc
+{ "usenet": { "type": "nzbget", "url": "http://localhost:6789", "username": "nzbget", "password": "tegbzn6789" } }
+```
+
+**SABnzbd**:
+```jsonc
+{ "usenet": { "type": "sabnzbd", "url": "http://localhost:8080", "api_key": "YOUR_SAB_API_KEY" } }
+```
+
+</details>
+
+## CLI
+
+fileclaw also works as a standalone command-line tool:
+
+```bash
+fileclaw search "machine learning" --type=book
+fileclaw stream "big buck bunny" --player=vlc
+fileclaw scan ~/Downloads/file.mkv
+fileclaw health
+fileclaw stats
+fileclaw setup
+```
+
+## Safety
+
+Downloaded files can be scanned for security issues — magic byte mismatches, embedded executables, and media codec validation via ffprobe. Just ask Claude to scan a file, or use `fileclaw scan <file>`.
+
+## Development
+
+```bash
+git clone https://github.com/RZacharias44/fileclaw && cd fileclaw
+bun install
+bun run cli search "sintel"          # CLI from source
+bun run dev                          # MCP server (stdio)
+bun run typecheck                    # type check
+SKIP_INTEGRATION=1 bun test          # unit tests (136 tests)
+bun test                             # all tests including integration
+bun run build                        # bundle dist/
+```
+
+### Architecture
+
+```
+src/
+  sources/       27 source implementations — each exports search(), healthCheck(), resolve()
+  tools/         Core logic: search, download, stream, scan
+  mcp/           MCP server + tool registrations (how Claude talks to fileclaw)
+  download/      Download routing: Real-Debrid, usenet, torrent client
+  config.ts      User config (~/.config/fileclaw/config.json)
+  quality.ts     Source ranking — learns from usage over time
+```
+
+Each source is a self-contained module that implements a shared `Source` interface. Adding a new source is ~100 lines of TypeScript. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Contributing
+
+fileclaw has built-in tooling for fixing broken sources and adding new ones:
+
+```bash
+fileclaw contribute check libgen              # diagnose a broken source
+fileclaw contribute add mysite https://...    # scaffold a new source
+fileclaw contribute pr                        # fork + commit + open PR
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+
+## License
+
+MIT

package/config.example.json

@@ -0,0 +1,51 @@
+{
+  "download_dir": "~/Downloads",
+
+  "realdebrid": {
+    "api_key": "YOUR_RD_API_KEY",
+    "prefer": true
+  },
+
+  "prowlarr": {
+    "url": "http://localhost:9696",
+    "api_key": "YOUR_PROWLARR_API_KEY"
+  },
+
+  "torrent_client": {
+    "type": "qbittorrent",
+    "url": "http://localhost:8080",
+    "username": "admin",
+    "password": "adminadmin"
+  },
+
+  "usenet": {
+    "type": "sabnzbd",
+    "url": "http://localhost:8080",
+    "api_key": "YOUR_SABNZBD_API_KEY"
+  },
+
+  "player": "vlc",
+
+  "subtitle_languages": ["english"],
+
+  "sources": {
+    "opensubtitles": { "api_key": "YOUR_OPENSUBTITLES_API_KEY" },
+    "newznab": [
+      { "name": "nzbgeek", "url": "https://api.nzbgeek.info", "api_key": "YOUR_KEY" }
+    ],
+    "nyaa": true,
+    "libgen": true,
+    "scihub": true
+  },
+
+  "scan": {
+    "claude_eval": true,
+    "ffprobe_path": "ffprobe"
+  },
+
+  "contribute": {
+    "enabled": false,
+    "mode": "suggest",
+    "github_token": ""
+  }
+}