yokatlas-mcp-server

A Python MCP server exposing YÖK ATLAS "tercih kılavuzu" (preference guide) reference-data tools: provinces, universities, and program groups (each tagged with its exam score type). Built on FastMCP with pydantic-settings config, a standard {ok, data, error} tool envelope, and a rate-limited HTTP client with retries.

⚠️ Sorumluluk Reddi Beyanı (Disclaimer)

Bu proje tamamen deneysel amaçlarla oluşturulmuştur. Yapay zeka modelleri hata yapabilir; bu sunucunun ürettiği hiçbir sonuç %100 doğru veya güncel olarak kabul edilmemelidir. Hangi okulu veya bölümü seçeceğinize karar verirken mutlaka bir rehber öğretmen, eğitim danışmanı veya alanında uzman bir kişiden profesyonel destek alın.

Bu proje, yalnızca puanınıza göre hangi okul/bölümlerin mevcut olabileceği konusunda size bir fikir vermek amacıyla oluşturulmuştur; resmî bir tercih/danışmanlık aracı değildir. Burada elde ettiğiniz sonuçları her zaman resmî YÖK ATLAS verileriyle karşılaştırıp doğrulayın.

Bu proje ve geliştiricisi, bu sunucunun ürettiği bilgilere dayanılarak yapılan üniversite/bölüm tercihlerinden veya bu tercihlerin sonuçlarından hiçbir şekilde sorumlu tutulamaz. Tercih sürecinde yapılan hatalardan dolayı proje sahibine sorumluluk yüklenemez.

A Turkish version of this same warning is returned in every tool response's disclaimer field (see below) — the server instructions tell the calling model to always surface it to the user verbatim, not just leave it in this file.

Bu projeyi (bu MCP sunucusunu) indirerek, kurarak, çalıştırarak veya Claude Desktop, Codex, ChatGPT ya da başka bir istemci üzerinden bu sunucuya bağlanıp kullanarak, yukarıdaki sorumluluk reddi beyanının tamamını okuduğunuzu, anladığınızı ve kabul ettiğinizi beyan etmiş sayılırsınız.

MCP İstemcilerine Bağlanma (Claude Desktop, Codex, ChatGPT)

Herkese Açık Sunucu (kurulum gerektirmez)

Bu sunucu zaten https://yokatlas.aykutbuyukkaya.com/mcp adresinde yayında. Kendi bilgisayarınızda hiçbir şey kurmadan/çalıştırmadan, aşağıdaki "Custom Connector" adımlarında bu URL'yi kullanarak doğrudan bağlanabilirsiniz. Kendi kopyanızı çalıştırmak isterseniz aşağıdaki yerel kurulum adımlarını izleyebilirsiniz.

Sunucu varsayılan olarak stdio üzerinden çalışır; Claude Desktop, Claude Code ve Codex gibi istemciler sunucuyu doğrudan yerel bir alt süreç olarak başlattığı için ayrı bir HTTP kurulumu gerekmez. ChatGPT ise yalnızca internetten erişilebilen (HTTPS) bir MCP sunucusuna bağlanabildiği için ya yukarıdaki herkese açık adresi ya da kendi deploy ettiğiniz bir adresi kullanmanız gerekir.

Kendi kopyanızı çalıştırmak için önce bağımlılıkları kurun:

git clone <bu-repo-url>
cd yokatlas-mcp-server
uv sync

Claude Desktop

Claude Desktop'ın ayar dosyasını açın:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

mcpServers altına aşağıdaki girdiyi ekleyin (yolu kendi klonladığınız dizinle değiştirin) ve Claude Desktop'ı yeniden başlatın:

{
  "mcpServers": {
    "yokatlas-mcp-server": {
      "command": "uv",
      "args": ["--directory", "/path/to/yokatlas-mcp-server", "run", "yokatlas-mcp-server"]
    }
  }
}

Claude Code CLI kullanıyorsanız aynı işi tek satırla yapabilirsiniz:

claude mcp add yokatlas-mcp-server -- uv --directory /path/to/yokatlas-mcp-server run yokatlas-mcp-server

Custom Connector (uzak/HTTP sunucu) ile bağlanma: Kendi bilgisayarınızda hiçbir şey kurmadan, herkese açık sunucuyu kullanarak bağlanabilirsiniz:

