DEV Community

Cover image for AI Ajanları İçin API Test Yetenekleri Sunan MCP Sunucusu Nasıl Kurulur
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

AI Ajanları İçin API Test Yetenekleri Sunan MCP Sunucusu Nasıl Kurulur

#tutorial #ai #api #mcp

Kısaca

Üç araç sunan bir TypeScript MCP sunucusu oluşturun: run_test, validate_schema ve list_environments. Claude Code için ~/.claude/settings.json veya Cursor için .cursor/mcp.json dosyasında yapılandırın. Böylece yapay zeka ajanlarınız sohbet arayüzünden ayrılmadan Apidog testlerini çalıştırabilir, OpenAPI şemalarını doğrulayabilir ve ortamları çekebilir. Tam kaynak kodu yaklaşık 150 satırdır ve @modelcontextprotocol/sdk paketini kullanır.

Apidog'u hemen deneyin

Claude Code, Cursor ve diğer yapay zeka ajanlarının sohbet arayüzlerinden ayrılmadan Apidog API testlerini çalıştırmasına, şemaları doğrulamasını ve yanıtları karşılaştırmasını sağlayan bir MCP sunucusu oluşturun.

💡 Bir kodlama oturumunun ortasındasınız. Yapay zeka ajanınız bir API uç noktasını yeni bitirdi. Kodu kopyalayıp, Apidog'u açıp, bir test koleksiyonu oluşturup doğrulamayı manuel olarak çalıştırmak yerine, tek bir komut yazıp sonuçları geri almak istiyorsunuz.

Model Bağlam Protokolü (MCP) bunu mümkün kılar. MCP, yapay zeka ajanlarının standartlaştırılmış bir arayüz aracılığıyla harici araçlara erişmesini sağlar. Apidog için bir MCP sunucusu oluşturun, böylece yapay zeka ajanınız bağlam değiştirmeden testleri çalıştırabilir, şemaları doğrulayabilir ve ortamları çekebilir.

MCP Nedir?

MCP (Model Context Protocol), yapay zeka ajanlarının harici araçlara ve veri kaynaklarına erişmesi için bir protokoldür. Bunu Claude Code, Cursor ve diğer MCP uyumlu istemcilerde çalışan bir eklenti sistemi olarak düşünebilirsiniz.

Bir MCP sunucusu, araçları (ajanın çağırabileceği fonksiyonlar) ve kaynakları (ajanın okuyabileceği veriler) açığa çıkarır. Apidog MCP sunucunuz, API testi için araçları açığa çıkaracaktır.

┌─────────────────┐         ┌──────────────────┐         ┌─────────────┐
│  Yapay Zeka Ajanı │         │  MCP Sunucusu    │         │  Apidog     │
│  (Claude Code)  │◄───────►│  (Kodunuz)       │◄───────►│  API        │
└─────────────────┘   JSON  └──────────────────┘  HTTP   └─────────────┘
Enter fullscreen mode Exit fullscreen mode

Adım 1: Projeyi Kurma

Yeni bir TypeScript projesi oluşturun:

mkdir apidog-mcp-server
cd apidog-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
Enter fullscreen mode Exit fullscreen mode

tsconfig.json dosyasını oluşturun:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
Enter fullscreen mode Exit fullscreen mode

package.json dosyasına build ve start betikleri ekleyin:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}
Enter fullscreen mode Exit fullscreen mode

Adım 2: MCP Sunucu İskeletini Oluşturma

src/index.ts dosyasını oluşturun:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "apidog",
  version: "1.0.0",
  description: "Apidog API testing tools for AI agents"
});

// Araçlar burada tanımlanacak

const transport = new StdioServerTransport();
await server.connect(transport);
Enter fullscreen mode Exit fullscreen mode

Bu iskelet bir MCP sunucusu oluşturur ve onu standart giriş/çıkış (stdio) aktarımına bağlar. Aktarım, yapay zeka ajanı ile sunucunuz arasındaki iletişimi standart giriş/çıkış aracılığıyla yönetir.

Adım 3: run_test Aracını Tanımlama

src/index.ts dosyasına ilk aracı ekleyin:

// Araç: run_test
server.tool(
  "run_test",
  {
    projectId: z.string().describe("Apidog proje kimliği (proje URL'sinde bulunur)"),
    environmentId: z.string().optional().describe("Test çalıştırma için isteğe bağlı ortam kimliği"),
    testSuiteId: z.string().optional().describe("Belirli bir test paketini çalıştırmak için isteğe bağlı test paketi kimliği")
  },
  async ({ projectId, environmentId, testSuiteId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Hata: APIDOG_API_KEY ortam değişkeni ayarlanmadı"
        }]
      };
    }

    let url = `https://api.apidog.com/v1/projects/${projectId}/tests/run?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation`;
    const params = new URLSearchParams();
    if (environmentId) params.append("environmentId", environmentId);
    if (testSuiteId) params.append("testSuiteId", testSuiteId);
    if (params.toString()) url += `&${params.toString()}`;

    try {
      const response = await fetch(url, {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${apiKey}`,
          "Content-Type": "application/json"
        }
      });

      if (!response.ok) {
        const error = await response.text();
        return {
          content: [{
            type: "text",
            text: `API Hatası: ${response.status} ${error}`
          }]
        };
      }

      const results = await response.json();
      return {
        content: [{
          type: "text",
          text: JSON.stringify(results, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `İstek başarısız oldu: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);
Enter fullscreen mode Exit fullscreen mode

Aracın üç bölümü var:

  1. Ad — run_test (ajanlar araçları ada göre seçer)
  2. Şema — Parametreler için açıklamaları içeren Zod doğrulaması
  3. İşleyici — Apidog API'sini çağıran asenkron fonksiyon

Adım 4: validate_schema Aracını Ekleme

Dağıtımdan önce OpenAPI hatalarını yakalamak için şema doğrulamasını ekleyin:

// Araç: validate_schema
server.tool(
  "validate_schema",
  {
    schema: z.object({}).describe("Doğrulanacak OpenAPI 3.x şema nesnesi"),
    strict: z.boolean().optional().default(false).describe("Ek kontroller için katı modu etkinleştir")
  },
  async ({ schema, strict }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Hata: APIDOG_API_KEY ortam değişkeni ayarlanmadı"
        }]
      };
    }

    try {
      const response = await fetch("https://api.apidog.com/v1/schemas/validate?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation", {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${apiKey}`,
          "Content-Type": "application/json"
        },
        body: JSON.stringify({ schema, strict })
      });

      const result = await response.json();

      if (!response.ok) {
        return {
          content: [{
            type: "text",
            text: `Doğrulama başarısız oldu: ${JSON.stringify(result.errors, null, 2)}`
          }]
        };
      }

      return {
        content: [{
          type: "text",
          text: result.valid
            ? "Şema geçerli OpenAPI 3.x"
            : `Uyarılar: ${JSON.stringify(result.warnings, null, 2)}`
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Doğrulama başarısız oldu: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);
Enter fullscreen mode Exit fullscreen mode

Adım 5: list_environments Aracını Ekleme

Mevcut test ortamlarını getirmek için bir araç ekleyin:

// Araç: list_environments
server.tool(
  "list_environments",
  {
    projectId: z.string().describe("Apidog proje kimliği")
  },
  async ({ projectId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Hata: APIDOG_API_KEY ortam değişkeni ayarlanmadı"
        }]
      };
    }

    try {
      const response = await fetch(
        `https://api.apidog.com/v1/projects/${projectId}/environments?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation`,
        {
          headers: {
            "Authorization": `Bearer ${apiKey}`
          }
        }
      );

      if (!response.ok) {
        const error = await response.text();
        return {
          content: [{
            type: "text",
            text: `API Hatası: ${response.status} ${error}`
          }]
        };
      }

      const environments = await response.json();
      return {
        content: [{
          type: "text",
          text: environments.length === 0
            ? "Bu proje için ortam bulunamadı"
            : environments.map((e: any) =>
                `- ${e.name} (Kimlik: ${e.id})${e.isDefault ? " [varsayılan]" : ""}`
              ).join("\n")
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `İstek başarısız oldu: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);
Enter fullscreen mode Exit fullscreen mode

Adım 6: Derleme ve Test Etme

Sunucuyu derleyin:

npm run build
Enter fullscreen mode Exit fullscreen mode

Basit bir MCP istemcisi ile test edin. test-client.js dosyasını oluşturun:

import { spawn } from "child_process";

const server = spawn("node", ["dist/index.js"], {
  env: { ...process.env, APIDOG_API_KEY: "your-api-key" }
});

server.stdout.on("data", (data) => {
  console.log(`Sunucu çıktısı: ${data}`);
});

server.stderr.on("data", (data) => {
  console.error(`Sunucu hatası: ${data}`);
});

// Bir test mesajı gönder
const message = {
  jsonrpc: "2.0",
  id: 1,
  method: "initialize",
  params: {
    protocolVersion: "2024-11-05",
    capabilities: {},
    clientInfo: { name: "test-client", version: "1.0.0" }
  }
};

server.stdin.write(JSON.stringify(message) + "\n");
Enter fullscreen mode Exit fullscreen mode

Adım 7: Claude Code için Yapılandırma

MCP sunucusunu Claude Code yapılandırmanıza ekleyin:

~/.claude/settings.json dosyasını oluşturun veya düzenleyin:

{
  "mcpServers": {
    "apidog": {
      "command": "node",
      "args": ["/absolute/path/to/apidog-mcp-server/dist/index.js"],
      "env": {
        "APIDOG_API_KEY": "your-api-key-here"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Claude Code'u yeniden başlatın. API testi yardımı istediğinizde Apidog araçları şimdi görünmelidir.

Claude Code'da Kullanım:

Apidog projemde testleri çalıştırmak için run_test aracını kullan.
Proje Kimliği: proj_12345
Ortam: staging
Enter fullscreen mode Exit fullscreen mode 
Bu OpenAPI şemasını Apidog kurallarına göre doğrula:
[şemayı yapıştır]
Enter fullscreen mode Exit fullscreen mode 
proj_12345 projesi için tüm ortamları listele
Enter fullscreen mode Exit fullscreen mode

Adım 8: Cursor için Yapılandırma

Cursor benzer bir MCP yapılandırması kullanır. Projenizin kök dizininde .cursor/mcp.json dosyasını oluşturun:

{
  "mcpServers": {
    "apidog": {
      "command": "node",
      "args": ["/absolute/path/to/apidog-mcp-server/dist/index.js"],
      "env": {
        "APIDOG_API_KEY": "your-api-key-here"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Cursor'da Kullanım:

@apidog run_test projectId="proj_12345" environmentId="staging"
Enter fullscreen mode Exit fullscreen mode

Tam Kaynak Kodu

İşte tam src/index.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "apidog",
  version: "1.0.0",
  description: "Apidog API testing tools for AI agents"
});

// Araç: run_test
server.tool(
  "run_test",
  {
    projectId: z.string().describe("Apidog proje kimliği"),
    environmentId: z.string().optional().describe("Ortam kimliği"),
    testSuiteId: z.string().optional().describe("Test paketi kimliği")
  },
  async ({ projectId, environmentId, testSuiteId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Hata: APIDOG_API_KEY ayarlanmadı"
        }]
      };
    }

    let url = `https://api.apidog.com/v1/projects/${projectId}/tests/run?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation`;
    const params = new URLSearchParams();
    if (environmentId) params.append("environmentId", environmentId);
    if (testSuiteId) params.append("testSuiteId", testSuiteId);
    if (params.toString()) url += `&${params.toString()}`;

    try {
      const response = await fetch(url, {
        method: "POST",
        headers: {
          "Authorization": `Bearer ${apiKey}`,
          "Content-Type": "application/json"
        }
      });

      const results = await response.json();
      return {
        content: [{
          type: "text",
          text: JSON.stringify(results, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `İstek başarısız oldu: ${error instanceof Error ? error.message : String(error)}`
        }]
      };
    }
  }
);

// Araç: validate_schema
server.tool(
  "validate_schema",
  {
    schema: z.object({}).describe("OpenAPI şeması"),
    strict: z.boolean().optional().default(false)
  },
  async ({ schema, strict }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Hata: APIDOG_API_KEY ayarlanmadı"
        }]
      };
    }

    const response = await fetch("https://api.apidog.com/v1/schemas/validate?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify({ schema, strict })
    });

    const result = await response.json();
    return {
      content: [{
        type: "text",
        text: result.valid
          ? "Şema geçerlidir"
          : `Sorunlar: ${JSON.stringify(result.errors || result.warnings, null, 2)}`
      }]
    };
  }
);

