Jak zbudować serwer MCP w TypeScript (SDK v2) | We.Inc
Zbuduj działający serwer MCP z oficjalnym TypeScript SDK v2: instalacja, rejestracja narzędzia ze schematem Zod, połączenie przez stdio i test w MCP Inspector.
Zainstaluj oficjalny pakiet @modelcontextprotocol/server i Zod, utwórz McpServer z nazwą i wersją, zarejestruj każde narzędzie przez registerTool z opisem i schematem wejścia Zod, a potem podłącz StdioServerTransport. Uruchom npx @modelcontextprotocol/inspector, aby ręcznie wywołać swoje narzędzia, zanim dotknie ich jakakolwiek aplikacja AI.
Elementy, których potrzebujesz
Element
Skąd pochodzi
Co robi
McpServer
@modelcontextprotocol/server
Przechowuje Twoje narzędzia i odpowiada na żądania protokołu
registerTool
Metoda McpServer
Dodaje jedno narzędzie: nazwę, opis, schemat wejścia, handler
StdioServerTransport
@modelcontextprotocol/server/stdio
Komunikuje się z hostem przez standardowe wejście i wyjście
z.object(...)
zod/v4
Opisuje i waliduje argumenty narzędzia
Inspector
npx @modelcontextprotocol/inspector
Pozwala ręcznie listować i wywoływać narzędzia
Odhaczaj kolejne kroki w trakcie pracy. Lista kontrolna pamięta, gdzie jesteś, a każdy krok ma dokładne polecenie lub plik, którego potrzebujesz. Gotowy serwer przeszukuje małą listę notatek, co wystarczy, aby zobaczyć każdy ruchomy element bez bazy danych.
Utwórz folder, dodaj pokazany niżej package.json i zainstaluj obie zależności.
Wklej server.ts i zmień tablicę notes na własne dane lub wywołanie API.
Uruchom Inspector i wskaż mu polecenie uruchamiające Twój serwer.
Wylistuj narzędzia, wywołaj notes_search z jakimś słowem i sprawdź zwrócony tekst.
Nigdy nie pisz na stdout z serwera stdio. Ten strumień przenosi wiadomości protokołu, więc przypadkowy console.log je psuje. Używaj console.error, który trafia na stderr.
Niech każde narzędzie będzie małe i konkretne. Między dwoma narzędziami notes_search i notes_create model wybiera łatwiej niż w jednym narzędziu notes z przełącznikiem trybu.
Gdy narzędzie dotyka pieniędzy, plików lub cudzych danych, waliduj w handlerze oprócz schematu. Schemat sprawdza kształt, a nie uprawnienia.
Przypnij główną wersję SDK w package.json. Wersja 1 była w innym pakiecie, @modelcontextprotocol/sdk, więc starsze tutoriale nie będą pasować do tych importów.
Najczęściej zadawane pytania
Który pakiet npm zainstalować?
Dla SDK w wersji 2 zainstaluj @modelcontextprotocol/server dla serwerów i @modelcontextprotocol/client dla klientów. Starszy pakiet v1, @modelcontextprotocol/sdk, żyje na gałęzi v1.x i dostaje poprawki błędów i bezpieczeństwa przez co najmniej sześć miesięcy po wydaniu v2.
Czy potrzebuję Zod?
README wersji v2 używa Zod v4 dla schematów wejścia i importuje go z zod/v4, a także podaje, że działają inne biblioteki Standard Schema, takie jak Valibot i ArkType. Zainstaluj wybraną obok SDK.
Czy serwer może działać na Bun lub Deno?
README SDK mówi, że działa na Node.js, Bun i Deno. Inspector to osobne narzędzie Node, a jego README wymaga Node 22.19.0 lub nowszego.
Jak udostępnić serwer zdalnie?
Zamień transport stdio na Streamable HTTP i uruchom proces w osiągalnym miejscu. Dodaj uwierzytelnianie, zanim wystawisz jakiekolwiek narzędzie zmieniające dane, bo każdy, kto dotrze do URL, może wysyłać żądania.
Skąd mam wiedzieć, że aplikacja AI zrozumie moje narzędzie?
Przeczytaj swój opis i schemat tak, jakbyś nic więcej nie wiedział o projekcie. Jeśli obca osoba nie potrafiłaby powiedzieć, kiedy wywołać narzędzie i co przekazać, model też będzie zgadywał. Inspector pokazuje dokładnie to, co zobaczy host.
Dlaczego najpierw stdio
Serwer stdio to po prostu program, który uruchamia host. Nie ma portu, hostingu ani logowania, co czyni go najszybszą drogą do działającego narzędzia, które przetestujesz na własnej maszynie.
Gdy narzędzia działają poprawnie, przejście na Streamable HTTP zmienia linię transportu i hosting, a nie kod narzędzi. To rozdzielenie jest głównym powodem, by trzymać logikę biznesową w zwykłych funkcjach wywoływanych przez handlery.
Projektowanie odpowiedzi handlera
Handler zwraca obiekt z tablicą content. Najczęściej są to elementy tekstowe, a najlepiej sprawdza się krótki, konkretny tekst: powiedz, co pasowało i ile tego było, zamiast wyrzucać cały zbiór rekordów.
Gdy nic nie pasuje, zwróć zdanie, które to mówi. Pusty string zostawia model w niepewności, czy wywołanie się nie udało, czy wyszukiwanie po prostu nic nie znalazło.
Kompletny serwer
Dwa pliki. Zmień tablicę notes na to, co ma przeszukiwać Twój serwer.
type module pozwala uruchamiać składnię import ES bezpośrednio, a skrypt start używa tsx, więc pomijasz krok budowania.
Jedno narzędzie ze schematem Zod, zwykła funkcja wyszukiwania i połączenie stdio. Logi trafiają na stderr, więc nigdy nie mieszają się z wiadomościami protokołu.
Przetestuj go w Inspectorze
Inspector ma trzy tryby. Interfejs webowy to najłatwiejszy start, a tryb CLI pasuje do skryptów i CI.
Tryby Inspectora
W interfejsie webowym połącz się poleceniem uruchamiającym Twój serwer (npx tsx server.ts), a potem otwórz listę narzędzi.
Zainstaluj SDK, Zod i runner TypeScript
Napisz server.ts z jednym narzędziem
Uruchom serwer raz, aby sprawdzić, że się nie wywraca