AI Destekli Yazılım Geliştirmede MCP Araçlarını Sözleşmeyle Test Etmek

AI destekli yazılım geliştirmede MCP sözleşmesini daraltmak

Model Context Protocol (MCP) sunucusunda en kritik tasarım kararı, aracı geniş bir "execute" fonksiyonuna dönüştürmemektir. Örneğin customer_lookup aracının sadece UUID kabul eden, alanları sınırlı ve sayfalamayı zorunlu kılan bir giriş şeması olmalıdır. Modelin serbest metinden SQL üretmesine izin verirseniz, prompt korumaları aşılmış bir çağrı doğrudan veri erişim katmanına iner; JSON Schema doğrulaması ise isteği iş mantığına ulaşmadan reddeder.

import { z } from "zod";

export const CustomerLookupInput = z.object({
  customerId: z.string().uuid(),
  include: z.array(z.enum(["profile", "invoices"])).max(2).default(["profile"]),
  pageSize: z.number().int().min(1).max(50).default(20)
}).strict();

export async function customerLookup(raw: unknown) {
  const input = CustomerLookupInput.parse(raw);
  return repository.findCustomer(input.customerId, input.include, input.pageSize);
}

.strict() ayrıntısı önemlidir: sadece beklenen alanları parse eden şemalar, modelin uydurduğu isAdmin, tenantId veya gelecekte yanlış anlam kazanabilecek ek alanları sessizce yok sayabilir. Strict doğrulama bunları hata olarak görünür kılar. Her araç sonucuna schemaVersion ve makinece ayrıştırılabilir errorCode ekleyin; istemci tarafında sonuç şeması değiştiğinde eski ajan sürümünü tespit edebilirsiniz.

Bir yazılım eğitimi veya teknoloji eğitimi laboratuvarında bu sözleşmeyi test ettirmek için olumlu örneklerin yanında adversarial fixture'lar tutun: geçersiz UUID, 51 elemanlı dizi, beklenmeyen alan ve farklı tenant'a ait kimlik. Bunları CI içinde Node.js için Vitest ile çalıştırmak, prompt değişikliklerinden bağımsız olarak aracın güvenlik sınırını doğrular.

Generative AI araç çağrılarını kayıt ve tekrar ile regresyona sokmak

Generative AI çıktısı olasısaldır; bu nedenle sadece "doğru cevap metni" snapshot'ı almak kırılgandır. Bunun yerine her senaryoda beklenen araç adı, doğrulanmış argümanlar, çağrı sırası ve yasaklı araçlar üzerinden assertion yazın. Model sağlayıcısının API yanıtındaki tool-call nesnesini ham olarak kaydedin; kimlik bilgileri ve müşteri verileri için kayıt öncesi redaction uygulayın.

import { expect, test } from "vitest";
import { runAgent } from "./agent.js";

test("iade talebi yalnızca order_lookup ile başlar", async () => {
  const trace = await runAgent({
    input: "ORD-1042 için iade durumunu göster",
    temperature: 0,
    toolChoice: "auto"
  });

  expect(trace.toolCalls.map(x => x.name)).toEqual(["order_lookup"]);
  expect(trace.toolCalls[0].arguments).toMatchObject({ orderId: "ORD-1042" });
  expect(trace.toolCalls.some(x => x.name === "refund_create")).toBe(false);
});

temperature: 0 test tekrarını iyileştirir ama deterministikliği garanti etmez; sağlayıcı tarafındaki model güncellemesi veya tool-selection katmanı çağrı davranışını değiştirebilir. Bu yüzden kaydedilmiş üretim izlerinden seçilen 50-100 vakayı nightly değerlendirmede yeniden oynatın ve "araç sırası doğru", "şema geçerli", "yetkisiz mutasyon yok" oranlarını ayrı metrikler olarak yayınlayın. Metin benzerliği yüksek olsa bile yanlış araca çağrı yapılması sürüm kapatma kriteri olmalıdır.

