MCP-nin inspeksiyası və sazlanması: MCP Jam, Inspector, jurnallar

1. Ümumiyyətlə MCP‑inspektor nə üçün lazımdır

Təsəvvür edin ki, frontend-i debug edirsiniz, amma sizə DevTools-u açmaq qadağandır. MCP‑inspektoru olmadan həyat təxminən belə görünür. MCP protokolu ChatGPT və Apps SDK-da “kapotun altında” işləyir; əgər siz yalnız çat cavabına baxıb belə düşünürsünüzsə: “Bəs niyə alətimi görmür?”, — əslində boşluğa atəş açırsınız.

MCP Inspector (rəsmi) və ya MCP Jam kimi inspektorlar — bunlar xüsusi tərtibatçılar üçün MCP müştəriləridir. Onlar aşağıdakıları bacarır:

• sizin MCP‑serverinizə ChatGPT-in etdiyi kimi qoşulmaq;
• handshake / capabilities mərhələlərini keçmək;
• tools/resources/prompts siyahısını istəmək;
• istənilən aləti əl ilə, ixtiyari arqumentlərlə çağırmaq;
• xam JSON‑mesajları (requests / replies / errors) göstərmək.

Əslində bu, “MCP üçün Postman, amma ağıllı”dır. Adi REST‑müştəridən fərqli olaraq, inspektor MCP-nin spesifikasını bilir: o, tools/list, tools/call-ı anlayır, arqument sxemlərini göstərə bilir, bəzən qorunan serverlər üçün hətta OAuth axınını da dəstəkləyir.

İnspektorunuz yoxdursa, sazlama belə görünür: ChatGPT-i işə salırsınız, App-ı çağırmağa çalışırsınız, “Error talking to app” görürsünüz və ya ümumiyyətlə alətin çağırılmadığını müşahidə edirsiniz, sonra isə təxmin edirsiniz: modeli aləti çağırmaq istəmədi, MCP-niz qalxmadı, yoxsa JSON xətasıdır? İnspektorla siz hər qatını ayrıca yoxlaya bilərsiniz: əvvəlcə MCP‑serveri inspektorla təkbətək, sonra isə ChatGPT ↔ MCP birləşməsini.

2. İnspektorların qısa icmalı: MCP Inspector, Jam və başqaları

Praktikada siz çox vaxt MCP üçün iki tip inspektordan istifadə edəcəksiniz.

Birincisi, Model Context Protocol deposundan rəsmi MCP Inspector-dur. Bu, veb‑tətbiqdir (adətən React üzərində SPA), lokal olaraq və ya npx/Docker vasitəsilə qaldırılır və HTTP/SSE üzərindən sizin MCP‑serverinizə qoşula bilir.

İkincisi, MCP Jam-tipli inspektorlardır ki, onlar tez-tez OAuth üzrə rahatlıqlar da əlavə edir. Onlar özləri .well-known/oauth-protected-resource-u oxuya, oradan authorization_endpoint və token_endpoint-i çıxara, PKCE axınından keçə və artıq avtorizə olunmuş vəziyyətdə MCP-yə müraciət edə bilərlər.

MCP Jam, MCP Inspector bazasında tərtibatçılar tərəfindən yaradılıb. Əgər MCP Inspector minimum dəst sazlama alətlərini həyata keçirirsə, MCP Jam tərtibatçının MCP ilə gündəlik işində lazım olacaq hər şeyi təmin edir. Şəxsən mən birbaşa MCP Jam-dan istifadə etməyi tövsiyə edirəm ki, sonradan öyrəşməni yenidən etməyəsiniz.

Bizim kursun baxış bucağından fərq ondadır ki:

• baza Inspector sizə həmişə lazımdır, hətta ən sadə, qorunmayan MCP‑server üçün belə;
• MCP Jam (və ya analoqu) autentifikasiya və avtorizasiya modullarına çatdığınızda faydalı olur.

Amma ümumi fikir eynidir: bu, adi MCP‑müştəridir, sadəcə ChatGPT-nin “səssiz” gördüyünü gözəl göstərməyi bacarır.

