Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@yek-mcp Osmanlı Türkçesi, 100 varaktan kısa bir şiir mecmuası arıyorum"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Sorumlu kullanım: Bu araç
portal.yek.gov.tradresine senin kendi yetkili hesabınla erişir. Kurumun kullanım şartları otomatik erişimi sınırlayabilir; bu yüzden aracı yalnızca düşük hacimde, kişisel/akademik araştırma amacıyla kullan. Görsel ya da varak (sayfa) indirme bilinçli olarak yoktur.
Türkiye Yazma Eserler Kurumu'nun kataloğunda 674 binin üzerinde yazma ve nadir eser var. Bu devasa hazinede aradığını bulmak çoğu zaman şuna bağlı: doğru anahtar kelimeyi, doğru imlâyla, doğru alana yazabilmek. Bir mecmuanın adını tam bilmiyorsan, yalnızca "şu özelliklerde bir eser arıyorum" diyebiliyorsan, klasik katalog arama kutusu seni çoğu zaman yarı yolda bırakır.
YEK MCP tam burada devreye girer. Bu proje, YEK kataloğunu Claude gibi bir yapay zekâ asistanına konuşabileceğin bir araç hâline getirir. Artık katalogla tek tek anahtar kelime denemek yerine, asistanla doğal dilde sohbet ederek beyin fırtınası yaparsın:
"Osmanlı Türkçesi, 100 varaktan kısa bir şiir mecmuası arıyorum" dersin,
asistan senin yerine kataloğa gider, kayıtları okur, insan ölçütlerinle eşleştirir,
sana uygun adayları gerekçeleriyle birlikte sıralar,
istediğinde doğrudan açılabilir katalog bağlantısını verir.
Yani bu, bir "arama kutusu" değil; 674 bin eser üzerinde seninle birlikte düşünen bir araştırma asistanıdır.
Related MCP server: National Library of Israel Search MCP
Önemli olan kodun iç iskeleti değil, yaklaşımdır. Klasik bir katalog araması "kelimeyi yaz, eşleşeni getir" mantığıyla çalışır; insanın gerçek araştırma soruları ise çok daha bulanıktır. Araştırmacı "tam olarak şu kelime" demez; "şuna benzer, şu dönemden, şu türde, şu hacimde bir şey" der.
Bu araç, o boşluğu kapatmak için iki şeyi birleştirir:
Kataloğa erişen sade bir köprü. Asistan, senin oturumunla katalog sayfalarını çeker ve içlerindeki kayıtları (eser adı, kütüphane, koleksiyon, varak sayısı, dil, istinsah tarihi, içerik notu, dijital görüntü var mı…) düzenli, okunabilir bir veriye dönüştürür.
Üstünde düşünen yapay zekâ. Asistan bu düzenli veriyi okur, senin koyduğun ölçütlerle karşılaştırır ve katalog kayıtlarındaki farklı yazım ve eksik alanları da hesaba katar. Örneğin YEK, dil alanına çoğu zaman "Osmanlı Türkçesi" değil sadece "Türkçe" yazar; asistan bunu göz önünde bulundurur ve bir eserin Osmanlı Türkçesi olup olmadığını Arap harfli yazı türü + istinsah tarihi + içerik üzerinden değerlendirir.
Bu sayede araştırmacı, teknik ayrıntılarla uğraşmadan, kendi sorusunu kendi diliyle sorabilir.
Aşağıdaki, araçla yapılmış gerçek bir beyin fırtınası araması. Hiçbir kayıt adını önceden bilmeden, yalnızca insan ölçütleriyle başlandı:
Araştırmacı: Arama konusu: — Yazma eser olacak — Osmanlı Türkçesi olacak — Bir şiir mecmuası veyahut mecmua İyi olur: en fazla 100 varak vb. Bu kıstaslarla bir eser çıkar.
Asistan (kataloğu tarayıp kayıtları okuduktan sonra):
Kıstaslara uyan en güçlü aday — Mecmûa-i Eş'âr (öneri)
Kayıt no:
611545Kütüphane: Milli Kütüphane
Koleksiyon no:
06 Mil Yz A 2519Materyal: Yazma eser
Hacim: 49 varak
Dil: Türkçe · Alfabe: Arap alfabesi, harekeli nesih
İstinsah: 19. yüzyıl
İçerik: Bâkî, Muhibbî, Hayâlî, Fevrî, Rahmî, Şevkî ve başka şairlerin şiirleri
Dijital görüntü: Var
Katalog notunda açıkça "Eser, şiir mecmuasıdır" deniyor. Türkçe, Arap harfli ve 19. yüzyıla tarihlendiği için Osmanlı Türkçesi ölçütünü en güçlü biçimde karşılayan kayıt bu.
Not: YEK dil alanında "Osmanlı Türkçesi" yerine genellikle yalnızca "Türkçe" yazar. Osmanlı Türkçesi değerlendirmesini Arap harfli yazı, istinsah tarihi ve katalog içeriğine dayanarak yaptım.
Dikkat: araştırmacı tek bir kayıt numarası bilmiyordu; yalnızca "şiir mecmuası, Osmanlı Türkçesi, kısa hacimli" dedi. Geri kalanını araç ve asistan birlikte yaptı.
Bir kaydı incelemek istediğinde asistandan "bunun linkini ver" demen yeterli; sana o eserin doğrudan açılabilen katalog sayfasını verir. Örneğin yukarıdaki öneri için:
https://portal.yek.gov.tr/works/detail/611545
Böylece beyin fırtınasından çıkan sonucu tek tıkla kurumun kendi sayfasında açıp doğrulayabilirsin.
Asistan, sohbet sırasında perde arkasında şu dört aracı kullanır:
search_yek_works — katalogda anahtar kelime / alan bazlı arama yapar.
get_yek_work_details — bir eserin tüm katalog künyesini getirir (yukarıdaki
Mecmûa örneğindeki gibi).
list_yek_libraries — katalogdaki kütüphaneleri listeler.
list_yek_collections — koleksiyonları listeler.
Sen bu araçların adlarını hiç bilmek zorunda değilsin; sadece ne aradığını anlatırsın, asistan doğru aracı kendi seçer.
Bu bölüm aracı kendi bilgisayarına kuracaklar içindir. Adımları sırasıyla izlemen yeterli.
pip install -e .
playwright install chromium
Copy-Item .env.example .env # PowerShell; gerekirse içini düzenleKatalog, içeriğine erişmek için giriş ister. Bunu bir kez yaparsın:
python -m yek_mcp.loginAçılan tarayıcıda kendi hesabınla giriş yap (gerekirse e-Devlet/SMS), sonra terminale dönüp
ENTER'a bas. Oturum bilgin yalnızca kendi bilgisayarında storage_state.json
dosyasına kaydedilir ve sonraki aramalarda yeniden kullanılır. Oturumun zamanla sona ererse
bu komutu tekrar çalıştırman yeterlidir.
yek-mcp # yerel (stdio) MCP server olarak başlarAşağıdaki ayarı MCP istemcine eklersen asistan bu araçları otomatik görür:
{
"mcpServers": {
"yek": {
"command": "yek-mcp",
"cwd": "C:/path/to/yek-mcp"
}
}
}Detaylı tasarım gerekçeleri için: ARCHITECTURE.md. Kısaca:
Katalog sayfaları sunucu tarafında HTML olarak üretilir; araç bu sayfaları çeker ve selectolax ile okunur veriye dönüştürür. Sonuçlar Pydantic modellerine yerleşir.
Varsayılan istemci hafif ve hızlı httpx'tir. Playwright/Chromium yalnızca bir
kerelik girişte (ve gerekirse YEK_ADAPTER=playwright ile tam-render yedeğinde) devreye
girer; her iki yol da aynı okuyucuları paylaşır.
Kimlik doğrulama, senin tarayıcı oturumundan alınan bir oturum bilgisiyle yapılır. Bu bilgi makineden dışarı çıkmaz, log'a/çıktıya yazılmaz ve depoya gönderilmez.
Oturum sona erdiğinde araç sessizce boş sonuç dönmez; net bir hata verir ve seni yeniden girişe yönlendirir. Geçici ağ ve hız-limiti durumlarında ölçülü biçimde yeniden dener (varsayılan: en çok ~1 istek/saniye).
Görsel/varak indirme yoktur (kota ve kullanım şartları hassasiyeti). Araç yalnızca katalog künyesiyle ilgilenir.
Aramada library/collection ölçütleri kabul edilir ama doğrudan filtrelemeye değil,
asistanın sonuçları kütüphane/koleksiyon bilgisine göre değerlendirmesine yarar.
Katalogdaki kütüphane/koleksiyon sayıları, kurumun güncel içeriğine bağlı olarak değişebilir; sabit bir liste garanti edilmez.
Tek bir eserin tam katalog kaydını döndürür.
| Name | Required | Description | Default |
|---|---|---|---|
| work_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses the basic read-only behavior (returns a record) but does not mention potential errors, permissions, rate limits, or edge cases. For a simple getter, this is minimally adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It is appropriately sized and front-loaded, efficiently conveying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, output schema present), so the description is largely sufficient. It explains the core function and result. However, it lacks context about how this tool relates to siblings or when to choose it, which is a minor gap given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and there is one parameter (work_id). The description adds meaning by implying work_id is the identifier for the single work whose record is returned, but it does not elaborate on format, constraints, or examples. Some semantic value is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'returns the full catalog record of a single work' (Tek bir eserin tam katalog kaydını döndürür). It uses a specific verb (returns) and resource (full catalog record) and distinguishes from siblings like search_yek_works and list_yek_libraries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: given a work_id, this retrieves the full record. However, the description does not explicitly state when to use this tool over alternatives (e.g., search_yek_works) or provide any exclusions. No clear when-to-use guidance beyond the obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Portalın yayımladığı koleksiyon facet'lerini listeler.
| Name | Required | Description | Default |
|---|---|---|---|
| library | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description carries the full burden of disclosing behavior. It only states that the tool 'lists' facets, implying a read-only operation, but does not elaborate on side effects, permissions, or return characteristics. The description adds minimal behavioral context beyond the verb itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff, making it efficient to read. However, the brevity borders on under-specification, especially regarding the library parameter. It earns a 4 because it is well-structured and to the point, though a bit more detail would be beneficial.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one optional parameter, no annotations), the description is incomplete. It does not explain the role of the 'library' parameter, nor does it provide any context about the output beyond what an output schema might contain. The lack of parameter semantics and usage guidance leaves significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter, 'library', with zero description coverage (0%). The tool description fails to mention this parameter or explain how it affects the results. This leaves the agent completely in the dark about whether the library is a filter, an input, or something else.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('list') and resource ('collection facets'), clearly distinguishing this tool from siblings like list_yek_libraries (lists libraries) and search_yek_works (searches works). The phrase 'published by the portal' adds context about the data source, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no information about when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites. Sibling tool names give some implicit context, but the description itself offers no guidance on selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Portalın yayımladığı kütüphane facet'lerini listeler.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must fully disclose behavior, but it only states that it lists facets. It does not mention output format, ordering, or any limitations, leaving the agent without operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-formed sentence that conveys the core purpose without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter list tool with an output schema, the description adequately identifies what is listed. However, it lacks sufficient context about the nature of the facets or how they relate to the portal's publishing model, though this is compensated by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, and the schema is empty with 100% coverage, so the baseline of 4 applies. The description adds no parameter information, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'listeler' (lists) and specifies the resource as 'library facets', clearly distinguishing it from sibling tools that handle work details, searches, and collections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool instead of alternatives. There is no mention of use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Yazma Eserler katalogunda anahtar kelime / alan bazlı arama yapar.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| field | No | ALL_FIELDS | |
| query | Yes | ||
| library | No | ||
| collection | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that it searches, but does not mention return format, pagination, default field behavior, or any side effects. It is not misleading, but it is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that states the core purpose. It is appropriately sized, front-loaded, and contains no unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, 0% schema description coverage, no annotations, and an output schema, the description is highly incomplete. It only covers the basic purpose and leaves all parameter semantics and behavioral details unexplained. The output schema exists but does not compensate for the missing parameter information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not add any meaning to the parameters. It only says 'keyword/field-based search' without explaining parameters like page, field, library, or collection. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs a keyword/field-based search in the Manuscripts catalog. This is a specific verb+resource and distinguishes it from sibling tools like get_yek_work_details (details) and list_yek_libraries/collections (lists).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention the sibling tools or any exclusions. The only implied usage is that it is for searching, but explicit when-to-use/not-to-use guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_yek_work_detailslist_yek_collectionslist_yek_librariessearch_yek_worksScored across 4 tools
Each tool has a clearly distinct purpose: search for works, fetch full details of a specific work, list library facets, and list collection facets. There is no overlap that would confuse an agent.
All tool names follow a consistent verb_noun pattern with a shared domain prefix: get_yek_, search_yek_, list_yek_. This makes it easy to predict the function of each tool.
With 4 tools, the server is on the smaller side but well-scoped for a read-only catalog interface: search, retrieve details, and enumerate facets. It feels appropriately lean rather than overly sparse.
Core workflows of searching and viewing work details are covered, and facet listing supports filtering. A minor gap is the lack of detail views for individual libraries or collections, but this can be worked around via search.
AI-powered biblical research tools — lexicons, morphology, manuscripts, and more.
AI-native art catalogue. Catalogue works, parse provenance, and generate signed RAIs.
Academic literature search, retrieval, and private library management on top of OpenAlex.
AI-curated book catalog that eliminates hallucinations and surfaces lesser-known titles.
