YOKATLAS API MCP Server

Instructions

Implementation Reference

• yokatlas_mcp_server.py:90-211 (handler)

  The complete handler function for 'search_bachelor_degree_programs', registered via @mcp.tool(). Includes input schema with Annotated Fields, fuzzy matching logic using yokatlas_py.search_lisans_programs (new API) or legacy YOKATLASLisansTercihSihirbazi, parameter mapping, validation, and error handling.
  @mcp.tool() def search_bachelor_degree_programs( # User-friendly parameters with fuzzy matching university: Annotated[str, Field(description="University name with fuzzy matching support (e.g., 'boğaziçi' → 'BOĞAZİÇİ ÜNİVERSİTESİ')")] = '', program: Annotated[str, Field(description="Program/department name with partial matching (e.g., 'bilgisayar' finds all computer programs)")] = '', city: Annotated[str, Field(description="City name where the university is located")] = '', score_type: Annotated[Optional[Literal['SAY', 'EA', 'SOZ', 'DIL']], Field(description="Score type")] = None, university_type: Annotated[Optional[Literal['Devlet', 'Vakıf', 'KKTC', 'Yurt Dışı']], Field(description="University type")] = None, fee_type: Annotated[Optional[Literal['Ücretsiz', 'Ücretli', 'İÖ-Ücretli', 'Burslu', '%50 İndirimli', '%25 İndirimli', 'AÖ-Ücretli', 'UÖ-Ücretli']], Field(description="Fee status: Ücretsiz (Free), Ücretli (Paid), İÖ-Ücretli (Evening-Paid), Burslu (Scholarship), İndirimli (Discounted), AÖ-Ücretli (Open Education-Paid), UÖ-Ücretli (Distance Learning-Paid)")] = None, education_type: Annotated[Optional[Literal['Örgün', 'İkinci', 'Açıköğretim', 'Uzaktan']], Field(description="Education type: Örgün (Regular), İkinci (Evening), Açıköğretim (Open Education), Uzaktan (Distance Learning)")] = None, availability: Annotated[Optional[Literal['Doldu', 'Doldu#', 'Dolmadı', 'Yeni']], Field(description="Program availability: Doldu (Filled), Doldu# (Filled with conditions), Dolmadı (Not filled), Yeni (New program)")] = None, results_limit: Annotated[int, Field(description="Maximum number of results to return", ge=1, le=500)] = 50, # Legacy parameter support for backward compatibility uni_adi: str = '', program_adi: str = '', sehir: str = '', puan_turu: str = '', universite_turu: str = '', ucret_burs: str = '', ogretim_turu: str = '', length: int = 0 ) -> dict: """ Search for bachelor's degree programs with smart fuzzy matching and user-friendly parameters. Smart Features: - Fuzzy university name matching (e.g., "boğaziçi" → "BOĞAZİÇİ ÜNİVERSİTESİ") - Partial program name matching (e.g., "bilgisayar" finds all computer programs) - Intelligent parameter normalization - Type-safe validation Parameters: - university: University name (fuzzy matching supported) - program: Program/department name (partial matching supported) - city: City name - score_type: Score type (SAY, EA, SOZ, DIL) - university_type: Type of university (Devlet, Vakıf, etc.) - fee_type: Fee/scholarship information - education_type: Type of education (Örgün, İkinci, etc.) - results_limit: Maximum number of results to return """ try: if NEW_SMART_API: # Use new smart search functions (v0.4.3+) search_params = {} # Map user-friendly parameters to API parameters if university or uni_adi: search_params['uni_adi'] = university or uni_adi if program or program_adi: search_params['program_adi'] = program or program_adi if city or sehir: search_params['city'] = city or sehir if score_type or puan_turu: search_params['score_type'] = score_type or puan_turu if university_type or universite_turu: search_params['university_type'] = university_type or universite_turu if fee_type or ucret_burs: search_params['fee_type'] = fee_type or ucret_burs if education_type or ogretim_turu: search_params['education_type'] = education_type or ogretim_turu if results_limit or length: search_params['length'] = results_limit or length # Use smart search with fuzzy matching results = search_lisans_programs(search_params, smart_search=True) # Validate and format results validated_results = [] for program_data in results: try: program = ProgramInfo(**program_data) validated_results.append(program.model_dump()) except Exception: # Include unvalidated data if validation fails validated_results.append(program_data) return { "programs": validated_results, "total_found": len(validated_results), "search_method": "smart_search_v0.4.3", "fuzzy_matching": True } else: # Fallback to legacy API params = { 'uni_adi': university or uni_adi, 'program_adi': program or program_adi, 'sehir_adi': city or sehir, 'puan_turu': (score_type or puan_turu).lower() if (score_type or puan_turu) else 'say', 'universite_turu': university_type or universite_turu, 'ucret_burs': fee_type or ucret_burs, 'ogretim_turu': education_type or ogretim_turu, 'page': 1 } # Remove empty parameters params = {k: v for k, v in params.items() if v} lisans_tercih = YOKATLASLisansTercihSihirbazi(params) result = lisans_tercih.search() return { "programs": result[:results_limit] if isinstance(result, list) else result, "total_found": len(result) if isinstance(result, list) else 0, "search_method": "legacy_api", "fuzzy_matching": False } except Exception as e: print(f"Error in search_bachelor_degree_programs: {e}") return { "error": str(e), "search_method": "smart_search" if NEW_SMART_API else "legacy_api", "parameters_used": { "university": university or uni_adi, "program": program or program_adi, "city": city or sehir } }
• yokatlas_mcp_server.py:90-90 (registration)

  FastMCP tool registration decorator for the search_bachelor_degree_programs tool.
  @mcp.tool()
• yokatlas_mcp_server.py:92-111 (schema)

  Pydantic-based input schema using Annotated and Field for type validation, descriptions, and constraints.
  # User-friendly parameters with fuzzy matching university: Annotated[str, Field(description="University name with fuzzy matching support (e.g., 'boğaziçi' → 'BOĞAZİÇİ ÜNİVERSİTESİ')")] = '', program: Annotated[str, Field(description="Program/department name with partial matching (e.g., 'bilgisayar' finds all computer programs)")] = '', city: Annotated[str, Field(description="City name where the university is located")] = '', score_type: Annotated[Optional[Literal['SAY', 'EA', 'SOZ', 'DIL']], Field(description="Score type")] = None, university_type: Annotated[Optional[Literal['Devlet', 'Vakıf', 'KKTC', 'Yurt Dışı']], Field(description="University type")] = None, fee_type: Annotated[Optional[Literal['Ücretsiz', 'Ücretli', 'İÖ-Ücretli', 'Burslu', '%50 İndirimli', '%25 İndirimli', 'AÖ-Ücretli', 'UÖ-Ücretli']], Field(description="Fee status: Ücretsiz (Free), Ücretli (Paid), İÖ-Ücretli (Evening-Paid), Burslu (Scholarship), İndirimli (Discounted), AÖ-Ücretli (Open Education-Paid), UÖ-Ücretli (Distance Learning-Paid)")] = None, education_type: Annotated[Optional[Literal['Örgün', 'İkinci', 'Açıköğretim', 'Uzaktan']], Field(description="Education type: Örgün (Regular), İkinci (Evening), Açıköğretim (Open Education), Uzaktan (Distance Learning)")] = None, availability: Annotated[Optional[Literal['Doldu', 'Doldu#', 'Dolmadı', 'Yeni']], Field(description="Program availability: Doldu (Filled), Doldu# (Filled with conditions), Dolmadı (Not filled), Yeni (New program)")] = None, results_limit: Annotated[int, Field(description="Maximum number of results to return", ge=1, le=500)] = 50, # Legacy parameter support for backward compatibility uni_adi: str = '', program_adi: str = '', sehir: str = '', puan_turu: str = '', universite_turu: str = '', ucret_burs: str = '', ogretim_turu: str = '', length: int = 0 ) -> dict: