YOKATLAS API MCP Server

Instructions

Implementation Reference

• yokatlas_mcp_server.py:213-332 (handler)

  The main handler function for the 'search_associate_degree_programs' tool. Decorated with @mcp.tool() for automatic registration in FastMCP. Implements fuzzy university/program name matching, parameter normalization, calls to yokatlas_py search functions (search_onlisans_programs or legacy), result validation with ProgramInfo, and error handling.
  @mcp.tool() def search_associate_degree_programs( # User-friendly parameters with fuzzy matching university: Annotated[str, Field(description="University name with fuzzy matching support (e.g., 'anadolu' → 'ANADOLU ÜNİVERSİTESİ')")] = '', program: Annotated[str, Field(description="Program name with partial matching (e.g., 'turizm' finds all tourism programs)")] = '', city: Annotated[str, Field(description="City name where the university is located")] = '', university_type: Annotated[Optional[Literal['Devlet', 'Vakıf', 'KKTC', 'Yurt Dışı']], Field(description="University type: Devlet (State), Vakıf (Foundation), KKTC (TRNC), Yurt Dışı (International)")] = 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 yop_kodu: str = '', uni_adi: str = '', program_adi: str = '', sehir_adi: str = '', universite_turu: str = '', ucret_burs: str = '', ogretim_turu: str = '', doluluk: str = '', ust_puan: float = 550.0, alt_puan: float = 150.0, page: int = 1 ) -> dict: """ Search for associate degree (önlisans) programs with smart fuzzy matching and user-friendly parameters. Smart Features: - Fuzzy university name matching (e.g., "anadolu" → "ANADOLU ÜNİVERSİTESİ") - Partial program name matching (e.g., "turizm" finds all tourism programs) - Intelligent parameter normalization - Type-safe validation Parameters: - university: University name (fuzzy matching supported) - program: Program/department name (partial matching supported) - city: City name - 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 Note: Associate degree programs use TYT scores, not SAY/EA/SOZ/DIL like bachelor programs. """ 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_adi: search_params['city'] = city or sehir_adi 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: search_params['length'] = results_limit # Use smart search with fuzzy matching results = search_onlisans_programs(search_params, smart_search=True) # Format results consistently return { "programs": results, "total_found": len(results), "search_method": "smart_search_v0.4.3", "fuzzy_matching": True, "program_type": "associate_degree" } else: # Fallback to legacy API params = { 'yop_kodu': yop_kodu, 'uni_adi': university or uni_adi, 'program_adi': program or program_adi, 'sehir_adi': city or sehir_adi, 'universite_turu': university_type or universite_turu, 'ucret_burs': fee_type or ucret_burs, 'ogretim_turu': education_type or ogretim_turu, 'doluluk': doluluk, 'ust_puan': ust_puan, 'alt_puan': alt_puan, 'page': page } # Remove empty parameters params = {k: v for k, v in params.items() if v or isinstance(v, (int, float))} onlisans_tercih = YOKATLASOnlisansTercihSihirbazi(params) result = onlisans_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, "program_type": "associate_degree" } except Exception as e: print(f"Error in search_associate_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_adi }, "program_type": "associate_degree" }
• yokatlas_mcp_server.py:215-236 (schema)

  Input schema defined using Pydantic's Annotated and Field for type validation, descriptions, and constraints (e.g., Literals for enums, ge/le for limits). Supports both modern user-friendly params and legacy params for backward compatibility.
  # User-friendly parameters with fuzzy matching university: Annotated[str, Field(description="University name with fuzzy matching support (e.g., 'anadolu' → 'ANADOLU ÜNİVERSİTESİ')")] = '', program: Annotated[str, Field(description="Program name with partial matching (e.g., 'turizm' finds all tourism programs)")] = '', city: Annotated[str, Field(description="City name where the university is located")] = '', university_type: Annotated[Optional[Literal['Devlet', 'Vakıf', 'KKTC', 'Yurt Dışı']], Field(description="University type: Devlet (State), Vakıf (Foundation), KKTC (TRNC), Yurt Dışı (International)")] = 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 yop_kodu: str = '', uni_adi: str = '', program_adi: str = '', sehir_adi: str = '', universite_turu: str = '', ucret_burs: str = '', ogretim_turu: str = '', doluluk: str = '', ust_puan: float = 550.0, alt_puan: float = 150.0, page: int = 1 ) -> dict:
• yokatlas_mcp_server.py:213-213 (registration)

  Tool registration via FastMCP's @mcp.tool() decorator, which automatically registers the function as an MCP tool with the defined schema from parameters.
  @mcp.tool()