AI modellerini harici araçlara ve veri kaynaklarına bağlayan özel bir Model Context Protocol (MCP) sunucusu oluşturmak için IBM Bob'u nasıl kullanacağını öğren. Bu uygulamalı tutorial; gelişmiş mod, onay iş akışı ve MCP yapılandırmasını kapsar.

Bu tutorial'da, bilimsel makaleler için açık erişimli bir içerik deposu olan arXiv'e salt okunur erişim sağlayan özel bir MCP sunucusu oluşturmak için IBM Bob'u kullanıyorsun. İsteğe bağlı olarak, sunucuyu bir watsonx Orchestrate AI ajanıyla entegre edecek şekilde genişletebilirsin.

Model Context Protocol (MCP), büyük dil modellerinin (LLM) birleşik bir istemci-sunucu mimarisi aracılığıyla harici araçlar, veri kaynakları ve içerik depolarıyla iletişim kurmasını sağlayan açık bir standarttır. MCP'den önce, her AI asistanının her harici araç için kendi özel entegrasyonuna ihtiyacı vardı; birlikte çalışabilirlik olmadan function calling kullanıyordu. Bunun yerine MCP, herhangi bir MCP host'unun herhangi bir MCP sunucusuna bağlanmak için kullanabileceği tek bir JSON-RPC 2.0 protokolü tanımlar.

Ön koşullar

Bu tutorial, arXiv API'sini sorgulayan bir TypeScript MCP sunucusu oluşturur. Önceden TypeScript veya MCP entegrasyonu deneyimi gerektirmez.

Bu tutorial'ı tamamlamak için aşağıdakilere ihtiyacın var:

IBM Bob IDE

IBM Bob uygulamasını bilgisayarına indirip kur. Bob, bir uzantı değil bağımsız bir IDE uygulamasıdır.

Node.js

TypeScript MCP sunucusunu yerel olarak oluşturmak ve çalıştırmak için Node.js 22 veya sonrasını kur.

Çalışma alanını ayarlama

IBM Bob'u başlat, MCP ayarlar panelini aç ve sunucu projesi için bir çalışma dizini hazırla.

IBM Bob'u başlatma

Bilgisayarındaki IBM Bob uygulamasını başlat.

Bob sohbet panelini açma

Sohbet paneli henüz açık değilse, navigasyon çubuğunun yanındaki Bob simgesine tıkla veya Option + Command + B (Mac) ya da Ctrl + Alt + B (Windows) kısayolunu kullan.

MCP ayarlar panelini açma

Sohbet penceresinin sağ üst köşesindeki dişli simgesine tıkla, ardından sol kenar çubuğundan MCP'yi seç.

MCP ayarlar paneli; sunucuları etkinleştirip devre dışı bırakarak, belirli araçları otomatik onaylayarak, ve MCP SDK ile özel entegrasyonlar oluşturarak erişim kontrolünü yönetmeni sağlar.

Global: mcp_settings.json dosyasında saklanır, tüm çalışma alanlarında uygulanır.
Proje: Proje kökündeki .bob/mcp.json dosyasında saklanır, sürüm kontrolü aracılığıyla ekibinle paylaşılabilir. Proje düzeyindeki ayarlar global olanları geçersiz kılar.

Otomatik onayı yapılandırma

Bob sohbetinde, sohbet giriş alanının hemen altındaki otomatik onay izinlerinin yalnızca "Read" olarak ayarlandığından emin ol. Bu yapılandırma, Bob'un dosyalarını ve dizin içeriğini görüntülemesine izin verirken her komutu çalıştırmadan önce inceleme ve onay istemesini sağlar.

Proje dizinini açma

Proje için tercih ettiğin bir dizin varsa, IDE'de aç. Ayrıca Bob'dan sohbet penceresinde bunu yapmasını isteyebilirsin.

Python sanal ortamını kurma

