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

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.

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.

düğme

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   └─────────────┘

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

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"]
}

package.json dosyasına bir derleme betiği ekleyin:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

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);

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

İlk aracı src/index.ts dosyasına ekleyin:

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 (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ı"
        }]
      };
    }

    // API URL'sini oluştur
    let url = `https://api.apidog.com/v1/projects/${projectId}/tests/run`;
    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)}`
        }]
      };
    }
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Araç tanımı üç bölümden oluşur:

Ad — run_test (ajanlar araçları ada göre seçer, bu yüzden açıklayıcı yapın)
Şema — Parametreler için açıklamaları içeren Zod doğrulaması
İş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", {
        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)}`
        }]
      };
    }
  }
);

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`,
        {
          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)}`
        }]
      };
    }
  }
);

Adım 6: Derleme ve Test Etme

Sunucuyu derleyin:

npm run build

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");

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"
      }
    }
  }
}

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

Bu OpenAPI şemasını Apidog kurallarına göre doğrula:
[şemayı yapıştır]

proj_12345 projesi için tüm ortamları listele

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"
      }
    }
  }
}

Cursor'da Kullanım:

@apidog run_test projectId="proj_12345" environmentId="staging"

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`;
    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", {
      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`,
      {
        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);

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

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

Beklenen çıktı:

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

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

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

düğme

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.