​
Галоўная > Ствараем свой першы MCP-сервер

Ствараем свой першы MCP-сервер

MCP

header

Вітанкі!

Я ўжо больш за месяц як пачаў пісаць гэты артыкул , але то часу няма, то настрою. Але ўсё ж я сабраўся з думкамі і нарэшце нешта зляпіў. Спадзяюся вам будзе карысна. Зьвярніце ўвагу на гітхаб - там ужо гатовыя працуючыя прыклады, якія можна запускаць. Для лепшага разумення што адбываецца - азнаемцеся з структурай і кодам MCP сервера

Сёння мы падключаем Cursor і VS Code да вашых API праз MCP.

Часам глядзіш на ўласныя карысныя скрыпты і думаеш: «Як акуратна, без лішняй мукі падключыць іх да ШІ? Што для гэтага трэба? З якога боку падысці?». І вось сёння ў гэтым артыкуле мы паспрабуем вырашыць гэтую праблему і навучыцца ствараць уласныя MCP.

Ну і можаце глянуць мае папярэднія артыкулы пра ШІ

MCP у двух словах

MCP (Model Context Protocol) - уніфікаваны «перакладчык» паміж вашымі інструментамі і разумнымі кліентамі (чат-асістэнтамі, напрыклад агентамі ў Cursor). Замест чарговага разрозненага API вы дакладна апісваеце, што ўмее ваш інструмент і якія ў яго ўваходы/выхады - далей усё працуе па стандарце.

Чым MCP зручны

Асноўная ідэя MCP у тым, што ваша API можа быць падлучана да мадэлі як асобны агент з празрыстымі правіламі:

  • Стандартызацыя. Адзіная мова для інструментаў і кліентаў замест набора разнастайных пратаколаў.
  • Кіраванасць. Падлучаныя да мадэлі інструменты маюць яўныя схемы, прадказальныя паводзіны, выразныя правы.
  • Хуткая інтэграцыя. Падключылі API/FS/БД/DevOps-працэсы - і карыстаецеся з IDE або з чата.

Дзе MCP асабліва дарэчны

MCP падыходзіць для розных задач, найчасцей звязаных з распрацоўкай (цяпер найперш рэдактары адаптаваныя для працы з вонкавымі інструментамі праз MCP). Напрыклад:

  • DevTools і ChatOps: CI/CD-каманды, дыягностыка, доступ да логаў.
  • Data/BI: агрэгаваныя запыты, разумныя зводкі.
  • Унутраныя API: адзіная кантрольная кропка для каманды.
  • RAG/аўтаматызацыя: збор, перад-/пасляапрацоўка дадзеных.
  • Праца з дакументацыяй (напрыклад, Confluence) і інш.

Спіс прапанаваных MCP для VS Code: github

Як зрабіць просты MCP-сервер з HTTP-транспартам (Bun/Node)

Вернемся да стварэння нашага сервера. Я ўжо падрыхтаваў некалькі прыкладаў інструментаў у навучальным рэпазіторыі; азнаёміцца з імі можна па спасылцы lesson8_mcp/mcp_server у рэпазіторыі bel_geek. Код сумяшчальны з Bun і Node.js.

Што збудуем

Створым просты сервер без лішніх «наваротаў». Гэта будзе лакальны HTTP-сервер з /healthz і /mcp, без стану (stateless), з трыма дэма-інструментамі (тым жа наборам, што ў рэпазіторыі) - каб адразу «памацаць» MCP:

  • Маршруты:
    • GET /healthz - праверка здароўя.
    • /mcp - MCP-эндапоінт (GET, POST, DELETE).
  • Stateless-рэжым (без сесій).
  • Тры інструменты:
    • echo - вяртае перададзены тэкст.
    • get_proverb_by_topic - прыказкі па тэме (topic, random, limit).
    • get_weather - лаканальнае надвор’е з wttr.in.

🚀 Збіраем сервер і падключаем яго да Cursor/VS Code

Тэорыя скончана, час дзейнічаць: клон, усталёўка, запуск - і MCP ўжо працуе.

🔑 Перадумовы (што трэба перад стартам)

Тут без сюрпрызаў:

  • Node.js ≥ 18 або Bun ≥ 1.x (Bun хутчэйшы пры старце - менш лішніх рухаў).
  • Два пакеты: @modelcontextprotocol/sdk (аснова MCP) і zod (каб апісваць уваходныя параметры дакладна і надзейна).
  • Docker - толькі калі хочаце адразу пакласці ўсё ў кантэйнер. Для лакальнага тэставання не патрэбны.

⚡️ Запускаем прыклад

Без лішняй філасофіі - проста клануем рэпазіторый і запускаем:

text
1
2git clone https://github.com/bel-frontend/RAG
3cd RAG/lesson8_mcp/mcp_server
text
1
2bun install
3bun index.ts

Калі ўсё добра - у кансолі з’явіцца паведамленне:

text
1MCP Streamable HTTP Server on http://localhost:3002/mcp
2Available endpoints: /healthz, /mcp

🎉 Сервер! Жыві!

Праверым яго «пульс»:

text
1curl -s http://localhost:3002/healthz

Адказ павінен быць у фармаце { ok: true, timestamp: ... }.

🧩 Архітэктура простымі словамі

