İhale MCP

Instructions

Implementation Reference

• ihale_mcp.py:226-242 (handler)

  MCP tool handler for search_authorities. Defines input schema via Annotated types, decorated with @mcp.tool for registration, and delegates to EKAPClient helper.

  @mcp.tool
  async def search_authorities(
      search_term: Annotated[str, "Search term to find matching authorities/institutions by name"] = "",
      limit: Annotated[int, "Maximum number of results to return (1-500)"] = 50
  ) -> Dict[str, Any]:
      """
      Search Turkish government authorities/institutions.
      
      Find ministries, municipalities, universities for tender filtering.
      Search in Turkish for best results.
      """
      
      # Use the client to search authorities
      return await ekap_client.search_authorities(
          search_term=search_term,
          limit=limit
      )

• ihale_client.py:558-639 (helper)

  Core helper method in EKAPClient class that implements the authority search by constructing API parameters and calling the EKAP v2 authority endpoint (/b_idare/api/DetsisKurumBirim/DetsisAgaci).

  async def search_authorities(
      self,
      search_term: str = "",
      limit: int = 50
  ) -> Dict[str, Any]:
      """Search Turkish government authorities/institutions"""
      
      # Validate limit
      if limit > 500:
          limit = 500
      elif limit < 1:
          limit = 1
      
      # Build API request payload for authority search
      authority_params = {
          "loadOptions": {
              "filter": {
                  "sort": [],
                  "group": [],
                  "filter": [],
                  "totalSummary": [],
                  "groupSummary": [],
                  "select": [],
                  "preSelect": [],
                  "primaryKey": []
              }
          }
      }
      
      # Add search filters if provided
      filters = []
      
      if search_term:
          # Search in authority names (correct field name is 'ad')
          filters.append(["ad", "contains", search_term])
      
      if filters:
          authority_params["loadOptions"]["filter"]["filter"] = filters
      
      # Set take limit for API
      authority_params["loadOptions"]["take"] = limit
      
      try:
          # Make API request to authority endpoint
          response_data = await self._make_request(self.authority_endpoint, authority_params)
          
          # Parse and format the response
          authority_items = response_data.get("loadResult", {}).get("data", [])
          
          # Format each authority for better readability
          results = []
          for item in authority_items:
              results.append({
                  "id": item.get("id"),
                  "name": item.get("ad"),
                  "parent_id": item.get("parentIdareKimlikKodu"),
                  "level": item.get("seviye"),
                  "has_children": item.get("hasItems", False),
                  "child_count": 0,  # Not available in response
                  "detsis_no": item.get("detsisNo"),
                  "idare_id": item.get("idareId")
              })
          
          return {
              "authorities": results,
              "total_found": len(results),
              "search_params": {
                  "search_term": search_term,
                  "limit": limit
              }
          }
          
      except httpx.HTTPStatusError as e:
          return {
              "error": f"API request failed with status {e.response.status_code}",
              "message": str(e)
          }
      except Exception as e:
          return {
              "error": "Request failed - authority search",
              "message": str(e)
          }