Mevzuat MCP

Instructions

Implementation Reference

• mevzuat_mcp_server.py:1286-1375 (handler)

  Primary handler for 'search_within_tuzuk' tool. Fetches Tüzük content via API client, invokes article search helper, formats and returns matching articles or error. Includes input schema via Pydantic Fields and @app.tool() registration.

  @app.tool()
  async def search_within_tuzuk(
      mevzuat_no: str = Field(
          ...,
          description="The statute number to search within (e.g., '20135150', '20134513', '200814001')"
      ),
      keyword: str = Field(
          ...,
          description='Search query supporting advanced operators: simple keyword ("kayıt"), exact phrase ("sicil kayıt"), AND/OR/NOT operators (tapu AND sicil, tescil OR ilan, kayıt NOT iptal). Operators must be uppercase.'
      ),
      mevzuat_tertip: str = Field(
          "5",
          description="Statute series from search results (e.g., '5')"
      ),
      case_sensitive: bool = Field(
          False,
          description="Whether to match case when searching (default: False)"
      ),
      max_results: int = Field(
          25,
          ge=1,
          le=50,
          description="Maximum number of matching articles to return (1-50, default: 25)"
      )
  ) -> str:
      """
      Search for a keyword within a specific Statute's (Tüzük) articles with advanced query operators.
  
      This tool is optimized for large statutes.
      Instead of loading the entire statute into context, it:
      1. Fetches the full content
      2. Splits it into individual articles (madde)
      3. Returns only the articles that match the search query
      4. Sorts results by relevance score (based on match count)
  
      Query Syntax (operators must be uppercase):
      - Simple keyword: kayıt
      - Exact phrase: "sicil kayıt"
      - AND operator: tapu AND sicil (both terms must be present)
      - OR operator: tescil OR ilan (at least one term must be present)
      - NOT operator: kayıt NOT iptal (first term present, second must not be)
      - Combinations: "sicil kayıt" AND tapu NOT iptal
  
      Returns formatted text with:
      - Article number and title
      - Relevance score (higher = more matches)
      - Full article content for matching articles
  
      Example use cases:
      - Search for "tapu" in Tapu Sicili Tüzüğü (20135150)
      - Search for "tescil AND ilan" in Vakıflar Tüzüğü (20134513)
      - Search for "kayıt OR sicil" in cadastral statutes
      """
      logger.info(f"Tool 'search_within_tuzuk' called: {mevzuat_no}, keyword: '{keyword}'")
  
      try:
          # Get full content
          content_result = await mevzuat_client.get_content(
              mevzuat_no=mevzuat_no,
              mevzuat_tur=2,  # Tüzük
              mevzuat_tertip=mevzuat_tertip
          )
  
          if content_result.error_message:
              return f"Error fetching statute content: {content_result.error_message}"
  
          # Search within articles
          matches = search_articles_by_keyword(
              markdown_content=content_result.markdown_content,
              keyword=keyword,
              case_sensitive=case_sensitive,
              max_results=max_results
          )
  
          result = ArticleSearchResult(
              mevzuat_no=mevzuat_no,
              mevzuat_tur=2,
              keyword=keyword,
              total_matches=len(matches),
              matching_articles=matches
          )
  
          if len(matches) == 0:
              return f"No articles found containing '{keyword}' in Tüzük {mevzuat_no}"
  
          return format_search_results(result)
  
      except Exception as e:
          logger.exception(f"Error in tool 'search_within_tuzuk' for {mevzuat_no}")
          return f"An unexpected error occurred while searching Tüzük {mevzuat_no}: {str(e)}"

