MCP server for TÜİK SDMX REST API (Turkish Statistical Institute)
Server has 5 tools with complete input schemas and descriptions. Naming follows verb_noun pattern (tuik_anahtar_ayarla, tuik_listele, tuik_ara, tuik_meta, tuik_cek). Descriptions are present and contextual (avg ~150 chars), explaining WHAT each tool does and WHEN to use it. However, descriptions lack explicit recovery guidance for error cases, and parameter descriptions are minimal (e.g., 'Dataflow tanımlayıcısı' is terse). Output schemas are not documented, LLMs cannot predict response structure. Error handling exists in code (MissingAPIKeyError, TokenServiceError) but is not surfaced in tool definitions. No tool annotations (readOnlyHint, destructiveHint) despite clear risk levels (WRITE vs READ_ONLY). Parameter constraints (e.g., version defaults to '1.0', limit defaults to 5000) are mentioned in descriptions but not formalized as JSON Schema defaults or enums.
TÜİK SDMX API anahtarını kaydeder. Diğer araçlar 'API anahtarı tanımlı değil' hatası verdiğinde kullan: kullanıcıdan TÜİK Veri Portalı (veriportali.tuik.gov.tr) API anahtarını al ve buraya ver. Anahtar token servisiyle doğrulanır, geçerliyse kalıcı olarak kaydedilir ve dataflow listesi hemen yüklenir. TUIK_API_KEY ortam değişkeni zaten tanımlıysa buna gerek yoktur.
TÜİK SDMX katalogunda anahtar kelime ile dataflow arar. Türkçe ve İngilizce terimleri destekler; eşanlamlılar otomatik olarak uygulanır.
TÜİK SDMX'ten veri çeker. Dataflow ID, boyut filtreleri ve tarih aralığı ile çağrılır. Sonuç satır sayısı varsayılan olarak 5000 ile sınırlandırılır (limit=0 ile kaldırılabilir).
TÜİK SDMX API'deki tüm production dataflow'ları listeler.
Bir dataflow'un boyut yapısını (dimensions) getirir. Hangi boyutların filtrelenebileceğini, hangi değerleri aldığını ve hangi boyutların sabit olduğunu gösterir.
Output schemas not documented. LLMs cannot predict response structure (e.g., what fields tuik_listele returns, what tuik_cek yields). This forces agents to guess and wastes tokens on trial-and-error parsing.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite explicit risk levels in metadata (WRITE vs READ_ONLY). tuik_anahtar_ayarla is destructive (modifies state); tuik_cek is read-only and idempotent. Annotations help agents reason about retry safety and side effects.
Parameter descriptions are terse (e.g., 'Dataflow tanımlayıcısı', 'Arama sorgusu'). Lack actionable format guidance. tuik_cek's 'boyut_filtre' is described as 'object' but LLMs need examples of valid structure (e.g., '{"REGION": "TR01", "TIME": "2024-01"}').
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 57 | 2026-07-28+ | v2 |
Error handling logic exists in code (MissingAPIKeyError, TokenServiceError, _NO_KEY_HINT) but is not exposed in tool definitions. LLMs cannot see recovery paths. tuik_anahtar_ayarla should document that it validates keys via token service and returns specific error messages.
tuik_cek's 'limit' parameter defaults to 5000 but is not formalized in schema (no 'default' field). Defaults mentioned in description only; LLMs may not respect them. JSON Schema should declare 'default': 5000 and 'minimum': 0.