get_tender_details

Instructions

Implementation Reference

• ihale_mcp.py:324-354 (handler)

  MCP tool handler function for 'get_tender_details'. This is the main entrypoint for the tool, decorated with @mcp.tool for registration, with input schema via Annotated type hint, and delegates to EKAPClient for core logic.

  @mcp.tool
  async def get_tender_details(
      tender_id: Annotated[int, "The tender ID to get comprehensive details for"]
  ) -> Dict[str, Any]:
      """
      Get comprehensive tender details with HTML-to-Markdown conversion.
      
      Returns: basic info, characteristics, OKAS codes, authority details, 
      process rules, announcements summary, cancellation info if applicable.
      """
      
      # Use the client to get tender details
      result = await ekap_client.get_tender_details(tender_id)
      
      if result.get("error"):
          return result
      
      return {
          "tender_details": result,
          "summary": {
              "tender_name": result.get("name"),
              "ikn": result.get("ikn"),
              "status": result.get("status", {}).get("description"),
              "authority": result.get("authority", {}).get("name"),
              "location": result.get("basic_info", {}).get("location"),
              "is_electronic": result.get("basic_info", {}).get("is_electronic"),
              "characteristics_count": len(result.get("characteristics", [])),
              "okas_codes_count": len(result.get("okas_codes", [])),
              "announcements_count": result.get("announcements_summary", {}).get("total_count", 0)
          }
      }