3. MCP-inspektoru ilə tipik iş ssenarisi

Gəlin tipik ssenarini addım-addım keçək: siz MCP‑serverinizdə yeni bir alət (tool) yazdınız və onun həqiqətən işlədiyinə əmin olmaq istəyirsiniz.

Önceki mühazirədə siz artıq minimal MCP‑serverini qaldırmışdınız. İndi isə buna sistemli yoxlama yanaşması əlavə edək: “server → inspektor → JSON‑məntiqi” tam dövrünü addım-addım keçirək.

Addım 1 — MCP‑serverini işə salırıq

Bunu əvvəlki mühazirədə etmisiniz: tutalım, sizdə npm run mcp-dev skripti var:

# MCP serverini işə salmanın nümunəsi
npm run mcp-dev
# arxa planda təxminən belə: ts-node src/mcp-server.ts

Vacibdir ki, server seçdiyiniz nəqliyyatı dinləsin: kursda bu adətən HTTP endpoint /mcp hər hansı bir portda olur, məsələn, http://localhost:4001/mcp.

Addım 2 — MCP Jam-ı işə salırıq

İkinci terminal:

# MCP Jam-ı işə salmağın variantlarından biri
npx @mcpjam/inspector@latest
# lazım olsa, --port 4002 və s. əlavə etmək olar

Bundan sonra inspektor brauzerdə açılır, çox vaxt http://localhost:6274 və ya oxşar portda.

MCP Jam-in başlanğıc ekranında sizdən MCP‑serverin URL-ini göstərməyinizi xahiş edəcəklər. Siz daxil edirsiniz:

http://localhost:4001/mcp

və ya artıq hər şeyi ngrok vasitəsilə ötürürsünüzsə, tunelləşdirilmiş URL-inizi.

Addım 3 — handshake / capabilities

MCP Jam qoşulan kimi, o, ChatGPT-in etdiyinin eynisini avtomatik edir:

1. Müştəri haqqında məlumatlarla ilkin sorğu (initialize) göndərir.
2. Protokol versiyası və serverinizin capabilities-i ilə cavab alır.
3. capabilities-ə əsasən serverin tools, resources, prompts və digər xüsusiyyətləri dəstəkləyib-dəstəkləmədiyini başa düşür.

UI-də bu adətən təxminən belə görünür:

Connected
Protocol: mcp/2025-06-18
Capabilities:
- tools: list, call
- resources: list, read
- prompts: list, get

Əgər bu mərhələdə inspektor qoşula bilmirsə (connection refused, CORS, 500 və s.), siz dərhal xətanı görür və anlayırsınız: problem modeldə və ya ChatGPT-də deyil, server tərəfinizdə və ya şəbəkədədir.

Addım 4 — discovery: tools/resources/prompts-a baxırıq

Uğurlu handshake-dən sonra inspektor adətən özü tools/list, resources/list, prompts/list kimi metodları çağırır ki, yan paneli doldursun. Siz görəcəksiniz:

• alətlərin siyahısını təsvirlərlə və giriş arqumentlərinin JSON Schema-sı ilə;
• resursların siyahısını kolleksiyalar/yollar üzrə qruplaşdırılmış şəkildə;
• qısa təsvirlərlə promtların siyahısını.

Yeni alət əlavə etmisinizsə, amma siyahıda yoxdursa, demək ki, o, serverdə düzgün qeydiyyatdan keçməyib və ya server yenilənmiş kodla qaldırılmayıb. Bunu burada görmək, ChatGPT-nin niyə alətinizi “çağırmaq istəməməsinə” dair ehtimallar yürütməkdən xeyli asandır.

4. MCP Jam vasitəsilə alətlərin əl ilə çağırılması

MCP Jam-ın ən faydalı funksiyası — alətləri əl ilə çağırmaqdır. Bu, tools/call üçün sizin şəxsi UI-nizdir.

Aləti seçirik və arqumentləri doldururuq

Tutaq ki, əvvəlki moduldə siz suggest_gifts adlı alət yazmısınız:

