🧩 Что это
MCP Server Patterns — это набор рекомендаций и шаблонов для создания серверов по протоколу MCP (Model Context Protocol) с использованием Node/TypeScript SDK. MCP позволяет AI-ассистентам (например, Claude Desktop, Cursor) вызывать инструменты, читать ресурсы и использовать подсказки (prompts), которые предоставляет ваш сервер. Навык охватывает ключевые концепции: регистрацию инструментов и ресурсов, выбор транспорта (stdio vs. HTTP), валидацию через Zod, а также лучшие практики по обработке ошибок и версионированию.
⚙️ Как работает
🛠️ Три основных компонента MCP-сервера
- Инструменты (Tools) — действия, которые модель может вызывать: поиск, запуск команд, запросы к API. Регистрируются через
registerTool() или tool() в зависимости от версии SDK.
- Ресурсы (Resources) — read-only данные, которые модель может получить: содержимое файлов, ответы API. Регистрируются через
registerResource() или resource(). Обработчик обычно принимает параметр uri.
- Подсказки (Prompts) — параметризованные шаблоны, которые клиент (например, Claude Desktop) может отобразить пользователю. Регистрируются через
registerPrompt().
🔌 Транспорт: stdio vs. HTTP
- stdio — для локальных клиентов (Claude Desktop). Создаётся транспорт stdio и передаётся в метод подключения сервера. API зависит от версии SDK (конструктор или фабричная функция).
- Streamable HTTP — для удалённых клиентов (Cursor, облачные сервисы). Рекомендуемый современный транспорт. Традиционный HTTP/SSE — только для обратной совместимости.
Важно: логика сервера (инструменты + ресурсы) должна быть независима от транспорта, чтобы можно было легко переключаться между stdio и HTTP в точке входа.
📦 Пример установки и базовой структуры
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"
});
Регистрация инструмента (синтаксис зависит от версии SDK):
- В некоторых версиях:
server.tool(name, description, schema, handler)
- В других:
server.tool({ name, description, inputSchema }, handler) или registerTool()
Всегда сверяйтесь с актуальной документацией MCP или используйте Context7 с запросом "MCP" для получения текущих сигнатур методов.
✅ Валидация с Zod
Используйте Zod для описания схемы входных параметров инструмента. Это обеспечивает типобезопасность и автоматическую проверку данных на стороне сервера.
🎯 Когда использовать
Этот навык пригодится, если вы:
- Создаёте новый MCP-сервер с нуля
- Добавляете инструменты или ресурсы в существующий сервер
- Выбираете между stdio и HTTP-транспортом
- Обновляете SDK с одной версии на другую
- Отлаживаете проблемы с регистрацией инструментов или транспортом
💡 Важно знать
🔁 Версионирование SDK
SDK @modelcontextprotocol/sdk активно развивается. API регистрации (tool() vs registerTool()) и подключения могут меняться. Фиксируйте версию SDK в package.json и читайте release notes перед обновлением.
🧠 Лучшие практики
- Схема прежде всего: всегда определяйте входную схему для каждого инструмента; документируйте параметры и возвращаемые данные.
- Обработка ошибок: возвращайте структурированные ошибки или понятные сообщения, которые модель сможет интерпретировать. Избегайте сырых stack trace.
- Идемпотентность: проектируйте инструменты так, чтобы повторные вызовы были безопасны (например, идемпотентные операции записи).
- Рейт-лимиты и стоимость: если инструмент вызывает внешние API, учитывайте ограничения по частоте и стоимости; укажите это в описании инструмента.
- Документация: используйте Context7 (запрос "MCP") или официальную документацию MCP для получения актуальных сигнатур методов.
🌐 Официальные SDK
Комментарии
Комментариев пока нет. Будьте первым.