🧩 Что это
Навык-референс по шаблонам разработки MCP-серверов (Model Context Protocol) на Node.js / TypeScript. Он описывает, как регистрировать инструменты (tools), ресурсы (resources) и промпты (prompts), настраивать транспорт (stdio vs Streamable HTTP) и валидировать входные данные с помощью Zod. Навык пригодится, когда вы создаёте новый MCP-сервер, добавляете в него возможности, переключаете транспорт или обновляете версию SDK.
Важно: API @modelcontextprotocol/sdk менялся между версиями (например, tool() против registerTool(), позиционные аргументы против объекта). Всегда сверяйтесь с актуальной документацией MCP или через навык Context7 (query-docs для "MCP").
⚙️ Как работает
🛠 Инструменты (Tools)
Действия, которые может вызывать AI-модель — поиск, запуск команды, вызов внешнего API. Регистрируются через registerTool() или tool() в зависимости от версии SDK.
- Требуют: имя, описание, схему входных параметров (через
Zod или inline-объект) и функцию-обработчик.
- Рекомендация: всегда указывать idempotency (безопасность повторных вызовов) и ограничения по rate limit / стоимости в описании.
📄 Ресурсы (Resources)
Данные только для чтения, которые модель может запрашивать — содержимое файла, ответ API, конфигурация. Регистрируются через registerResource() или resource().
- Обработчик получает
uri — путь к ресурсу.
- Используйте ресурсы для data-контекста (например, загрузить документацию, прочитать настройки проекта).
💬 Промпты (Prompts)
Многоразовые шаблоны с параметрами, которые клиент (например, Claude Desktop) может предложить пользователю. Регистрируются через registerPrompt().
- Принимают аргументы (например,
language) и возвращают массив сообщений.
- Подходят для повторяющихся сценариев: "напиши письмо", "объясни код".
🌐 Транспорт
stdio — для локальных клиентов (Claude Desktop). Создаётся StdioServerTransport и передаётся в server.connect(). Логика инструментов и ресурсов не должна зависеть от транспорта — меняйте только точку входа.
Streamable HTTP — для удалённых клиентов (Cursor, облачные плагины). Один endpoint, совместимый с текущей спецификацией MCP. Устаревший HTTP/SSE — только для обратной совместимости.
📦 Пример минимального сервера
npm install @modelcontextprotocol/sdk zod
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
const server = new McpServer({
name: "my-server",
version: "1.0.0"
});
// Регистрация инструмента с Zod-схемой
server.tool(
"greet",
"Приветствие пользователя по имени",
{ name: z.string() },
async ({ name }) => ({
content: [{ type: "text", text: `Hello, ${name}!` }]
})
);
Уточните сигнатуру tool() / registerTool() для вашей версии SDK в документации или через Context7.
🎯 Когда использовать
- Создание нового MCP-сервера — стартовая настройка, выбор транспорта.
- Добавление/изменение инструментов — регистрация с правильной схемой и обработчиком.
- Подключение ресурсов — загрузка данных из внешних систем.
- Миграция транспорта — замена
stdio на Streamable HTTP (или наоборот).
- Отладка регистрации — если MCP-клиент не видит инструменты или ресурсы.
- Обновление SDK — проверка изменений API, замена старых вызовов.
⚠️ Важно знать
- Схемы важны в первую очередь (
Schema first): всегда определяйте inputSchema для инструментов — это улучшает автодополнение и валидацию у клиента.
- Обработка ошибок: возвращайте структурированные сообщения (
{ type: "text", text: "Не удалось найти заказ: 404" }), а не бросайте исключения с трейсами.
- Версионирование: фиксируйте версию
@modelcontextprotocol/sdk в package.json, проверяйте changelog при обновлении.
- Не копируйте слепо: сигнатуры менялись —
server.tool(name, desc, schema, handler) превратилась в server.tool({ name, description, inputSchema }, handler). Всегда сверяйте синтаксис по свежей документации.
- Дискорд-сообщество MCP — хороший источник деталей по имплементации, которые часто обгоняют документацию.
Комментарии
Комментариев пока нет. Будьте первым.