tdk-api-wrapper 1.6.0 → 1.7.0

package/README.md

@@ -1,6 +1,6 @@
 # TDK API Node.js Wrapper
 
-Bu proje, Türk Dil Kurumu (TDK) sözlük verilerine Node.js ortamından doğrudan, hızlı ve güvenilir bir şekilde erişim sağlamak amacıyla geliştirilmiş, TypeScript tabanlı resmî olmayan bir sarmalayıcı (wrapper) kütüphanedir. Herhangi bir dış bağımlılığa veya ikili (binary) dosyaya ihtiyaç duymadan HTTP üzerinden güncel verileri çeker.
+Bu proje, Türk Dil Kurumu (TDK) sözlük verilerine Node.js ortamından doğrudan, hızlı ve güvenilir bir şekilde erişim sağlamak amacıyla geliştirilmiş, TypeScript tabanlı resmî olmayan bir sarmalayıcı (wrapper) kütüphanedir. Herhangi bir dış bağımlılığa veya ikili (binary) dosyaya ihtiyaç duymadan HTTP üzerinden güncel verileri çeker. Kütüphanenin yanı sıra bir terminal CLI'si (`tdk`) ve dahili bir **Model Context Protocol (MCP)** sunucusu da paketle birlikte gelir.
 
 ## Kurulum
 
@@ -46,6 +46,7 @@ tdk repl
 tdk kubbealti merhaba
 tdk nisanyan merhaba
 tdk viki merhaba
