Dowiedz się, jak używać IBM Bob do tworzenia niestandardowego serwera Model Context Protocol (MCP), który łączy modele AI z zewnętrznymi narzędziami i źródłami danych. Tutorial obejmuje tryb zaawansowany, przepływ zatwierdzeń i konfigurację MCP.

W tym tutorialu używasz IBM Bob do zbudowania niestandardowego serwera MCP zapewniającego dostęp tylko do odczytu do arXiv — otwartego repozytorium treści z pracami naukowymi. Opcjonalnie możesz rozbudować serwer o integrację z agentem AI watsonx Orchestrate.

Model Context Protocol (MCP) to otwarty standard umożliwiający dużym modelom językowym (LLM) komunikację z zewnętrznymi narzędziami, źródłami danych i repozytoriami treści poprzez ujednoliconą architekturę klient-serwer. Przed MCP każdy asystent AI potrzebował własnej, dedykowanej integracji z każdym zewnętrznym narzędziem, korzystając z function calling bez możliwości współdziałania. MCP definiuje jeden protokół JSON-RPC 2.0, z którego każdy host MCP może korzystać do łączenia się z dowolnym serwerem MCP.

Wymagania wstępne

Ten tutorial buduje serwer MCP w TypeScript, który odpytuje API arXiv. Nie wymaga wcześniejszego doświadczenia z TypeScript ani integracją MCP.

Do ukończenia tego tutorialu potrzebujesz:

IBM Bob IDE

Pobierz i zainstaluj aplikację IBM Bob na swoim komputerze. Bob to samodzielna aplikacja IDE, nie rozszerzenie.

Node.js

Zainstaluj Node.js 22 lub nowszy, aby zbudować i uruchomić serwer MCP w TypeScript lokalnie.

Konfiguracja przestrzeni roboczej

Uruchom IBM Bob, otwórz panel ustawień MCP i przygotuj katalog roboczy dla projektu serwera.

Uruchom IBM Bob

Uruchom aplikację IBM Bob na swoim komputerze.

Otwórz panel czatu Bob

Jeśli panel czatu nie jest jeszcze otwarty, kliknij ikonę Bob obok paska nawigacji lub użyj skrótu Option + Command + B (Mac) lub Ctrl + Alt + B (Windows).

Otwórz panel ustawień MCP

Kliknij ikonę zębatki w prawym górnym rogu okna czatu, a następnie wybierz MCP z lewego paska bocznego.

Panel ustawień MCP pozwala zarządzać kontrolą dostępu poprzez włączanie lub wyłączanie serwerów, automatyczne zatwierdzanie określonych narzędzi, oraz tworzenie niestandardowych integracji za pomocą SDK MCP.

Globalny: Przechowywany w mcp_settings.json, stosowany we wszystkich przestrzeniach roboczych.
Projektu: Przechowywany w .bob/mcp.json w katalogu głównym projektu, możliwy do udostępnienia zespołowi przez system kontroli wersji. Ustawienia na poziomie projektu mają pierwszeństwo przed globalnymi.

Skonfiguruj automatyczne zatwierdzanie

W czacie Bob upewnij się, że uprawnienia automatycznego zatwierdzania tuż poniżej pola wprowadzania czatu są ustawione tylko na „Read". Ta konfiguracja pozwala Bobowi przeglądać twoje pliki i zawartość katalogów, jednocześnie prosząc o przegląd i zatwierdzenie przed każdym uruchomionym poleceniem.

Otwórz katalog projektu

Jeśli masz preferowany katalog dla projektu, otwórz go w IDE. Możesz też poprosić Boba o to w oknie czatu.

Konfiguracja wirtualnego środowiska Python

Powszechną praktyką jest tworzenie wirtualnych środowisk Python w celu izolowania zależności projektu, aby różne projekty nie kolidowały ze sobą. Przełącz Boba do trybu Agent — trybu, który może czytać, pisać i uruchamiać polecenia terminala — a następnie utwórz środowisko.

