Шаблон MCP

Шаблон 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 включен для дополнительной стабильности соединения.
Проверьте наличие тайм-аутов прокси-сервера, если вы используете прокси-сервер.

Настраивать

Установить зависимости:

npm install

Создайте файл .env со следующими переменными:

PORT=4005
API_KEY=your_api_key

Создайте проект:

npm run build

Запустите сервер:

npm run start:sse

Разработка

# 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 .

MCP Boilerplate

Integrations