Farklı projelerin birbirleriyle çakışmaması için bir projenin bağımlılıklarını izole etmek amacıyla sanal Python ortamları oluşturmak yaygın bir uygulamadır. Bob'u terminal komutlarını okuyabilen, yazabilen ve çalıştırabilen Agent moduna geçir, ardından ortamı oluştur.

Sanal ortamı oluşturma ve etkinleştirme

Bob sohbet panelinde aşağıdaki prompt'u gir:

In this directory, activate a Python virtual environment.

Bob bir dizi terminal komutu çalıştırır. Her istendiğinde onayla. Komutlar venv/ dizininde yeni bir sanal ortam oluşturur ve etkinleştirir.

MCP sunucu derleme planını oluşturma

Plan moduna geçme

Etkileşim modunu Plan olarak değiştirmek için sohbet giriş alanının hemen altındaki düğmeye tıkla. Bu mod, Bob'un herhangi bir kod yazmadan önce MCP sunucusu için yapılandırılmış bir plan oluşturmasına olanak tanır.

Sunucu gereksinimlerini gönderme

Sanal ortam etkin durumdayken, aşağıdaki prompt'u Bob'a gönder. Önceden özel gereksinimler sağlamak, Bob'a herhangi bir kod yazmadan önce eksiksiz bir plan formüle etmesi için yeterli bağlam verir:

Create an MCP server named arxiv-server that provides read-only access to arXiv. The server should:
- Expose one tool, search_papers, for querying arXiv papers by keyword
- Accept a query string and an optional max_results parameter (default 5, max 20)
- Limit results to paper metadata and abstracts (no PDFs)
- Return title, authors, publication date, abstract, and arXiv URL for each result
- Normalize responses into a clean, structured JSON schema
- Handle API errors and empty results gracefully, returning a clear message instead of failing
- Use TypeScript/Node.js with the stdio transport
- Use the arXiv API v2, which requires no authentication

Bob; proje iskeleti oluşturma, MCP sunucusu implementasyonu, bağımlılık kurulumu, sunucu yapılandırması ve testleri kapsayan yapılandırılmış bir yapılacaklar listesi üretir. Bob'un hata işleme ve kimlik doğrulama değerlendirmelerini otomatik olarak planladığına dikkat et. Hedef API (arXiv) bir anahtar gerektirmese bile, Bob anahtarların gerektiren sunucular için nereye ekleneceğini belirtir.

Bob açıklayıcı sorular sorarsa, elinden geldiğince yanıtla veya Bob'dan makul varsayımlar yapmasını iste.

MCP sunucusunu oluşturma ve inceleme

Planı inceleyip onayladıktan sonra, her adımı yürütmek için Agent moduna geç. Bob yanıtları gerçek zamanlı olarak oluşturduğundan, çıktın ve sıran aşağıdaki örnekten biraz farklı olabilir.

Bob'a aşağıdaki prompt'la sunucu oluşturmaya başlamasını söyle:

Implement the plan.

Bob önce proje yapısını iskelet haline getirir ve proje dizinini oluşturmak için mkdir -p arxiv-server/src komutunu çalıştırır.

Ardından Bob, projenin meta verilerini, scriptlerini ve bağımlılıklarını bildiren Node.js yapılandırma merkezi olan arxiv-server/package.json dosyasını oluşturur:

{
  "name": "arxiv-server",
  "version": "0.1.0",
  "description": "MCP server for read-only access to arXiv papers",
  "type": "module",
  "bin": {
    "arxiv-server": "./build/index.js"
  },
  "scripts": {
    "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
    "prepare": "npm run build",
    "watch": "tsc --watch"
  },
  "keywords": ["mcp", "arxiv", "research", "papers"],
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.0.4",
    "axios": "^1.7.9",
    "zod": "^3.24.1"
  },
  "devDependencies": {
    "@types/node": "^22.10.5",
    "typescript": "^5.7.3"
  }
}

Bob ayrıca TypeScript derleyicisini yapılandırmak için arxiv-server/tsconfig.json dosyasını oluşturur:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "build"]
}

