MCP 服务器

agent-native-ops-demo

Enables testing of stateless MCP server patterns including idempotent retries, server-minted handles, and progress reporting, built with NestJS and MCP-Nest.

README

agent-native-ops-demo

Agent-Native Operations yazı serisinin demo reposu — MCP 2026-07-28 spec'ine göre, NestJS + MCP-Nest ile yazılmış stateless bir MCP server.

Donmuş snapshot: Bu repo, serinin yazıları için tarihli bir kanıt ortamıdır; MCP 2026-07-28 revizyonu ve @rekog/mcp-nest@2.0.0 esas alınmıştır. Spec değiştikçe güncel tutulmayacaktır — her yazının changelog'u hangi tag'e dayandığını söyler.

Ne gösteriyor

Tool	Ne kanıtlıyor
`echo_upper`	Saf stateless tool — replica ölçekleme ölçümlerinin yükü
`search_start` / `search_next`	Server-minted handle (Redis, `h1_` prefix, 15 dk TTL) — "state nereye gitti"; expire olan handle `handle_expired` + `recovery` döner
`create_invoice_naive`	Mutlu yolda doğru, retry'da duplicate üreten bilerek-naif tool
`create_invoice`	`idempotency_key` ile bayt-bayt replay — retry baş tacı
`slow_report`	Bilerek yavaş, progress bildiren tool — pod-kill / kopan-stream deneylerinin hedefi

Sunucu dual-era çalışır (protocol: 'dual'): aynı /mcp endpoint'i hem eski protokolü (initialize + session) hem stateless 2026-07-28'i cevaplar. tools/list cevabı SEP-2549 gereği ttlMs: 3600000, cacheScope: "public" taşır (cacheHints ile ayarlı; varsayılan ttlMs: 0, private).

Hızlı başlangıç

Gereksinimler: Node 22+, Redis (lokal :6379 ya da docker compose up -d), REDIS_URL ile değiştirilebilir.

npm install
npm run build
npm start          # :3000/mcp (MCP), :3000/healthz (liveness)

Duman testi (modern era, 2026-07-28)

Her istek kendi kendine yeterlidir: _meta içinde protocolVersion + clientCapabilities taşır, Mcp-Method header'ı zorunludur (eksiğinde sunucu hangi alanın eksik olduğunu söyleyen -32602 döner).

curl -s -X POST localhost:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Mcp-Method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{
    "io.modelcontextprotocol/protocolVersion":"2026-07-28",
    "io.modelcontextprotocol/clientInfo":{"name":"smoke","version":"0.0.1"},
    "io.modelcontextprotocol/clientCapabilities":{}}}}'

İdempotency replay'ini görmek için aynı idempotency_key ile create_invoice'u iki kez çağırın (Mcp-Method: tools/call + Mcp-Name: create_invoice) ve redis-cli get invoice:count ile sayacı izleyin: key'li tool'da sayaç 1'de kalır, create_invoice_naive'de her çağrı sayacı artırır.

Alternatif: MCP Inspector ile http://localhost:3000/mcp'ye bağlanın.

Kanıt katmanı

Her tool çalıştırması benzersiz bir executionId ile hem stdout'a (JSON log) hem Redis exec-log listesine yazılır. Retry'lar protokol seviyesinde yeni request-id taşıdığı için (SSE resumability kaldırıldı), duplicate sayımı protokole değil bu kayıtlara yaslanır.

Yol haritası (serinin ölçüm parçaları)

[x] Parça 1 — NestJS + MCP-Nest iskeleti: 5 tool, Redis handle store, idempotency, execution log
[x] Parça 2 — k8s/kind manifest'leri: 1↔3 replica, NodePort Service, terminationGracePeriodSeconds, chaos endpoint'i
[x] Parça 3 — k6 senaryoları + koşulmuş deneyler (aşağıda)
[ ] Parça 4 — cache katmanı deneyi: ttlMs + paylaşımlı cache, origin-hit sayımı
[ ] Parça 5 — OTel GenAI facade + trace waterfall (serinin OTEL-GENAI yazısı)

Deneyler (Parça 2-3)

Ortam: lokal kind cluster'ı (tek node, Docker Desktop, Apple Silicon); k6 aynı makinede. Kurulum:

docker build -t agent-native-ops-demo:0.1.0 .
kind create cluster --config kind-config.yaml
kind load docker-image agent-native-ops-demo:0.1.0 --name anops
kubectl apply -f k8s/

Sabit yük (1 vs 3 replica, echo_upper): k6 run -e RATE=100 -e DURATION=60s k6/steady-load.js

Yük	1 replica p95 / p99	3 replica p95 / p99
100 rps · 60 sn	6.7 ms / 21.1 ms	7.4 ms / 30.8 ms
600 rps · 45 sn	14.2 ms / 51.6 ms	16.2 ms / 52.4 ms

Bu iş yükünde yatay ölçeklemenin latency getirisi yok — kazanç kapasite değil, dayanıklılık (aşağıda).

Pod-kill duplicate deneyi: 30 rps fatura niyeti, 90 sn, delay_ms=500 (commit-sonrası cevap penceresi); koşu sırasında 8 kez POST /chaos/crash ile rastgele pod'lar düşürüldü. Client, 2026-07-28'in zorunlu kıldığı gibi kopan isteği yeni request-id ile tekrar gönderiyor (k6/pod-kill.js).

Koşu	Niyet	Retry	Duplicate fatura	Oran
`create_invoice_naive`	2 700	132	37	%1.37
`create_invoice` (idempotency_key)	2 108	1 121	1	%0.05

Sekiz crash'e rağmen kaybolan niyet: naifte 0/2700, key'lide 1/2108 — servis 3 replica ile ayakta kaldı. Key'li koşudaki tek duplicate, crash'in iş commit'i ile idempotency kaydının arasına denk geldiği vaka: read-then-write idempotency atomik değildir; gerçek exactly-once için ikisini tek transaction'a koyun (serinin tool-contract yazısının konusu). Analiz: kubectl exec deploy/redis -- redis-cli lrange exec-log 0 -1 | python3 scripts/analyze-duplicates.py <run-prefix>; ham k6 çıktıları results/ altında.