MCP Gateway və lokallaşdırma arxitekturası: təkdilli serverlər, locale parametr kimi, klient vəziyyəti

1. Ümumiyyətlə lokallaşdırma arxitekturası barədə niyə düşünməliyik

Bir diliniz və kiçik kataloqunuz olduğu müddətdə hər şey sadədir: gift_catalog.json saxlayırsınız, bütün mətnlər rus dilindədir və MCP‑server bu hədiyyələri hamıya eyni qaydada verir. Amma elə ki, istəyirsiniz:

• ABŞ və Avropa üçün ingilis UI,
• matryoşkalar və rus dilində kitablarla ayrıca rusdilli kataloq,
• müxtəlif bazarlar (ABŞ üçün Amazon, RF üçün Ozon),

sadəlövh yanaşma — “hər handler‑də daha bir if (locale === "ru")” — kodu Yeni il yolkası kimi bəzəyir.

MCP, bir tərəfdən, protokoldur, digər tərəfdən isə bu protokolun server tərəfli reallaşdırılmasıdır. Server ChatGPT‑dən, o cümlədən locale və userLocation daxil olmaqla, metadatalarla gələn sorğuları alır. Sual “o, locale oxuya bilir, ya yox” deyil, sual budur ki, bu siqnalı arxitekturanın məhz harasında nəzərə alırsınız. Bunu hər alətin içində edə bilərsiniz, yaxud məntiqin bir hissəsini ayrıca qat — Gateway — səviyyəsinə çıxara bilərsiniz.

Yaxşı lokallaşdırma arxitekturası üç suala cavab verməlidir:

1. Hansı dil və regiondan istifadə etməyə harada qərar veririk.
2. Lazımi məlumatları və inteqrasiyaları (kataloqlar, mağaza API‑ləri, valyutalar) harada seçirik.
3. İstifadəçinin vəziyyətini (locale, valyuta, bəlkə də bəzi üstünlükləri) harada və necə saxlayırıq ki, hər dəfə əllə ötürməyək.

Bu gün məhz bunları nəzərdən keçirəcəyik.

2. MCP, _meta və stateless təbiət: niyə locale açıq şəkildə ötürülməlidir

Locale‑u arxitekturada harada nəzərə almaq barədə qərar verməzdən əvvəl, MCP‑sorğunun protokol səviyyəsində necə göründüyünü və platformanın hansı metadataları artıq ötürdüyünü xatırlamaq faydalıdır.

Vacib fakti xatırladım: MCP‑sorğuları JSON‑RPC mesajlarıdır. Hər mesaj öz‑özlüyündədir, protokol sizə stateful sessiya məcbur etmir. Buna görə də serverin lokalı nəzərə almasını istəyirsinizsə, onu ya:

• alət arqumenti kimi açıq ötürməlisiniz (locale inputSchema daxilində), ya da
• ChatGPT‑nin sorğuya əlavə etdiyi _meta["openai/locale"] dəyərindən oxumalısınız.

Locale‑u _meta‑dan oxuyan sadə handler nümunəsi:

server.registerTool(
  "suggest_gifts",
  {
    title: "Suggest gifts",
    inputSchema: { /* ... */ },
  },
  async (args, extra) => {
    const meta = extra?._meta ?? {};
    const locale = (meta["openai/locale"] as string | undefined) || "en-US";
    const country = meta["openai/userLocation"]?.country as string | undefined;

    // Sonrakı mərhələdə kataloqu seçmək üçün locale və country istifadə edirik
    const gifts = await loadGiftCatalog(locale, country);
    return { structuredContent: { gifts } };
  }
);

Burada locale‑u arqumentlərlə ötürmürük, SDK‑nın artıq extra daxilinə qoyduğu _meta‑ya güvənirik. Bu tam işlək variantdır və birinci modeldə — tək çoxdilli MCP ilə — işimizə yarayacaq.

İkinci modeldə — Gateway ilə — _meta da əsas rolu oynayır: şlüz metadatalardan locale‑u oxuyur və bunun əsasında sorğunu hara yönləndirməyi qərar verir. Locale‑un hansı formada saxlanması — yalnız _meta‑da, yoxsa alət sxemlərində də — bunu aşağıda ayrıca blokda müzakirə edəcəyik.

