chore: align project config with torrentclaw org standards
This commit is contained in:
Deivid Soto
parent
2f58ac7bf8
commit
8bb8e5507e
9 changed files with 367 additions and 46 deletions
120
README.md
120
README.md
|
|
@ -1,6 +1,13 @@
|
|||
# torrentclaw-mcp
|
||||
|
||||
MCP server for [TorrentClaw](https://torrentclaw.com) — search movies and TV shows with torrent download options, streaming availability, and metadata.
|
||||
[](https://www.npmjs.com/package/torrentclaw-mcp)
|
||||
[](LICENSE)
|
||||
[](https://github.com/torrentclaw/torrentclaw-mcp/actions/workflows/ci.yml)
|
||||
[](https://nodejs.org)
|
||||
|
||||
[Model Context Protocol](https://modelcontextprotocol.io/) server for [TorrentClaw](https://torrentclaw.com) — giving AI assistants the ability to search movies and TV shows, find torrents with magnet links, check streaming availability, and explore cast/crew metadata.
|
||||
|
||||
torrentclaw-mcp is developed by [TorrentClaw](https://torrentclaw.com) as part of its open-source ecosystem. It wraps the TorrentClaw API into the MCP standard so that any compatible AI assistant (Claude, GPT, etc.) can access the platform's search and discovery features natively.
|
||||
|
||||
## Quick Start
|
||||
|
||||
|
|
@ -8,26 +15,32 @@ MCP server for [TorrentClaw](https://torrentclaw.com) — search movies and TV s
|
|||
npx torrentclaw-mcp
|
||||
```
|
||||
|
||||
No API key required.
|
||||
No API key required (optional for higher rate limits).
|
||||
|
||||
## Available Tools
|
||||
## What can it do?
|
||||
|
||||
| Tool | Description |
|
||||
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `search_content` | Search movies/shows with filters (query, type, genre, year, rating, quality, language, sort). Returns content with torrents and magnet links. |
|
||||
| `get_popular` | Get popular content ranked by user clicks |
|
||||
| `get_recent` | Get recently added content |
|
||||
| `get_watch_providers` | Streaming availability by country (Netflix, Disney+, etc.) |
|
||||
| `get_credits` | Cast and director for a title |
|
||||
| `get_torrent_url` | Get .torrent file download URL from info hash |
|
||||
### Tools
|
||||
|
||||
## Resources
|
||||
| Tool | Description |
|
||||
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `search_content` | Search movies/shows with filters (query, type, genre, year, rating, quality, language, audio, HDR, season, episode, sort). Returns torrents, magnet links, and optional streaming info. |
|
||||
| `autocomplete` | Type-ahead search suggestions (up to 8 results). Use to validate titles before a full search. |
|
||||
| `get_popular` | Get popular content ranked by user clicks |
|
||||
| `get_recent` | Get recently added content |
|
||||
| `get_watch_providers` | Streaming availability by country (Netflix, Disney+, etc.) |
|
||||
| `get_credits` | Cast and director for a title |
|
||||
| `get_torrent_url` | Get .torrent file download URL from info hash |
|
||||
| `track_interaction` | Track user interaction with a torrent (magnet click, download, copy) |
|
||||
| `submit_scan_request` | Submit a torrent for audio/video quality analysis via [TrueSpec](https://github.com/torrentclaw/truespec) |
|
||||
| `get_scan_status` | Check the status of a torrent scan request |
|
||||
|
||||
### Resources
|
||||
|
||||
| URI | Description |
|
||||
| --------------------- | ----------------------------------------------------- |
|
||||
| `torrentclaw://stats` | Catalog statistics (content/torrent counts by source) |
|
||||
|
||||
## Prompts
|
||||
### Prompts
|
||||
|
||||
| Prompt | Description |
|
||||
| ---------------- | -------------------------------------------------------- |
|
||||
|
|
@ -68,39 +81,56 @@ Add to `.mcp.json` or `~/.claude/settings.json`:
|
|||
}
|
||||
```
|
||||
|
||||
### Self-hosted
|
||||
### Environment Variables
|
||||
|
||||
Point to your own TorrentClaw instance:
|
||||
| Variable | Default | Description |
|
||||
| --------------------- | ------------------------- | -------------------------------------------------------------- |
|
||||
| `TORRENTCLAW_API_URL` | `https://torrentclaw.com` | Base URL of the TorrentClaw API |
|
||||
| `TORRENTCLAW_API_KEY` | _(none)_ | Optional API key for authenticated access (higher rate limits) |
|
||||
|
||||
## Project Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"torrentclaw": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "torrentclaw-mcp"],
|
||||
"env": {
|
||||
"TORRENTCLAW_API_URL": "http://localhost:3030",
|
||||
"TORRENTCLAW_ALLOW_PRIVATE": "true"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
| --------------------------- | ------------------------- | ---------------------------------------------------------------------- |
|
||||
| `TORRENTCLAW_API_URL` | `https://torrentclaw.com` | Base URL of the TorrentClaw API |
|
||||
| `TORRENTCLAW_ALLOW_PRIVATE` | `false` | Set to `true` to allow private/localhost URLs (for self-hosted setups) |
|
||||
.
|
||||
├── src/
|
||||
│ ├── index.ts # MCP server entry point
|
||||
│ ├── config.ts # Configuration & URL validation
|
||||
│ ├── api-client.ts # TorrentClaw API client with caching
|
||||
│ ├── types.ts # TypeScript interfaces for API responses
|
||||
│ ├── prompts.ts # MCP prompt definitions
|
||||
│ ├── tools/ # MCP tool implementations
|
||||
│ │ ├── search-content.ts
|
||||
│ │ ├── autocomplete.ts
|
||||
│ │ ├── get-popular.ts
|
||||
│ │ ├── get-recent.ts
|
||||
│ │ ├── get-watch-providers.ts
|
||||
│ │ ├── get-credits.ts
|
||||
│ │ ├── get-torrent-url.ts
|
||||
│ │ ├── track-interaction.ts
|
||||
│ │ └── scan-request.ts
|
||||
│ ├── formatters/ # Output formatting
|
||||
│ │ ├── content.ts
|
||||
│ │ ├── providers.ts
|
||||
│ │ └── credits.ts
|
||||
│ └── resources/ # MCP resources
|
||||
│ └── stats.ts
|
||||
├── tests/ # Test suite (vitest)
|
||||
├── .github/workflows/ # CI/CD (lint, build, test, release)
|
||||
├── lefthook.yml # Git hooks (commit lint, prettier, tsc)
|
||||
├── Makefile # Dev workflow (build, test, lint, fmt)
|
||||
├── CONTRIBUTING.md # Contribution guidelines
|
||||
├── LICENSE # MIT
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
git clone https://github.com/buryni/torrentclaw-mcp.git
|
||||
git clone https://github.com/torrentclaw/torrentclaw-mcp.git
|
||||
cd torrentclaw-mcp
|
||||
npm install
|
||||
npm run build
|
||||
make install-tools
|
||||
make hooks
|
||||
make build && make test
|
||||
```
|
||||
|
||||
Test with MCP Inspector:
|
||||
|
|
@ -109,12 +139,16 @@ Test with MCP Inspector:
|
|||
npx @modelcontextprotocol/inspector node build/index.js
|
||||
```
|
||||
|
||||
Run tests:
|
||||
## About TorrentClaw
|
||||
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
[TorrentClaw](https://torrentclaw.com) is an open platform focused on improving the quality and reliability of torrent metadata. Our mission is to make torrent search engines more accurate and the torrent ecosystem healthier — by building tools that verify, enrich, and standardize metadata across the network.
|
||||
|
||||
torrentclaw-mcp is part of the TorrentClaw open-source ecosystem, alongside [TrueSpec](https://github.com/torrentclaw/truespec) (torrent metadata verification).
|
||||
|
||||
## Contributing
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
MIT License — see [LICENSE](LICENSE) for details.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue