Ygg Torrent MCP

🚀 YggTorrent MCP 服務器與包裝器

本項目提供了一個用於 YggTorrent 網站的 Python 包裝器，以及一個 MCP（模型上下文協議）服務器，可通過編程方式與之交互。這使得 YggTorrent 的功能能夠輕鬆集成到其他應用程序或服務中。

🚀 快速開始

如何使用 MCP 客戶端與之交互

使用 Docker 運行以繞過常見的 DNS 問題

📑 目錄

• ✨ 主要特性
• 📦 安裝指南
  • 📋 前提條件
  • ⚙️ 配置
  • 📥 安裝步驟
    • 從 PyPI 安裝（推薦）
    • 本地開發安裝
    • 使用 Docker 安裝
• 💻 使用示例
  • 作為 Python 包裝器使用
  • 作為 MCP 服務器使用
  • 作為 FastAPI 服務器使用
  • 通過 MCP 客戶端使用
    • 使用 Windsurf 的示例
• 🤝 貢獻指南
• 📜 更新日誌
• 📄 許可證

✨ 主要特性

• 為 YggAPI（YggTorrent 的非官方 API）提供 API 包裝器
  • 你的 Ygg 通行證密鑰會在本地注入到種子文件/磁力鏈接中，確保不會對外暴露
• 提供 MCP 服務器接口，用於標準化通信（標準輸入輸出、服務器發送事件、可流式 HTTP）
• 提供 FastAPI 服務器接口，用於替代 HTTP 訪問（例如，用於直接 API 調用或測試）
• 工具功能：
  • 在 YggTorrent 上搜索種子文件
  • 獲取特定種子文件的詳細信息
  • 獲取磁力鏈接
  • 獲取種子文件
  • 獲取種子文件的類別

📦 安裝指南

📋 前提條件

• 一個活躍的 YggTorrent 賬戶和通行證密鑰。
• Python 3.10 及以上版本（PyPI 安裝需要）。
• uv（用於本地開發）
• Docker 和 Docker Compose（用於 Docker 安裝）

⚙️ 配置

此應用程序需要你的 YggTorrent 通行證密鑰才能與 API 進行交互。

1. 查找你的通行證密鑰：在 YggTorrent 網站上，導航到 Mon compte -> Mes paramètres。你的通行證密鑰是跟蹤器 URL 的一部分，格式類似於 http://tracker.p2p-world.net:8080/{YOUR_PASSKEY}/announce。

2. 設置環境變量：應用程序從 YGG_PASSKEY 環境變量中讀取通行證密鑰。推薦的設置方法是在項目根目錄下創建一個 .env 文件，應用程序會自動加載該文件。

📥 安裝步驟

選擇以下其中一種安裝方法。

從 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 服務器使用

本項目還包含一個 FastAPI 服務器，作為通過標準 HTTP API 與 YggTorrent 功能進行交互的替代方式。這對於直接 API 調用、與其他 Web 服務集成或測試目的非常有用。

運行 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": {
    ...
    # 使用標準輸入輸出（僅需安裝 uv）
    "mcp-ygg-torrent": {
      "command": "uvx",
      "args": ["ygg-torrent-mcp"],
      "env": { "YGG_PASSKEY": "your_passkey_here" }
    }
    # 使用服務器發送事件傳輸（需要安裝）
    "mcp-ygg-torrent": {
      "serverUrl": "http://127.0.0.1:8000/sse"
    }
    # 使用可流式 HTTP 傳輸（需要安裝）
    "mcp-ygg-torrent": {
      "serverUrl": "http://127.0.0.1:8000/mcp" # 並非所有客戶端都支持
    }
    ...
  }
}

📜 更新日誌

有關本項目的變更歷史，請參閱 CHANGELOG.md。

🤝 貢獻指南

歡迎貢獻！請提交問題或拉取請求。

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。