// src/mcp/tools/suggestGifts.ts faylında haradasa
export const suggestGiftsTool = {
  name: "suggest_gifts",
  description: "Yaş, büdcə və maraqlara görə hədiyyə ideyalarını seçir",
  inputSchema: {
    type: "object",
    properties: {
      age: { type: "number" },
      budget: { type: "number" },
      interests: {
        type: "array",
        items: { type: "string" }
      }
    },
    required: ["age", "budget"]
  },
  // handler ayrıca təyin edilir
};

MCP Jam-da siz suggest_gifts-ə klikləyirsiniz. Sağ tərəfdə inputSchema-ya əsasən generasiya olunmuş forma açılır. Orada belə doldurursunuz:

{
  "age": 30,
  "budget": 100,
  "interests": ["oyunlar", "kitablar"]
}

və “Call” və ya oxşar düyməni basırsınız.

İnspektor MCP sorğusunu tools/call göndərir və siz dərhal görürsünüz:

• serverə dəqiq nə göndərildiyini göstərən xam JSON sorğunu;
• xam JSON cavabı (result və ya error);
• mümkündür ki, nəticənin rahat ön-baxışını.

JSON jurnallarını inspektorda oxuyuruq

Adətən inspektor təxminən belə göstərir:

// Request
{
  "id": "1",
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "suggest_gifts",
    "arguments": {
      "age": 30,
      "budget": 100,
      "interests": ["oyunlar", "kitablar"]
    }
  }
}

// Reply
{
  "id": "1",
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "1) Stolüstü oyun ... 2) Kitab mağazasına hədiyyə sertifikatı ..."
      }
    ]
  }
}

Əgər handler-iniz istisna ilə yıxılırsa, siz JSON‑RPC üslubunda error görəcəksiniz:

{
  "id": "1",
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": "TypeError: Cannot read properties of undefined ..."
  }
}

Çox vacibdir: məhz burada siz protokol səviyyəsini görürsünüz. Cavab, Apps SDK/ChatGPT-in gözlədiyi formata uyğun deyilsə, bunu “GPT-nin bugu” deyə qınamağa başlamazdan əvvəl də görə biləcəksiniz.

5. Resursların və prompt-ların sazlanması

Alətlər — MCP-nin bacardıqlarının hamısı deyil. Siz artıq bilirsiniz ki, daha resources və prompts da var.

İnspektor vasitəsilə siz aşağıdakıları edə bilərsiniz:

• resursların siyahısını açmaq (resources/list) və onların metadatasına baxmaq;
• konkret resursu oxumaq (resources/read) və qaytarılan məlumatların düzgünlüyünə əmin olmaq;
• resurslarda axtarış aparmaq (əgər belə imkan reallaşdırılıbsa);
• hazır promtları və onların mətnini görmək.

Məsələn, sizdə gift_catalog adlı resurs varsa:

// resursun qeydiyyatı üçün psevdokod
registerResource({
  uri: "resource://giftgenius/catalog",
  name: "Hədiyyələr kataloqu",
  mimeType: "application/json",
  handler: async () => {
    return JSON.stringify(giftCatalogData);
  }
});

İnspektorda bu resursu görəcək, üzərinə klikləyəcək və dərhal JSON-u görə biləcəksiniz. Əgər JSON etibarlı deyilsə və ya MIME tipi qəribədirsə, — ChatGPT onu oxumağa və ya vidcetə yerləşdirməyə çalışarkən ilişmədən əvvəl siz bunu tutacaqsınız.

6. MCP‑serverin jurnalları: nəyi, harada və necə jurnallaşdırmaq

MCP Jam yaxşıdır, amma təkcə o kifayət deyil: sizə MCP‑serverin öz jurnalları lazımdır. Onlarsız istənilən production lotereyaya çevriləcək.

Nələri jurnala yazmalı

Faydalı minimum:

• hər bir daxil olan MCP mesajı (request/notification) ilə birlikdə:
  • zaman;
  • metod (tools/call, tools/list və s.);
  • alətin adı (əgər varsa);
  • qısaldılmış arqumentlər (həssas məlumatlar olmadan);
• hər bir çıxan cavab:
  • status (uğur / xəta);
  • icra vaxtı;
  • nəticənin qısa versiyası və ya heç olmasa tipi;
• texniki xətalar:
  • JSON parsinqi;
  • handlers-də gözlənilməz istisnalar.

Eyni zamanda çox vacibdir ki, PII və sirləri tam şəkildə jurnala yazmayasınız: tokenlər, parollar, konfidensial sorğuların tam mətni. Production-loqlaşdırma üzrə tövsiyələrdə adətən PII-nin qısaldılmış formada yazılması birbaşa qeyd olunur.

Jurnalları hara yazmalı: stdout / stderr

MCP üçün vacib bir tələb var: JSON‑mesajlar “düzgün kanalla” getməlidir, bütün sazlama jurnalları isə başqa kanalla. Məsələn, stdout/stderr üzərində transportdan istifadə edirsinizsə:

• JSON‑RPC mesajları stdout-a getməlidir;
• bütün console.log, console.error və s. isə stderr-ə yönləndirilməlidir.

JSON ilə mətn jurnallarını eyni axında qarışdırsanız, müştəri (MCP Jam və ya ChatGPT) sadəcə mesajları pars etməkdə aciz qalacaq, çünki JSON-un arasında qəfil Server started at http://localhost:4001 kimi bir sətir çıxacaq. Bu, MCP‑serverlərində tez-tez rast gəlinən xətalardandır.

HTTP ssenarisində problem bir az sadələşir, amma prinsip eynidir: HTTP cavabında təmiz JSON olmalıdır, bütün jurnallar isə konsola/fayla getməlidir, cavab gövdəsinə yox.

TypeScript MCP‑serveri üçün sadə logger

Gəlin şərti MCP‑serverimizə kiçik bir logger əlavə edək:

// src/logger.ts
export function logRequest(method: string, details: unknown) {
  console.error(
    JSON.stringify({
      level: "info",
      type: "request",
      method,
      details,
      ts: new Date().toISOString(),
    })
  );
}

export function logError(method: string, error: unknown) {
  console.error(
    JSON.stringify({
      level: "error",
      type: "error",
      method,
      error: String(error),
      ts: new Date().toISOString(),
    })
  );
}

Və tools handler-ində:

// src/mcp-server.ts (fraqment)
server.setRequestHandler("tools/call", async (req) => {
  logRequest("tools/call", {
    name: req.params?.name,
    // burada bütün payload-u qoymaq əvəzinə, yalnız təhlükəsiz sahələri yazmaq daha yaxşıdır
  });

  try {
    const result = await handleToolCall(req);
    return result;
  } catch (e) {
    logError("tools/call", e);
    throw e;
  }
});

Beləcə konsolda strukturlaşdırılmış JSON jurnallarını görəcəksiniz; onları sonra ts və ya əlavə requestId üzrə bir-biri ilə asanlıqla tutuşdurmaq olar.

7. Birləşmə: MCP Jam + jurnallar

Düzgün MCP sazlama strategiyası demək olar ki, həmişə belə görünür:

1. Problemi inspektorda təkrarlayırsınız: tools/list boş siyahı qaytarır, tools/call yıxılır, JSON cavab qəribədir və s.
2. Eyni anda MCP‑serverin jurnallarına baxırsınız: o, işə düşəndə nə yazır, hər mesajda hansı xətaları çıxarır, stack trace varmı.
3. Loqlarda id, method, ts-i inspektorda görünənlə tutuşdurursunuz.

Məsələn, inspektorda görürsünüz:

{
  "error": {
    "code": -32603,
    "message": "Internal error"
  }
}

Və paralel olaraq jurnallarda:

{
  "level": "error",
  "type": "error",
  "method": "tools/call",
  "error": "TypeError: Cannot read properties of undefined (reading 'age')",
  "ts": "2025-11-21T10:15:12.345Z"
}

Hər şey aydındır: haradasa handler-də siz age gözləyirsiniz, amma sxem/arqumentlər fərqlidir.