Bir yapay zeka kursu ya da llm eğitimi kapsamında bu yaklaşımın pratik ödevi, başarısız her çağrıyı invalid_arguments, authorization_denied ve tool_timeout olarak etiketleyip hata dağılımını çıkarmaktır. Bu sınıflandırma, prompt'u değiştirmenin mi yoksa araç sözleşmesini düzeltmenin mi gerekli olduğunu gösterir; örneğin hataların çoğu invalid_arguments ise açıklama metninden önce enum ve örnek girişleri düzeltmek daha düşük risklidir.

MCP gecikmesini OpenTelemetry ve k6 ile ölçmek

Araçlı ajanlarda kullanıcı gecikmesi yalnızca LLM üretim süresi değildir: model turu, MCP istemci-serileştirme, araç kuyruğu, veritabanı ve ikinci model turunun toplamıdır. OpenTelemetry ile her araç çağrısını ayrı span olarak işaretleyin; tool.name, tool.schema_version, tenant.tier ve retry.count öznitelikleri Jaeger veya Grafana Tempo'da p95 ayrıştırması için yeterlidir. Ham müşteri kimliği ya da prompt metnini span attribute olarak yazmayın; trace depoları çoğu ekipte uygulama loglarından daha geniş erişime sahiptir.

import { trace, SpanStatusCode } from "@opentelemetry/api";

const tracer = trace.getTracer("agent-tools");

export async function invokeTool(name: string, args: unknown) {
  return tracer.startActiveSpan(`mcp.${name}`, async (span) => {
    span.setAttribute("tool.name", name);
    const started = performance.now();
    try {
      const result = await mcpClient.callTool({ name, arguments: args });
      span.setAttribute("tool.latency_ms", performance.now() - started);
      span.setStatus({ code: SpanStatusCode.OK });
      return result;
    } catch (err) {
      span.recordException(err as Error);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw err;
    } finally {
      span.end();
    }
  });
}

Önce-sonra karşılaştırmasını aynı prompt veri kümesi ve aynı eşzamanlılıkla yapın. Örneğin önce her araç çağrısında yeni HTTP/TLS bağlantısı açan istemcide, sonra keep-alive etkinleştirilmiş istemcide k6 ile 30 saniyelik 20 sanal kullanıcı testi çalıştırın. Başarı kriterini ortalama değil http_req_duration p95, checks oranı ve araç zaman aşımı sayısı olarak belirleyin; ortalama 300 ms iken p95'in 4 saniye olması kuyruk veya bağlantı havuzu doygunluğunu gizler.

import http from "k6/http";
import { check } from "k6";

export const options = {
  vus: 20,
  duration: "30s",
  thresholds: {
    http_req_duration: ["p(95)<1200"],
    checks: ["rate>0.99"]
  }
};

export default function () {
  const res = http.post(`${__ENV.API_URL}/agent`, JSON.stringify({
    input: "ORD-1042 siparişini getir"
  }), { headers: { "Content-Type": "application/json" } });
  check(res, { "200 döndü": r => r.status === 200 });
}

Vibe coding eğitiminde onay kapısı ve idempotent mutasyonlar

Vibe coding eğitimi ve vibe coding kursu projelerinde en sık atlanan sınır, okuma araçlarıyla mutasyon araçlarını aynı güven seviyesinde sunmaktır. refund_create, deploy_release veya send_email gibi etkili araçlar için modelin doğrudan çağrısı yerine kullanıcıdan alınmış, kısa ömürlü bir onay belirteci zorunlu kılın. Onay ekranı araç adı, normalize edilmiş parametreler ve etkisini göstermeli; modelin açıklamasını değil sunucunun doğruladığı argümanları kaynak kabul etmelidir.

export async function createRefund(input: {
  orderId: string; amountCents: number; approvalToken: string; idempotencyKey: string;
}) {
  await approvals.verify(input.approvalToken, {
    action: "refund_create",
    payloadHash: sha256(`${input.orderId}:${input.amountCents}`)
  });

  return db.transaction(async (tx) => {
    const previous = await tx.refunds.findByIdempotencyKey(input.idempotencyKey);
    if (previous) return previous;
    return tx.refunds.insert({ ...input, status: "pending" });
  });
}

