Насколько сложно создать MCP-сервер на Cursor и выложить его в npx: честный разбор трудностей

Model Context Protocol (MCP) обещает простую идею: подключаешь к ИИ-редактору вроде Cursor внешний сервер с инструментами — и модель умеет делать реальные вещи, например публиковать статьи в WordPress. На бумаге это выглядит как «пара функций и готово». На практике между «написал код» и «работает в Cursor и ставится через npx» скрывается целая полоса препятствий. Ниже — честный разбор трудностей, собранный на реальном проекте MCP-сервера для WordPress.

1. Окружение и капризы PATH в Windows

Первая же стена возникает ещё до кода. MCP-сервер на TypeScript требует Node.js, а на Windows после установки Node новый путь не подхватывается уже открытыми терминалами и самим редактором. В результате команды node, npm, npx «не распознаются как внутренняя или внешняя команда», хотя всё установлено. Лечится полным перезапуском приложения или ручным добавлением C:\Program Files\nodejs в PATH — но сначала это стоит нескольких потерянных минут и недоумения.

2. Транспорт stdio и логи, которые нельзя писать в stdout

MCP по умолчанию общается через stdio: канал stdout занят протоколом JSON-RPC. Любой случайный console.log в stdout ломает связь. Поэтому всё логирование нужно с самого начала вести в stderr (или в файл), иначе клиент будет получать «битые» сообщения и обрывать соединение без внятной причины.

3. Какую версию SDK брать

У MCP TypeScript SDK параллельно живут поколения (v1 и v2) с разными пакетами и слегка разным API — от того, как объявляется входная схема инструмента, до путей импорта транспорта. Выбор версии влияет на то, соберётся ли проект и запустится ли он у пользователя. Ошибиться здесь легко, а диагностировать — тяжело.

4. Аутентификация в WordPress: пароль приложения ≠ пароль от админки

Самая коварная ловушка. WordPress REST API не принимает обычный пароль пользователя — нужен отдельный «пароль приложения» (Application Password). При этом на любые неверные данные API отвечает одинаково: rest_not_logged_in. Из-за этого легко потратить время на ложные гипотезы (например, «хостинг срезает заголовок Authorization»), тогда как причина проста — в конфиг вписали не тот тип пароля.

5. Кодировка UTF-8

Кириллица добавляет отдельный слой боли. При ручном тестировании через консоль строки могут превратиться в «????», если терминал использует не UTF-8. Сам сервер обрабатывает UTF-8 корректно, но пока это докажешь, успеваешь несколько раз усомниться в собственном коде.

6. Публикация в npm и обязательная 2FA

Выложить пакет в npm, чтобы он запускался через npx, тоже не одна кнопка. Вход на сайте npm — это не то же самое, что вход в CLI: для публикации нужен npm login в терминале. А затем реестр требует двухфакторную аутентификацию: без включённой 2FA (или специального токена) публикация возвращает 403 Forbidden. Приходится настраивать аутентификатор и вводить одноразовый код прямо при npm publish.

7. Подключение в Cursor: таймауты npx и абсолютные пути

Когда пакет уже в npm, кажется, что финал близок. Но при первом запуске npx скачивает пакет, и это занимает десятки секунд — а MCP-клиент ждёт stdio-рукопожатие всего секунду и закрывает соединение с ошибкой -32000: Connection closed. Плюс на Windows встречаются нюансы запуска .cmd-обёрток. Надёжное решение — прописывать в конфиге абсолютный путь и по возможности запускать собранный файл напрямую через node, а не через npx.

8. Безопасность секретов

Наконец, доступы. Пароль приложения и npm-токены легко случайно «засветить» — в конфиге .cursor/mcp.json, в истории терминала, в переписке. Такие файлы обязательно нужно держать вне git (в .gitignore), а утёкшие токены — сразу отзывать.

Вывод

Создать MCP-сервер концептуально несложно — сложность рассыпана по «стыкам»: окружение, транспорт, аутентификация, кодировки, публикация и интеграция с клиентом. Каждый из этих этапов по отдельности решается за минуты, но вместе они превращаются в квест, где непонятная ошибка на одном уровне маскирует проблему на другом. Хорошая новость: пройдя этот путь один раз, получаешь надёжную схему и рабочий инструмент — сервер, который прямо из чата Cursor публикует статьи в WordPress. Эта статья, к слову, создана именно им.