8. Kiçik yoxlama siyahısı: MCP‑serveri App ilə inteqrasiyaya hazırdırmı?

MCP‑serveri real ChatGPT App-a qoşmazdan əvvəl inspektorla kiçik bir yoxlama siyahısından keçmək rahatdır.

Birincisi, handshake və capabilities xətasız keçməlidir. MCP Jam serverin sizə lazım olan entitiləri dəstəklədiyini göstərməlidir: heç olmasa tools və əgər istifadə olunursa, resources / prompts.

İkincisi, inspektordakı tools/resources/prompts siyahısı sizin özünüzdə reallaşdırılmış hesab etdiyiniz alət, resurs və promtlarla üst-üstə düşməlidir. name-dəki hərf səhvləri, unudulmuş qeydiyyatlar və s. burada dərhal tutulur.

Üçüncüsü, düzgün arqumentlərlə alət çağırışları stabil şəkildə korrekt result qaytarmalıdır. Məsləhətdir ki, prod-da həqiqətən güvəndiyiniz bir neçə tipik hadisəni də sınayasınız.

Dördüncüsü, düzgün olmayan arqumentlərlə çağırışlar anlaşılır error cavabları (JSON‑RPC üslubunda) qaytarmalıdır, HTTP 500 ilə yıxılmamalıdır. Məsələn, məcburi parametr çatışmırsa, ChatGPT-in sonradan istifadəçiyə çevirməsi üçün strukturlu xəta qaytarmaq yaxşı olardı.

Beşincisi, bu zaman server jurnalları hər xırda detal üçün konsolu gigabaytlarla stack trace ilə doldurmamalıdır. Xətalar strukturlu olmalı, həssas məlumatlar isə səliqəli şəkildə filtrlənməlidir.

Bunların hamısı inspektorda yerinə yetirilirsə, MCP‑serveri Apps SDK‑ya daha rahatlıqla qoşub Dev Mode-da vidcetlərlə işləyə bilərsiniz.

9. MCP‑serverinin tipik xətaları və onları inspektor vasitəsilə necə tutmaq

İndi ən maraqlı hissəyə keçək — ən çox nə sınır və bunu necə görmək olar.

Konfiqurasiya və qoşulma

Bəzən “server işləmir” kimi görünür, amma problem ondadır ki, o, lazım olan portu və ya endpoint-i ümumiyyətlə dinləmir. Belə halda inspektor səmimi şəkildə connection refused deyəcək və ya heç qoşula bilməyəcək. Tez-tez rast gəlinən səbəblər: səhv URL (məsələn, /mcp əvəzinə /api/mcp), portun başqa proses tərəfindən tutulması, tunelin qaldırılmaması və ya CORS-un sorğuları kəsməsi.

Yararsız JSON / jurnalların protokolla qarışdırılması

Ən ağrılı hekayələrdən biri — siz console.log("Server started")-u stdout-a yazırsınız, amma bunun üzərindən JSON‑RPC mesajları getməlidir. Müştəri təmiz JSON gözləyir, amma mətn + JSON alır, pars etməyə çalışır və format xətası ilə yıxılır.

Həll sadədir: protokol axınına (stdout və ya HTTP cavab gövdəsi) nə getdiyini, jurnallara (stderr və ya ayrıca loq‑fayl) nə getdiyini sərt şəkildə ayırın.

Sxem ilə alətin implementasiyasının uyğunsuzluğu

Başqa bir populyar xəta: inputSchema-da birini elan etmisiniz, amma kodda başqa cür gözləyirsiniz. Məsələn, sxem deyir: age — ədəd, interests — məcburi olmayan sətrlər massividir, amma kod arguments.interests.toLowerCase() etməyə çalışır. Model (və inspektor) vicdanla interests-i null kimi göndərir və ya ümumiyyətlə sahəni göndərmir — və burada hər şey yıxılır.

İnspektor sizə tools/call-a əslində hansı JSON-un getdiyini açıq şəkildə görməyə imkan verir və bunu kodunuzla tutuşdurmağa kömək edir.