3. Model 1: bir çoxdilli MCP‑server (“poliglot‑monolit”)

Ən sadə arxitektura variantından başlayaq. Sizdə bir MCP‑server, bir URL, bir deploy, bir kod bazası var. Hər alətin içində siz:

1. Locale‑u əldə edirsiniz (_meta‑dan və ya arqumentdən).
2. Locale əsasında lazımi resursları seçirsiniz: gift_catalog.en.json, gift_catalog.ru.json və s.
3. Nəticəni artıq lazım olan dildə qaytarırsınız.

GiftGenius üçün nümunə

Güman edək ki, bizdə iki kataloq faylı var:

• data/gift_catalog.en.json
• data/gift_catalog.ru.json

Lazımi faylı seçən kiçik loadGiftCatalog(locale) köməkçisini yazaq:

async function loadGiftCatalog(locale: string) {
  const lang = locale.split("-")[0]; // "en-US" → "en"
  const fileName = lang === "ru" ? "gift_catalog.ru.json" : "gift_catalog.en.json";
  const data = await import(`../data/${fileName}`);
  return data.default; // hədiyyələr massivi
}

İndi suggest_gifts alətimiz sadəcə bu köməkçini çağırır:

server.registerTool(
  "suggest_gifts",
  { title: "Hədiyyə seçimi", inputSchema: {/* ... */} },
  async (args, extra) => {
    const locale = (extra?._meta?.["openai/locale"] as string) || "en-US";
    const catalog = await loadGiftCatalog(locale);
    const filtered = filterGifts(catalog, args);
    return { structuredContent: { gifts: filtered } };
  }
);

Beləliklə, lokallaşdırma bir yerdə — loadGiftCatalog daxilində gizlənir, alətlər isə sadəcə ora locale ötürür. Eyni qaydada tarix formatlarını, valyutaları və digər regiona bağlı elementləri də seçmək olar.

Bu modelin üstün və zəif tərəfləri

Mətndə itməyək deyə, bu ilk modelin üstün və zəif tərəflərini kiçik bir cədvəldə toplayaq (hələ ki, yalnız “bir MCP” barədə — Gateway ilə müqayisəyə sonra qayıdacağıq).

Bu model aşağıdakılar üçün əladır:

• MVP və kiçik tətbiqlər, 2–3 dil və o qədər də fərqli olmayan bazarlar;
• tədris layihələri (məsələn, kurs çərçivəsində GiftGenius).

Bu model aşağıdakılar üçün zəifdir:

• dillərin sayı çoxaldıqda,
• fərqli bazarlar üçün komandalar və məlumatlar köklü surətdə fərqləndikdə (ayrı DB, öz e‑commerce API‑ləri, xüsusi hüquqi tələblər).

Elə bu hallarda ikinci model səhnəyə çıxır.

4. Model 2: MCP Gateway + təkdilli backend‑serverlər

İndi təsəvvür edin ki, GiftGenius həm ABŞ‑da, həm RF‑də, həm də, məsələn, Almaniyada işləyir. ABŞ üçün Amazon API, RF üçün Ozon, Almaniya üçün yerli retail şəbəkəsi ilə işləyirsiniz. Hər bazarın öz müqaviləsi, öz xüsusiyyətləri, öz komandası var. Hamısını bir MCP‑monolitə yığmaq xoş deyil.

Model 2‑nin ideyası belədir:

ChatGPT ilə real MCP‑servisləri arasında Gateway dayanır. ChatGPT üçün bu sadəcə daha bir MCP‑serverdir, içəridə isə o, sorğuları müxtəlif backend‑serverlərə marşrutlaşdırır; hər biri yalnız bir dildə “danışır” və bir bazarla işləyir.

Diaqramda bu necə görünür

Əvvəlcə iki modeli müqayisə üçün çəkək.

flowchart LR
    subgraph Model1["Model 1: Bir MCP"]
      A1[ChatGPT] --> B1["GiftGenius MCP (çoxdilli)"]
    end

    subgraph Model2["Model 2: Gateway + təkdillilər"]
      A2[ChatGPT] --> G[MCP Gateway]
      G --> R["GiftGenius MCP RU (ru-RU, Ozon)"]
      G --> E["GiftGenius MCP EN (en-US, Amazon"]
      G --> D["GiftGenius MCP DE (de-DE, Yerli mağaza)"]
    end