• article_search.py:176-251 (helper)

  Core helper implementing article extraction from markdown, advanced query parsing (AND/OR/NOT/\"phrase\"), relevance scoring, and filtering for matching articles.

  def search_articles_by_keyword(
      markdown_content: str,
      keyword: str,
      case_sensitive: bool = False,
      max_results: int = 50
  ) -> List[MaddeMatch]:
      """
      Search for keyword within articles with support for advanced operators.
  
      Query syntax:
      - Simple keyword: "yatırımcı"
      - Exact phrase: "mali sıkıntı"
      - AND operator: yatırımcı AND tazmin
      - OR operator: yatırımcı OR müşteri
      - NOT operator: yatırımcı NOT kurum
      - Combinations: "mali sıkıntı" AND yatırımcı NOT kurum
  
      Args:
          markdown_content: Full legislation content in markdown
          keyword: Search query with optional operators (AND, OR, NOT, "exact phrase")
          case_sensitive: Whether to match case
          max_results: Maximum number of matching articles to return
  
      Returns:
          List of matching articles sorted by relevance (score based on match count)
      """
      articles = split_into_articles(markdown_content)
      matches = []
  
      for article in articles:
          content = article['madde_content']
  
          # Check if article matches query
          matches_query, score = _matches_query(content, keyword, case_sensitive)
  
          if matches_query and score > 0:
              # Generate preview (first occurrence of a search term)
              search_content = content if case_sensitive else content.lower()
              search_keyword = keyword if case_sensitive else keyword.lower()
  
              # Try to find first quoted phrase or first word
              preview_terms = re.findall(r'"([^"]*)"', search_keyword)
              if not preview_terms:
                  # Use first word (excluding operators)
                  words = re.split(r'\s+(?:AND|OR|NOT)\s+', search_keyword)
                  preview_terms = [w.strip() for w in words if w.strip() and w.strip() not in ('AND', 'OR', 'NOT')]
  
              preview = ""
              if preview_terms:
                  first_term = preview_terms[0] if case_sensitive else preview_terms[0].lower()
                  if first_term in search_content:
                      keyword_pos = search_content.find(first_term)
                      start = max(0, keyword_pos - 100)
                      end = min(len(content), keyword_pos + len(first_term) + 100)
                      preview = content[start:end]
  
                      if start > 0:
                          preview = "..." + preview
                      if end < len(content):
                          preview = preview + "..."
  
              if not preview:
                  preview = content[:200] + "..."
  
              matches.append(MaddeMatch(
                  madde_no=article['madde_no'],
                  madde_title=article['madde_title'],
                  madde_content=content,
                  match_count=score,
                  preview=preview
              ))
  
      # Sort by score (most relevant first)
      matches.sort(key=lambda x: x.match_count, reverse=True)
  
      return matches[:max_results]

• article_search.py:254-271 (helper)

  Helper function that formats the ArticleSearchResult into a human-readable string output returned by the tool.

  def format_search_results(result: ArticleSearchResult) -> str:
      """Format search results as readable text."""
      output = []
      output.append(f"Keyword: '{result.keyword}'")
      output.append(f"Total matching articles: {result.total_matches}")
      output.append("")
  
      for i, match in enumerate(result.matching_articles, 1):
          output.append(f"=== MADDE {match.madde_no} ===")
          if match.madde_title:
              output.append(f"Title: {match.madde_title}")
          output.append(f"Matches: {match.match_count}")
          output.append("")
          output.append("Full content:")
          output.append(match.madde_content)
          output.append("")
  
      return "\n".join(output)

• article_search.py:19-25 (schema)

  Pydantic model defining the internal structure for search results passed between handler and format helper.

  class ArticleSearchResult(BaseModel):
      """Search results within a legislation."""
      mevzuat_no: str
      mevzuat_tur: int
      keyword: str
      total_matches: int
      matching_articles: List[MaddeMatch]

• article_search.py:10-16 (schema)

  Pydantic model for individual matching article data used in search results.

  class MaddeMatch(BaseModel):
      """A single article match result."""
      madde_no: str  # e.g., "1", "15", "142"
      madde_title: str  # e.g., "Amaç", "Tanımlar"
      madde_content: str  # Full article text
      match_count: int  # Number of keyword occurrences
      preview: str  # Short preview showing keyword in context