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 文件。