Skip to main content
Glama
Sign In
KBÜ MCP

KBÜ MCP

by 1ffatihgur
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

KBÜ MCP: Karabük Üniversitesi Arama Motoru ve MCP Sunucusu

Sürüm Lisans: MIT Python 3.11+

Karabük Üniversitesi'nin bütün web varlığını (*.karabuk.edu.tr: 140+ site, sayfalar, binlerce PDF / Word / Excel / PowerPoint belgesi, UNIS akademisyen profilleri, KBÜ Medya haberleri) tarayıp indeksleyen bir hibrit arama motoru ve onu yapay zekâ uygulamalarına açan bir Model Context Protocol (MCP) sunucusu. Claude, Codex, Cursor veya kurumun kendi LLM'iyle (ör. Qwen) çalışan bir sohbet arayüzü; üniversiteyle ilgili soruları yalnızca üniversitenin kendi kaynaklarından, kaynak bağlantısı ve tarih vererek cevaplar.

⚠️ Karabük Üniversitesi'nin resmi ürünü değildir. Yalnızca herkese açık sayfaları okur; giriş gerektiren sistemlere (OBS, EBYS, e-posta vb.) erişmez.

Kullanıcı: Yemekhane ücretleri ne kadar?
Asistan:   SKS'nin "Yemekhane Fiyat Listesi"ne (25.06.2026) göre personel öğle yemeği ücreti ek göstergeye göre
           82,56 TL ile 105,68 TL arasında; 4/D sürekli işçiler için 165,12 TL ...
           Kaynaklar: sks.karabuk.edu.tr/yuklenen/dosyalar/12625062026154907.pdf (taranmış belge, OCR ile okundu)
           Şunları da sorabilirsiniz: Yemekhane hangi saatlerde açık? · Bu haftaki yemek menüsü ne?

🎯 Neler var?

Hibrit arama

Anahtar kelime (PostgreSQL tam metin, Türkçe kök/ek işleme, BM25F) + anlamsal arama (pgvector, bge-m3 embedding) → Reciprocal Rank Fusion. Sonuçlar ilgililiğe ve tarihe göre sıralanır (yeni belge önde).

Temiz veri

Her şey Markdown'a çevrilir (başlık, liste, tablo — PDF içindeki tablolar dahil); site şablonlarının menü / üst bilgi / alt bilgi kısımları atılır. Taranmış PDF'ler OCR ile önceden metne çevrilir; sorgu anında beklenmez.

Kaynaklar

Birim siteleri ve dosyaları · UNIS (her akademisyen için profil + idari görevler + tüm yayın, proje, tez, ödül) · KBÜ Medya (son 2 yıl) · OBS Bologna (ders planı, AKTS) · canlı telefon rehberi, yemek listesi, akademik takvim. Her sonuç kaynak etiketiyle gelir; filtrelenebilir.

Kişi grafiği

academic_profile: bir hocanın UNIS profili, rehber kaydı ve adının geçtiği en yeni site/medya belgeleri tek çağrıda.

Üretim altyapısı

PostgreSQL + pgvector, Docker Compose, kalıcı iş kuyruğu (kesilirse kaldığı yerden), saatlik istek sınırı, hata logları, API anahtarıyla kimlik doğrulama.

Doğruluk kuralları

Model yalnızca araç çıktısına dayanır, bulamadığını uydurmaz (başka üniversitenin bilgisini vermez), kaynak + tarih + "şunları da sorabilirsiniz" önerileriyle cevaplar, KBÜ dışı sorulara girmez.

Related MCP server: AmritaGPT MCP Server

🏗️ Mimari

 *.karabuk.edu.tr ─┐
 UNIS (DataTables) ├─► worker: iş kuyruğu ─► çıkarıcılar ─────► PostgreSQL ◄──── mcp: uzak MCP sunucusu ◄── Claude / Codex /
 KBÜ Medya         │   (hız sınırı,          (Markdown, OCR,     docs, chunks      (Streamable HTTP,        kurum sohbet arayüzü
 rehber, takvim ───┘    kaldığı yerden)       UNIS profilleri)    tsvector + vektör  API anahtarı, 10 araç)
                                                    │                   ▲
                                                    └─► embedding servisi (Ollama / vLLM / kurum LLM sunucusu, OpenAI uyumlu)

📊 Arama kalitesi

55 soruluk altın sette (eval/questions.json) ilk 5 sonuçta doğru belge: hibrit %96, yalnızca anahtar kelime %93. Açık kaynak Meilisearch aynı veri ve aynı embedding'lerle %89 (eval/compare_meilisearch.py).

🚀 Sunucu Kurulumu (üretim, Docker)

Adım adım ve internetsiz sunucu için: docs/SUNUCU_KURULUM.md.

