Mevzuat MCP

Instructions

Implementation Reference

• mevzuat_mcp_server.py:727-816 (handler)

  The main handler and registration for the 'search_cbbaskankarar' tool using @app.tool(). It constructs a MevzuatSearchRequestNew with mevzuat_tur='Cumhurbaşkanı Kararı' and delegates the search to mevzuat_client.search_documents, handling errors and logging.

  async def search_cbbaskankarar(
      aranacak_ifade: Optional[str] = Field(
          None,
          description='Search query with optional Boolean operators: simple word (organize), AND (organize AND suç), OR (suç OR ceza), NOT (organize NOT terör), + for required (+term), grouping with (), exact phrase with quotes ("organize suç"). Leave empty to list all decrees.'
      ),
      tam_cumle: bool = Field(
          False,
          description="Exact phrase match (true) or any word match (false, default). Set to true when searching for exact phrases."
      ),
      baslangic_tarihi: Optional[str] = Field(
          None,
          description="Start year for filtering results (format: YYYY, e.g., '2018')"
      ),
      bitis_tarihi: Optional[str] = Field(
          None,
          description="End year for filtering results (format: YYYY, e.g., '2024')"
      ),
      page_number: int = Field(
          1,
          ge=1,
          description="Page number for pagination (starts at 1)"
      ),
      page_size: int = Field(
          25,
          ge=1,
          le=100,
          description="Number of results per page (1-100)"
      )
  ) -> MevzuatSearchResultNew:
      """
      Search for Turkish Presidential Decisions (Cumhurbaşkanı Kararı) in both titles and content.
  
      This tool searches in Presidential Decision titles and full text content.
      Presidential Decisions are executive decisions issued by the President of Turkey (different from Presidential Decrees/Kararnamesi).
  
      Query Syntax:
      - Simple keyword: atama
      - Boolean AND: atama AND tayin (both terms)
      - Boolean OR: atama OR görevden (at least one term)
      - Boolean NOT: atama NOT görevden (first yes, second no)
      - Required term: +atama +tayin (similar to AND)
      - Grouping: (atama OR tayin) AND görev
      - Exact phrase: "görevden alma" (or use tam_cumle=true)
      - Empty search: List all decisions (use date filters)
  
      Returns:
      - Decision number, title, and publication date
      - Official Gazette publication date and issue number
      - URLs for viewing online (PDF format)
  
      Example queries:
      - "atama tayin" - Find decisions about appointments
      - Leave empty with dates to list all decisions from a period
      - "görevden AND alma" - Decisions about dismissals
      """
      search_req = MevzuatSearchRequestNew(
          mevzuat_tur="Cumhurbaşkanı Kararı",
          aranacak_ifade=aranacak_ifade or "",
          aranacak_yer=1,  # Search in titles and content
          tam_cumle=tam_cumle,
          mevzuat_no=None,
          baslangic_tarihi=baslangic_tarihi,
          bitis_tarihi=bitis_tarihi,
          page_number=page_number,
          page_size=page_size
      )
  
      log_params = search_req.model_dump(exclude_defaults=True)
      logger.info(f"Tool 'search_cbbaskankarar' called with parameters: {log_params}")
  
      try:
          result = await mevzuat_client.search_documents(search_req)
  
          if not result.documents and not result.error_message:
              result.error_message = "No Presidential Decisions found matching the specified criteria."
  
          return result
  
      except Exception as e:
          logger.exception("Error in tool 'search_cbbaskankarar'")
          return MevzuatSearchResultNew(
              documents=[],
              total_results=0,
              current_page=page_number,
              page_size=page_size,
              total_pages=0,
              query_used=log_params,
              error_message=f"An unexpected error occurred: {str(e)}"
          )

• mevzuat_models.py:107-117 (schema)

  Output schema: MevzuatSearchResultNew model defining the structure of search results returned by the tool.

  class MevzuatSearchResultNew(BaseModel):
      """Model for search results from mevzuat.gov.tr"""
  
      documents: List[MevzuatDocumentNew]
      total_results: int
      current_page: int
      page_size: int
      total_pages: int
      query_used: Dict[str, Any]
      error_message: Optional[str] = None

• mevzuat_models.py:32-84 (schema)

  Input schema components: MevzuatSearchRequestNew model used internally by the tool for API requests. Tool parameters map directly to this model.

  class MevzuatSearchRequestNew(BaseModel):
      """Request model for searching legislation on mevzuat.gov.tr"""
  
      mevzuat_tur: MevzuatTurLiteral = Field(
          "Kanun",
          description="Type of legislation. Currently only 'Kanun' (laws) are fully supported for content extraction."
      )
  
      aranacak_ifade: Optional[str] = Field(
          None,
          description="Search term or phrase to look for in legislation"
      )
  
      aranacak_yer: int = Field(
          3,
          ge=1,
          le=3,
          description="Where to search: 1=Title only, 2=Article titles, 3=Full text (default)"
      )
  
      tam_cumle: bool = Field(
          False,
          description="Exact phrase match (true) or any word match (false, default)"
      )
  
      mevzuat_no: Optional[str] = Field(
          None,
          description="Specific legislation number to search for"
      )
  
      baslangic_tarihi: Optional[str] = Field(
          None,
          description="Start date for filtering (format: DD.MM.YYYY)"
      )
  
      bitis_tarihi: Optional[str] = Field(
          None,
          description="End date for filtering (format: DD.MM.YYYY)"
      )
  
      page_number: int = Field(
          1,
          ge=1,
          description="Page number of results"
      )
  
      page_size: int = Field(
          10,
          ge=1,
          le=100,
          description="Number of results per page"
      )

