MCP-сервер поверх своего REST API без SDK: что видит модель и где она ломает данные

Model Context Protocol (MCP) позволяет агенту вроде Claude Code или Cursor вызывать внешние инструменты. Я подключал так свой сервис коротких ссылок: агент пишет рассылку или release notes и сам создаёт ссылку с UTM-метками, а потом смотрит по ней клики. Сервер получился маленький, около 360 строк на чистом Node.js, без SDK и зависимостей. Но почти каждая строка в нём появилась после того, как модель повела себя не так, как я ожидал.

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

Архитектура: тонкая обёртка

У сервиса уже был REST API с ключом. MCP-сервер не содержит своей логики: он принимает вызов инструмента, ходит в тот же API и возвращает ответ. Вся валидация, лимиты и проверки безопасности остаются на сервере API.

Плюсы такого подхода:

  • одно место, где живут правила. Если поменять лимит или проверку URL, MCP-клиенты получат изменение сразу, обновлять пакет не нужно;

  • MCP-сервер можно запускать локально через npx, ему нужны только ключ и адрес API;

  • его легко тестировать: это просто маппинг «инструмент → HTTP-запрос».

async function callTool(name, args = {}) { if (!API_KEY) { throw new Error( "API_KEY is not set. Create a key at https://linkbit.live/api-keys and set API_KEY to the slk_ value.", ); } switch (name) { case "shorten_url": return api("/api/v1/links", { method: "POST", body: JSON.stringify(args) }); case "delete_link": return api(`/api/v1/links/${args.id}`, { method: "DELETE" }); // ... ещё 7 инструментов default: throw new Error(`Unknown tool: ${name}`); }}

Транспорт: stdio и два формата сообщений

Локальный MCP-сервер общается с клиентом через stdin и stdout сообщениями JSON-RPC 2.0. По спецификации каждое сообщение — одна строка JSON. Но на случай, если клиент или отладочная утилита пришлёт сообщение в формате LSP, с заголовком Content-Length, парсер понимает оба варианта:

function takeJsonMessages(chunk) { const messages = []; let rest = chunk; while (rest.length) { const headerMatch = rest.match(/^Content-Length:s*(d+)r?nr?n/i); if (headerMatch) { const size = Number(headerMatch[1]); const start = headerMatch[0].length; const body = rest.slice(start, start + size); if (body.length < size) break; // сообщение пришло не целиком, ждём остаток messages.push(body); rest = rest.slice(start + size); continue; } const nl = rest.indexOf("n"); if (nl === -1) break; const line = rest.slice(0, nl).trim(); rest = rest.slice(nl + 1); if (line) messages.push(line); } return { messages, rest };}

Две важные мелочи:

  • stdin приходит кусками произвольной длины. Одно сообщение может разрезаться пополам, а в одном куске может оказаться три сообщения. Поэтому нужен буфер и возврат необработанного остатка.

  • В stdout нельзя писать ничего, кроме протокола. Один случайный console.log ломает клиенту парсинг, и он молча отключает сервер. Всю отладку — в stderr.

Методов, которые реально нужны, немного: initialize, tools/list, tools/call и ping. На уведомления (сообщения без id) отвечать не надо.

Решение 1. Ошибки — это результат инструмента, а не ошибка протокола

Самый очевидный путь — возвращать ошибки API как ошибки JSON-RPC. Но тогда клиент часто показывает модели просто «tool failed», и она начинает гадать: повторяет вызов, меняет аргументы, извиняется перед пользователем.

В MCP есть другой путь: вернуть обычный результат с флагом isError: true. Тогда текст ошибки попадает модели в контекст как данные, и она может с ними работать.

try { const result = await callTool(name, params.arguments || {}); reply(id, { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] });} catch (error) { reply(id, { isError: true, content: [{ type: "text", text: error instanceof Error ? error.message : "Tool failed" }], });}

Ошибки протокола я оставил только для того, что действительно сломано на уровне протокола: неизвестный метод, неизвестный инструмент, невалидный JSON.

Второе следствие: текст ошибки надо писать для модели, а не для логов. Не 401, а:

401 Unauthorized: API_KEY is invalid. Create a key at https://linkbit.live/api-keys

Получив такой ответ, агент обычно не повторяет запрос, а говорит пользователю, где взять ключ. То же с лимитами и запрещёнными URL: короткая причина и что делать дальше.

Решение 2. Аннотации опасных инструментов

У инструментов в MCP есть подсказки для клиента: readOnlyHint, destructiveHint, idempotentHint, openWorldHint. Клиенты используют их, чтобы решать, когда спрашивать подтверждение у человека.

{ name: "delete_link", description: "Permanently delete a short link. This cannot be undone.", inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], }, annotations: { title: "Delete link", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true, },}

destructiveHint: true стоит у удаления и отключения ссылки. Чтение списка и статистики помечено readOnlyHint: true, его клиент вызывает без вопросов. Отдельно помогает фраза «This cannot be undone» прямо в описании: модель читает описание и сама переспрашивает пользователя.

Важно помнить, что это подсказки, а не защита. Клиент может их проигнорировать. Настоящие ограничения — права ключа и проверки на сервере API.

Решение 3. Модель «исправляет» URL, сервер должен быть предсказуемым

Модели любят переписывать URL «как им кажется правильнее». Представим: пользователь просит «сократи ссылку и добавь utm_source=newsletter», а в самом URL уже есть utm_source=partner. Что должно победить?

Я решил, что существующие параметры в URL не перезаписываются, а якорь #fragment сохраняется. Ссылка часто приходит из готовой кампании, и метки в ней кто-то ставил осознанно. Это закреплено тестом на стороне API:

it("does not overwrite existing utm_* params", () => { const out = applyUtm("https://example.com/?utm_source=original", { utm_source: "other", utm_medium: "cpc", }); const url = new URL(out); assert.equal(url.searchParams.get("utm_source"), "original"); // старая метка осталась assert.equal(url.searchParams.get("utm_medium"), "cpc"); // новая добавилась});

И то же правило написано в описании инструмента: «Optional UTM fields are merged without overwriting existing utm_* params». Модель читает описание и перестаёт удивляться результату.

Общий вывод: если модель может передать лишнее или противоречивое, поведение сервера должно быть детерминированным и описанным. Не стоит надеяться, что модель передаст «правильно».

Решение 4. Частичный успех в пакетных операциях

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

Поэтому API для пакета отвечает объектом с двумя массивами, created и errors, и MCP-сервер передаёт его модели как обычный результат, даже при HTTP-ошибке:

const data = await response.json().catch(() => ({}));if (!response.ok) { if (data && Array.isArray(data.created) && Array.isArray(data.errors)) return data; // ...}

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

Решение 5. Картинки отдаются картинками

Инструмент get_qr возвращает QR-код. Если отдать base64 текстом, модель получит несколько килобайт бессмысленных символов в контексте. В MCP есть тип контента image, и клиент покажет картинку пользователю:

if (mime.startsWith("image/")) { content.push({ type: "image", data: result.base64, mimeType: mime });}content.push({ type: "text", text: JSON.stringify({ contentType: result.contentType, bytes: result.bytes }, null, 2),});

Рядом идёт короткий текстовый блок с типом и размером: модели этого достаточно, чтобы сказать «QR готов, PNG, 4 КБ».

Подключение

Для Claude Code сервер добавляется одной командой:

claude mcp add linkbit -e API_KEY=slk_... -e APP_URL=https://linkbit.live -- npx -y linkbit-mcp

Для Cursor и Claude Desktop то же самое описывается в mcp.json. После этого агенту можно писать обычным текстом: «сократи ссылку со слагом spring и utm_source newsletter», «покажи клики по последней ссылке с 1 января».

Что бы я сделал иначе

  • Сразу проектировал бы ответы API под модель. Короткие причины ошибок и явный частичный успех полезны не только агенту, но и обычным интеграциям.

  • Не писал бы своё без нужды. Без SDK сервер получился прозрачным, и я хорошо понял протокол. Но для чего-то большего, с ресурсами, промптами и HTTP-транспортом, официальный SDK сэкономит время.

  • Проверял бы на нескольких клиентах с первого дня. Claude Code, Cursor и MCP Inspector могут по-разному показывать ошибки и по-разному решать, когда спрашивать подтверждение.

Код сервера целиком можно посмотреть в пакете linkbit-mcp на npm. Если вы тоже делали MCP-серверы поверх своих API, интересно узнать в комментариях, на какие ещё грабли вы наступали.

Источник: habr.com

0 0 голоса
Рейтинг новости
1
0
Подписаться
Уведомить о
0 комментариев