Ygg Torrent MCP

🚀 YggTorrent MCP Server & Wrapper

このプロジェクトは、YggTorrentウェブサイト用のPythonラッパーと、プログラムからやり取りするためのMCP（Model Context Protocol）サーバーを提供します。これにより、YggTorrentの機能を他のアプリケーションやサービスに簡単に統合することができます。

🚀 クイックスタート

MCPクライアントでの使用方法

一般的なDNS問題を回避するためにDockerで実行する

📑 目次

• ✨ 主な機能
• 📦 インストール
  • 前提条件
  • 設定
  • インストール方法
    • PyPIからインストール（推奨）
    • ローカル開発用
    • Docker用
• 💻 使用例
  • Pythonラッパーとして
  • MCPサーバーとして
  • FastAPIサーバーとして
  • MCPクライアント経由
    • Windsurfを使った例
• 🤝 コントリビューション
• 📜 更新履歴
• 📄 ライセンス

✨ 主な機能

• YggAPI（YggTorrentの非公式API）用のAPIラッパー
  • Yggのパスキーはローカルでトレントファイル/マグネットリンクに注入されるため、外部に公開されません
• 標準化された通信（stdio、sse、streamable-http）用のMCPサーバーインターフェイス
• 代替HTTPアクセス用のFastAPIサーバーインターフェイス（例: 直接のAPI呼び出しやテスト用）
• ツール:
  • YggTorrentでトレントを検索する
  • 特定のトレントの詳細を取得する
  • マグネットリンクを取得する
  • トレントファイルを取得する
  • トレントカテゴリを取得する

📦 インストール

前提条件

• 有効なYggTorrentアカウントとパスキー
• Python 3.10以上（PyPIインストールに必要）
• uv（ローカル開発用）
• DockerとDocker Compose（Dockerセットアップ用）

設定

このアプリケーションは、APIとやり取りするためにYggTorrentのパスキーが必要です。

1. パスキーを見つける: YggTorrentウェブサイトで、Mon compte -> Mes paramètresに移動します。パスキーはトラッカーURLの一部で、http://tracker.p2p-world.net:8080/{YOUR_PASSKEY}/announceのような形式になっています。

2. 環境変数を設定する: アプリケーションはYGG_PASSKEY環境変数からパスキーを読み取ります。これを設定する推奨方法は、プロジェクトのルートディレクトリに.envファイルを作成することです。アプリケーションは自動的に読み込みます。

インストール方法

以下のインストール方法から1つを選択してください。

PyPIからインストール（推奨）

この方法は、パッケージをライブラリとして使用するか、コードを変更せずにサーバーを実行するのに最適です。

1. PyPIからパッケージをインストールします。

pip install ygg-torrent-mcp

2. アプリケーションを実行するディレクトリに.envファイルを作成し、パスキーを追加します。

YGG_PASSKEY=your_passkey_here

3. MCPサーバーを実行します（デフォルトポート: 8000）。

python -m ygg_torrent

ローカル開発用

この方法は、ソースコードを変更したい貢献者向けです。 uvを使用します。

1. リポジトリをクローンします。

git clone https://github.com/philogicae/ygg-torrent-mcp.git
cd ygg-torrent-mcp

2. uvを使用して依存関係をインストールします。

uv sync

3. サンプルファイルをコピーして設定ファイルを作成し、パスキーを追加します。

cp .env.example .env

4. MCPサーバーを実行します（デフォルトポート: 8000）。

uv run -m ygg_torrent

Docker用

この方法は、サーバーをコンテナ内で実行するためにDockerを使用します。

compose.yamlは、DNS問題を回避するように構成されています（quad9 DNSを使用）。

1. まだクローンしていない場合は、リポジトリをクローンします。

git clone https://github.com/philogicae/ygg-torrent-mcp.git
cd ygg-torrent-mcp

2. サンプルファイルをコピーして設定ファイルを作成し、パスキーを追加します。

cp .env.example .env

3. Docker Composeを使用してコンテナをビルドして実行します（デフォルトポート: 8765）。

docker-compose -f docker/compose.yaml up --build [-d]

💻 使用例

Pythonラッパーとして

from ygg_torrent import ygg_api

results = ygg_api.search_torrents('...')
for torrent in results:
    print(f"{torrent.filename} | {torrent.size} | {torrent.seeders} SE | {torrent.leechers} LE | {torrent.downloads} DL | {torrent.date}")

MCPサーバーとして

from ygg_torrent import ygg_mcp

ygg_mcp.run(transport="sse")

FastAPIサーバーとして

このプロジェクトには、標準的なHTTP APIを介してYggTorrentの機能とやり取りするためのFastAPIサーバーも含まれています。これは、直接のAPI呼び出し、他のウェブサービスとの統合、またはテスト目的に役立ちます。

FastAPIサーバーの実行方法:

# 開発環境
python -m ygg_torrent --fastapi
# 本番環境
uvicorn ygg_torrent.fastapi_server:app

• --host <host>: デフォルト: 0.0.0.0
• --port <port>: デフォルト: 8000
• --reload: コードが変更されたときに自動的に再読み込みを有効にします（開発に便利）
• --workers <workers>: デフォルト: 1

FastAPIサーバーはhttp://<host>:<port>でアクセスできます。

利用可能なエンドポイント: FastAPIサーバーは、MCPサーバーと同様の機能を公開しています。主要なエンドポイントは次のとおりです。

• /: 簡単なヘルスチェックエンドポイント。{"status": "ok"}を返します。
• /docs: 対話型APIドキュメント（Swagger UI）。
• /redoc: 代替APIドキュメント（ReDoc）。

環境変数（YGG_PASSKEYなど）は、MCPサーバーと同じ方法で構成されます（プロジェクトルートの.envファイルを介して）。

MCPクライアント経由

任意のMCP互換クライアントで使用できます。利用可能なツールは次のとおりです。

• search_torrents: トレントを検索する
• get_torrent_details: 特定のトレントの詳細を取得する
• get_magnet_link: トレントのマグネットリンクを取得する
• download_torrent_file: トレントの.torrentファイルをダウンロードする

Windsurfを使った例

設定:

{
  "mcpServers": {
    ...
    # stdioを使用する場合（uvのインストールのみ必要）
    "mcp-ygg-torrent": {
      "command": "uvx",
      "args": ["ygg-torrent-mcp"],
      "env": { "YGG_PASSKEY": "your_passkey_here" }
    }
    # sseトランスポートを使用する場合（インストールが必要）
    "mcp-ygg-torrent": {
      "serverUrl": "http://127.0.0.1:8000/sse"
    }
    # streamable-httpトランスポートを使用する場合（インストールが必要）
    "mcp-ygg-torrent": {
      "serverUrl": "http://127.0.0.1:8000/mcp" # すべてのクライアントでサポートされているわけではありません
    }
    ...
  }
}

📜 更新履歴

このプロジェクトの変更履歴については、CHANGELOG.mdを参照してください。

🤝 コントリビューション

コントリビューションは大歓迎です！ 問題を開くか、プルリクエストを送信してください。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。