1. Claude Desktop'ta Settings → Connectors'a gidin.
2. Add custom connector'a tıklayıp https://yokatlas.aykutbuyukkaya.com/mcp adresini MCP sunucu URL'si olarak girin ve ekleyin.
3. Yeni bir sohbette bu connector'ı etkinleştirip araçları kullanmaya başlayın.

Kendi deploy ettiğiniz bir sunucuyu kullanmak isterseniz (bkz. Docker), 2. adımda kendi https://<alan-adiniz> adresinizi girmeniz yeterlidir.

Codex CLI (OpenAI)

~/.codex/config.toml dosyasına aşağıdaki bloğu ekleyin:

[mcp_servers.yokatlas-mcp-server]
command = "uv"
args = ["--directory", "/path/to/yokatlas-mcp-server", "run", "yokatlas-mcp-server"]

Codex CLI sürümünüz destekliyorsa aynı satırı komut satırından da ekleyebilirsiniz:

codex mcp add yokatlas-mcp-server -- uv --directory /path/to/yokatlas-mcp-server run yokatlas-mcp-server

ChatGPT (Connectors / Developer mode)

ChatGPT yerel bir komut çalıştıramadığı için sunucunun internetten erişilebilir bir HTTPS adresi olması gerekir. Herkese açık sunucuyu kullanabilir ya da kendi kopyanızı MCP_TRANSPORT=streamable-http ile (bkz. Docker) bir alan adının arkasına deploy edebilirsiniz, ardından:

1. ChatGPT'de Settings → Connectors → Advanced → Developer mode'u açın (bu özellik hesap planınıza göre farklı bir menüde görünebilir).
2. Add custom connector ile https://yokatlas.aykutbuyukkaya.com/mcp adresini (veya kendi deploy ettiğiniz https://<alan-adiniz> adresini) MCP sunucu URL'si olarak girin.
3. Sohbette bu connector'ı etkinleştirip get_university_cities, get_universities, get_university_programs ve search_university_programs araçlarını kullanmaya başlayın.

command/args yolları uv'nin sistem PATH'inizde bulunduğunu varsayar; değilse command alanına uv'nin tam yolunu (örn. /opt/homebrew/bin/uv) yazmanız gerekir.

Diğer HTTP tabanlı istemciler için de MCP_TRANSPORT=streamable-http (veya sse) ayarlayıp http://<MCP_HOST>:<MCP_PORT> adresine bağlanmanız yeterlidir.

Tools

Tool	Upstream endpoint	Filters
get_university_cities	GET /api/tercih-kilavuz/universite-iller	name_contains, limit
get_universities	GET /api/tercih-kilavuz/universiteler	name_contains, limit
get_university_programs	GET /api/tercih-kilavuz/universite-programlar	name_contains, score_type, limit
search_university_programs	POST /api/tercih-kilavuz/search	see below