Utwórz i aktywuj wirtualne środowisko

W panelu czatu Bob wprowadź następujący prompt:

In this directory, activate a Python virtual environment.

Bob uruchamia serię poleceń terminala. Zatwierdzaj każde z nich po wyświetleniu monitu. Polecenia tworzą nowe wirtualne środowisko w katalogu venv/ i je aktywują.

Generowanie planu budowy serwera MCP

Przełącz na tryb Plan

Kliknij przycisk tuż poniżej pola wprowadzania czatu, aby zmienić tryb interakcji na Plan. Ten tryb pozwala Bobowi wygenerować ustrukturyzowany plan dla serwera MCP przed napisaniem jakiegokolwiek kodu.

Prześlij wymagania serwera

Przy aktywnym wirtualnym środowisku prześlij Bobowi następujący prompt. Podanie szczegółowych wymagań z góry daje Bobowi wystarczający kontekst do sformułowania kompletnego planu przed napisaniem jakiegokolwiek kodu:

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 tworzy ustrukturyzowaną listę zadań obejmującą szkieletowanie projektu, implementację serwera MCP, instalację zależności, konfigurację serwera i testowanie. Zauważ, że Bob automatycznie planuje obsługę błędów i kwestie uwierzytelniania. Nawet gdy docelowe API (arXiv) nie wymaga klucza, Bob zaznacza, gdzie należałoby wstrzyknąć dane uwierzytelniające dla serwerów, które tego wymagają.

Jeśli Bob zadaje pytania wyjaśniające, odpowiadaj na nie w miarę możliwości lub poproś Boba, aby przyjął rozsądne założenia.

Budowanie i przeglądanie serwera MCP

Po przejrzeniu i zatwierdzeniu planu przełącz się na tryb Agent, aby wykonać każdy krok. Twój wynik i kolejność mogą się nieznacznie różnić od poniższego przykładu, ponieważ Bob generuje odpowiedzi w czasie rzeczywistym.

Powiedz Bobowi, aby rozpoczął budowanie serwera za pomocą następującego promptu:

Implement the plan.

Najpierw Bob szkieletuje strukturę projektu i uruchamia mkdir -p arxiv-server/src, aby utworzyć katalog projektu.

Następnie Bob generuje arxiv-server/package.json — centrum konfiguracji Node.js deklarujące metadane, skrypty i zależności projektu:

