MCP (Model Context Protocol) ile Yapay Zeka Ajanı Geliştirme Rehberi

Hızla gelişen yapay zeka dünyasında, Büyük Dil Modelleri (LLM'ler); muhakeme yapma, kod yazma ve karmaşık problemleri çözme konusunda kendilerini kanıtladılar. Ancak, yerel dosyalara, veritabanlarına, API'lere ve geliştirici araçlarına güvenli bir şekilde erişmek için standartlaştırılmış bir protokole sahip değillerdi.

Bu kopukluğu gidermek için Anthropic, Model Context Protocol (MCP) standardını duyurdu. Bu açık kaynaklı protokol, yapay zeka modellerinin dış veri kaynakları ve araçlarla (tools) güvenli ve yapılandırılmış bir şekilde iletişim kurmasını sağlar.

Yapay zeka entegrasyonu ve otomasyon süreçlerinde aktif çalışan bir Senior Full Stack Architect olarak, çeşitli otomasyon süreçlerinde MCP sunucularını yaygın olarak kullanmaktayım. Bu makalede, kendi ilk MCP sunucunuzu sıfırdan TypeScript ile nasıl kuracağınızı adım adım anlatacağım.

---

1. MCP Mimarisi Nasıl Çalışır?

MCP, yapay zeka ana uygulaması (Host) ile veri/araç kaynağı arasında bir istemci-sunucu (Client-Server) ilişkisi kurar:

• Host (Ev Sahibi - örn. Claude Desktop, Cursor veya Özel AI Ajanı): LLM'in çalıştığı ve hangi araçları tetikleyeceğine karar verdiği ana uygulama.
• Client (İstemci): Host içinde çalışan ve sunucuya bağlantıyı (genellikle standart girdi/çıktı - stdio veya SSE aracılığıyla) başlatan katman.
• Server (Sunucu): Yerel makinede veya bulutta çalışan, kaynakları, araçları ve hazır şablonları (prompts) istemciye sunan hafif bir uygulama.

graph LR
    Host[AI Host / Masaüstü İstemcisi] <--> Client[MCP İstemcisi]
    Client <-->|Stdio/SSE Protokolü| Server[MCP Sunucusu]
    Server <--> Filesystem[(Yerel Dosyalar)]
    Server <--> Database[(Veritabanları)]
    Server <--> APIs[Harici API'ler]

---

2. Temel Kavramlar: Kaynaklar, Araçlar ve Şablonlar

Bir MCP sunucusu geliştirirken yapay zeka modellerine üç temel yetenek sunarsınız:

1. Resources (Kaynaklar): Yapay zekanın referans alabileceği salt okunur veri kaynakları (veritabanı tabloları, sistem logları veya dosya içerikleri).
2. Tools (Araçlar): Yapay zekanın tetikleyebileceği çalıştırılabilir fonksiyonlar (dosya yazma, veritabanı sorgusu yapma veya API isteği atma). Araçlar genellikle kullanıcı onayı gerektirir.
3. Prompts (Şablonlar): Yapay zekanın rolünü, davranışını veya girdi formatını yönlendiren önceden yapılandırılmış prompt şablonları.

---

3. TypeScript ile Adım Adım MCP Sunucusu Yapımı

Geliştireceğimiz örnek sunucuda, yapay zeka ajanının yerel bilgisayarınızın CPU ve bellek durumunu sorgulayabileceği dinamik bir araç oluşturacağız.

Adım 1: Projeyi Başlatma

Yeni bir dizin oluşturup gerekli bağımlılıkları yükleyelim:

mkdir my-mcp-server
cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript @types/node tsx
npx tsc --init

Adım 2: Sunucu Kodunu Yazma

Bir index.ts dosyası oluşturup aşağıdaki kodları ekleyin:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";
import os from "os";

// Sunucuyu Tanımla
const server = new Server(
  {
    name: "system-monitor-mcp",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// Kullanılabilir Araçları Kaydet
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "get_system_metrics",
        description: "Bilgisayarın gerçek zamanlı CPU, RAM kullanımı ve çalışma süresi (uptime) bilgilerini döndürür.",
        inputSchema: {
          type: "object",
          properties: {},
        },
      },
    ],
  };
});

// Araç Çalıştırıldığında Tetiklenecek Mantık
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name } = request.params;

  if (name === "get_system_metrics") {
    const freeMem = os.freemem();
    const totalMem = os.totalmem();
    const usagePercent = ((totalMem - freeMem) / totalMem) * 100;

    const metrics = {
      platform: os.platform(),
      arch: os.arch(),
      uptimeSeconds: os.uptime(),
      cpuCount: os.cpus().length,
      memoryUsagePercentage: usagePercent.toFixed(2) + "%",
      freeMemoryGB: (freeMem / 1024 / 1024 / 1024).toFixed(2) + " GB",
    };

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(metrics, null, 2),
        },
      ],
    };
  }

  throw new Error(`Tool ${name} bulunamadı.`);
});

// Sunucuyu stdio ile Başlat
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("System Monitor MCP Sunucusu stdio üzerinde çalışıyor");
}

main().catch((err) => {
  console.error("Kritik hata:", err);
  process.exit(1);
});

---

4. MCP Sunucusunu Claude Desktop'a Bağlama

Yazdığınız bu sunucuyu Claude Desktop üzerinde test etmek için Claude yapılandırma dosyasını düzenlemeniz gerekir.

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Aşağıdaki yapılandırmayı ekleyin:

{
  "mcpServers": {
    "system-monitor": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "C:/dosya-yolunuz/my-mcp-server/index.ts"
      ]
    }
  }
}

Claude Desktop uygulamasını yeniden başlattığınızda, sağ altta bir çekiç simgesi göreceksiniz. Bu, yapay zekanın yerel aracınıza başarıyla eriştiğini gösterir.

---

5. Güvenlik ve Üretim (Production) Tavsiyeleri

MCP sunucularını uzak sunucularda veya ekipler genelinde yayına alırken dikkat edilmesi gerekenler:

• Strict Sandboxing (Sıkı Yalıtım): Yapay zekaya komut satırı yetkisi verirken komutları mutlaka filtreleyin ve doğrudan çalıştırılmasına izin vermeyin.
• Güvenli Kimlik Doğrulama: Bulut sunuculardaki MCP entegrasyonlarında stdio yerine Server-Sent Events (SSE) kullanarak araya OAuth2 veya API anahtarları gibi güvenlik katmanları ekleyin.
• Minimum Yetki İlkesi: MCP sunucusunun çalıştığı yerel işletim sistemi kullanıcısının yetkilerini olabildiğince kısıtlayın.

---

Sonuç

Model Context Protocol (MCP), statik LLM mantığı ile aktif sistem yürütme süreçleri arasındaki köprüdür. Araçları standart şemalarla tanımlayarak, yapay zeka modellerini tam teşekküllü asistanlara dönüştürebiliriz.

Geliştirici Ömer Özbay'ın portföy vitrini olan gucluyumhe.dev adresinde de uyguladığı üzere; MCP yapılarından faydalanmak, güvenli ve esnek bir yerel otomasyon döngüsü kurmanızı sağlayarak yazılım geliştirme üretkenliğinizi üst seviyeye taşır.