+tdk mcp                    # MCP (Model Context Protocol) stdio sunucusunu başlatır
 ```
 
 Herhangi bir komuta `--json` bayrağı eklendiğinde çıktı, insan-okunur metin yerine tek satırlık JSON olarak basılır (script/otomasyon kullanımı için):
@@ -138,6 +139,25 @@ TDK dışındaki bu üç kaynak da her zaman kullanılabilir/dokümante edilmiş
 - **`TDK.getNisanyan(word)`**: Nişanyan Sözlük'ten kelimenin etimoloji paragrafını düz metin olarak döner; kelime bulunamazsa `null`.
 - **`TDK.getWiktionary(word)`**: Türkçe Vikisözlük'ten (`tr.wiktionary.org`) resmî MediaWiki API'si (`action=query&prop=extracts`) üzerinden veri çeker — bu üçü arasında scraping olmayan, resmî ve en kararlı olanı. `{ raw, sections }` döner; `sections` metni `== Köken ==`, `=== Söyleniş ===` gibi başlıklara göre bir sözlüğe ayırır. `getWiktionarySection(word, sectionName)` tek bir bölümü (örn. `"Köken"`) büyük/küçük harf duyarsız süzer. Bu wiki'de başlık büyütme kapalı (`$wgCapitalLinks=false` — "Türkiye" ile bir küçük harfli kelime ayrı sayfalardır), o yüzden `TDK.getWiktionary("türkiye")` gibi tam eşleşmeyen aramalar otomatik olarak ilk harfi (Türkçe kurallarına göre, örn. `istanbul` → `İstanbul`) büyütülmüş hâliyle tekrar denenir.
 
+## Model Context Protocol (MCP) Sunucusu
+
+Paket, bir MCP stdio sunucusu içerir; böylece TDK sözlük, morfoloji, yazım denetimi ve etimoloji araçlarını Claude Desktop, Cursor, Antigravity veya herhangi bir MCP istemcisine yalnızca Node.js ile bağlayabilirsiniz — Python ya da ek bir çalışma zamanı gerekmez.
+
+```json
+{
+  "mcpServers": {
+    "tdk": {
+      "command": "npx",
+      "args": ["-y", "tdk-api-wrapper", "mcp"]
+    }
+  }
+}
+```
+
+Global kuruluysa `tdk mcp` (veya `tdk-mcp`) komutu da aynı sunucuyu başlatır. Sunucu programatik olarak dışa aktarılan `createMcpServer()` / `runMcpServer()` ile de gömülebilir.
+
+Sunulan araçlar: `tdk_lookup`, `tdk_meanings`, `tdk_examples`, `tdk_proverbs`, `tdk_compound_words`, `tdk_part_of_speech`, `tdk_synonyms`, `tdk_antonyms`, `tdk_origin`, `tdk_nisanyan`, `tdk_kubbealti`, `tdk_wiktionary`, `tdk_spell_check`, `tdk_proofread`, `tdk_stem`, `tdk_analyze_text`, `tdk_syllables`, `tdk_vowel_harmony`, `tdk_autocomplete`, `tdk_pattern_search`, `tdk_anagram`, `tdk_rhymes`, `tdk_compare`, `tdk_audio_url`, `tdk_word_of_the_day`, `tdk_random_word`, `tdk_rules`. Her araç JSON metin döndürür; ağ/scraping hataları fırlatmak yerine `isError: true` ile `{ "error": ... }` olarak döner.
+
 ## Hata Yönetimi
 
 Kütüphane, ayırt edilebilir hata sınıfları fırlatır (hepsi `Error`'dan türer):

package/dist/chunk-MELLECWT.mjs

@@ -0,0 +1,279 @@
+import {
+  TDK
+} from "./chunk-ZFWZXNGY.mjs";
+
+// src/mcp.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var VERSION = "1.7.0";
+function ok(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function fail(message) {
+  return {
+    content: [{ type: "text", text: JSON.stringify({ error: message }, null, 2) }],
+    isError: true
+  };
+}
+function guard(fn) {
+  return async (args) => {
+    try {
+      return await fn(args);
+    } catch (error) {
+      return fail(error instanceof Error ? error.message : String(error));
+    }
+  };
+}
+function createMcpServer() {
+  const server = new McpServer({
+    name: "TDK API Server",
+    version: VERSION
+  });
+  server.tool(
+    "tdk_lookup",
+    "Bir kelimenin TDK G\xFCncel T\xFCrk\xE7e S\xF6zl\xFCk'teki ham kayd\u0131n\u0131 (t\xFCm anlamlar, \xF6rnekler, birle\u015Fikler, k\xF6ken, atas\xF6zleri) d\xF6nd\xFCr\xFCr.",
+    { word: z.string().describe("Aranacak T\xFCrk\xE7e kelime (\xF6rn: 'kalem').") },
+    guard(async ({ word }) => {
+      const results = await TDK.getWord(word);
+      if (results.length === 0)
+        return fail(`"${word}" TDK s\xF6zl\xFC\u011F\xFCnde bulunamad\u0131.`);
+      return ok(results);
+    })
+  );
+  server.tool(
+    "tdk_meanings",
+    "Bir kelimenin sadele\u015Ftirilmi\u015F anlam listesini (madde madde tan\u0131mlar) d\xF6nd\xFCr\xFCr.",
+    { word: z.string().describe("Aranacak T\xFCrk\xE7e kelime.") },
+    guard(async ({ word }) => ok({ word, meanings: await TDK.getMeanings(word) }))
+  );
+  server.tool(
+    "tdk_examples",
+    "Bir kelimenin s\xF6zl\xFCkteki \xF6rnek c\xFCmlelerini (varsa yazar\u0131yla) d\xF6nd\xFCr\xFCr.",
+    { word: z.string().describe("Aranacak T\xFCrk\xE7e kelime.") },
+    guard(async ({ word }) => ok({ word, examples: await TDK.getExamples(word) }))
+  );
+  server.tool(
+    "tdk_proverbs",
+    "Bir kelime ile kurulan atas\xF6z\xFC ve deyimleri listeler.",
+    { word: z.string().describe("Aranacak T\xFCrk\xE7e kelime (\xF6rn: 'g\xF6z').") },
+    guard(async ({ word }) => ok({ word, proverbs: await TDK.getProverbs(word) }))
+  );
+  server.tool(
+    "tdk_compound_words",
+    "Bir kelime ile olu\u015Fturulmu\u015F birle\u015Fik kelimeleri listeler (\xF6rn: 'kalem' -> 'dolma kalem').",
+    { word: z.string().describe("Aranacak T\xFCrk\xE7e kelime.") },
+    guard(async ({ word }) => ok({ word, compounds: await TDK.getCompoundWords(word) }))
+  );
+  server.tool(
+    "tdk_part_of_speech",
+    "Bir kelimenin s\xF6zc\xFCk t\xFCrlerini (isim, s\u0131fat, zarf, fiil vb.) d\xF6nd\xFCr\xFCr.",
+    { word: z.string().describe("Aranacak T\xFCrk\xE7e kelime.") },
+    guard(async ({ word }) => ok({ word, partsOfSpeech: await TDK.getPartOfSpeech(word) }))
+  );
+  server.tool(
+    "tdk_synonyms",
+    "Bir kelimenin e\u015F anlaml\u0131lar\u0131n\u0131 (yak\u0131n anlaml\u0131 kelimeler) d\xF6nd\xFCr\xFCr.",
+    { word: z.string().describe("Aranacak T\xFCrk\xE7e kelime.") },
+    guard(async ({ word }) => ok({ word, synonyms: await TDK.getSynonyms(word) }))
+  );
+  server.tool(
+    "tdk_antonyms",
+    "Bir kelimenin z\u0131t (kar\u015F\u0131t) anlaml\u0131lar\u0131n\u0131 d\xF6nd\xFCr\xFCr.",
+    { word: z.string().describe("Aranacak T\xFCrk\xE7e kelime.") },
+    guard(async ({ word }) => ok({ word, antonyms: await TDK.getAntonyms(word) }))
+  );
+  server.tool(
+    "tdk_origin",
+    "Bir kelimenin TDK'deki k\xF6ken bilgisini ve yabanc\u0131 k\xF6kenli olup olmad\u0131\u011F\u0131n\u0131 d\xF6nd\xFCr\xFCr.",
+    { word: z.string().describe("Aranacak T\xFCrk\xE7e kelime.") },
+    guard(async ({ word }) => {
+      const [origin, foreign] = await Promise.all([TDK.getOrigin(word), TDK.isForeignWord(word)]);
+      return ok({ word, origin, isForeign: foreign });
+    })
+  );
+  server.tool(
+    "tdk_nisanyan",
+    "Ni\u015Fanyan S\xF6zl\xFCk'ten bir kelimenin ayr\u0131nt\u0131l\u0131 etimolojisini (server-rendered meta a\xE7\u0131klamas\u0131) \xE7eker.",
+    { word: z.string().describe("Etimolojisi aranacak kelime.") },
+    guard(async ({ word }) => {
+      const etymology = await TDK.getNisanyan(word);
+      return etymology ? ok({ word, etymology }) : fail(`Ni\u015Fanyan S\xF6zl\xFCk'te "${word}" bulunamad\u0131.`);
+    })
+  );
+  server.tool(
+    "tdk_kubbealti",
+    "Kubbealt\u0131 Lugat\u0131'ndan (ticari s\xF6zl\xFCk) bir kelimenin anlamlar\u0131n\u0131 \xE7eker.",
+    { word: z.string().describe("Aranacak kelime.") },
+    guard(async ({ word }) => {
+      const meanings = await TDK.getKubbealtiMeanings(word);
+      if (meanings === null)
+        return fail("Kubbealt\u0131 Lugat\u0131'na ula\u015F\u0131lamad\u0131.");
+      return ok({ word, meanings });
+    })
+  );
+  server.tool(
+    "tdk_wiktionary",
+    "T\xFCrk\xE7e Wiktionary'den (tr.wiktionary.org, resmi MediaWiki API) bir maddenin b\xF6l\xFCmlere ayr\u0131lm\u0131\u015F i\xE7eri\u011Fini \xE7eker.",
+    {
+      word: z.string().describe("Aranacak madde ba\u015Fl\u0131\u011F\u0131."),
+      section: z.string().optional().describe("Sadece belirli bir b\xF6l\xFCm istenirse ba\u015Fl\u0131k ad\u0131 (\xF6rn: 'K\xF6ken', '\xC7eviriler').")
+    },
+    guard(async ({ word, section }) => {
+      if (section) {
+        const text = await TDK.getWiktionarySection(word, section);
+        return text ? ok({ word, section, text }) : fail(`Wiktionary'de "${word}" i\xE7in "${section}" b\xF6l\xFCm\xFC bulunamad\u0131.`);
+      }
+      const entry = await TDK.getWiktionary(word);
+      return entry ? ok(entry) : fail(`Wiktionary'de "${word}" bulunamad\u0131.`);
+    })
+  );
+  server.tool(
+    "tdk_spell_check",
+    "Bir kelimenin do\u011Fru yaz\u0131l\u0131p yaz\u0131lmad\u0131\u011F\u0131n\u0131 denetler; yanl\u0131\u015Fsa klavye/diakritik fark\u0131ndal\u0131kl\u0131 en yak\u0131n madde \xF6nerisi verir, \xE7ekimli bi\xE7imse k\xF6k\xFCn\xFC d\xF6nd\xFCr\xFCr.",
+    { word: z.string().describe("Yaz\u0131m\u0131 denetlenecek kelime (\xF6rn: 'yanl\u0131z', 'arabs').") },
+    guard(async ({ word }) => ok(await TDK.checkSpelling(word)))
+  );
+  server.tool(
+    "tdk_proofread",
+    "Bir T\xFCrk\xE7e metni imla, ayr\u0131/biti\u015Fik yaz\u0131m ve 'da/de', 'ki', 'mi' ba\u011Fla\xE7/ek hatalar\u0131 a\xE7\u0131s\u0131ndan denetler.",
+    { text: z.string().describe("Denetlenecek T\xFCrk\xE7e metin.") },
+    guard(async ({ text }) => ok(await TDK.proofread(text)))
+  );
+  server.tool(
+    "tdk_stem",
+    "Bir kelimenin morfolojik k\xF6k\xFCn\xFC (ek s\u0131y\u0131rma / stemming) bulur ve \xE7ekimli olup olmad\u0131\u011F\u0131n\u0131 belirtir (\xF6rn: 'kitab\u0131m\u0131z\u0131n' -> 'kitap').",
+    { word: z.string().describe("K\xF6k\xFC aranacak kelime.") },
+    guard(async ({ word }) => {
+      const result = await TDK.stem(word);
+      return result ? ok(result) : fail(`"${word}" i\xE7in k\xF6k tespit edilemedi.`);
+    })
+  );
+  server.tool(
+    "tdk_analyze_text",
+    "Bir metindeki her kelime i\xE7in k\xF6k, anlam ve k\xF6ken bilgisini toplu olarak \xE7\u0131kar\u0131r.",
+    { text: z.string().describe("Analiz edilecek T\xFCrk\xE7e metin.") },
+    guard(async ({ text }) => ok(await TDK.analyzeText(text)))
+  );
+  server.tool(
+    "tdk_syllables",
+    "Bir kelimeyi T\xFCrk\xE7e hece kurallar\u0131na g\xF6re hecelere ay\u0131r\u0131r (tamamen yerel, a\u011F iste\u011Fi yok).",
+    { word: z.string().describe("Hecelenecek kelime.") },
+    guard(async ({ word }) => ok({ word, syllables: TDK.syllabicate(word) }))
+  );
+  server.tool(
+    "tdk_vowel_harmony",
+    "Bir kelimenin b\xFCy\xFCk \xFCnl\xFC uyumuna ve k\xFC\xE7\xFCk \xFCnl\xFC uyumuna (d\xFCzl\xFCk-yuvarlakl\u0131k) uyup uymad\u0131\u011F\u0131n\u0131 kontrol eder.",
+    { word: z.string().describe("Kontrol edilecek kelime.") },
+    guard(
+      async ({ word }) => ok({
+        word,
+        vowelHarmony: TDK.checkVowelHarmony(word),
+        labialHarmony: TDK.checkLabialHarmony(word)
+      })
+    )
+  );
+  server.tool(
+    "tdk_autocomplete",
+    "Bir \xF6nek ile ba\u015Flayan s\xF6zl\xFCk maddelerini (autocomplete) d\xF6nd\xFCr\xFCr.",
+    { prefix: z.string().describe("Aranacak \xF6nek (\xF6rn: 'kalem').") },
+    guard(async ({ prefix }) => ok({ prefix, suggestions: await TDK.getSuggestions(prefix) }))
+  );
+  server.tool(
+    "tdk_pattern_search",
+    "Bulmaca deseni ile e\u015Fle\u015Fen s\xF6zl\xFCk maddelerini bulur: '_' veya '?' tek harf, '*' s\u0131f\u0131r ya da daha fazla harf yerine ge\xE7er (\xF6rn: 'k_l_m').",
+    {
+      pattern: z.string().describe("Desen. '_'/'?' = tek harf, '*' = s\u0131f\u0131r ya da daha fazla harf."),
+      max_results: z.number().int().min(1).max(500).default(50).describe("En fazla sonu\xE7 say\u0131s\u0131.")
+    },
+    guard(async ({ pattern, max_results }) => {
+      const matches = await TDK.patternSearch(pattern, { maxResults: max_results });
+      return ok({ pattern, count: matches.length, matches });
+    })
+  );
+  server.tool(
+    "tdk_anagram",
+    "Verilen harflerle kurulabilecek T\xFCrk\xE7e s\xF6zl\xFCk maddelerini bulur. Birebir anagram varsa onlar, yoksa harflerin bir alt k\xFCmesiyle kurulan kelimeler d\xF6ner.",
+    {
+      letters: z.string().describe("Kullan\u0131lacak harfler (\xF6rn: 'kalem')."),
+      exact_length: z.boolean().default(false).describe("Sadece harflerin tamam\u0131n\u0131 kullanan birebir anagramlar\u0131 d\xF6nd\xFCr."),
+      max_results: z.number().int().min(1).max(500).default(50).describe("En fazla sonu\xE7 say\u0131s\u0131.")
+    },
+    guard(async ({ letters, exact_length, max_results }) => {
+      const words = await TDK.findAnagrams(letters, { exactLength: exact_length, maxResults: max_results });
+      return ok({ letters, count: words.length, words });
+    })
+  );
+  server.tool(
+    "tdk_rhymes",
+    "Bir kelime ile kafiyeli (son harfleri uyu\u015Fan) s\xF6zl\xFCk maddelerini bulur.",
+    {
+      word: z.string().describe("Kafiyesi aranacak kelime."),
+      min_letters: z.number().int().min(1).default(3).describe("Uyu\u015Fmas\u0131 gereken en az son harf say\u0131s\u0131."),
+      max_results: z.number().int().min(1).max(500).default(50).describe("En fazla sonu\xE7 say\u0131s\u0131.")
+    },
+    guard(async ({ word, min_letters, max_results }) => {
+      const rhymes = await TDK.findRhymes(word, { minLetters: min_letters, maxResults: max_results });
+      return ok({ word, count: rhymes.length, rhymes });
+    })
+  );
+  server.tool(
+    "tdk_compare",
+    "\u0130ki kelimeyi anlam say\u0131s\u0131, k\xF6ken, hece b\xF6l\xFCn\xFC\u015F\xFC ve \xFCnl\xFC uyumu a\xE7\u0131s\u0131ndan kar\u015F\u0131la\u015Ft\u0131r\u0131r.",
+    {
+      a: z.string().describe("Birinci kelime."),
+      b: z.string().describe("\u0130kinci kelime.")
+    },
+    guard(async ({ a, b }) => ok(await TDK.compareWords(a, b)))
+  );
+  server.tool(
+    "tdk_audio_url",
+    "Bir kelimenin TDK seslendirme (.wav) URL'sini d\xF6nd\xFCr\xFCr (bulunamazsa null).",
+    { word: z.string().describe("Seslendirmesi aranacak kelime.") },
+    guard(async ({ word }) => ok({ word, audioUrl: await TDK.getAudioUrl(word) }))
+  );
+  server.tool(
+    "tdk_word_of_the_day",
+    "TDK'nin 'g\xFCn\xFCn kelimesi'ni anlamlar\u0131yla d\xF6nd\xFCr\xFCr.",
+    {},
+    guard(async () => {
+      const wotd = await TDK.getWordOfTheDay();
+      return wotd ? ok(wotd) : fail("G\xFCn\xFCn kelimesi al\u0131namad\u0131.");
+    })
+  );
+  server.tool(
+    "tdk_random_word",
+    "TDK i\xE7eri\u011Finden rastgele bir kelime ya da atas\xF6z\xFC d\xF6nd\xFCr\xFCr.",
+    {},
+    guard(async () => {
+      const pick = await TDK.getRandomWord();
+      return pick ? ok(pick) : fail("Rastgele i\xE7erik al\u0131namad\u0131.");
+    })
+  );
+  server.tool(
+    "tdk_rules",
+    "TDK Yaz\u0131m K\u0131lavuzu kurallar\u0131n\u0131 listeler; 'name' verilirse o kural\u0131n tam metnini d\xF6nd\xFCr\xFCr.",
+    {
+      name: z.string().optional().describe("\u0130stenirse tek bir kural\u0131n ad\u0131 (\xF6rn: 'Ba\u011Fla\xE7 Olan da, de'nin Yaz\u0131l\u0131\u015F\u0131').")
+    },
+    guard(async ({ name }) => {
+      if (name) {
+        const rule = await TDK.getRule(name);
+        return rule ? ok({ name, rule }) : fail(`"${name}" kural\u0131 bulunamad\u0131.`);
+      }
+      const rules = await TDK.getKurallar();
+      return ok({ count: rules.length, rules });
+    })
+  );
+  return server;
+}
+async function runMcpServer() {
+  const server = createMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+export {
+  createMcpServer,
+  runMcpServer
+};