{
  "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 tworzy również arxiv-server/tsconfig.json w celu konfiguracji kompilatora TypeScript:

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

Następnie Bob tworzy główny plik serwera w arxiv-server/src/index.ts. Plik ten rejestruje narzędzie search_arxiv za pomocą SDK MCP, implementuje parsowanie XML-do-JSON dla odpowiedzi API arXiv, egzekwuje limity wyników i uruchamia serwer na transporcie STDIO — lokalnym, niskoopóźnieniowym typie transportu odpowiednim dla serwerów działających na tej samej maszynie co host MCP.

Wywołanie server.tool() z SDK MCP to główny punkt integracji. Udostępnia narzędzie każdemu klientowi MCP.

#!/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');

Flaga isError: true w bloku catch to standardowy wzorzec obsługi błędów MCP. Sygnalizuje klientowi MCP, że wywołanie narzędzia zakończyło się niepowodzeniem bez zatrzymywania procesu serwera.

Następnie Bob instaluje zależności w katalogu arxiv-server, uruchamiając cd arxiv-server && npm install.

Rejestracja serwera na poziomie projektu

Bob nie rejestruje nowego serwera automatycznie. Powiedz Bobowi, aby dodał go jawnie, i określ zakres projektu, aby konfiguracja była przechowywana w .bob/mcp.json i mogła być udostępniona zespołowi przez system kontroli wersji.

Poproś Boba o zarejestrowanie serwera

W panelu czatu Bob wprowadź następujący prompt:

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

Przejrzyj wygenerowaną konfigurację

Bob zapisuje następujące dane do .bob/mcp.json w katalogu głównym projektu. Pola command i args informują klienta MCP, jak uruchomić proces serwera przy użyciu transportu STDIO.

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

Potwierdź załadowanie serwera

Bob automatycznie przeładowuje konfigurację MCP po zapisaniu tego pliku. Otwórz panel ustawień MCP (ikona zębatki > MCP), aby potwierdzić, że serwer arxiv-server jest wymieniony i włączony, zanim przejdziesz dalej. Jeśli nie pojawi się, kliknij ikonę przeładowania obok listy serwerów.

Uruchom ponownie Boba

Uruchom ponownie Boba, aby upewnić się, że serwer działa i jest gotowy do przyjmowania zapytań.

Testowanie serwera MCP

Po zarejestrowaniu serwera Bob automatycznie uruchamia dwa zapytania walidacyjne na narzędziu search_arxiv.

Pierwsze zapytanie dotyczy trzech prac z zakresu obliczeń kwantowych posortowanych według trafności. Drugie dotyczy dwóch prac z uczenia maszynowego posortowanych malejąco według daty zgłoszenia. Oba wykonują się pomyślnie, potwierdzając, że narzędzie jest dostępne i że obsługa błędów serwera poprawnie zarządza różnymi kombinacjami parametrów.

Teraz uruchom własne zapytania, aby sprawdzić, czy Bob poprawnie wyodrębnia parametry z języka naturalnego. Przykładowy prompt do wklejenia w panelu czatu Bob:

What are the latest papers on LLM agent tracing?

Dokumentowanie serwera

Implementacje serwerów MCP open source zazwyczaj zawierają dokumentację, aby inni mogli szybko zacząć. Poproś Boba o jej wygenerowanie:

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

Bob tworzy kompleksowy README.md obejmujący instalację, konfigurację dla wielu hostów MCP (IBM Bob, Claude Desktop, Cursor, Claude Code), wskazówki dotyczące uwierzytelniania dla serwerów wymagających kluczy API, wzorce dostępu do plików lokalnych i wskazówki dotyczące rozwiązywania problemów.

Czyszczenie zasobów

Ten tutorial tworzy lokalne pliki i rejestrację serwera. Usuń je, jeśli nie planujesz dalej korzystać z serwera MCP arXiv.

Otwórz panel ustawień MCP w Bobie (ikona zębatki > MCP) i wyłącz lub usuń wpis arxiv-server. Alternatywnie usuń blok arxiv-server bezpośrednio z mcp_settings.json (zakres globalny) lub .bob/mcp.json (zakres projektu).

Następne kroki

W tym tutorialu użyłeś IBM Bob do zbudowania serwera MCP w TypeScript, skonfigurowania go z transportem STDIO i przetestowania za pomocą zapytań na żywo do arXiv — wszystko przez prompty w języku naturalnym.

Ten sam przepływ pracy dotyczy bardziej złożonych implementacji serwerów MCP: serwerów łączących się z bazami danych, plikami lokalnymi lub innymi zewnętrznymi źródłami danych. Serwery wymagające uwierzytelniania potrzebują danych uwierzytelniających wstrzykniętych jako zmienne środowiskowe w konfiguracyjnym JSON MCP. W przypadku zdalnych wdrożeń zamień transport STDIO na SSE.

Dowiedz się o funkcji Code review Boba, aby wykrywać problemy przed zatwierdzeniem kodu serwera.

Dowiedz się o trybach, aby zrozumieć, kiedy używać trybów Advanced, Code, Ask i innych person Boba.

Zapoznaj się z konfiguracją MCP, aby uzyskać szczegółowe informacje na temat zakresu globalnego i projektu, automatycznie zatwierdzanych narzędzi i konfiguracji transportu SSE.

Przejdź przez serię tutoriali Get started with IBM Bob, aby kontynuować naukę.

Tworzenie serwerów MCP z IBM Bob