Ardından Bob, arxiv-server/src/index.ts konumunda ana sunucu dosyasını oluşturur. Bu dosya, search_arxiv aracını MCP SDK ile kaydeder, arXiv'in API yanıtları için XML-JSON ayrıştırmasını uygular, sonuç sınırlarını zorlar ve sunucuyu STDIO transport üzerinde başlatır; STDIO, MCP host ile aynı makinede çalışan sunucular için uygun yerel, düşük gecikmeli transport türüdür.

MCP SDK'nın server.tool() çağrısı birincil entegrasyon noktasıdır. Aracı herhangi bir MCP istemcisine sunar.

#!/usr/bin/env node
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import axios from 'axios';

interface ArxivEntry {
  id: string;
  title: string;
  summary: string;
  authors: Array<{ name: string }>;
  published: string;
  updated: string;
  categories: string[];
  primary_category: string;
  links: Array<{ href: string; rel: string; type?: string }>;
}

interface ArxivSearchResult {
  entries: ArxivEntry[];
  totalResults: number;
  startIndex: number;
  itemsPerPage: number;
}

const server = new McpServer({ name: "arxiv-server", version: "0.1.0" });

const arxivApi = axios.create({
  baseURL: 'http://export.arxiv.org/api',
  timeout: 30000,
});