get_university_cities, get_universities, and get_university_programs are reference-data lookups. search_university_programs is the actual preference search — it returns program placements (university + program + quota + fee + scholarship + prior guide's minimum success rank / score cutoff), and its university_ids, program_group_ids, and city_codes filters are meant to be resolved first from the three lookup tools' id/ilKodu fields, not guessed.

search_university_programs also filters by program_type (46/"LİSANS", 47/"ÖNLİSANS"), university_type (DEVLET, VAKIF, "VAKIF MYO", KKTC, "YURTDIŞI KAMU", "YURTDIŞI VAKIF"), scholarship_type (0/"ÜCRETSİZ", 154/"ÜCRETLİ", 158/"BURSLU", 155/"%25 İNDİRİMLİ", 156/"%50 İNDİRİMLİ"), study_mode (86/"ÖRGÜN ÖĞRETİM", 182/"UZAKTAN ÖĞRETİM", 203/"AÇIK ÖĞRETİM"), an exact guide_code (to fetch one specific placement), a min_success_rank/max_success_rank range, and standard page/size (max 50)/sort_by/ direction pagination. All of the above accept either the raw id/code or the Turkish label — with or without diacritics, in any case ("lisans", "LİSANS", and 46 are equivalent). Set include_conditions_text=True to also get each result's full admission-condition paragraphs (conditions_text); left off by default since they can be long.

score_type accepts SAY, EA, SÖZ (or ASCII SOZ), DİL (or ASCII DIL), and TYT. Name filters are case-insensitive substring matches that handle Turkish dotted/dotless I correctly (e.g. name_contains="istanbul" matches İSTANBUL).

Every tool returns a standard envelope so callers can branch on success/failure without parsing exceptions. Every response also carries a disclaimer field with the Turkish warning above (experimental/AI-generated data, verify against the official YÖK ATLAS, get professional guidance):

{"ok": true, "data": {...}, "error": null, "disclaimer": "Bu sonuç deneysel..."}
{"ok": false, "data": null, "error": {"code": "INVALID_INPUT", "message": "...", "retryable": false}, "disclaimer": "Bu sonuç deneysel..."}

This full envelope (including disclaimer) is always available as structuredContent. But relying only on a JSON field inside structuredContent, plus the server's MCP instructions telling the model to relay it, turned out not to be reliable in practice — not every client forwards instructions to the model, and a field buried in a large JSON blob is easy for a model to summarize away. So each tool's actual text output (content) leads with the disclaimer as its own explicit, unmissable directive block, ahead of the JSON data — see envelope.to_call_tool_result().

Project layout

src/yokatlas_mcp_server/
  __init__.py
  settings.py                    # pydantic-settings config, loaded from env vars / .env
  errors.py                       # domain exceptions + {code, message, retryable} error payloads
  envelope.py                      # shared {ok, data, error, disclaimer} response helpers
  text_utils.py                     # Turkish-aware casefold/upper + int/limit validation
  enums.py                           # search filter value normalization (labels <-> ids)
  rate_limiter.py                     # async token-bucket limiter for the upstream client
  models.py                            # City, University, ProgramGroup dataclasses
  yokatlas_client.py                    # TercihKilavuzuClient: retries, rate limiting, error mapping
  server.py                              # FastMCP app: tool/resource/prompt registration, entry point
  tools/
    __init__.py
    get_university_cities.py
    get_universities.py
    get_university_programs.py
    search_university_programs.py

tests/
  test_scaffold.py                # settings + transport validation
  test_envelope.py                 # {ok, data, error, disclaimer} response helpers
  test_server_tool_dispatch.py     # real FastMCP tool-call dispatch, not execute_* directly
  test_enums.py                    # filter value normalization
  test_yokatlas_client.py          # HTTP client behavior against a mocked transport
  test_get_university_cities_tool.py
  test_get_universities_tool.py
  test_get_university_programs_tool.py
  test_search_university_programs_tool.py

Getting started

uv sync
cp .env.example .env
uv run pytest
uv run yokatlas-mcp-server

The default transport is stdio, so uv run yokatlas-mcp-server will sit waiting for an MCP client to speak to it over stdin/stdout — that's expected. Use mcp dev for an interactive inspector instead:

uv run mcp dev src/yokatlas_mcp_server/server.py

Adding a new tool

1. Add a method to TercihKilavuzuClient in yokatlas_client.py, or create a new <domain>_client.py module following the same pattern (owns retries, rate limiting via RateLimiter, and translates HTTP/network failures into the errors.py exception hierarchy).
2. Create tools/<name>.py with a Protocol describing the client methods the tool needs and an async def execute_<name>(...) that validates input, calls the client, and returns the envelope via envelope.make_success_response / make_error_response (copy tools/get_university_cities.py as a starting point).
3. Register it in server.py with @mcp.tool(name=..., description=...), describing each parameter with a pydantic Field(description=...) so MCP clients get useful tool docs.
4. Add tests mirroring test_get_university_cities_tool.py (fake client, no network) and, if you added a client method, test_yokatlas_client.py (real client, httpx.MockTransport, no network).

Docker

uv lock
docker build -t yokatlas-mcp-server .
docker run --rm -p 8000:8000 yokatlas-mcp-server

The image defaults MCP_TRANSPORT to streamable-http and binds to 0.0.0.0:8000. uv lock must be run once (and whenever dependencies change) to produce uv.lock, which the Dockerfile installs from with --frozen for reproducible builds.

Configuration

See .env.example for all supported environment variables: MCP transport/host/port, logging, and the YÖK ATLAS API's base URL, timeouts, retry policy, and rate limit.

License

MIT — see LICENSE.