YggTorrent MCP Server

Instructions

Implementation Reference

• ygg_torrent/mcp_server.py:33-57 (handler)

  The primary MCP tool handler for 'search_torrents'. Registers the tool via @mcp.tool() decorator and implements the logic by calling YggTorrentApi.search_torrents, slicing results, and formatting as string.

  @mcp.tool()
  def search_torrents(
      query: str,
      categories: list[str] | None = None,
      page: int = 1,
      per_page: int = 25,
      order_by: str = "seeders",
      max_items: int = 25,
  ) -> str:
      """Searches for torrents on YggTorrent using a query (space-separated keywords) and returns a list of torrent results.
      # Instructions:
      - To be called after `prepare_search_query`.
      - Provide **only** `query`, except if user mentions other parameters.
      - Prioritize results using the following hierarchy: is 1080p > smaller file size > is x265 > max seeders+leechers.
      - Recommend up to 3 of the best results, **always** providing filename, file size, seeders/leechers, date, source, and an ultra concise reason.
      - If the search results are too broad, suggest the user provide more specific keywords.
      - Keep recommendations and suggestions concise."""
      logger.info(
          f"Searching for torrents: {query}, categories: {categories}, page: {page}, per_page: {per_page}, order_by: {order_by}, max_items: {max_items}"
      )
      torrents: list[Torrent] = ygg_api.search_torrents(
          query, categories, page, per_page, order_by
      )[:max_items]
      return "\n".join([str(torrent) for torrent in torrents])

• ygg_torrent/wrapper/api_client.py:76-114 (helper)

  Core helper function implementing the torrent search logic in YggTorrentApi class. Makes HTTP GET request to yggapi.eu/torrents, processes categories, formats results into Torrent objects.

  def search_torrents(
      self,
      query: str,
      categories: list[int] | list[str] | None = None,
      page: int = 1,
      per_page: int = 25,
      order_by: str = "seeders",
  ) -> list[Torrent]:
      """
      Get a list of torrents.
      Corresponds to GET /torrents
  
      Args:
          query: Search query.
          categories: Optional list of category IDs (int) or keywords (str).
          page: Page number.
          per_page: Number of results per page (25, 50, 100).
          order_by: Field to order by (descending). Valid values: uploaded_at, seeders, downloads.
  
      Returns:
          A list of torrent results or an error dictionary.
  
      Raises:
          TypeError: If 'categories' is a mixed list of integers and strings,
                     or contains types other than int or str.
      """
      params = {"q": query, "page": page, "per_page": per_page, "order_by": order_by}
  
      processed_category_ids: list[int] = (
          check_categories(categories) if categories else []
      )
      if processed_category_ids:
          params["category_id"] = processed_category_ids
  
      torrents = self._request("GET", "torrents", params=params)
      if torrents:
          return [format_torrent(torrent) for torrent in torrents]
      return []

• ygg_torrent/mcp_server.py:21-31 (helper)

  Supporting MCP tool 'prepare_search_query' that helps prepare optimal query parameters for the 'search_torrents' tool, as instructed in its docstring.

  @mcp.tool()
  def prepare_search_query(user_intent: str, search_query: str) -> str:
      """Always use this tool to prepare a query for `search_torrents`.
      Properly split the user's intention and the actual search query (space-separated keywords) to avoid unfruitful results.
      # Instructions:
      - `user_intent`: Must reflect user's overall intention (e.g., "last episode of Breaking Bad", "season 5 of Breaking Bad", "complete series of Breaking Bad").
      - `search_query`: The actual search terms, consisting of lowercase, space-separated keywords. Do not add generic terms (e.g., "movie", "series"), common prefixes (e.g., "the", "a", "and"), or extra information (e.g., episode name, resolution, codec). For TV series, use `sXXeYY` for specific episodes (e.g., "breaking bad s05e16"), `sXX` for complete seasons (e.g., "breaking bad s05") and only the show name for complete series (e.g., "breaking bad").
      - For non-French language, if requested, just add 'multi' to the query
      """
      return "Ready to search for torrents."

• ygg_torrent/mcp_server.py:33-33 (registration)

  The @mcp.tool() decorator registers the search_torrents function as an MCP tool.

  @mcp.tool()