ChatGPT baxımından ikinci modeldə yalnız bir MCP endpoint var — Gateway. Daxildə o, _meta["openai/locale"] və/və ya _meta["openai/userLocation"] dəyərlərini analiz edir və düzgün backend seçir.

Gateway nə edir (bu mühazirənin kontekstində)

Gateway‑i “bütün biznes məntiqi olan ikinci monolit”ə çevirməmək vacibdir. Bizim modulda onun rolu ciddi şəkildə məhduddur:

1. ChatGPT‑dən MCP mesajını qəbul etmək (_meta daxil olmaqla).
2. Locale / userLocation çıxarmaq.
3. Bunun əsasında lazımi backend‑serveri seçmək.
4. Sorğunu ora (JSON‑RPC) proksi edib cavabı geri qaytarmaq.

Hədiyyə kataloqunun konkret olaraq hansını götürmək, Amazon və ya Ozon‑a necə çağırış etmək kimi qərarlar spesifik dil MCP‑serverinin içində qalır. Gateway “qayınana üçün ideal hədiyyə”nin nə olduğunu bilmir. O, ru-RU üçün mcp-giftgenius-ru, en-US üçün mcp-giftgenius-en‑ə getməyin kifayət qədər olduğunu bilir.

TypeScript‑də ən sadə MCP Gateway skeleti

Detallarda itirməmək üçün xeyli sadələşdirək. Güman edək ki, bizdə daxili MCP‑serverlərlə JSON‑RPC vasitəsilə danışmağı bacaran callDownstreamTool köməkçisi var (bu HTTP sorğuları və ya daimi SSE bağlantısı ola bilər, detalları 16‑cı modulda saxlayacağıq).

import { Server } from "@modelcontextprotocol/sdk/server";

const server = new Server({ name: "giftgenius-gateway" });

function chooseBackend(locale?: string) {
  if (!locale) return "en";              // defolt
  const lang = locale.split("-")[0];     // ru-RU → ru
  return ["ru", "de"].includes(lang) ? lang : "en";
}

server.registerTool(
  "suggest_gifts",
  { title: "Suggest gifts (via gateway)", inputSchema: {/* ... */} },
  async (args, extra) => {
    const locale = extra?._meta?.["openai/locale"] as string | undefined;
    const backendKey = chooseBackend(locale); // "ru" | "en" | "de"
    // Lazım olan backend‑serverdə eyni aləti çağırırıq
    return await callDownstreamTool(backendKey, "suggest_gifts", args, extra);
  }
);

Daxili MCP‑serverlər özlərində eyni kontraktla suggest_gifts qeydiyyatdan keçirirlər, ancaq hər biri yalnız öz dili/bazarı ilə işləyir və haradasa başqa dillərin olduğunu bilmir.

Eyni qaydada Gateway listTools, listResources və digər MCP metodlarını da proksi edə bilər, amma bu artıq ayrıca modulun mövzusudur.

5. Lokallaşdırma üçün iki modelin müqayisəsi

Əvvəl “bir MCP” modelinin üstün və zəif cəhətlərinə ayrıca baxdıq. İndi əsas parametrlər üzrə hər iki modelin fərqlərini cədvəldə toplayaq.

Tədris kursumuz üçün əsasən model 1‑ə (bir MCP + locale parametr kimi) sadiq qalacağıq, Gateway modeli isə onlarla bazarı olan “həqiqi biznes” üçün təbii miqyasyönümlü yol kimi baxılacaq. Bununla belə, Gateway təbii növbəti addım olduğundan, bu arxitekturanın bir vacib detalına baxacağıq: locale və istifadəçi ölkəsini sessiya vəziyyətində necə saxlamaq.

6. Gateway‑də klient vəziyyətinin bir hissəsi kimi locale

İndiyə qədər güman edirdik ki, hər sorğu lazım olan hər şeyi daşıyır. Amma real həyatda məlumatın bir hissəsini sessiya vəziyyətində saxlamaq rahatdır. Məsələn:

• istifadəçi bir dəfə locale = "ru-RU" və userLocation.country = "RU" ilə gəldi;
• sonra isə siz onun bütün sorğularını RU‑backend‑ə yönləndirmək istəyirsiniz, hətta aralıq çağırışların bəzilərində locale arqumentlərdə açıq gəlməsə belə.

MCP‑də faydalı bir sahə var: _meta["openai/subject"] — OpenAI‑nın servislərinizə göndərdiyi anonim istifadəçi identifikatoru. Onu sessiya açarı kimi istifadə etmək olar.

Sadə yaddaşdaxili vəziyyət reallaşdırması

Gateway‑də kiçik bir state qatı yazaq (əlbəttə, production üçün Map əvəzinə Redis və ya başqa xarici yaddaşdan istifadə etmək daha yaxşıdır).

type ClientState = {
  locale?: string;
  country?: string;
};

const clientState = new Map<string, ClientState>();

function getClientId(extra: any): string | undefined {
  return extra?._meta?.["openai/subject"] as string | undefined;
}

function updateClientState(extra: any) {
  const clientId = getClientId(extra);
  if (!clientId) return;

  const meta = extra?._meta ?? {};
  const current = clientState.get(clientId) ?? {};
  const next: ClientState = {
    locale: meta["openai/locale"] || current.locale,
    country: meta["openai/userLocation"]?.country || current.country,
  };
  clientState.set(clientId, next);
}

İndi Gateway handler‑ində əvvəlcə vəziyyəti yeniləyib, sonra da backend seçərkən ondan istifadə edə bilərik:

server.registerTool(
  "suggest_gifts",
  { title: "Suggest gifts (via gateway)", inputSchema: {/* ... */} },
  async (args, extra) => {
    updateClientState(extra);
    const clientId = getClientId(extra)!;
    const state = clientState.get(clientId);
    const locale = state?.locale || "en-US";

    const backendKey = chooseBackend(locale);
    return await callDownstreamTool(backendKey, "suggest_gifts", args, extra);
  }
);

Beləliklə, siz bir dəfə clientId → locale, country cütlüyünü “yadda saxlayırsınız” və sonra bu məlumatdan bütün sonrakı alət çağırışlarında istifadə edə bilirsiniz — arqumentlərə hər dəfə eyni sahələri kopyalamadan.

Eyni qaydada Gateway üstünlük verilən valyutanı, qiymət formatını və commerce məntiqinə yarayan digər ayarları da yadda saxlaya bilər (amma bu artıq ACP barədə modulda daha çoxdur).

7. GiftGenius: iki ssenari və arxitektura seçiminin təsiri

Boş “kvadratları” müzakirə etmirikmiş kimi olmasın deyə, GiftGenius üçün konkret ssenarilərə baxaq.

Ssenari 1: İstifadəçi Rusiyadandır, rus dilində yazır

Varsayım:

• _meta["openai/locale"] = "ru-RU",
• _meta["openai/userLocation"].country = "RU".

İstifadəçi yazır: “Həmkarım üçün hədiyyə seç, stolüstü oyunları sevir, 3000 rubladək”.

Model 1‑də (bir MCP):

1. Handler _meta‑dan locale oxuyur, "ru-RU" alır.
2. gift_catalog.ru.json yükləyir — bütün adlar rus dilində, qiymətlər rubladır.
3. Kateqoriya və büdcəyə görə filtrləyir, strukturlu hədiyyə siyahısını rus dilində qaytarır.

Model 2‑də (Gateway + təkdillilər):

1. Gateway locale və userLocation oxuyur, bunun RU istifadəçi olduğunu müəyyən edir.
2. suggest_gifts çağırışını mcp-giftgenius-ru‑ya yönləndirir.
3. O isə yalnız rus kataloqu və Ozon API ilə işləyir, hədiyyələri rubl ilə verir.

Hər iki halda istifadəçi hər şeyi öz dilində görür, amma ikinci variantda sizin ingilis MCP‑serveriniz Rusiyaya aid kataloqun mövcudluğundan belə xəbərsizdir.

Ssenari 2: İstifadəçi Almaniyadandır, ingiliscə yazır

İndi isə:

• _meta["openai/locale"] = "en",
• _meta["openai/userLocation"].country = "DE".

İstifadəçi yazır: “Gift for my German coworker, budget 50 EUR”.