• mevzuat_client.py:451-556 (helper)

  Core helper method implementing the search logic: search_documents in MevzuatApiClientNew. Makes authenticated POST request to mevzuat.gov.tr API, parses JSON response into documents.

  async def search_documents(self, request: MevzuatSearchRequestNew) -> MevzuatSearchResultNew:
      """Search for legislation documents using httpx with Playwright cookies."""
      # Get session/cookies with Playwright first
      await self._ensure_session()
  
      # If session establishment failed, fallback to full Playwright method
      if not self._antiforgery_token and not self._cookies:
          logger.warning("Session establishment failed, using full Playwright search method as fallback")
          return await self.search_documents_with_playwright(request)
  
      # Build DataTables compatible payload
      # Normalize mevzuat type for API
      mevzuat_tur_api = self._normalize_mevzuat_tur_for_api(request.mevzuat_tur)
  
      payload = {
          "draw": 1,
          "columns": [
              {"data": None, "name": "", "searchable": True, "orderable": False, "search": {"value": "", "regex": False}},
              {"data": None, "name": "", "searchable": True, "orderable": False, "search": {"value": "", "regex": False}},
              {"data": None, "name": "", "searchable": True, "orderable": False, "search": {"value": "", "regex": False}}
          ],
          "order": [],
          "start": (request.page_number - 1) * request.page_size,
          "length": request.page_size,
          "search": {"value": "", "regex": False},
          "parameters": {
              "MevzuatTur": mevzuat_tur_api,
              "YonetmelikMevzuatTur": "OsmanliKanunu",  # Required for all searches
              "AranacakIfade": request.aranacak_ifade or "",
              "TamCumle": "true" if request.tam_cumle else "false",
              "AranacakYer": str(request.aranacak_yer),
              "MevzuatNo": request.mevzuat_no or "",
              "KurumId": "0",
              "AltKurumId": "0",
              "BaslangicTarihi": request.baslangic_tarihi or "",
              "BitisTarihi": request.bitis_tarihi or "",
              "antiforgerytoken": self._antiforgery_token or ""
          }
      }
  
      try:
          # Log payload for debugging
          logger.debug(f"Search payload: {payload}")
  
          # Make request with cookies properly
          response = await self._http_client.post(
              self.SEARCH_ENDPOINT,
              json=payload,
              cookies=self._cookies if self._cookies else None
          )
  
          # Log response for debugging
          if response.status_code != 200:
              logger.error(f"Search API error {response.status_code}: {response.text[:500]}")
  
          response.raise_for_status()
          data = response.json()
  
          total_results = data.get("recordsTotal", 0)
          documents = []
  
          for item in data.get("data", []):
              doc = MevzuatDocumentNew(
                  mevzuat_no=item.get("mevzuatNo", ""),
                  mev_adi=item.get("mevAdi", ""),
                  kabul_tarih=item.get("kabulTarih", ""),
                  resmi_gazete_tarihi=item.get("resmiGazeteTarihi", ""),
                  resmi_gazete_sayisi=item.get("resmiGazeteSayisi", ""),
                  mevzuat_tertip=item.get("mevzuatTertip", ""),
                  mevzuat_tur=item.get("tur", 1),
                  url=item.get("url", "")
              )
              documents.append(doc)
  
          return MevzuatSearchResultNew(
              documents=documents,
              total_results=total_results,
              current_page=request.page_number,
              page_size=request.page_size,
              total_pages=(total_results + request.page_size - 1) // request.page_size if request.page_size > 0 else 0,
              query_used=request.model_dump()
          )
  
      except httpx.HTTPStatusError as e:
          logger.error(f"Search request failed: {e.response.status_code}")
          return MevzuatSearchResultNew(
              documents=[],
              total_results=0,
              current_page=request.page_number,
              page_size=request.page_size,
              total_pages=0,
              query_used=request.model_dump(),
              error_message=f"API request failed: {e.response.status_code}"
          )
      except Exception as e:
          logger.exception("Unexpected error during search")
          return MevzuatSearchResultNew(
              documents=[],
              total_results=0,
              current_page=request.page_number,
              page_size=request.page_size,
              total_pages=0,
              query_used=request.model_dump(),
              error_message=f"An unexpected error occurred: {e}"
          )