• ihale_client.py:744-922 (helper)

  Core helper implementation in EKAPClient class that fetches tender details from EKAP API endpoint '/b_ihalearama/api/IhaleDetay/GetByIhaleIdIhaleDetay', parses response, converts HTML to Markdown, formats data including characteristics, OKAS codes, authority info, process rules, and announcements summary.

  async def get_tender_details(
      self,
      tender_id: int
  ) -> Dict[str, Any]:
      """Get comprehensive details for a specific tender"""
      
      # Build API request payload for tender details
      details_params = {
          "ihaleId": str(tender_id)
      }
      
      try:
          # Make API request to tender details endpoint
          response_data = await self._make_request(self.tender_details_endpoint, details_params)
          
          # Parse and format the response
          item = response_data.get("item", {})
          
          if not item:
              return {
                  "error": "Tender details not found",
                  "tender_id": tender_id
              }
          
          # Format tender characteristics
          characteristics = []
          for char in item.get("ihaleOzellikList", []):
              char_text = char.get("ihaleOzellik", "")
              # Clean up the characteristic text
              if "TENDER_DETAIL." in char_text:
                  char_text = char_text.replace("TENDER_DETAIL.", "").replace("_", " ").title()
              characteristics.append(char_text)
          
          # Format basic tender info
          basic_info = item.get("ihaleBilgi", {})
          
          # Format OKAS codes
          okas_codes = []
          for okas in item.get("ihtiyacKalemiOkasList", []):
              okas_codes.append({
                  "code": okas.get("kodu"),
                  "name": okas.get("adi"),
                  "full_description": okas.get("koduAdi")
              })
          
          # Format authority info
          authority = item.get("idare", {})
          authority_info = {
              "id": authority.get("id"),
              "name": authority.get("adi"),
              "code1": authority.get("kod1"),
              "code2": authority.get("kod2"),
              "phone": authority.get("telefon"),
              "fax": authority.get("fax"),
              "parent_authority": authority.get("ustIdare"),
              "top_authority_code": authority.get("enUstIdareKod"),
              "top_authority_name": authority.get("enUstIdareAdi"),
              "province": authority.get("il", {}).get("adi"),
              "district": authority.get("ilce", {}).get("ilceAdi")
          }
          
          # Format process rules
          rules = item.get("islemlerKuralSeti", {})
          process_rules = {
              "can_download_documents": rules.get("dokumanIndirmisMi", False),
              "has_submitted_bid": rules.get("teklifteBulunmusMu", False),
              "can_submit_bid": rules.get("teklifVerilebilirMi", False),
              "has_non_price_factors": rules.get("fiyatDisiUnsurVarMi", False),
              "contract_signed": rules.get("sozlesmeImzaliMi", False),
              "is_electronic": rules.get("eIhaleMi", False),
              "is_own_tender": rules.get("idareKendiIhaleMi", False),
              "electronic_auction": rules.get("eEksiltmeYapilacakMi", False)
          }
          
          # Initialize markdown converter for tender details HTML content
          markitdown = MarkItDown()
          
          # Format announcements list (basic info) with markdown conversion
          announcements = []
          for announcement in item.get("ilanList", []):
              # Map announcement types
              announcement_type_map = {
                  "1": "Ön İlan",
                  "2": "İhale İlanı", 
                  "3": "İptal İlanı",
                  "4": "Sonuç İlanı",
                  "5": "Ön Yeterlik İlanı",
                  "6": "Düzeltme İlanı"
              }
              
              announcement_type = announcement.get("ilanTip", "")
              announcement_type_desc = announcement_type_map.get(announcement_type, f"Type {announcement_type}")
              
              # Convert HTML content to markdown if available
              html_content = announcement.get("veriHtml", "")
              markdown_content = None
              if html_content:
                  try:
                      # Create BytesIO from HTML content
                      html_bytes = BytesIO(html_content.encode('utf-8'))
                      result = markitdown.convert_stream(html_bytes, file_extension=".html")
                      markdown_content = result.text_content if result else None
                  except Exception as e:
                      print(f"Warning: Failed to convert HTML to markdown in tender details: {e}")
                      markdown_content = None
              
              announcements.append({
                  "id": announcement.get("id"),
                  "type": {
                      "code": announcement_type,
                      "description": announcement_type_desc
                  },
                  "title": announcement.get("baslik"),
                  "date": announcement.get("ilanTarihi"),
                  "status": announcement.get("status"),
                  "markdown_content": markdown_content,
                  "content_preview": self._extract_text_preview(html_content)
              })
          
          # Build comprehensive response
          result = {
              "tender_id": item.get("id"),
              "ikn": item.get("ikn"),
              "name": item.get("ihaleAdi"),
              "status": {
                  "code": item.get("ihaleDurum"),
                  "description": basic_info.get("ihaleDurumAciklama")
              },
              "basic_info": {
                  "is_electronic": item.get("eIhale", False),
                  "method_code": item.get("ihaleUsul"),
                  "method_description": basic_info.get("ihaleUsulAciklama"),
                  "type_description": basic_info.get("ihaleTipiAciklama"),
                  "scope_description": item.get("ihaleKapsamAciklama"),
                  "tender_datetime": basic_info.get("ihaleTarihSaat"),
                  "location": basic_info.get("isinYapilacagiYer"),
                  "venue": basic_info.get("ihaleYeri"),
                  "complaint_fee": basic_info.get("itirazenSikayetBasvuruBedeli"),
                  "is_partial": item.get("kismiIhale", False)
              },
              "characteristics": characteristics,
              "okas_codes": okas_codes,
              "authority": authority_info,
              "process_rules": process_rules,
              "announcements_summary": {
                  "total_count": len(announcements),
                  "announcements": announcements,
                  "types_available": list(set(ann["type"]["description"] for ann in announcements))
              },
              "flags": {
                  "is_authority_tender": item.get("ihaleniIdaresiMi", False),
                  "is_without_announcement": item.get("ihaleIlansizMi", False),
                  "is_invitation_only": item.get("ihaleyeDavetEdilenMi", False),
                  "show_detail_documents": item.get("ihaleDetayDokumaniGorsunMu", False),
                  "show_document_downloaders": item.get("dokumanIndirenlerGosterilsinMi", False)
              },
              "document_count": item.get("dokumanSayisi", 0)
          }
          
          # Add cancellation info if tender is cancelled
          if basic_info.get("iptalTarihi"):
              result["cancellation_info"] = {
                  "cancelled_date": basic_info.get("iptalTarihi"),
                  "cancellation_reason": basic_info.get("iptalNedeni"),
                  "cancellation_article": basic_info.get("iptalMadde")
              }
          
          return result
          
      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 - tender details",
              "message": str(e)
          }

• ihale_mcp.py:21-29 (registration)

  MCP server initialization. Tool functions decorated with @mcp.tool are automatically registered here.

  mcp = FastMCP(
      name="ihale-mcp",
      instructions="""
  This server provides access to Turkish government tender (ihale) data from EKAP v2 portal.
  Use the search_tenders tool to find tenders based on various criteria.
  The server supports filtering by text, tender type, region, dates, and other parameters.
  All tender information is in Turkish as it comes directly from the government portal.
  """
  )

• ihale_mcp.py:32-32 (helper)

  Global EKAPClient instance used by all EKAP-related tools including get_tender_details.

  ekap_client = EKAPClient()

• ihale_mcp.py:11-11 (helper)

  Import of EKAPClient class containing the core API logic.

  from ihale_client import EKAPClient