Як працуе сервер:

  1. Ствараецца MCP-сервер - у ім рэгіструюцца інструменты (echo, get_proverb_by_topic, get_weather).
  2. Дадаецца HTTP-транспарт - MCP можа прымаць і адпраўляць запыты праз /mcp.
  3. Маршруты:
    • /healthz - вяртае просты JSON, каб праверыць, што сервер жывы.
    • /mcp - асноўны эндпоінт, праз які Cursor або VS Code звязваюцца з інструментамі.
  4. Кантэкст - загалоўкі (apikey, applicationid) кладуцца ў сховішча, каб інструменты маглі іх выкарыстоўваць.
  5. Завяршэнне - пры спыненні (SIGINT/SIGTERM) сервер карэктна закрываецца.

🛠 Інструменты - галоўная магія тут

Дададзены тры простыя інструменты для хуткага эксперымента:

  • echo - вяртае тэкст, які вы яму перадалі (карысна для праверак).
  • get_proverb_by_topic - выдае прыказкі па тэме; падтрымлівае random і limit.
  • get_weather - паказвае надвор’е праз сэрвіс wttr.in.

Кожны інструмент апісаны праз zod-схему. Гэта гарантуе дакладнасць: калі карыстальнік пераблытаў параметры, MCP паведаміць пра няправільны фармат.

🖇 Падключаемся да Cursor і VS Code

І тут пачынаецца самае цікавае - інтэграцыя. Калі MCP працуе, мы можам выкарыстоўваць яго праз Cursor або GitHub Copilot у VS Code.

Cursor:

  1. Запусці сервер (bun index.ts).
  2. Ствары ў праекце файл ./.cursor/mcp.json з канфігурацыяй:
text
1{
2  "mcpServers": {
3    "test-mcp": {
4      "type": "http",
5      "url": "http://localhost:3002/mcp",
6      "headers": {
7        "apiKey": "API_KEY_1234567890",
8        "applicationid": "APPLICATION_ID"
9      }
10    }
11  }
12}

Адкрый налады → Model Context Protocol і пераканайся, што test-mcp ёсць у спісе. У чаце Cursor напішы (пераканайся, што ўключаны менавіта агент): «Выкліч тул get_weather для Minsk» - і паглядзі адказ.

VS Code (Copilot Chat)

Тут амаль тое самае, толькі файл трэба пакласці ў .vscode/mcp.json. Пасля гэтага ў панэлі інструментаў Copilot Chat павінен з’явіцца ваш інструмент.

text
1{
2    "servers": {
3        "test-mcp": {
4            "type": "http",
5            "url": "http://localhost:3002/mcp",
6            "headers": {
7                "apiKey": "API_KEY_1234567890",
8                "applicationid": "APPLICATION_ID"
9            }
10        }
11    }
12}

🐳 Docker-рэжым

Хочаце адразу ўпакоўку? Збіраем і запускаем у Docker:

text
1docker compose build --no-cache
2docker compose up -d

MCP будзе даступны на http://localhost:3002/mcp. Зручна для каманднай працы: усе карыстаюцца аднолькавым вобразам і не марнуюць час на «у мяне працуе - у цябе не».

🤔 Тыповыя «граблі» і як іх абысці

  • CORS - калі падключаецеся з браўзера, трэба дазволіць загалоўкі. Мы дадалі базавы варыянт у код.
  • Stateless/Stateful - ў прыкладзе сервер «без памяці». Калі патрэбныя сесіі - уключайце sessionIdGenerator.
  • API-загалоўкі - - у Node.js яны прыходзяць у ніжнім рэгістры (apikey, а не apiKey). Лёгка заблытацца.
  • Знешнія сэрвісы - прыказкі і надвор’е могуць тармазіць. Дадавайце таймаўты і кэш.

✍️ Як зрабіць свой інструмент

Просты прыклад:

text
1import { z } from 'zod';
2import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
3
4export function registerMyTools(mcp: McpServer) {
5  mcp.registerTool(
6    'my_tool',
7    {
8      title: 'my_tool',
9      description: 'Просты інструмент, які складае 2+2',
10      inputSchema: { name: z.string() },
11    },
12    async ({ name }) => ({
13      content: [{ type: 'text', text: `Вітаю, ${name}! 2+2 = 4` }],
14    }),
15  );
16}

Гатова - цяпер вы можаце дадаваць свае «чараўніцтвы» ў MCP і карыстацца імі з IDE.

🎯 Вынікі

Мы сабралі MCP-сервер на Bun/Node, дадалі тры дэма-інструменты, падключылі яго да Cursor і VS Code, запусцілі ў Docker і абмеркавалі тыповыя праблемы. Галоўнае - MCP робіць падключэнне ўласных інструментаў да разумных IDE простым і стандартызаваным.

Далейшае - толькі ваша фантазія: можна інтэграваць DevOps-працэсы, базу дадзеных, BI-запыты, унутраныя API. MCP дазваляе гэта зрабіць так, каб іншыя члены каманды маглі проста ўзяць і выкарыстоўваць.

Што далей

Мы сабралі акуратны MCP-сервер з HTTP-транспартам, дадалі тры наглядныя інструменты, наладзілі CORS і паказалі канфігурацыі для Cursor і GitHub Copilot (VS Code), а таксама Docker-запуск. Наступныя крокі - пашырэнне набору інструментаў, аўтэнтыфікацыя, лагіраванне, кэш; пры патрэбе - stateful-сесіі і вынясенне ў prod.

Калі гэта вас зачапіла - стварайце ўласныя інструменты і дзяліцеся імі з супольнасцю! Запрашаем далучацца да аўтараў bel-geek.com - будзем разам ствараць разумныя і карысныя рэчы.

Admin, 2025-08-13
Каментары

    (Каб даслаць каментар залагуйцеся ў свой уліковы запіс)