Tools/resources üçün səhv adlar

Əgər capabilities / tools/list-də siz aləti suggest_gifts_v2 kimi ixrac edirsinizsə, amma Apps manifestində və ya vidcetdə suggest_gifts gözləyirsinizsə, “alət tapılmadı” sizi layihənin sonuna qədər müşayiət edəcək. İnspektorda tools siyahısı və onların name sahələri üzrə bunu dərhal görmək olur, GPT-nin nə düşündüyünü təxmin etmədən.

Yavaş və ya ilişən alətlər

Əgər inspektorda alətin çağırışı 30 saniyə işləyir və sonra vaxt limiti ilə yıxılırsa, — ChatGPT-in daha yaxşı reaksiya verəcəyinə ümid etməyin. MCP‑inspektor hansı mərhələdə ləngidiyinizi anlamağa kömək edəcək: şəbəkə çağırışı, DB, xarici API. Jurnallarda hər sorğunun işlənməsinin başlanğıc və bitiş vaxtına sahib olmaq yaxşıdır ki, anomaliyaları dərhal görəsiniz.

10. MCP-nin inspeksiyası və sazlanması zamanı tipik səhvlər

Səhv №1: MCP-ni yalnız ChatGPT vasitəsilə debug etməyə çalışmaq.
Bir çox tərtibatçı əvvəlcə MCP-ni App-a qoşur, “nəsə işləmir” görür və promtları, alət təsvirini, hətta bəzən model versiyasını dəyişməyə başlayır. Bu vaxt MCP‑server ümumiyyətlə qaldırılmayıb və ya tools/list boşdur. Həmişə inspektordan başlayın: əgər orada hər şey pisdirsə, problem modeldə deyil.

Səhv №2: JSON‑RPC və jurnalları eyni axında qarışdırmaq.
MCP‑müştəri təmiz JSON gözləyəndə, siz isə stdout-a sazlama sətrləri yazanda, nəticə gözləniləndir — parsinq pozulur, Inspector qəribə xətalar göstərir. Jurnallar ayrıca getməlidir (stderr, fayllar, xarici loqlaşdırma sistemləri), protokol mesajları isə ciddi şəkildə öz kanalında.

Səhv №3: capabilities və tools siyahısına baxmamaq.
Tez-tez alət sadəcə ona görə “yox olur” ki, siz onu qeydiyyatdan keçirməyi və ya uyğun capability-ni qoşmağı unutmusunuz. Əgər inspektorda capabilities və tools/list-ə baxmırsınızsa, uzun müddət günahı modeldə axtara bilərsiniz, halbuki problem qeydiyyat kodunuzdadır.

Səhv №4: sxema xətalarını və JSON uyğunsuzluğunu görməməzlikdən gəlmək.
inputSchema və faktiki JSON fərqli olanda, model və inspektor təbii olaraq qəribə davranmağa başlayır. Əgər inspektorda xam JSON mesajlarına baxmır və sxemanı validasiya etmirsinizsə, bu xətalar ən gözlənilməz yerlərdə üzə çıxacaq.

Səhv №5: hər şeyi, o cümlədən PII və tokenləri jurnala yazmaq.
Sazlama həyəcanında request body-ni bütövlükdə, potensial şəxsi məlumatlar və ya sirlər daxil olmaqla, yazmaq asandır. Production-da bu, gecikmiş partlayıcıya çevrilir: sızmalar, uyğunluq problemləri və s. Yalnız diaqnostika üçün həqiqətən lazım olanı yazın və onu qısaldılmış/anomimləşdirilmiş şəkildə edin.

Səhv №6: problemi minimal ssenarilərlə təkrarlamamaq.
Bəzən xəta ChatGPT vasitəsilə mürəkkəb dialoqda üzə çıxır və tərtibatçı elə həmin kimi sazlamağa çalışır. Daha səmərəlisi həmin ssenarini inspektorda bir-iki MCP sorğusu ilə təkrarlamaq, promtların, dialoq tarixçəsinin və modelin “əhvalının” təsirini kəsməkdir.