server.tool(
  "search_arxiv",
  {
    query: z.string().describe("Search query (supports arXiv query syntax)"),
    max_results: z.number().min(1).max(50).optional()
      .describe("Maximum results to return (1–50, default: 10)"),
    start: z.number().min(0).optional()
      .describe("Starting index for pagination (default: 0)"),
    sort_by: z.enum(["relevance", "lastUpdatedDate", "submittedDate"]).optional(),
    sort_order: z.enum(["ascending", "descending"]).optional()
  },
  async ({ query, max_results = 10, start = 0, sort_by = "relevance", sort_order = "descending" }) => {
    try {
      const params: Record<string, string | number> = {
        search_query: query,
        start: Math.max(start, 0),
        max_results: Math.min(max_results, 50),
        ...(sort_by && { sortBy: sort_by }),
        ...(sort_order && { sortOrder: sort_order }),
      };
      const response = await arxivApi.get('/query', { params });
      return {
        content: [{ type: "text", text: formatSearchResults(parseArxivXML(response.data)) }],
      };
    } catch (error) {
      if (axios.isAxiosError(error)) {
        return {
          content: [{ type: "text", text: `arXiv API error: ${error.response?.data?.message ?? error.message}` }],
          isError: true,
        };
      }
      throw error;
    }
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);
console.error('arXiv MCP server running on stdio');

Catch bloğundaki isError: true bayrağı, MCP'nin standart hata işleme desenidir. MCP istemcisine, sunucu sürecini çökertmeden araç çağrısının başarısız olduğunu bildirir.

Sonraki adım olarak Bob, cd arxiv-server && npm install komutunu çalıştırarak arxiv-server dizinindeki bağımlılıkları yükler.

Sunucuyu proje kapsamında kaydetme

Bob yeni bir sunucuyu otomatik olarak kaydetmez. Bob'a açıkça eklemesini söyle ve yapılandırmanın .bob/mcp.json içinde yer alması ve sürüm kontrolü aracılığıyla ekibinle paylaşılabilmesi için proje kapsamını belirt.

Bob'a sunucuyu kaydetmesini söyleme

Bob sohbet panelinde aşağıdaki prompt'u gir:

Register the arxiv-server as an MCP server at project scope. Build it first if needed, then add it to .bob/mcp.json.

Oluşturulan yapılandırmayı inceleme

Bob, proje kökündeki .bob/mcp.json dosyasına aşağıdakileri yazar. command ve args alanları, MCP istemcisine STDIO transport kullanarak sunucu sürecini nasıl başlatacağını söyler.

{
  "mcpServers": {
    "arxiv-server": {
      "command": "node",
      "args": ["${workspaceFolder}/arxiv-server/build/index.js"]
    }
  }
}

Sunucunun yüklendiğini onaylama

Bob bu dosyayı yazdıktan sonra MCP yapılandırmasını otomatik olarak yeniden yükler. Devam etmeden önce arxiv-server sunucusunun listelendiğini ve etkin olduğunu onaylamak için MCP ayarlar panelini aç (dişli simgesi > MCP). Görünmezse, sunucu listesinin yanındaki yenile simgesine tıkla.

Bob'u yeniden başlatma

Sunucunun çalıştığından ve sorguları kabul etmeye hazır olduğundan emin olmak için Bob'u yeniden başlat.

MCP sunucusunu test etme

Sunucu kaydedildikten sonra Bob, search_arxiv aracına karşı otomatik olarak iki doğrulama sorgusu çalıştırır.

İlk test, ilgi düzeyine göre sıralanmış üç kuantum bilişim makalesi için sorgu yapar. İkincisi, azalan gönderim tarihine göre sıralanmış iki makine öğrenmesi makalesi için sorgu yapar. Her ikisi de başarıyla çalışır; bu, aracın erişilebilir olduğunu ve sunucunun hata işlemesinin farklı parametre kombinasyonlarını doğru şekilde yönettiğini doğrular.

Şimdi Bob'un doğal dilden doğru parametreleri çıkardığını doğrulamak için kendi sorgularını çalıştır. Bob sohbet paneline yapıştırılacak bir prompt örneği:

What are the latest papers on LLM agent tracing?

Sunucuyu belgeleme

Açık kaynak MCP sunucu implementasyonları genellikle başkalarının hızlıca başlayabilmesi için belgeler içerir. Bob'dan oluşturmasını iste:

In this directory, create a README.md file to document this MCP server.
Include setup and usage instructions.

Bob; kurulum, birden fazla MCP host için yapılandırma (IBM Bob, Claude Desktop, Cursor, Claude Code), API anahtarı gerektiren sunucular için kimlik doğrulama kılavuzu, yerel dosya erişim desenleri ve sorun giderme ipuçlarını kapsayan kapsamlı bir README.md üretir.

Kaynakları temizleme

Bu tutorial yerel dosyalar ve bir sunucu kaydı oluşturur. arXiv MCP sunucusunu kullanmaya devam etmeyeceksen bunları kaldır.

Bob'da MCP ayarlar panelini aç (dişli simgesi > MCP) ve arxiv-server girdisini devre dışı bırak veya sil. Alternatif olarak, arxiv-server bloğunu doğrudan mcp_settings.json (global kapsam) veya .bob/mcp.json (proje kapsamı) dosyasından kaldır.

Sonraki adımlar

Bu tutorial'da, bir TypeScript MCP sunucusu oluşturmak, STDIO transport ile yapılandırmak ve canlı arXiv sorguları ile test etmek için IBM Bob'u kullandın; bunların hepsini doğal dil prompt'ları aracılığıyla yaptın.

Aynı iş akışı daha karmaşık MCP sunucu implementasyonları için de geçerlidir: veritabanlarına, yerel dosyalara veya diğer harici veri kaynaklarına bağlanan sunucular. Kimlik doğrulama gerektiren sunucuların, MCP yapılandırma JSON'undaki ortam değişkenleri olarak enjekte edilmiş kimlik bilgilerine ihtiyacı vardır. Uzak dağıtımlar için STDIO transport'unu SSE ile değiştir.

Sunucu kodunu commit etmeden önce sorunları yakalamak için Bob'un Code review özelliği hakkında bilgi edin.

Advanced, Code, Ask ve diğer Bob personalarını ne zaman kullanacağını anlamak için modlar hakkında bilgi edin.

Global ve proje kapsamı, otomatik onaylanan araçlar ve SSE transport kurulumu hakkında ayrıntılar için MCP yapılandırmasını keşfet.

Öğrenmeye devam etmek için Get started with IBM Bob tutorial serisi üzerinde çalış.

IBM Bob ile MCP sunucuları oluşturma