Gerekenler: Docker + Docker Compose, bir embedding servisi (OpenAI uyumlu /v1/embeddings; ör. Ollama'da ollama pull bge-m3, ya da kurumun LLM sunucusunun embedding uç noktası).

git clone https://github.com/1ffatihgur/kbu-mcp.git && cd kbu-mcp
cp .env.example .env        # POSTGRES_PASSWORD, KBU_API_KEYS, KBU_EMBED_URL, KBU_CRAWL_MAX_PER_HOUR
docker compose up -d --build

Üç servis kalkar: db (PostgreSQL 17 + pgvector), mcp (:7860/mcp), worker (kuyruk + zamanlanmış güncellemeler). İlk açılışta indeks boşsa worker tam taramayı kendiliğinden başlatır.

Dışarıdan model/paket indirilemeyen ağlarda: imajları internet erişimi olan bir makinede hazırlayıp taşıyın:

docker compose build && docker pull pgvector/pgvector:pg17
docker save kbu-mcp:2 pgvector/pgvector:pg17 | gzip > kbu-mcp-images.tar.gz
# sunucuda:
docker load < kbu-mcp-images.tar.gz && docker compose up -d

Mevcut bir indeksi taşımak için: pg_dump -Fc → pg_restore (veya v1 SQLite dosyasından kbu migrate-sqlite).

Önce küçük ölçekli test, sonra tam tarama

docker compose exec worker kbu sample                  # 5 site sayfası + 10 UNIS hocası + 10 KBÜ Medya haberi
#   → /data/sample/*.md (indekse girecek Markdown) ve RAPOR.md (başlık, tarih, uzunluk, menü/alt bilgi kalıntısı)
docker compose exec worker kbu jobs add site --all     # her site ayrı iş, sırayla taranır
docker compose exec worker kbu jobs add unis           # UNIS akademisyen profilleri
docker compose exec worker kbu jobs add medya          # KBÜ Medya (son 2 yıl)
docker compose exec worker kbu jobs list               # durum ve hata nedenleri

İstemcileri bağlama

İstemci

Nasıl

Claude Code

claude mcp add --scope user --transport http karabuk-universitesi https://SUNUCU/mcp --header "Authorization: Bearer ANAHTAR"

Codex

codex mcp add karabuk-universitesi --url https://SUNUCU/mcp --bearer-token-env-var KBU_API_KEY

Claude Desktop / claude.ai

Settings → Connectors → Add custom connector → URL: https://SUNUCU/mcp?key=ANAHTAR

Kurumun sohbet arayüzü (Qwen vb.)

Herhangi bir MCP istemci kütüphanesiyle aynı adrese bağlanın; sistem promptu olarak sunucunun kbu_asistan prompt'unu (MCP prompts/get) kullanın.

Sunucunun MCP talimatları ve araç açıklamaları, modelin KBÜ ile ilgili her soruda araçları kendiliğinden kullanmasını sağlar ("MCP kullan" demeye gerek yoktur).

🛠️ MCP Araçları

Araç

Ne yapar

search

Hibrit arama. Parametreler: query, kaynak (site · unis · medya · bologna), unit (birim), file_type (pdf, word, excel…), since, limit. Eşleşen rehber kayıtlarını da ekler.

read_document

Belgenin tamamı (PDF'te sayfa numaralı Markdown). İndeksteki kopya 24 saatten eskiyse canlı siteden okur.

academic_profile

Bir hoca hakkında her şey: UNIS profili (unvan, birim, idari görevler, tüm yayın/proje/tez), rehber, adının geçtiği en yeni belgeler.

phone_directory

Resmi telefon rehberi (canlı).

food_menu · academic_calendar · latest_announcements

Yemek listesi (gün gün), akademik takvim, birim duyuruları (canlı).

list_units · fetch_page · index_status

Birimler, herhangi bir KBÜ sayfasını canlı okuma, indeks durumu.

prompt kbu_asistan

Kapsam, doğruluk ve cevap biçimi kurallarını içeren sistem promptu.

🧰 Komut Satırı

Komut

Açıklama

kbu worker

Kuyruk işçisi: işleri sırayla çalıştırır, boştayken saatlik/günlük güncellemeleri sıraya koyar

kbu jobs add <tür> [url…] · list · retry

İş kuyruğu. Türler: site (--all), unis, medya, update, update_hot, people, ocr, embed

kbu errors [--host H]

Taranamayan adresler ve nedenleri (site başına)

kbu sample [--url …]

Küçük ölçekli parse testi → data/sample/

kbu search "…" [--source unis] [--keyword-only]

Deneme araması

kbu update [--hot] · kbu unis · kbu embed · kbu ocr · kbu people

Tek seferlik işler

kbu stats · kbu status · kbu queries

İstatistik, durum, uzak sorgu logu

kbu migrate-sqlite [kbu.db]

v1 SQLite indeksini PostgreSQL'e taşı

kbu serve [--http --port 7860]

MCP sunucusu (stdio veya uzak)

⚙️ Ortam değişkenleri (.env)

Değişken

Varsayılan

Açıklama

KBU_DATABASE_URL

postgresql://kbu:…@127.0.0.1:5432/kbu

PostgreSQL bağlantısı (compose'da otomatik)

KBU_API_KEYS

—

Uzak MCP anahtarları (virgülle). Boşsa kimlik doğrulama kapalı

KBU_EMBED_URL / KBU_EMBED_MODEL

http://127.0.0.1:11434/v1 / bge-m3

OpenAI uyumlu embedding servisi; yoksa arama anahtar kelimeyle sürer

KBU_EMBED_DIM

1024

Vektör boyutu (model değişirse)

KBU_CRAWL_MAX_PER_HOUR

0 (sınırsız)

Tüm sitelere toplam saatlik istek sınırı (ör. 1000)

KBU_MEDYA_MAX_AGE_DAYS

730

KBÜ Medya'da geriye dönük gün sınırı

KBU_MAX_FILE_MB / KBU_MAX_OCR_PAGES

300 / 300

Büyük dosya sınırı / OCR sayfa tavanı

KBU_SEARCH_LIMIT / KBU_SNIPPET_CHARS / KBU_DOC_CHARS

5 / 700 / 8000

Araç cevap boyutu (bağlamı küçük modellerde taşmasın; model gerekirse daha fazlasını ister)

KBU_RATE_LIMIT_PER_MIN

120

Uzak MCP'de IP başına dakikalık istek

KBU_QUERY_LOG

1

0: uzak araç çağrılarını data/queries.jsonl'e yazma (veritabanında tutulmaz)

👩‍💻 Geliştirici Kurulumu (yerel)

git clone https://github.com/1ffatihgur/kbu-mcp.git && cd kbu-mcp
cp .env.example .env                 # yerelde: POSTGRES_PORT=5433, KBU_EMBED_URL=http://127.0.0.1:11434/v1
docker compose up -d db              # yalnızca veritabanı
ollama pull bge-m3                   # anlamsal arama için (isteğe bağlı)
python -m venv .venv && .venv/Scripts/activate    # macOS/Linux: source .venv/bin/activate
pip install -e ".[dev]"
kbu update                           # ilk tarama (saatler sürer) — ya da: kbu migrate-sqlite data/kbu.db
pytest && python eval/run_eval.py    # birim testleri + arama kalitesi (altın soru seti)

Depo kopyasındaki .env otomatik okunur. Yerel MCP (stdio) için istemcide command olarak .venv içindeki Python'u, args olarak ["-m", "kbu_mcp.server"] verin. Kendi bilgisayarınızdan geçici paylaşım için scripts/remote.ps1 (Cloudflare quick tunnel) hâlâ kullanılabilir.

🔍 Sitelere özgü çözülmüş tuzaklar

  • Alt sitelerde BA parametresi olmadan sayfa ana sayfaya yönlenir; aynı parametre bölümü de belirtir (BA=bilgisayar).

  • Duyuru arşivleri Referer olmadan açılmaz; ASP.NET GridView sayfalamaları __doPostBack ile gezilir.

  • UNIS'in arama sayfaları sonsuz filtre kombinasyonu üretir; bu yüzden sitenin kendi veri uç noktasından akademisyen başına tek belge derlenir.

  • KBÜ Medya tarihleri "25 Şubat, 2025" biçimindedir; 2 yıldan eski haberler indekslenmez.

  • Telefon rehberinde birimler fakülte düzeyindedir; bölüm bilgisi bölüm sitesiyle çapraz doğrulanır.

  • Yemek listesi PDF'inde yemekler kelime koordinatlarıyla günlere atanır.

  • Geçici bağlantı hatası indekslenmiş bir belgeyi artık aramadan düşürmez (yalnızca iki kez 404/410 alan belge kaldırılır).

⚠️ Bilinen Sınırlar

  • Giriş gerektiren sistemler ve kişisel öğrenci bilgileri kapsam dışıdır.

  • Resim olarak yayınlanan duyurular (JPG/PNG afişler) okunmaz. OCR rakam ve isimlerde hata yapabilir; araçlar bu durumda orijinal belgeyi önerir.

  • Cevapların doğruluğu sitedeki bilginin güncelliğiyle sınırlıdır; bu yüzden her cevap kaynak ve tarihle verilir.

🙏 Sorumlu Kullanım

Tarayıcı tanımlayıcı bir User-Agent, host başına eşzamanlılık/gecikme sınırı ve isteğe bağlı saatlik toplam sınırla çalışır. Üretimde KBU_CRAWL_MAX_PER_HOUR tanımlamanız önerilir. İçeriğin hakları Karabük Üniversitesi'ne aittir.

📜 Lisans: MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • 学生資料室 MCP

    nekko-lab
    A
    license
    Not graded
    quality
    A
    maintenance
    Lets AI agents browse and read a university's student resource center portal, retrieving the resource pages for a given admission year and department along with progression and graduation requirements, student handbook sections, academic calendars, bus timetables, class advisors, application forms and manuals, and contact information, each answer cited with its source document and page. It is an unofficial tool that runs locally and drives Chrome or Edge to access the portal on the user's behalf.
    4
    MIT

  • metu-mcp

    izzetemredemir
    A
    license
    Not graded
    quality
    B
    maintenance
    Lets METU (ODTÜ) students ask an AI assistant about university life — announcements, academic calendar, cafeteria menus, courses and prerequisites, parking rules, ring buses, campus places, health center, dorms and official links — with answers in Turkish and English that cite their official source and last-checked time.
    MIT