Model 1‑də:

• "en" locale ingilisdilli mətnlər verir,
• "DE" country isə Avropaya uyğunlaşdırılmış assortiment və avro ilə qiymətlər olan kataloqu seçmək üçün istifadə oluna bilər.

Model 2‑də:

• Gateway belə qərar verə bilər: locale = "en" → ingilis servis, amma country = "DE" → Avropa anbardan məhsullar; sizin biznes məntiqinizdən asılı olaraq siz:

• sorğunu mcp-giftgenius-en üzərinə country=DE parametri ilə yönləndirə bilərsiniz,
• və ya Avropa üçün ayrıca mcp-giftgenius-eu saxlayırsınız.

Burada açıq görünür ki, lokal (dil) və region (userLocation) fərqli ölçülərdir və onları “hansı servisi çağırmalı və hansı məhsulları göstərməli” qərarına birləşdirmək üçün Gateway əlverişli yerdir.

8. Alət sxemlərində locale vs yalnız _meta daxilində locale

İstər bir MCP‑dən istifadə edin, istər Gateway + təkdilli servislər dəstindən, sonda incə, amma vacib məqamı müzakirə etməyə dəyər: locale‑u yalnız _meta daxilində saxlamaq, yoxsa alətin arqumenti etmək?

İki yanaşma var.

Birinci: yalnız _meta‑ya güvənmək.

Bu rahatdır, çünki alət sxemləri əlavə bir sahə ilə “çirklənmir”. Server locale‑u extra._meta daxilindən oxuyur və özü qərar verir. Model 1‑də bu tez‑tez kifayətdir.

İkinci: locale‑u (və bəlkə də currency‑ni) inputSchema‑ya açıq şəkildə əlavə etmək.

const suggestGiftsSchema = {
  type: "object",
  properties: {
    locale: {
      type: "string",
      description: "User locale in BCP 47 format, e.g. en-US or ru-RU"
    },
    recipient: { type: "string" },
    // ...
  },
  required: ["recipient"]
};

Sonra system‑prompt‑da modeli istifadəçi kontekstindəki dəyərdən istifadə edərək locale sahəsini həmişə doldurmağa təşviq edə bilərsiniz. Bu, niyyəti şəffaf edir: JSON arqumentlərində serverin hansı dildə işləməli olduğu birbaşa görünür. Bu yanaşma, xüsusilə locale əsasında içəridə müxtəlif servislərə və ya resurslara marşrutlaşdıran bir ümumi MCP olduğu daha mürəkkəb arxitekturalarda faydalıdır.

Təcrübədə tez‑tez hər iki yanaşmanı birləşdirirlər: sxemlərdə locale sahəsi var, amma model bunu hər hansı səbəbdən doldurmasa, server _meta["openai/locale"] ilə sığortalanır.

9. Gateway‑də lokallaşdırma ilə “artıq məntiq” arasında sərhəd haradan keçir

Asanlıqla düşülən tələ: “ağıllı Gateway”imiz var deyə, gəlin o:

• hansı hədiyyələri göstərəcəyinə özü qərar versin,
• tarix və qiymətləri özü formatlasın,
• kliklər üzrə hesabatları özü toplasın və s.

Bu cəlbedici səslənsə də, Gateway‑i “ikinci monolit”ə çevirir və onun yenilənməsini və istismarını çətinləşdirir. Sənayedə API şlüzlərinin (və rolu etibarilə MCP Gateway də elə şlüzdür) praktikalarında onların fokusunu bir neçə vəzifədə saxlayırlar: autentifikasiya, avtorizasiya, marşrutlaşdırma və yüngül kontekst zənginləşdirməsi. Məsələn, şlüz HTTP başlıqlarını əlverişli metadatalara çevirə bilər. Biznes məntiqi və ağır əməliyyatlar backend‑servislərdə yaşamalıdır.

Lokallaşdırma üçün bu o deməkdir ki:

• Gateway _meta["openai/locale"] və _meta["openai/userLocation"] dəyərlərini parse edə bilər.
• Onları klientin vəziyyətində yadda saxlaya bilər.
• Lazımi dil serverini seçə və ya sorğuya locale/country sahələrini əlavə edə bilər.

