search_emsal_detailed_decisions

Instructions

Implementation Reference

• emsal_mcp_module/client.py:41-73 (handler)

  Core handler logic for searching detailed Emsal decisions. Maps user-friendly input params to API payload, cleans it, and executes the API POST request.

  async def search_detailed_decisions(
      self,
      params: EmsalSearchRequest
  ) -> EmsalApiResponse:
      """Performs a detailed search for Emsal decisions."""
      
      data_for_api_payload = EmsalDetailedSearchRequestData(
          arananKelime=params.keyword or "",
          Bam_Hukuk_Mahkemeleri=params.selected_bam_civil_court, # Uses alias "Bam Hukuk Mahkemeleri"
          Hukuk_Mahkemeleri=params.selected_civil_court,         # Uses alias "Hukuk Mahkemeleri"
          birimHukukMah="+".join(params.selected_regional_civil_chambers) if params.selected_regional_civil_chambers else "",
          esasYil=params.case_year_esas or "",
          esasIlkSiraNo=params.case_start_seq_esas or "",
          esasSonSiraNo=params.case_end_seq_esas or "",
          kararYil=params.decision_year_karar or "",
          kararIlkSiraNo=params.decision_start_seq_karar or "",
          kararSonSiraNo=params.decision_end_seq_karar or "",
          baslangicTarihi=params.start_date or "",
          bitisTarihi=params.end_date or "",
          siralama=params.sort_criteria,
          siralamaDirection=params.sort_direction,
          pageSize=params.page_size,
          pageNumber=params.page_number
      )
      
      # Create request dict and remove empty string fields to avoid API issues
      payload_dict = data_for_api_payload.model_dump(by_alias=True, exclude_none=True)
      # Remove empty string fields that might cause API issues
      cleaned_payload = {k: v for k, v in payload_dict.items() if v != ""}
      final_payload = {"data": cleaned_payload} 
      
      logger.info(f"EmsalApiClient: Performing DETAILED search with payload: {final_payload}")
      return await self._execute_api_search(self.DETAILED_SEARCH_ENDPOINT, final_payload)

• emsal_mcp_module/models.py:37-61 (schema)

  Pydantic input schema for the tool, defining all parameters for detailed Emsal decision search with descriptions and defaults.

  class EmsalSearchRequest(BaseModel): # This is the model the MCP tool will accept
      """Model for Emsal detailed search request, with user-friendly field names."""
      keyword: str = Field("", description="Keyword")
      
      selected_bam_civil_court: str = Field("", description="BAM Civil Court")
      selected_civil_court: str = Field("", description="Civil Court")
      selected_regional_civil_chambers: List[str] = Field(default_factory=list, description="Regional chambers")
  
      case_year_esas: str = Field("", description="Case year")
      case_start_seq_esas: str = Field("", description="Start case no")
      case_end_seq_esas: str = Field("", description="End case no")
      
      decision_year_karar: str = Field("", description="Decision year")
      decision_start_seq_karar: str = Field("", description="Start decision no")
      decision_end_seq_karar: str = Field("", description="End decision no")
      
      start_date: str = Field("", description="Start date (DD.MM.YYYY)")
      end_date: str = Field("", description="End date (DD.MM.YYYY)")
      
      sort_criteria: str = Field("1", description="Sort by")
      sort_direction: str = Field("desc", description="Direction")
      
      page_number: int = Field(default=1, ge=1)
      page_size: int = Field(default=10, ge=1, le=10)

• emsal_mcp_module/client.py:75-97 (helper)

  Helper function that executes the HTTP POST to the Emsal API, parses response into EmsalApiResponse, adds document URLs to results.

  async def _execute_api_search(self, endpoint: str, payload: Dict) -> EmsalApiResponse:
      """Helper method to execute search POST request and process response for Emsal."""
      try:
          response = await self.http_client.post(endpoint, json=payload)
          response.raise_for_status()
          response_json_data = response.json()
          logger.debug(f"EmsalApiClient: Raw API response from {endpoint}: {response_json_data}")
          
          api_response_parsed = EmsalApiResponse(**response_json_data)
  
          if api_response_parsed.data and api_response_parsed.data.data:
              for decision_item in api_response_parsed.data.data:
                  if decision_item.id:
                      decision_item.document_url = f"{self.BASE_URL}{self.DOCUMENT_ENDPOINT}?id={decision_item.id}"
          
          return api_response_parsed
      except httpx.RequestError as e:
          logger.error(f"EmsalApiClient: HTTP request error during Emsal search to {endpoint}: {e}")
          raise
      except Exception as e:
          logger.error(f"EmsalApiClient: Error processing or validating Emsal search response from {endpoint}: {e}")
          raise

• emsal_mcp_module/models.py:86-89 (schema)

  Output/response schema models for the API response, including decision entries with added document_url.

  """Model for the complete search response from the Emsal API."""
  data: Optional[EmsalApiResponseInnerData] = None
  metadata: Optional[Dict[str, Any]] = Field(None, description="Optional metadata (Meta Veri) from API, if any.")