Разработка MCP серверов: Связь ИИ с внешним миром

Введение в Model Context Protocol: Архитектура, основные понятия и роль в экосистеме ИИ

Добро пожаловать в курс по разработке MCP серверов. Мы начинаем путешествие, которое изменит ваше представление о том, как искусственный интеллект взаимодействует с реальным миром. В этой первой статье мы разберем фундамент: что такое Model Context Protocol (MCP), зачем он был создан и как он решает одну из самых больших проблем современной разработки ИИ.

Проблема «Мозга в колбе»

Современные большие языковые модели (LLM), такие как Claude, GPT-4 или Llama — это невероятно мощные инструменты. Они могут писать код, сочинять стихи и анализировать сложные тексты. Однако у них есть фундаментальное ограничение: они изолированы.

Представьте себе гениального ученого, запертого в пустой комнате без интернета, телефона и книг. Он помнит все, что выучил до момента заточения, но не знает, какая сегодня погода, не может проверить вашу почту и не имеет доступа к базе данных вашей компании. Это и есть состояние «ванильной» LLM.

До появления стандартов разработчики решали эту проблему, создавая уникальные интеграции для каждого случая. Хотите подключить модель к Google Drive? Пишите специфический код. Нужно подключить Slack? Пишите другой код. Это привело к проблеме, которую в информатике называют проблемой .

!Сравнение хаотичных прямых интеграций с упорядоченной структурой через протокол MCP

Если у нас есть клиентов (различные приложения с ИИ) и сервисов (источники данных), нам нужно создать и поддерживать интеграций. Это дорого, сложно и плохо масштабируется.

Что такое Model Context Protocol (MCP)?

Model Context Protocol (MCP) — это открытый стандарт, который позволяет приложениям предоставлять контекст (данные, инструменты, промпты) для LLM унифицированным способом.

Проще всего думать об MCP как о USB-порте для приложений искусственного интеллекта.

Раньше для каждого устройства (принтер, мышь, клавиатура) нужен был свой уникальный порт. Появление USB стандартизировало подключение: вы просто втыкаете кабель, и устройство работает. MCP делает то же самое для ИИ: он позволяет разработчикам один раз написать «драйвер» (MCP сервер) для своих данных, и этот сервер сможет работать с любым приложением, поддерживающим протокол.

Ключевые преимущества:

* Универсальность: Один сервер работает с множеством клиентов (Claude Desktop, IDE Cursor, Zed и другие). * Безопасность: Данные остаются внутри вашей инфраструктуры. Вы контролируете, к чему модель имеет доступ. * Модульность: Вы можете комбинировать разные серверы, давая модели доступ одновременно к локальным файлам, базе данных и веб-поиску.

Архитектура MCP

Архитектура протокола построена по классической схеме «клиент-сервер», но с некоторыми нюансами, специфичными для работы с LLM. Давайте разберем основных участников процесса.

!Структурная схема взаимодействия между Хостом, Сервером и LLM

1. MCP Host (Хост-приложение)

Это приложение, в котором работает пользователь. Примером может служить Claude Desktop или редактор кода Cursor. Хост отвечает за: * Управление жизненным циклом подключений. * Получение запросов от пользователя. * Отображение интерфейса. * Безопасность (запрос разрешения у пользователя на выполнение действий).

2. MCP Client (Клиент протокола)

Часто этот компонент встроен в Хост. Его задача — поддерживать соединение с серверами по протоколу MCP. Он выступает посредником между LLM и инструментами.

3. MCP Server (Сервер)

Это то, что мы будем учиться создавать в этом курсе. Сервер — это легковесная программа, которая предоставляет доступ к конкретному ресурсу или инструменту.

Например: * Сервер файловой системы: Позволяет читать и редактировать файлы. * Сервер PostgreSQL: Позволяет выполнять SQL-запросы к базе данных. * Сервер Google Calendar: Позволяет читать расписание и создавать встречи.

4. Транспортный слой

Как общаются клиент и сервер? MCP поддерживает два основных типа транспорта: * Stdio (Standard Input/Output): Сервер запускается как локальный подпроцесс. Обмен данными идет через стандартный ввод/вывод. Это идеально для локальных инструментов и обеспечивает высокую безопасность. * SSE (Server-Sent Events): Используется для удаленных серверов через HTTP. Позволяет отправлять обновления в реальном времени.