Amma hədiyyələrin seçimi, yaşa, büdcəyə görə filtrasiya və s. — bütün bunlar MCP backend‑lərində qalmalıdır.

10. MCP və Gateway vasitəsilə lokallaşdırma dizaynında tipik səhvlər

Səhv №1: İstifadəçi mətninə görə dili “təyin etməyə” yalnız güvənmək.
Bəzən istəyirsiniz ki, mesaj mətni ilə language‑detector işlədib bunun əsasında hansı serverin çağırılacağını müəyyən edəsiniz. Bu, faydalı fallback ola bilər, amma əsas mexanizm deyil. Platforma sizə artıq openai/locale və openai/userLocation verir — onlar ChatGPT ayarlarını və istifadəçi mühitini nəzərə alır. Bu siqnalları görməməzliyə vurub “dili tap” oyunu oynamaq UX‑i ən gözlənilməz hallarda pozmağın “səmərəli” yoludur.

Səhv №2: Locale‑u yalnız modelin “beynində” saxlayıb serverə ötürməmək.
Əgər locale nə _meta‑da, nə də alət arqumentlərində görünmürsə, server istifadəçinin dili barədə heç nə bilmir. Model “книги” sözünü books şəklinə “tərcümə etməyə” cəhd edə bilər, amma bu etibarlı deyil, xüsusən mürəkkəb kateqoriyalarınız varsa. Düzgün yol locale‑u açıq ötürməkdir: ya locale arqumenti ilə, ya da _meta‑dan oxuyaraq və arxitekturanı bunun ətrafında quraraq.

Səhv №3: Lokallaşdırmanın bütün biznes məntiqini Gateway‑ə daşımaq.
Gateway özü hədiyyə seçir, DB‑lərə gedir və xarici API‑lərlə vuruşursa, o, artıq yüngül marşrutlaşdırıcı deyil, miqyaslandırması və yenilənməsi çətin ağır servisdən ibarət olur. Nəticədə bir monolit əvəzinə iki monolit əldə edirsiniz. Gateway‑i maksimum “sadə” tutmaq daha yaxşıdır: o, locale/userLocation‑a baxır, lazımi backend‑i seçir və metadataları səliqə ilə ötürür.

Səhv №4: Marşrutlaşdırmanı yalnız IP və ya userLocation‑a sərt bağlamaq.
Bəzən sadə etmək istəyirsiniz: “əgər ölkə RU‑dursa — RU serverinə gedirik”. Amma istifadəçi Almaniyada ola bilər və yenə də interfeysi rus dilində istəyə bilər, yaxud sessiyanın ortasında “switch to English” deyə bilər. Gateway‑də openai/locale və istifadəçinin dili dəyişmək istəyini nəzərə almırsınızsa, marşrutlaşdırma “beton kimi” olur və UX‑i pozur. Locale və userLocation kombinasiyasına söykənmək və sessiya vəziyyəti vasitəsilə ayarları yenidən təyin etməyə imkan vermək daha yaxşıdır.

Səhv №5: _meta["openai/subject"] istifadə etməmək və bütün parametrləri hər arqumentdə təkrarlamaq.
Hər tool arqumentində locale, country, currency, userId və daha yarım interfeysi daşımağa başlayanda həyat tez kədərlənir. MCP artıq anonim istifadəçi identifikatorunu _meta["openai/subject"] vasitəsilə ötürür və siz bu məlumatı Gateway və ya backend‑server tərəfində klientin vəziyyətində saxlaya bilərsiniz. Bu, kontraktları sadələşdirəcək və arqument uyğunsuzluğu riskini azaldacaq.

Səhv №6: İnkişaf strategiyasının olmaması: “dərhal on dil üçün mürəkkəb Gateway qururuq”.
Tez‑tez hər şeyi dərhal ideal etmək istəyirsiniz: Gateway, beş dil, üç region, on MCP‑servis. Praktikada “bir MCP + locale parametr kimi və ya _meta” modeli ilə başlamaq, davranışı sabitləşdirmək və sonra böyüdükcə Gateway və təkdilli servisləri ayırmaq daha asandır. Dərhal nəhəng “zoopark” qurmağa cəhd, demək olar ki, buraxılışı gecikdirəcək və sazlamanı çətinləşdirəcək.