search_kvkk_decisions

Instructions

Implementation Reference

• kvkk_mcp_module/client.py:106-193 (handler)

  Main handler function that performs the KVKK decisions search using Brave Search API, extracts metadata, and returns structured results.

  async def search_decisions(self, params: KvkkSearchRequest) -> KvkkSearchResult:
      """Search for KVKK decisions using Brave API."""
      
      search_query = self._construct_search_query(params.keywords)
      logger.info(f"KvkkApiClient: Searching with query: {search_query}")
      
      try:
          # Calculate offset for pagination
          offset = (params.page - 1) * params.pageSize
          
          response = await self.http_client.get(
              self.BRAVE_API_URL,
              headers={
                  "Accept": "application/json",
                  "Accept-Encoding": "gzip",
                  "x-subscription-token": self.brave_api_token
              },
              params={
                  "q": search_query,
                  "country": "TR",
                  "search_lang": "tr",
                  "ui_lang": "tr-TR",
                  "offset": offset,
                  "count": params.pageSize
              }
          )
          
          response.raise_for_status()
          data = response.json()
          
          # Extract search results
          decisions = []
          web_results = data.get("web", {}).get("results", [])
          
          for result in web_results:
              title = result.get("title", "")
              url = result.get("url", "")
              description = result.get("description", "")
              
              # Extract metadata from title
              metadata = self._extract_decision_metadata_from_title(title)
              
              # Extract decision ID from URL
              decision_id = self._extract_decision_id_from_url(url)
              
              decision = KvkkDecisionSummary(
                  title=title,
                  url=HttpUrl(url) if url else None,
                  description=description,
                  decision_id=decision_id,
                  publication_date=metadata.get("decision_date"),
                  decision_number=metadata.get("decision_number")
              )
              decisions.append(decision)
          
          # Get total results if available
          total_results = None
          query_info = data.get("query", {})
          if "total_results" in query_info:
              total_results = query_info["total_results"]
          
          return KvkkSearchResult(
              decisions=decisions,
              total_results=total_results,
              page=params.page,
              pageSize=params.pageSize,
              query=search_query
          )
          
      except httpx.RequestError as e:
          logger.error(f"KvkkApiClient: HTTP request error during search: {e}")
          return KvkkSearchResult(
              decisions=[], 
              total_results=0, 
              page=params.page, 
              pageSize=params.pageSize,
              query=search_query
          )
      except Exception as e:
          logger.error(f"KvkkApiClient: Unexpected error during search: {e}")
          return KvkkSearchResult(
              decisions=[], 
              total_results=0, 
              page=params.page, 
              pageSize=params.pageSize,
              query=search_query
          )

• kvkk_mcp_module/models.py:6-14 (schema)

  Input schema defining the parameters for the search: keywords, page, and pageSize.

  class KvkkSearchRequest(BaseModel):
      """Model for KVKK (Personal Data Protection Authority) search request via Brave API."""
      keywords: str = Field(..., description="""
          Keywords to search for in KVKK decisions. 
          The search will automatically include 'site:kvkk.gov.tr "karar özeti"' to target KVKK decision summaries.
          Examples: "açık rıza", "veri güvenliği", "kişisel veri işleme"
      """)
      page: int = Field(1, ge=1, le=50, description="Page number for search results (1-50).")
      pageSize: int = Field(10, ge=1, le=10, description="Number of results per page (1-10).")

• kvkk_mcp_module/models.py:25-32 (schema)

  Output schema for search results including list of decisions, pagination info, and query.

  class KvkkSearchResult(BaseModel):
      """Model for the overall search result for KVKK decisions."""
      decisions: List[KvkkDecisionSummary] = Field(default_factory=list, description="List of KVKK decisions found.")
      total_results: Optional[int] = Field(None, description="Value")
      page: int = Field(1, description="Current page number of results.")
      pageSize: int = Field(10, description="Number of results per page.")
      query: Optional[str] = Field(None, description="The actual search query sent to Brave API.")

• kvkk_mcp_module/models.py:16-24 (schema)

  Schema for individual decision summary in search results.

  class KvkkDecisionSummary(BaseModel):
      """Model for a single KVKK decision summary from Brave search results."""
      title: Optional[str] = Field(None, description="Decision title from search results.")
      url: Optional[HttpUrl] = Field(None, description="URL to the KVKK decision page.")
      description: Optional[str] = Field(None, description="Brief description or snippet from search results.")
      decision_id: Optional[str] = Field(None, description="Value")
      publication_date: Optional[str] = Field(None, description="Value")
      decision_number: Optional[str] = Field(None, description="Value")

• kvkk_mcp_module/client.py:60-105 (helper)

  Helper methods for constructing search query, extracting decision ID from URL, and metadata from title used in the search handler.

  def _construct_search_query(self, keywords: str) -> str:
      """Construct the search query for Brave API."""
      base_query = 'site:kvkk.gov.tr "karar özeti"'
      if keywords.strip():
          return f"{base_query} {keywords.strip()}"
      return base_query
  
  def _extract_decision_id_from_url(self, url: str) -> Optional[str]:
      """Extract decision ID from KVKK decision URL."""
      try:
          # Example URL: https://www.kvkk.gov.tr/Icerik/7288/2021-1303
          parsed_url = urlparse(url)
          path_parts = parsed_url.path.strip('/').split('/')
          
          if len(path_parts) >= 3 and path_parts[0] == 'Icerik':
              # Extract the decision ID from the path
              decision_id = '/'.join(path_parts[1:])  # e.g., "7288/2021-1303"
              return decision_id
          
      except Exception as e:
          logger.debug(f"Could not extract decision ID from URL {url}: {e}")
      
      return None
  
  def _extract_decision_metadata_from_title(self, title: str) -> Dict[str, Optional[str]]:
      """Extract decision metadata from title string."""
      metadata = {
          "decision_date": None,
          "decision_number": None
      }
      
      if not title:
          return metadata
      
      # Extract decision date (DD/MM/YYYY format)
      date_match = re.search(r'(\d{1,2}/\d{1,2}/\d{4})', title)
      if date_match:
          metadata["decision_date"] = date_match.group(1)
      
      # Extract decision number (YYYY/XXXX format)
      number_match = re.search(r'(\d{4}/\d+)', title)
      if number_match:
          metadata["decision_number"] = number_match.group(1)
      
      return metadata