Test Task: Trainee Mcp Server

Учебный MCP-сервер на TypeScript: даёт Claude два инструмента (add, get_weather) и один ресурс (favorite-cities). Работает локально, общается с хостом по транспорту stdio, подключается к Claude Desktop.

Источник данных о погоде — Open-Meteo. Ключ API не нужен, регистрация не требуется.

Что умеет

Схема инструмента get_weather

Схема описана через Zod; SDK превращает её в JSON Schema, которую видит модель. Значения вне перечисленных (например, kelvin) отсекаются до попадания в код инструмента.

Требования

• Node.js 18+ (рекомендуется актуальная LTS) — используются встроенные fetch и AbortSignal.timeout

• Claude Desktop или другой MCP-хост

• Доступ в интернет для запросов к Open-Meteo

Установка и сборка

git clone <ссылка-на-репозиторий>
cd trainee-mcp-server
npm install
npm run build

После сборки появится dist/index.js — именно этот файл запускает хост.

Проверить, что сервер стартует:

npm start

Ожидаемое поведение: в консоль (stderr) выводится MCP-сервер запущен на stdio, после чего процесс остаётся висеть — он ждёт JSON-RPC-сообщения на stdin. Это нормально, выход по Ctrl+C.

Подключение к Claude Desktop

1. Открой файл конфигурации:

Быстрый путь: меню Claude → Settings → вкладка Developer → Edit Config.

2. Добавь блок сервера. Путь до dist/index.js должен быть абсолютным:

{
  "mcpServers": {
    "trainee-mcp-server": {
      "command": "node",
      "args": ["C:/Users/Имя/trainee-mcp-server/dist/index.js"],
      "env": {
        "FAVORITE_CITIES": "Minsk,Gomel,Moscow",
        "DEFAULT_UNITS": "celsius",
        "REQUEST_TIMEOUT_MS": "8000"
      }
    }
  }
}

Блок env опционален — без него применяются значения по умолчанию (см. ниже).

Windows: в JSON обратный слэш — управляющий символ, поэтому путь пишется либо через прямые слэши (C:/Users/...), либо через двойные обратные (C:\\Users\\...).

3. Полностью закрой и заново запусти Claude Desktop. Закрыть окно недостаточно — конфиг читается только при старте приложения.

4. Проверь подключение: Settings → Developer — сервер должен быть в списке. Список его инструментов виден в меню вложений рядом с полем ввода.

Переменные окружения

Все переменные необязательны. Значения читаются при старте и валидируются через Zod: при некорректном значении сервер завершается с ненулевым кодом и пишет причину в stderr — вместо того чтобы молча работать с мусором.

Значения в claude_desktop_config.json задаются строками, включая числовые (требование JSON) — схема приводит их к нужному типу самостоятельно.

Сервер, запущенный из Claude Desktop, не наследует пользовательское окружение: переменные, выставленные в терминале, до него не дойдут. Задавать их нужно в блоке env конфига.

Примеры запросов к Claude

Ресурс, в отличие от инструмента, модель не запрашивает сама: его прикладывает пользователь через меню вложений.

Обработка ошибок

Все ошибки возвращаются как результат вызова с флагом isError: true, а не выбрасываются исключением. Разница существенная: при исключении модель получает протокольную ошибку без деталей, а так текст ошибки приходит ей как обычный ответ инструмента — и она может на него осмысленно отреагировать. Процесс сервера при этом не падает и продолжает обслуживать следующие вызовы.

Отдельно: fetch не выбрасывает исключение на статусах 4xx/5xx, поэтому res.ok проверяется явно. Таймаут реализован через AbortSignal.timeout() — без него зависший внешний сервис подвесил бы вызов инструмента на неопределённое время.

Контрольная проверка — обычный запрос после серии сбоев: сервер жив, инструмент отрабатывает штатно.

Что такое MCP

MCP простыми словами - это "USB-порт" для подключения различных инструментов к модели. В силу того, что модель сама не ходит в интернет, а также писать кучу отдельных интеграций под каждый инструмент нецелесообразно, MCP выступает удобным единым протоколом.

Сам по себе MCP-сервер включает в себя 3 основных составляющие:

• tools — действия/функции, которые использует сама модель (два примера реализованы в данном тестовом задании);

• resources — данные для чтения, дополнительные справочники для модели (файлы, БД);

• prompts — уже готовые шаблоны для запросов.

Структура проекта

trainee-mcp-server/
├── src/
│   └── index.ts        # типы, конфигурация, инструменты, ресурс, запуск
├── screenshots/        # скриншоты вызовов из Claude Desktop
├── *dist/              # результат сборки, в репозиторий не коммитится
├── package-lock.json
├── package.json
├── README.md
└── tsconfig.json

Логи сервера пишутся только в stderr: stdout занят транспортом JSON-RPC, и любой вывод туда ломает обмен сообщениями с хостом.