// Araç: list_environments
server.tool(
  "list_environments",
  {
    projectId: z.string().describe("Apidog proje kimliği")
  },
  async ({ projectId }) => {
    const apiKey = process.env.APIDOG_API_KEY;
    if (!apiKey) {
      return {
        content: [{
          type: "text",
          text: "Hata: APIDOG_API_KEY ayarlanmadı"
        }]
      };
    }

    const response = await fetch(
      `https://api.apidog.com/v1/projects/${projectId}/environments?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation`,
      {
        headers: { "Authorization": `Bearer ${apiKey}` }
      }
    );

    const environments = await response.json();
    return {
      content: [{
        type: "text",
        text: environments.map((e: any) =>
          `- ${e.name} (${e.id})${e.isDefault ? " [varsayılan]" : ""}`
        ).join("\n")
      }]
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);
Enter fullscreen mode Exit fullscreen mode

Ne İnşa Ettiniz

Bileşen Amaç
MCP Sunucusu Yapay zeka ajanları ile Apidog API arasında köprü kurar
run_test Test koleksiyonlarını programatik olarak yürütür
validate_schema Dağıtımdan önce OpenAPI hatalarını yakalar
list_environments Mevcut test ortamlarını keşfeder
Zod doğrulaması Tip güvenli parametre işleme
Stdio aktarımı Claude Code, Cursor ve herhangi bir MCP istemcisi ile çalışır

Sonraki Adımlar

Sunucuyu genişletin:

  • Ortamlar arası test sonuçlarını karşılaştırmak için compare_responses aracını ekleyin
  • Geçmiş test çalışmalarını getirmek için get_test_history aracını ekleyin
  • Sahte uç noktaları başlatmak/durdurmak için trigger_mock_server aracını ekleyin

Üretim değerlendirmeleri:

  • Hatalı ağ istekleri için yeniden deneme mantığı ekleyin
  • API kısıtlamasını önlemek için hız sınırlaması uygulayın
  • Başarısız araç çağrılarının hata ayıklaması için günlük kaydı ekleyin
  • API anahtarlarını ortam değişkenleri yerine güvenli bir kasada saklayın

Ekibinizle paylaşın:

  • @your-org/apidog-mcp-server olarak npm'e yayınlayın
  • Gerekli ortam değişkenlerini belgeleyin
  • Ortak istemciler için örnek MCP yapılandırmalarını ekleyin

Sık Karşılaşılan Sorun Giderme

Claude Code'da MCP sunucusu yüklenmiyor:

  • ~/.claude/settings.json dosyasındaki yolun mutlak (göreli değil) olduğunu doğrulayın
  • node'un PATH'inizde olup olmadığını kontrol edin: which node
  • Derlenmiş dist/index.js dosyasının mevcut olduğundan emin olun: ls -la dist/
  • Claude Code'un MCP günlüklerinde hatalara bakın

Yapılandırmadan sonra araçlar görünmüyor:

  • Claude Code'u tamamen yeniden başlatın (kapatın ve tekrar açın)
  • TypeScript'in derlendiğinden emin olmak için npm run build komutunu çalıştırın
  • Üç aracın da server.connect() öncesinde tanımlandığından emin olun
  • Sunucunun hatasız başladığını doğrulayın: node dist/index.js

API istekleri 401 hatasıyla başarısız oluyor:

  • Yapılandırmada APIDOG_API_KEY'in ayarlandığını onaylayın
  • Anahtar değerinin etrafında boşluk veya tırnak işaretleri olup olmadığını kontrol edin
  • Apidog hesabınızın API erişiminin etkin olduğunu doğrulayın
  • Anahtarı manuel olarak test edin: curl -H "Authorization: Bearer $APIDOG_API_KEY" https://api.apidog.com/v1/user?utm_source=dev.to&utm_medium=wanda&utm_content=n8n-post-automation

Zod doğrulama hataları:

  • Parametre adlarının şemayla tam olarak eşleştiğinden emin olun
  • Gerekli alanların sağlandığını kontrol edin (projectId'de yazım hatası yok)
  • İsteğe bağlı alanların şemada .optional() kullandığını doğrulayın
  • Tam hata mesajını okuyun — Zod size hangi alanın başarısız olduğunu söyleyecektir

TypeScript derleme hataları:

  • Tüm bağımlılıkların yüklendiğinden emin olmak için npm install komutunu çalıştırın
  • TypeScript sürümünü kontrol edin: npx tsc --version (5.x olmalı)
  • Temizle ve yeniden derle: rm -rf dist && npm run build
  • Getirilen yanıtlarda tür uyuşmazlıkları olup olmadığına bakın (as tür atamaları ekleyin)

MCP Sunucunuzu Yerel Olarak Test Etme

Üretime dağıtmadan önce sunucunuzu yerel olarak test edin:

Stdio ile manuel test:

# Sunucuyu başlat
node dist/index.js

# Başka bir terminalde, bir test mesajı gönder
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js
Enter fullscreen mode Exit fullscreen mode

Beklenen çıktı:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      { "name": "run_test", "description": "...", "inputSchema": {...} },
      { "name": "validate_schema", "description": "...", "inputSchema": {...} },
      { "name": "list_environments", "description": "...", "inputSchema": {...} }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

Bir araç çağrısını test et:

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_environments","arguments":{"projectId":"your-project-id"}}}' | node dist/index.js
Enter fullscreen mode Exit fullscreen mode

Yapay zeka ajanlarınızın artık Apidog'un test yeteneklerine doğrudan erişimi var. Sohbet ile tarayıcı arasında kopyala-yapıştır yok. Manuel test çalıştırmaları yok. Bir komut yazın, sonuçları geri alın.

MCP'nin gücü budur: yapay zeka ajanlarınızı alana özgü araçlarla genişletin ve onların yapmaları gerekeni yapmalarına izin verin — daha hızlı gönderim yapmanıza yardımcı olun.

Temel Çıkarımlar

  • MCP sunucuları yapay zeka ajanlarını harici API'lere bağlar — Bir kez oluşturun, Claude Code, Cursor ve tüm MCP uyumlu istemcilerde kullanın
  • Üç araç çoğu API testi ihtiyacını karşılar — Yürütme için run_test, OpenAPI doğrulaması için validate_schema, keşif için list_environments
  • Zod doğrulaması kötü parametreleri önler — Tip güvenli araç tanımları API çağrılarından önce hataları yakalar
  • Yapılandırma araca özeldir — Claude Code ~/.claude/settings.json kullanır, Cursor .cursor/mcp.json kullanır
  • Üretim hata işlemeyi gerektirir — Dağıtımdan önce yeniden deneme mantığı, hız sınırlaması ve güvenli anahtar depolama ekleyin

SSS

Yapay Zeka'da MCP nedir?

MCP (Model Context Protocol), yapay zeka ajanlarının harici araçlara ve veri kaynaklarına erişmesini sağlayan standartlaştırılmış bir protokoldür. Bunu yapay zeka ajanları için bir eklenti sistemi olarak düşünebilirsiniz.

Apidog için nasıl bir MCP sunucusu oluşturabilirim?

@modelcontextprotocol/sdk'yı yükleyin, Zod doğrulamasıyla araçları tanımlayın, Apidog API'sini çağıran işleyicileri uygulayın ve StdioServerTransport aracılığıyla bağlanın.

Bunu Cursor ile kullanabilir miyim?

Evet. Proje kök dizininizdeki .cursor/mcp.json dosyasına MCP sunucu yapılandırmasını ekleyin. Aynı sunucu Claude Code, Cursor ve diğer MCP istemcileriyle çalışır.

Hangi araçları açığa çıkarmalıyım?

Test koleksiyonlarını yürütmek için run_test, OpenAPI doğrulaması için validate_schema ve mevcut ortamları getirmek için list_environments ile başlayın.

Apidog MCP sunucusu üretime hazır mı?

Eğitim kodu bir başlangıç noktasıdır. Üretimde kullanmadan önce yeniden deneme mantığı, hız sınırlaması, uygun hata işleme ve güvenli API anahtarı depolaması ekleyin.

Bir Apidog API anahtarına ihtiyacım var mı?

Evet. APIDOG_API_KEY'i ortam değişkeni olarak ayarlayın. Sunucu, API isteklerini doğrulamak için bunu çalışma zamanında okur.

Bu MCP sunucusunu ekibimle paylaşabilir miyim?

Evet. Özel bir paket olarak npm'e yayınlayın, gerekli ortam değişkenlerini belgeleyin ve örnek MCP yapılandırmalarını ekleyin.

Top comments (0)