İdempotency anahtarı sadece istemci kolaylığı değildir: ağ zaman aşımından sonra ajan aynı mutasyonu tekrar deneyebilir ve model, önceki aracın sonucunu bağlam penceresinden kaybedebilir. Anahtarı kullanıcı isteği başına üretin, veritabanında benzersiz indeksle saklayın ve payload hash'iyle eşleştirin. Aynı anahtarla farklı tutar gelirse 409 döndürün; aksi halde yanlışlıkla ikinci bir iade yerine ilk işlemin sonucunu döndürerek veri tutarsızlığını gizlersiniz.

Yapay zeka eğitimi için sürümleme, canary ve geri alma ölçütleri

Yapay zeka eğitimi materyalindeki ajan örneklerini üretime taşırken prompt, araç şeması ve model kimliğini tek bir sürüm kaydında birleştirin. Örneğin agent-config.yaml içinde prompt_revision, tool_contract_revision ve değerlendirme veri kümesi commit SHA'sını saklayın. Böylece bir regresyon görüldüğünde "hangi model" kadar "hangi araç açıklaması" sorusuna da izlenebilir cevap verilir.

agent:
  prompt_revision: "support-v18"
  tool_contract_revision: "2026-08-17.2"
  eval_dataset_commit: "8fb4c21"
  rollout:
    canary_percent: 5
    rollback_if:
      invalid_tool_args_rate: 0.02
      mutation_without_approval_count: 1
      tool_p95_ms: 1500

Canary'de eski ve aday yapılandırmayı aynı trafik diliminde ayrı trace öznitelikleriyle çalıştırın; karşılaştırmayı en az çağrı başına araç sayısı, geçersiz argüman oranı, onay gerektiren mutasyon denemesi ve p95 araç gecikmesi üzerinden yapın. Örneğin aday prompt daha kısa diye token tüketimi düşerken ikinci bir order_lookup turu ekliyorsa toplam gecikme artabilir. Bu nüans, ai destekli yazılım geliştirme derslerinde yalnız token sayısına bakmanın neden yetersiz olduğunu somutlaştırır.

Sık Sorulan Sorular

AI destekli yazılım geliştirmede MCP tool çağrıları nasıl test edilir?

Vitest veya pytest ile model yanıt metnini değil, araç adı, argüman şeması, çağrı sırası ve yasaklı mutasyon araçlarını doğrulayın. Her senaryoyu temperature 0 ile çalıştırın; ayrıca sağlayıcı/model değişikliklerini yakalamak için kayıtlı 50+ gerçekçi vakayı nightly regresyonda yeniden oynatın.

LLM eğitimi projelerinde MCP araç gecikmesi hangi araçla ölçülür?

Araç çağrılarını @opentelemetry/api ile span'layıp Jaeger veya Grafana Tempo'ya gönderin; tool.name ve retry.count ile filtreleyin. Yük altında p95'i görmek için k6 kullanın ve bağlantı yeniden kullanımı gibi bir değişiklikten önce ve sonra aynı VU, süre ve prompt kümesiyle test çalıştırın.

Vibe coding kursu projelerinde yapay zeka aracına deploy yetkisi verilir mi?

Doğrudan yetki vermeyin. Deploy veya para iadesi gibi mutasyonları sunucu tarafında doğrulanan kısa ömürlü approval token ile kapılayın; isteğe idempotency key ekleyin ve bu anahtar için veritabanında benzersiz indeks kullanın. Aynı anahtarla farklı payload gelirse işlemi 409 ile reddedin.

Yapay zeka kursu için generative AI araç şeması neden strict olmalı?

Zod'daki .strict() veya JSON Schema'daki additionalProperties:false, modelin uydurduğu alanları iş mantığına taşımadan reddeder. Özellikle tenantId, role veya isAdmin gibi alanların sessizce kabul edilmesi, sonraki bir kod değişikliğinde yetki genişlemesine dönüşebileceği için giriş reddi testini CI'a ekleyin.