Основные примитивы протокола

Чтобы ИИ мог эффективно взаимодействовать с внешним миром, MCP определяет три основных типа возможностей (примитивов), которые сервер может предоставить клиенту. Понимание этих трех китов критически важно для разработчика.

1. Ресурсы (Resources)

Ресурсы — это пассивные данные, которые модель может прочитать. Они похожи на файлы. Это контекст, который мы загружаем в модель.

Примеры:* Логи приложения, содержимое файла, схема базы данных, список пользователей. Аналогия:* Книга в библиотеке. Вы можете ее взять и прочитать, но книга сама по себе ничего не делает. Как это работает:* Пользователь или модель запрашивает ресурс по URI (например, file:///logs/error.log), и сервер возвращает его содержимое.

2. Инструменты (Tools)

Инструменты — это исполняемые функции. Это способ модели воздействовать на мир или получать динамические данные.

Примеры:* Выполнить SQL-запрос, отправить сообщение в Slack, создать файл, сделать API-запрос к прогнозу погоды. Аналогия:* Руки и инструменты рабочего. С их помощью можно изменить состояние окружающего мира. Как это работает:* Модель понимает описание инструмента (например, «функция send_email принимает to и body») и генерирует запрос на его вызов. Хост выполняет этот вызов на сервере и возвращает результат модели.

3. Промпты (Prompts)

Промпты — это шаблоны запросов, заранее настроенные разработчиком сервера. Они помогают пользователям эффективно использовать возможности сервера, не придумывая сложные инструкции с нуля.

Примеры:* «Проанализируй этот лог на ошибки», «Сгенерируй юнит-тесты для этого кода», «Сделай саммари встречи». Аналогия:* Меню в ресторане. Вам не нужно объяснять повару, как готовить блюдо, вы просто выбираете название из списка.

Жизненный цикл запроса

Давайте проследим, как происходит взаимодействие, когда пользователь просит ИИ выполнить задачу, используя MCP.

Инициализация: Пользователь открывает приложение (Хост). Хост запускает настроенные MCP серверы (например, сервер базы данных).

Обнаружение (Handshake): Хост спрашивает у серверов: «Что вы умеете?». Серверы отвечают списком доступных Инструментов и Ресурсов.

Запрос пользователя: Пользователь пишет: «Найди в базе данных пользователя с email 'test@example.com'».

Выбор инструмента: LLM анализирует запрос и видит, что у нее есть инструмент query_db. Она формирует JSON-структуру для вызова этой функции.

Подтверждение (опционально): Хост может спросить у пользователя: «Разрешить выполнение SQL-запроса?».

Выполнение: Хост отправляет команду на MCP сервер. Сервер выполняет запрос к реальной базе данных.

Ответ: Сервер возвращает результат (найденную строку таблицы) Хосту, а тот передает его LLM.

Финальный ответ: LLM формулирует ответ пользователю на естественном языке: «Я нашла пользователя, его ID — 42».

Роль в экосистеме ИИ

Почему MCP стал таким важным именно сейчас? Мы переходим от эры Чат-ботов к эре Агентов.

Чат-бот просто разговаривает. Агент выполняет работу. Чтобы выполнять работу, нужен стандартизированный доступ к инструментам. MCP предоставляет именно этот стандарт.

> «Протоколы побеждают продукты. SMTP победил проприетарные почтовые системы. HTTP победил закрытые сети. MCP стремится сделать то же самое для контекста ИИ.»

Компания Anthropic открыла исходный код протокола, сделав его доступным для всех. Это означает, что вы, как разработчик, можете написать один сервер, который будет работать и в Claude, и в JetBrains IDE (в будущем), и в любых других инструментах, которые внедрят этот стандарт.

Заключение

Мы разобрали теоретическую базу Model Context Protocol. Теперь вы знаете, что это «USB для ИИ», который состоит из Хоста, Клиента и Сервера, общающихся через Ресурсы, Инструменты и Промпты.

В следующей статье мы перейдем от теории к практике. Мы подготовим рабочее окружение, установим необходимые инструменты и создадим каркас вашего первого MCP сервера на TypeScript. Готовьте свои терминалы!

Настройка окружения и создание первого Hello World сервера с использованием SDK

В предыдущей статье мы погрузились в теорию Model Context Protocol (MCP), узнали о проблеме «Мозга в колбе» и разобрали архитектуру взаимодействия между хостом, клиентом и сервером. Теперь пришло время перейти от слов к делу.

В этой статье мы создадим ваш первый работающий MCP сервер. Мы не будем сразу нырять в сложные базы данных или API. Наша цель — создать минимально жизнеспособный продукт (MVP): сервер, который умеет просто здороваться. Это позволит нам отладить всю цепочку инструментов и убедиться, что ваша локальная среда готова к серьезной разработке.

Подготовка рабочего места

Прежде чем писать код, нам нужно убедиться, что у нас есть все необходимые инструменты. MCP серверы можно писать на разных языках (Python, Go), но «родным» языком для протокола и большинства SDK является TypeScript/Node.js. Именно его мы и будем использовать в этом курсе.

Необходимые компоненты

Node.js: Среда выполнения JavaScript. Вам потребуется версия LTS (Long Term Support), желательно 18 или выше.

Как проверить:* Откройте терминал и введите node -v. Если версия ниже 18 или команда не найдена, скачайте установщик с официального сайта Node.js.

Менеджер пакетов: Обычно npm устанавливается вместе с Node.js. Можно также использовать pnpm или yarn.

Редактор кода: Рекомендуется Visual Studio Code или Cursor. Cursor особенно хорош тем, что сам является MCP-хостом, но для начала мы будем тестировать всё через Claude Desktop.

Claude Desktop: Это приложение будет выступать в роли Хоста (клиента), который будет подключаться к нашему серверу. Скачайте его с официального сайта Anthropic.

!Визуализация локального окружения: редактор кода, среда выполнения и хост-приложение Claude Desktop.

Шаг 1: Инициализация проекта

Откройте ваш терминал. Мы создадим новую папку для проекта и инициализируем её.

Команда npm init -y создаст файл package.json с настройками по умолчанию. Теперь нам нужно установить зависимости. Нам понадобятся две ключевые библиотеки:

@modelcontextprotocol/sdk: Официальный SDK для создания серверов.

zod: Библиотека для валидации схем данных. Она критически важна, так как позволяет описывать типы входных данных для инструментов, чтобы LLM понимала, какие аргументы нужно передавать.

Выполните команду установки:

Также нам нужно настроить TypeScript, так как мы хотим строгую типизацию. Установим его как зависимость для разработки:

Создайте файл tsconfig.json в корне проекта и добавьте туда следующие настройки:

Обратите внимание на outDir: "./build". Это означает, что наш скомпилированный JavaScript код будет попадать в папку build.

Шаг 2: Создание сервера

Создайте папку src и внутри неё файл index.ts. Это будет точка входа нашего приложения.

Импорт зависимостей

В начале файла src/index.ts импортируем необходимые классы:

Инициализация экземпляра сервера

Теперь создадим экземпляр сервера. Мы дадим ему имя и версию. Эта информация будет передаваться хосту при первом рукопожатии (handshake).

Добавление инструмента (Tool)

Самое интересное — научить сервер что-то делать. В терминологии MCP функции, которые может вызывать ИИ, называются Инструментами (Tools).

Мы создадим инструмент say_hello. Он будет принимать один аргумент — имя пользователя, и возвращать приветствие.

Разберем этот код: * Первый аргумент — имя инструмента, которое увидит LLM. * Второй аргумент — схема данных с использованием zod. Мы говорим: «Ожидай объект, у которого есть поле name, и это должна быть строка». * Третий аргумент — асинхронная функция, которая выполняет логику и возвращает результат.

Подключение транспорта

Последний шаг в коде — запустить сервер, используя транспортный слой. Для локального взаимодействия мы используем StdioServerTransport (стандартный ввод/вывод).

> Важно: Мы используем console.error для логов, потому что console.log (стандартный вывод stdout) используется протоколом для передачи JSON-сообщений. Если вы напишете console.log('Hello'), это сломает протокол, так как Хост будет ожидать валидный JSON, а получит простой текст.

Шаг 3: Сборка и запуск

Теперь нам нужно превратить TypeScript в JavaScript. Добавьте скрипт сборки в ваш package.json в секцию scripts:

Выполните сборку:

Если ошибок нет, в папке build появится файл index.js. Вы можете попробовать запустить его вручную через node build/index.js, но ничего не произойдет — сервер будет висеть и ждать команд через stdin. Это нормально.

Шаг 4: Подключение к Claude Desktop

Теперь самое главное — «поженить» наш сервер и клиент (Claude Desktop). Для этого нужно отредактировать конфигурационный файл Claude.

Где найти конфиг?

Расположение файла зависит от вашей операционной системы:

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

Откройте этот файл в любом текстовом редакторе. Если файла нет, создайте его.

Настройка конфига

Вам нужно добавить запись о вашем сервере в секцию mcpServers. Нам потребуется абсолютный путь к папке вашего проекта.

Пример конфигурации:

Внимание: Замените /Users/username/projects/mcp-hello-world/build/index.js на реальный полный путь к вашему скомпилированному файлу. На Windows пути нужно экранировать (использовать двойные слэши \\).

!Пример конфигурационного файла claude_desktop_config.json.

Шаг 5: Тестирование

Полностью закройте Claude Desktop (Cmd+Q на macOS). Конфигурация считывается только при старте приложения.

Откройте Claude Desktop снова.

Обратите внимание на иконку «вилки» (значок подключений) в интерфейсе. Если она появилась, значит, Claude увидел ваш сервер.

Напишите в чат: «Используй инструмент say_hello, чтобы поприветствовать пользователя Иван».

Если всё настроено верно, Claude:

Поймет, что у него есть инструмент say_hello.

Сформирует запрос к вашему локальному Node.js процессу.

Ваш скрипт вернет строку «Привет, Иван!...».

Claude покажет вам этот ответ.

Возможные проблемы

* Сервер не появляется в Claude: Проверьте логи Claude (обычно лежат рядом с конфигом в папке logs). Частая ошибка — неправильный путь к файлу в конфиге. * Ошибка command not found: Убедитесь, что node доступен в системном PATH, или укажите полный путь к исполняемому файлу node в конфиге (вместо просто "node"). * Синтаксическая ошибка в JSON: Проверьте валидность JSON в конфиге (запятые, скобки).

Заключение

Поздравляю! Вы только что создали свой первый MCP сервер. Да, он пока делает простую вещь, но архитектурно он ничем не отличается от сервера, который управляет облачной инфраструктурой или анализирует гигабайты данных.

Вы научились:

Инициализировать проект с @modelcontextprotocol/sdk.

Описывать инструменты с помощью схем zod.

Использовать транспорт Stdio.

Подключать локальный сервер к Claude Desktop.

В следующей статье мы усложним задачу. Мы научим наш сервер работать с реальными данными — читать файлы с вашего компьютера и предоставлять их содержимое модели для анализа.

Предоставление контекста: Реализация ресурсов (Resources) и шаблонов промптов (Prompts) для чтения данных

В предыдущей статье мы успешно настроили окружение и создали наш первый MCP сервер, который умел здороваться. Это был важный шаг, но пока наш «цифровой сотрудник» слеп. Он может выполнять простые команды, но не видит данных, с которыми ему предстоит работать.

Сегодня мы превратим наш сервер из простого исполнителя в источник знаний. Мы разберем два фундаментальных понятия протокола: Ресурсы (Resources) и Промпты (Prompts). Вы научитесь «скармливать» модели файлы, логи, записи из базы данных и создавать удобные шаблоны для работы с ними.

Что такое Ресурсы в MCP?

Если Инструменты (Tools) — это руки ИИ, которыми он воздействует на мир, то Ресурсы (Resources) — это его глаза. Это способ предоставить модели доступ к данным для чтения.

Ресурс — это любой кусок информации, который можно идентифицировать по уникальному адресу (URI) и прочитать. Это могут быть:

* Текстовые файлы или код. * Логи системы. * Изображения. * Записи в базе данных (в режиме только для чтения). * Текущее состояние приложения.

Философия прямого доступа

В традиционной разработке, если вы хотите передать данные в LLM, вы обычно копируете их и вставляете в чат. MCP автоматизирует этот процесс. Клиент (например, Claude Desktop) может запросить у сервера список доступных ресурсов, а затем прочитать содержимое конкретного ресурса по требованию пользователя или самой модели.

!Диаграмма последовательности запроса и чтения ресурсов между хостом и MCP сервером

Практика: Создаем сервер заметок

Давайте создадим сервер, который управляет простыми текстовыми заметками. Мы не будем подключать настоящую базу данных, чтобы не усложнять код, а будем хранить данные в памяти.

Откройте ваш проект mcp-hello-world (или создайте новый) и откройте файл src/index.ts.

Шаг 1: Подготовка данных

Сначала определим интерфейс наших данных и создадим несколько тестовых заметок.

Шаг 2: Реализация списка ресурсов

Хост должен знать, какие ресурсы доступны. В MCP ресурсы идентифицируются по URI. Мы будем использовать схему note://internal/{id}.

Добавим код для регистрации ресурса. В SDK это делается через метод server.resource.

Что здесь происходит?

Мы регистрируем промпт с именем summarize_note.

Мы описываем аргументы с помощью zod (как и в Инструментах).

Мы возвращаем массив сообщений. Это те сообщения, которые будут вставлены в чат от имени пользователя.

Важный момент: Промпт сам по себе не выполняет действие. Он подготавливает контекст для LLM. Когда пользователь активирует этот промпт, в чат «вставляется» сообщение, содержащее ссылку на ресурс. Клиент (Claude) видит эту ссылку, понимает, что это MCP-ресурс, автоматически запрашивает его содержимое через наш read_note и скармливает всё это модели.

Сборка и запуск

Не забудьте добавить код запуска сервера в конце файла src/index.ts, если его там нет:

Соберите проект:

Убедитесь, что путь к вашему серверу прописан в конфиге Claude Desktop (как мы делали в прошлой статье).

Тестирование в Claude Desktop

Перезапустите Claude Desktop.

Нажмите на иконку «скрепки» или значок подключения данных.

Вы должны увидеть раздел с вашим сервером notes-server.

Попробуйте найти там «Промпты» или просто напишите в чат.

Однако, самое интересное взаимодействие происходит через UI промптов. В Claude Desktop вы можете нажать на специальную кнопку (обычно / или меню шаблонов), выбрать summarize_note, ввести ID 1, и магия произойдет сама собой.

Модель получит текст: > Пожалуйста, сделай краткое содержание следующей заметки. Ресурс: note://internal/1

Затем она автоматически «подтянет» содержимое «Молоко, хлеб...» и выдаст ответ: «Это список покупок продуктов».

Ресурсы vs Инструменты: Как выбрать?

Новички часто путают, когда использовать Ресурс, а когда Инструмент (Tool). Вот простое правило:

| Характеристика | Ресурс (Resource) | Инструмент (Tool) | | :--- | :--- | :--- | | Действие | Пассивное чтение | Активное выполнение | | Побочные эффекты | Нет (Safe) | Возможны (изменение БД, отправка email) | | Контекст | Данные загружаются в контекст окна | Результат выполнения функции | | Пример | Файл логов, профиль пользователя | Функция delete_user, search_logs |

Используйте Ресурсы, когда вы хотите дать модели «почитать» что-то, что уже существует. Используйте Инструменты, когда модели нужно что-то сделать или найти информацию по сложным критериям.

Заключение

Сегодня мы научили наш сервер делиться данными. Мы создали виртуальную файловую систему заметок и научились отдавать их содержимое через URI. Также мы создали шаблоны промптов, чтобы упростить жизнь пользователю.

Теперь ваш ИИ-агент имеет «глаза» (Ресурсы) и «голос» (Промпты). В следующей статье мы вернемся к «рукам» и углубимся в создание сложных Инструментов (Tools): мы научимся изменять данные, обрабатывать ошибки и работать с внешними API.

Активные действия: Создание и регистрация инструментов (Tools) для выполнения команд агентами

Мы продолжаем наш курс по разработке MCP серверов. В прошлых статьях мы научились настраивать окружение и создали сервер, который умеет «читать» данные через Ресурсы (Resources). Мы дали нашему ИИ глаза. Теперь пришло время дать ему руки.

В этой статье мы разберем Инструменты (Tools). Это механизм, который превращает пассивного чат-бота в активного агента, способного изменять данные, вызывать внешние API и управлять системами.

Что такое Инструменты в MCP?

Инструмент (Tool) — это исполняемая функция, которую сервер предоставляет модели. В отличие от Ресурсов, которые предназначены только для чтения, Инструменты могут выполнять вычисления и иметь побочные эффекты (создание файлов, запись в базу данных, отправка уведомлений).

Как ИИ «нажимает кнопки»?

Важно понимать механику процесса. Сама по себе Большая Языковая Модель (LLM) — это просто генератор текста. Она не может напрямую запустить функцию deleteDatabase() на вашем сервере. Процесс выглядит иначе:

Декларация: Сервер сообщает модели: «У меня есть инструмент add_task, который принимает title (строка) и priority (число)».

Решение: Модель, анализируя запрос пользователя («Напомни купить молока»), решает, что нужно использовать этот инструмент.

Генерация: Модель генерирует JSON-объект с аргументами: { "title": "Купить молоко", "priority": 1 }.

Выполнение: Хост-приложение (например, Claude Desktop) берет этот JSON, передает его вашему MCP серверу, запускает функцию и возвращает результат обратно модели.

!Диаграмма последовательности выполнения инструмента: от запроса пользователя до реакции сервера.

Подготовка проекта: Менеджер задач

Чтобы продемонстрировать работу инструментов, мы создадим простой сервер «Менеджер задач» (To-Do List). Он будет уметь добавлять задачи и отмечать их как выполненные.

Если вы продолжаете работу с предыдущим проектом, вы можете создать новый файл или очистить src/index.ts. Нам понадобятся те же импорты.

Регистрация первого инструмента: Добавление задачи

Для создания инструмента мы используем метод server.tool(). Ему нужны три вещи:

Имя: Уникальный идентификатор инструмента.

Схема: Описание входных параметров с помощью библиотеки Zod.

Обработчик: Асинхронная функция, которая выполняет логику.

Важность валидации данных (Zod)

LLM могут ошибаться. Они могут прислать строку там, где ожидается число, или пропустить обязательный аргумент. Библиотека Zod позволяет нам жестко описать контракт. Если модель пришлет неверные данные, Zod выбросит ошибку еще до того, как запустится наша бизнес-логика, и модель увидит эту ошибку, чтобы исправиться.

Давайте создадим инструмент add_todo:

Обратите внимание на метод .describe(). Это не просто комментарий для программиста. Этот текст передается в LLM. Чем лучше вы опишете поле, тем точнее модель будет его заполнять.

Регистрация второго инструмента: Выполнение задачи

Теперь добавим возможность отмечать задачи как выполненные. Здесь нам потребуется обработка ошибок. Если модель попытается закрыть несуществующую задачу, мы должны сообщить об этом.

Запуск и тестирование

Не забудьте добавить код запуска сервера в конце файла:

Скомпилируйте проект (npm run build) и перезапустите Claude Desktop. Убедитесь, что в конфигурации указан правильный путь к вашему build/index.js.

Сценарий тестирования

Попробуйте написать в чат следующие команды:

«Добавь задачу купить хлеб» — Claude должен вызвать add_todo.

«Какие у меня есть задачи?» — Claude вызовет list_todos.

«Отметь задачу 1 как выполненную» — Claude вызовет complete_todo.

«Отметь задачу 999 как выполненную» — Claude должен показать сообщение об ошибке, которое мы запрограммировали.

Лучшие практики создания инструментов

При разработке инструментов для ИИ следуйте этим правилам:

* Атомарность: Один инструмент должен делать одно простое действие. Не делайте «супер-инструмент», который и создает, и удаляет, и редактирует в зависимости от флага. * Понятные имена: create_user лучше, чем func1. Модель ориентируется на семантику названия. * Описания (Descriptions): Всегда добавляйте .describe() к полям Zod. Это ваша документация для ИИ. * Безопасность: Помните, что модель может вызвать инструмент с любыми параметрами. Всегда валидируйте данные внутри функции, даже если Zod пропустил их (например, проверка существования ID в базе).

Заключение

Поздравляю! Вы создали сервер, который позволяет ИИ активно взаимодействовать с данными. Теперь ваш агент может не только читать, но и действовать.

Мы разобрали: * Как регистрировать инструменты через server.tool. * Как описывать схемы данных с помощью zod. * Как обрабатывать ошибки и возвращать статус isError.

В следующей статье мы объединим всё вместе и рассмотрим сложные сценарии: как создавать цепочки действий и отлаживать взаимодействие между клиентом и сервером.

Отладка с MCP Inspector, обработка ошибок и подключение сервера к клиентам (Claude Desktop, IDE)

Мы прошли большой путь. Мы начали с теории, настроили окружение, научили сервер читать данные через Ресурсы и выполнять действия через Инструменты. Ваш сервер работает... или вам так кажется.

В реальной разработке код редко работает идеально с первой попытки. Когда вы просите Claude выполнить действие, а он отвечает: «Извините, произошла ошибка», — это черный ящик. Вы не видите, что произошло внутри. Вы не знаете, упал ли сервер, вернул ли он неправильный JSON или просто не понял запрос.

В этой статье мы превратим этот черный ящик в прозрачный механизм. Мы научимся использовать официальный отладчик MCP Inspector, правильно обрабатывать ошибки (чтобы ИИ мог исправиться) и подключать ваш сервер не только к Claude, но и к средам разработки, таким как Cursor.

Проблема стандартного ввода-вывода

Прежде чем перейти к инструментам, нужно вспомнить, как работает транспорт stdio. Это критически важно для отладки.

Ваш сервер и клиент (Claude) общаются через стандартные потоки ввода и вывода. Это похоже на разговор по двум трубам:

Stdin (Вход): Клиент отправляет запросы серверу.

Stdout (Выход): Сервер отправляет ответы клиенту в формате JSON.

!Схематическое изображение разделения потоков данных в протоколе MCP

Главное правило MCP разработки: Никогда не используйте console.log() для отладки.

Если вы напишете console.log("Я тут!") внутри вашего кода, эта строка попадет в stdout. Клиент ожидает валидный JSON-RPC сообщение, а получает текст «Я тут!». Это мгновенно ломает протокол, и соединение разрывается.

Куда же писать логи?

Используйте console.error(). В Node.js (и большинстве других сред) этот поток (stderr) отделен от основного вывода. MCP клиенты игнорируют мусор в stderr при разборе протокола, но сохраняют его в лог-файлы, которые вы можете прочитать.

MCP Inspector: Рентген для вашего сервера

Отлаживать сервер через чат с LLM — это долго и дорого. Вы не знаете, галлюцинирует ли модель или сервер действительно сломан. Для решения этой проблемы команда Anthropic создала MCP Inspector.

MCP Inspector — это веб-интерфейс, который подключается к вашему серверу вместо Claude. Он позволяет: * Видеть список всех доступных ресурсов, промптов и инструментов. * Вручную вызывать инструменты с заданными параметрами. * Видеть сырые JSON-запросы и ответы. * Читать логи из stderr в реальном времени.

Запуск инспектора

Вам не нужно устанавливать его глобально. Вы можете запустить его с помощью npx, указав команду запуска вашего сервера.

Откройте терминал в папке вашего проекта и выполните:

Если вы используете Windows, команда может выглядеть так:

После запуска в терминале появится ссылка (обычно http://localhost:5173). Откройте её в браузере.

Работа в интерфейсе

Интерфейс инспектора интуитивно понятен. Слева вы увидите меню с разделами:

Resources: Здесь можно проверить, правильно ли работают ваши шаблоны URI. Вы можете ввести note://internal/1 и нажать «Read», чтобы увидеть содержимое.

Prompts: Позволяет просмотреть доступные промпты и их аргументы.

Tools: Самый важный раздел. Вы увидите список ваших инструментов (например, add_todo). Вы можете заполнить поля формы (которые генерируются на основе вашей Zod-схемы) и нажать «Run Tool».

В правой части экрана вы увидите лог обмена сообщениями. Это «сырая правда» о том, что происходит.

!Интерфейс разработчика MCP Inspector для тестирования инструментов

Если ваш инструмент падает с ошибкой, вы увидите её здесь, в чистом виде, без вежливых извинений ИИ.

Обработка ошибок: Помогаем ИИ исправиться

Когда в коде происходит ошибка (например, база данных недоступна или файл не найден), у вас есть два пути:

Выбросить исключение (Throw exception): Это приведет к внутренней ошибке сервера (Internal Server Error). Модель увидит, что инструмент сломался, но не поймет почему.

Вернуть результат с флагом ошибки: Это «штатная» ошибка. Модель прочитает текст ошибки и попытается исправить свои действия.

Паттерн безопасной обработки

Рекомендуется оборачивать логику инструментов в блок try-catch и возвращать понятное сообщение.

Вспомним наш пример с заметками из прошлой статьи. Допустим, мы хотим удалить заметку.

Почему важен isError: true?

Когда LLM получает ответ с isError: true, она воспринимает это как обратную связь.

Сценарий:* Пользователь просит: «Удали заметку про молоко». Модель вызывает delete_note(id="milk"). Ответ сервера:* isError: true, текст: «Ошибка: ID должен быть числом». Реакция модели:* Она анализирует ошибку, смотрит на список заметок (возможно, вызывая list_notes) и делает повторный вызов: delete_note(id="1").

Без флага isError модель может подумать, что текст ошибки — это просто результат выполнения, и радостно сообщить пользователю: «Я удалила заметку, вот ответ сервера: ID должен быть числом».

Подключение к IDE (Cursor и другие)

Claude Desktop — отличный клиент, но сила MCP в его универсальности. Одним из самых мощных применений является интеграция с редакторами кода, такими как Cursor или Zed.

Представьте, что вы пишете код, и ваш ИИ-помощник в редакторе имеет доступ к вашей локальной базе данных Jira, документации во внутренней вики или логам продакшена — и всё это через MCP.

Настройка в Cursor

Cursor — это форк VS Code со встроенным ИИ. Он нативно поддерживает MCP.

Откройте настройки Cursor (Cmd + , или Ctrl + ,).

Перейдите в раздел Features -> MCP.

Нажмите кнопку Add New MCP Server.

Вам нужно будет указать:

* Name: Имя сервера (любое, например My Local Tools). * Type: Выберите command (или stdio). * Command: node (или полный путь к node). * Args: Абсолютный путь к вашему файлу build/index.js.

После добавления индикатор должен загореться зеленым. Теперь, общаясь с чатом в Cursor (Composer или Chat), вы можете просить его использовать ваши инструменты.

Настройка в Zed

Редактор Zed также поддерживает MCP через конфигурационный файл.

Откройте палитру команд (Cmd + Shift + P) и введите task: open settings.

В JSON конфигурации добавьте секцию mcp_servers:

После сохранения Zed запустит сервер. Вы можете проверить статус, нажав на значок MCP в статус-баре.

Чек-лист перед релизом

Прежде чем считать ваш сервер готовым, пройдитесь по этому списку:

Сборка: Код компилируется (npm run build) без ошибок TypeScript.

Инспектор: Все инструменты проверены в MCP Inspector и возвращают ожидаемый JSON.

Логи: Вы убрали все console.log и заменили их на console.error.

Ошибки: Все инструменты корректно обрабатывают невалидные входные данные и возвращают isError: true.

Пути: В конфигурации клиентов указаны абсолютные пути к файлам, чтобы сервер запускался из любой рабочей директории.

Заключение курса

Поздравляю! Вы прошли путь от понимания концепции «Мозга в колбе» до создания полнофункционального, отлаженного MCP сервера, интегрированного в вашу рабочую среду.

Теперь вы обладаете навыком, который становится стандартом индустрии. Вы можете создавать агентов, которые управляют вашим умным домом, автоматизируют рабочие процессы в Jira, анализируют локальные файлы или взаимодействуют с любым API, для которого вы напишете обертку.

Мир ИИ больше не изолирован. Благодаря MCP и вашим новым навыкам, он подключен к реальности.