add_show_by_tvdb_id

Instructions

Implementation Reference

• src/arr_assistant_mcp/main.py:434-450 (handler)

  The MCP tool handler function that adds a TV show to Sonarr by TVDB ID. Decorated with @mcp.tool, it delegates to MediaServerAPI.add_series_to_sonarr().

  async def add_show_by_tvdb_id(tvdb_id: int, title: str, root_folder: str | None = None) -> AddMediaResponse:
      """
      Add a specific TV show to Sonarr using its TVDB ID.
      
      Args:
          tvdb_id: The TV Database ID for the show
          title: The title of the show
          root_folder: Optional root folder path (e.g., "/storage/anime")
      
      Returns:
          Result of the add operation
      """
      if not config:
          raise ValueError("Server not configured. Please set up Sonarr API key.")
      
      async with MediaServerAPI(config) as api:
          return await api.add_series_to_sonarr(tvdb_id, title, root_folder)

• src/arr_assistant_mcp/main.py:225-281 (helper)

  The MediaServerAPI.add_series_to_sonarr() method that actually calls the Sonarr API v3/series endpoint to add the series. Handles payload construction (TVDB ID, title, quality profile, root folder selection via parameter > config > auto-detection), the POST request, and error handling.

  async def add_series_to_sonarr(
      self,
      tvdb_id: int,
      title: str,
      root_folder: str | None = None,
  ) -> AddMediaResponse:
      """Add TV series to Sonarr using TVDB ID"""
      url = f"{self.config.sonarr_url}/api/v3/series"
      headers = {"X-Api-Key": self.config.sonarr_api_key}
  
      payload = {
          "title": title,
          "tvdbId": tvdb_id,
          "qualityProfileId": self.config.quality_profile_id,
          "monitored": True,
          "seasonFolder": True,
          "addOptions": {
              "searchForMissingEpisodes": True
          }
      }
  
      # Set root folder (parameter > config > auto-detect)
      if root_folder:
          payload["rootFolderPath"] = root_folder
          logger.info(f"Using specified root folder: {root_folder}")
      elif self.config.sonarr_root_folder:
          payload["rootFolderPath"] = self.config.sonarr_root_folder
          logger.info(f"Using configured root folder: {self.config.sonarr_root_folder}")
      else:
          # Auto-detect first available root folder
          root_folders = await self.get_sonarr_root_folders()
          if root_folders:
              payload["rootFolderPath"] = root_folders[0]["path"]
              logger.info(f"Using auto-detected Sonarr root folder: {root_folders[0]['path']}")
          else:
              logger.warning("No Sonarr root folders found - series may fail to add")
  
      try:
          response = await self.client.post(url, json=payload, headers=headers)
          if response.status_code == 201:
              result = response.json()
              return AddMediaResponse(
                  success=True,
                  message=f"Successfully added '{title}' to Sonarr",
                  media_id=result.get("id")
              )
          else:
              return AddMediaResponse(
                  success=False,
                  message=f"Failed to add series: {response.text}"
              )
      except Exception as e:
          logger.error(f"Sonarr API error: {e}")
          return AddMediaResponse(
              success=False,
              message=f"Error communicating with Sonarr: {str(e)}"
          )

• src/arr_assistant_mcp/main.py:46-49 (schema)

  The AddMediaResponse Pydantic model used as the return type for the tool.

  class AddMediaResponse(BaseModel):
      success: bool
      message: str
      media_id: int | None = None

• src/arr_assistant_mcp/main.py:433-434 (registration)

  The @mcp.tool decorator that registers add_show_by_tvdb_id as an MCP tool on the FastMCP server instance.

  @mcp.tool
  async def add_show_by_tvdb_id(tvdb_id: int, title: str, root_folder: str | None = None) -> AddMediaResponse: