Yargı MCP

Instructions

Implementation Reference

• mcp_server_main.py:600-664 (handler)

  The primary handler function decorated with @app.tool for the 'search_emsal_detailed_decisions' MCP tool. It accepts detailed search parameters, constructs an EmsalSearchRequest Pydantic model, invokes the EmsalApiClient's search_detailed_decisions method, processes the response into a CompactEmsalSearchResult, and serializes it to a dictionary for the MCP protocol response.
  @app.tool( description="Search Emsal precedent decisions with detailed criteria", annotations={ "readOnlyHint": True, "openWorldHint": True, "idempotentHint": True } ) async def search_emsal_detailed_decisions( keyword: str = Field("", description="Keyword to search."), selected_bam_civil_court: str = Field("", description="Selected BAM Civil Court."), selected_civil_court: str = Field("", description="Selected Civil Court."), selected_regional_civil_chambers: List[str] = Field(default_factory=list, description="Selected Regional Civil Chambers."), case_year_esas: str = Field("", description="Case year for 'Esas No'."), case_start_seq_esas: str = Field("", description="Starting sequence for 'Esas No'."), case_end_seq_esas: str = Field("", description="Ending sequence for 'Esas No'."), decision_year_karar: str = Field("", description="Decision year for 'Karar No'."), decision_start_seq_karar: str = Field("", description="Starting sequence for 'Karar No'."), decision_end_seq_karar: str = Field("", description="Ending sequence for 'Karar No'."), start_date: str = Field("", description="Start date for decision (DD.MM.YYYY)."), end_date: str = Field("", description="End date for decision (DD.MM.YYYY)."), sort_criteria: str = Field("1", description="Sorting criteria (e.g., 1: Esas No)."), sort_direction: str = Field("desc", description="Sorting direction ('asc' or 'desc')."), page_number: int = Field(1, ge=1, description="Page number (accepts int)."), # page_size: int = Field(10, ge=1, le=10, description="Results per page.") ) -> Dict[str, Any]: """Search Emsal precedent decisions with detailed criteria.""" page_size = 10 # Default value search_query = EmsalSearchRequest( keyword=keyword, selected_bam_civil_court=selected_bam_civil_court, selected_civil_court=selected_civil_court, selected_regional_civil_chambers=selected_regional_civil_chambers, case_year_esas=case_year_esas, case_start_seq_esas=case_start_seq_esas, case_end_seq_esas=case_end_seq_esas, decision_year_karar=decision_year_karar, decision_start_seq_karar=decision_start_seq_karar, decision_end_seq_karar=decision_end_seq_karar, start_date=start_date, end_date=end_date, sort_criteria=sort_criteria, sort_direction=sort_direction, page_number=page_number, page_size=page_size ) logger.info(f"Tool 'search_emsal_detailed_decisions' called.") try: api_response = await emsal_client_instance.search_detailed_decisions(search_query) if api_response.data: return CompactEmsalSearchResult( decisions=api_response.data.data, total_records=api_response.data.recordsTotal if api_response.data.recordsTotal is not None else 0, requested_page=search_query.page_number, page_size=search_query.page_size ).model_dump() logger.warning("API response for Emsal search did not contain expected data structure.") return CompactEmsalSearchResult(decisions=[], total_records=0, requested_page=search_query.page_number, page_size=search_query.page_size).model_dump() except Exception as e: logger.exception(f"Error in tool 'search_emsal_detailed_decisions'.") raise
• emsal_mcp_module/models.py:37-61 (schema)

  Pydantic BaseModel defining the input schema for the search_emsal_detailed_decisions tool, with user-friendly field names and descriptions matching the tool parameters. Used directly in the handler to instantiate the search query.
  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:41-74 (helper)

  Core helper method in EmsalApiClient class that transforms EmsalSearchRequest into API-specific EmsalDetailedSearchRequestData payload (using field aliases matching the Emsal API), cleans empty fields, sends POST request to /aramadetaylist endpoint via _execute_api_search, parses EmsalApiResponse, and appends document URLs to results.
  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:96-101 (schema)

  Pydantic model for the compact output schema returned by the tool handler after processing the API response.
  class CompactEmsalSearchResult(BaseModel): """A compact search result model for the MCP tool to return.""" decisions: List[EmsalApiDecisionEntry] total_records: int requested_page: int page_size: int
• emsal_mcp_module/client.py:75-97 (helper)

  Supporting private helper method that performs the actual HTTP POST to the Emsal search endpoint, parses and validates the JSON response into EmsalApiResponse model, and dynamically adds document_url to each decision entry.
  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