Шаблон MCP: сервер контекстного протокола модели
Этот сервер реализует Model Context Protocol (MCP) для глобального использования в качестве шаблона. Он обеспечивает стандартизированный способ подключения моделей ИИ к различным источникам данных и инструментам с использованием Model Context Protocol.
Функции
- Реализует транспорт MCP Server-Sent Events (SSE)
- Обеспечивает надежную структуру для создания пользовательских серверов MCP
- Включает примеры инструментов с правильными определениями типов.
- Безопасная аутентификация с помощью ключа API
- Возможности ведения журнала с различными уровнями серьезности
- Управление сеансами для нескольких клиентских подключений
- Мягкая обработка завершения работы сигналов SIGINT и SIGTERM
Инструменты
В настоящее время сервер включает в себя следующий пример инструмента:
calculator : выполняет основные арифметические операции (сложение, вычитание, умножение, деление)
Информацию о том, как добавлять собственные инструменты, можно найти в разделе «Расширение шаблона» .
Конфигурация
Конфигурация сервера централизована в src/config.ts . Это позволяет легко настраивать параметры без изменения нескольких файлов.
// Essential configuration options
export const config = {
server: {
name: "mcp-boilerplate",
version: "1.0.0",
port: parseInt(process.env.PORT || "4005"),
host: process.env.HOST || "localhost",
apiKey: process.env.API_KEY || "dev_key",
},
sse: {
// How often to send keepalive messages (in milliseconds)
keepaliveInterval: 30000,
// Whether to send ping events in addition to comments
usePingEvents: true,
// Initial connection message
sendConnectedEvent: true,
},
tools: {
// Number of retries for failed tool executions
maxRetries: 3,
// Delay between retries (in milliseconds)
retryDelay: 1000,
// Whether to send notifications about tool execution status
sendNotifications: true,
},
logging: {
// Default log level
defaultLevel: "debug",
// How often to send log messages (in milliseconds)
logMessageInterval: 10000,
},
};
Устранение неполадок, связанных с тайм-аутами SSE
Если вы столкнулись с ошибкой «Body timeout error» при подключении MCP:
- Уменьшите
keepaliveInterval , чтобы отправлять более частые сообщения keepalive (например, 15000 мс) - Убедитесь, что
usePingEvents включен для дополнительной стабильности соединения. - Проверьте наличие тайм-аутов прокси-сервера, если вы используете прокси-сервер.
Настраивать
- Установить зависимости:
- Создайте файл
.env со следующими переменными:
PORT=4005
API_KEY=your_api_key
- Создайте проект:
- Запустите сервер:
Разработка
# Start in development mode with hot reloading
npm run start
# Start with PM2 for production
npm run start:pm2
# Development mode with nodemon
npm run dev
Конечные точки API
/health : Конечная точка проверки работоспособности, которая возвращает статус и версию сервера./sse : конечная точка SSE для установления соединений MCP (требуется ключ API)/messages : Конечная точка обработки сообщений для клиент-серверного взаимодействия
Конфигурация МКП
Чтобы подключить MCP к этому серверу, добавьте следующую конфигурацию:
{
"mcpServers": {
"mcp-server": {
"url": "http://localhost:4005/sse?API_KEY={{your_api_key_here}}"
}
}
}
Расширение шаблона
Добавление пользовательских инструментов
Чтобы добавить новый инструмент на сервер MCP, выполните следующие действия:
- Создайте свой обработчик инструментов :
- Добавьте новый обработчик инструментов в файл
src/tools.ts или создайте новый файл в каталоге src/tools - Инструмент должен соответствовать интерфейсу
ToolHandler
- Настройте свой инструмент :
- Добавьте конфигурацию вашего инструмента в массив
toolConfigs в src/tools.ts - Определите имя, описание, схему ввода и обработчик для вашего инструмента.
- Экспортируйте и зарегистрируйте свой инструмент :
- Если вы создали отдельный файл, экспортируйте свой обработчик и импортируйте его в
src/tools.ts - Убедитесь, что ваш инструмент правильно зарегистрирован в массиве
toolConfigs
Пример:
// In src/tools.ts (adding directly to the toolConfigs array)
{
name: "myTool",
description: "My tool description",
inputSchema: {
type: "object" as const,
properties: {},
required: [],
},
handler: async () => {
return createSuccessResult({ result: "Tool result" });
},
}
Обработка ошибок
На сервере реализована комплексная обработка ошибок:
- Все операции заключены в блоки try/catch.
- Правильная проверка параметров и входных данных
- Соответствующие сообщения об ошибках для лучшей отладки
- Вспомогательные функции для создания стандартизированных ответов об ошибках и успешном выполнении
Соображения безопасности
- Аутентификация API-ключа для всех подключений
- Проверка типа для всех параметров
- Отсутствие жестко запрограммированной конфиденциальной информации
- Правильная обработка ошибок для предотвращения утечки информации
- Управление транспортом на основе сеансов
Особенности протокола MCP
Этот шаблон поддерживает основные функции MCP:
- Инструменты: список и вызов инструментов с надлежащей проверкой параметров.
- Ведение журнала: различные уровни серьезности (отладка, информация, уведомление, предупреждение, ошибка, критическое, оповещение, аварийное состояние)
- Конфигурация сервера: имя, версия и возможности
Управление сеансом
Сервер управляет клиентскими сеансами посредством:
- Уникальные идентификаторы сеансов для каждого клиентского соединения
- Отслеживание активных транспортов по идентификатору сеанса
- Автоматическая очистка отключенных сеансов
- Отслеживание статуса соединения
Дополнительные ресурсы
Лицензия
Данный проект лицензирован по лицензии MIT — подробности см. в файле LICENSE .