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